将 LLVM 项目迁移到 GitHub¶

当前状态¶

我们计划在 2019 年 10 月 21 日之前完成向 GitHub 的过渡。请参阅 GitHub 迁移状态页面以获取最新更新以及关于如何迁移您的工作流程的说明。

简介¶

这是一个将我们当前的修订控制系统从我们自己托管的 Subversion 迁移到 GitHub 的提案。以下是关于我们为何提出此迁移以及人们（和验证基础设施）将如何继续使用基于 Git 的 LLVM 的财务和技术论据。

本提案不涉及的内容¶

更改开发策略。

本提案仅关系到将我们的源代码仓库从我们自己的服务器上托管的 SVN 迁移到 GitHub 上托管的 Git。我们不打算使用 GitHub 的 issue 跟踪器、pull-request 或代码审查。

贡献者将继续根据开发者策略按需获得提交权限，除了需要一个 GitHub 帐户来代替 SVN 用户名/密码哈希。

为什么选择 Git，以及为什么选择 GitHub？¶

为什么要迁移？¶

此讨论的开始是因为我们目前在志愿的基础上托管我们自己的 Subversion 服务器和 Git 镜像。LLVM 基金会赞助服务器并提供有限的支持，但它能做的也有限。

志愿者本身不是系统管理员，而是碰巧对托管服务器略知一二的编译器工程师。我们也没有 24/7 支持，我们有时醒来会发现持续集成已中断，因为 SVN 服务器宕机或无响应。

我们应该利用外界提供的服务之一（GitHub、GitLab 和 BitBucket 等），它们提供更好的服务（24/7 稳定性、磁盘空间、Git 服务器、代码浏览、fork 功能等），而且是免费的。

为什么选择 Git？¶

现在许多新的程序员都从 Git 入门，很多人从未用过 SVN、CVS 或其他任何东西。像 GitHub 这样的网站已经改变了开源贡献的格局，降低了首次贡献的成本并促进了协作。

Git 也是许多 LLVM 开发者使用的版本控制系统。尽管源代码存储在 SVN 服务器中，但这些开发者已经通过 Git-SVN 集成在使用 Git。

Git 允许您

在本地提交、压缩、合并和 fork，而无需接触远程服务器。
维护本地分支，从而实现多个开发线程。
在这些分支上进行协作（例如，通过您自己在 GitHub 上的 llvm fork）。
在没有 Internet 访问的情况下检查仓库历史记录（blame、log、bisect）。
在 Git 托管服务上维护远程 fork 和分支，并集成回主仓库。

此外，由于 Git 似乎正在取代许多 OSS 项目的版本控制系统，因此有许多工具是基于 Git 构建的。未来的工具可能会首先（如果不是仅）支持 Git。

为什么选择 GitHub？¶

与 GitLab 和 BitBucket 一样，GitHub 为开源项目提供免费的代码托管。这些服务中的任何一个都可以取代我们今天拥有的代码托管基础设施。

这些服务还拥有专门的团队来监控、迁移、改进和分发仓库的内容，具体取决于地区和负载。

GitHub 比 GitLab 和 BitBucket 有一个重要的优势：它提供对仓库的读写 SVN 访问 (https://github.com/blog/626-announcing-svn-support)。这将使人们能够在迁移后继续工作，就像我们的代码仍然在规范的 SVN 仓库中一样。

此外，GitHub 上已经有多个 LLVM 镜像，表明我们社区的一部分已经在此安家。

关于使用 Git 管理修订号¶

当前的 SVN 仓库将所有 LLVM 子项目并排托管在一起。因此，单个修订号（例如 r123456）标识了所有 LLVM 子项目的一致版本。

Git 不使用顺序整数修订号，而是使用哈希来标识每次提交。

丢失顺序整数修订号一直是过去关于 Git 讨论的一个症结所在

“我最关心的 ‘分支’ 是 mainline，而失去说 ‘在 r1234 中修复’（带有一些单调递增的数字）的能力将是一个悲剧性的损失。” [LattnerRevNum]
“我喜欢按时间排序的结果，时间顺序应该很明显，但时间戳非常麻烦，并且难以验证给定的检出是否与给定的结果集匹配。” [TrickRevNum]
“仍然存在不可读的版本号的重大倒退。鉴于 Bugzilla 中有大量 ‘Fixed in…’ 的流量，这是一个不小的问题。” [JSonnRevNum]
“顺序 ID 对于 LNT 和 llvm实验室二分工具很重要。” [MatthewsRevNum]。

但是，Git 可以模拟此递增的修订号：git rev-list --count <commit-hash>。此标识符仅在单个分支中是唯一的，但这表示元组 (num, branch-name) 唯一地标识了一个提交。

因此，我们可以使用此修订号来确保例如 clang -v 报告用户友好的修订号（例如 main-12345 或 4.0-5321），从而解决上面提出的关于 Git 这方面的反对意见。

分支和合并呢？¶

与 SVN 相比，Git 使分支变得容易。Git 的提交历史记录表示为 DAG（有向无环图），这与 SVN 的线性历史记录不同。但是，我们建议强制禁止在我们的规范 Git 仓库中进行合并提交。

不幸的是，GitHub 不支持服务器端钩子来强制执行此策略。我们必须依靠社区来避免推送合并提交。

GitHub 提供了一个名为状态检查的功能：受状态检查保护的分支要求在推送发生之前显式允许提交。我们可以在客户端提供一个 pre-push 钩子，该钩子将在允许推送提交之前运行并检查历史记录 [statuschecks]。但是，此解决方案有点脆弱（如何更新安装在每台开发人员机器上的脚本？），并且阻止了对仓库的 SVN 访问。

提交邮件呢？¶

我们将需要一个新的机器人来为每次提交发送电子邮件。除了提交 URL 之外，此提案保持电子邮件格式不变。

初步迁移计划¶

步骤 #1：迁移之前¶

更新文档以提及迁移，以便人们了解正在发生的事情。
设置 GitHub 项目的只读版本，镜像我们当前的 SVN 仓库。
添加所需的机器人以实现提交电子邮件，以及 umbrella 仓库更新（如果选择 multirepo）或子项目的只读 Git 视图（如果选择 monorepo）。

步骤 #2：Git 迁移¶

更新 buildbot 以从 GitHub 仓库获取更新和提交。并非所有机器人此时都必须迁移，但这将有助于提供基础设施测试。
更新 Phabricator 以从 GitHub 仓库获取提交。
LNT 和 llvm实验室必须更新：它们依赖于跨分支的唯一单调递增整数 [MatthewsRevNum]。
指示下游集成商从 GitHub 仓库获取提交。
审查并准备 LLVM 文档的更新。

在此之前，对于开发人员来说没有任何改变，它只会归结为 buildbot 和其他基础设施所有者的大量工作。

迁移将在此处暂停，直到所有依赖项都已清除，并且所有问题都已解决。

步骤 #3：写入权限迁移¶

收集开发人员的 GitHub 帐户信息，并将他们添加到项目中。
将 SVN 仓库切换为只读，并允许推送到 GitHub 仓库。
更新文档。
将 Git 镜像到 SVN。

步骤 #4：迁移后¶

存档 SVN 仓库。
更新 LLVM 网站上指向 viewvc/klaus/phab 等的链接，以指向 GitHub。

GitHub 仓库描述¶

Monorepo（单仓库）¶

托管在 https://github.com/llvm/llvm-project 的 LLVM git 仓库在一个源代码树中包含所有子项目。它通常被称为 monorepo（单仓库），并模仿当前 SVN 仓库的导出，每个子项目都有自己的顶层目录。并非所有子项目都用于构建工具链。例如，www/ 和 test-suite/ 不是 monorepo 的一部分。

将所有子项目放在一个检出中使跨项目重构自然而然地变得简单

新的子项目可以很容易地拆分出来，以便更好地重用和/或分层（例如，允许 libSupport 和/或 LIT 被运行时使用，而无需添加对 LLVM 的依赖）。

在 LLVM 中更改 API 并升级子项目将始终在一次提交中完成，从而避免了临时构建中断的常见来源。

在一次提交中跨子项目移动代码（例如在重构期间）可以在跟踪代码更改历史记录时实现准确的 git blame。

基于 git grep 的工具可以跨子项目本地工作，从而更容易找到跨项目的重构机会（例如，通过将最初在 LLDB 中的数据结构移动到 libSupport 中来重用它）。

拥有所有源代码鼓励在更改 API 时维护其他子项目。

最后，monorepo 保持了现有 SVN 仓库的属性，即子项目同步移动，并且单个修订号（或提交哈希）标识了所有项目开发的整体状态。

构建单个子项目¶

即使只有一个源代码树，您也不需要一起构建所有子项目。为单个子项目配置构建非常简单。

例如

mkdir build && cd build
# Configure only LLVM (default)
cmake path/to/monorepo
# Configure LLVM and lld
cmake path/to/monorepo -DLLVM_ENABLE_PROJECTS=lld
# Configure LLVM and clang
cmake path/to/monorepo -DLLVM_ENABLE_PROJECTS=clang

未解决的问题¶

只读子项目镜像¶

使用 Monorepo，尚未决定是否继续维护现有的单子项目镜像（例如 https://git.llvm.org/git/compiler-rt.git）。

读/写 SVN 桥接¶

GitHub 支持其仓库的读/写 SVN 桥接。但是，过去此桥接的正常工作一直存在问题，因此尚不清楚这是否是未来将支持的功能。

Monorepo 的缺点¶

对于那些为独立子项目（特别是像 libcxx 和 compiler-rt 这样的运行时，它们不依赖于 LLVM）做出贡献的人来说，使用单体仓库可能会增加开销；目前，libcxx 的全新克隆只有 15MB（而 monorepo 为 1GB），LLVM 的提交率可能会导致上游时更频繁的 git push 冲突。受影响的贡献者或许可以使用 SVN 桥接或单子项目 Git 镜像。但是，尚未决定是否继续维护这些项目。

对于那些集成独立子项目的人来说，即使他们没有为其做出贡献，使用单体仓库也可能会增加开销，原因与上述磁盘空间问题相同。子项目 Git 镜像的可用性将解决此问题。

保留现有的基于读/写 SVN 的工作流程依赖于 GitHub SVN 桥接，这是一个额外的依赖项。维护此功能会将我们锁定在 GitHub 上，并可能限制未来的工作流程更改。

工作流程¶

检出/克隆单个项目，没有提交权限.

检出/克隆多个项目，具有提交权限.

在 LLVM 中提交 API 更改并更新子项目.

为本地开发或实验进行分支/暂存/更新.

二分查找.

工作流程前后对比¶

本节将介绍几个工作流程示例，旨在说明最终用户或开发人员将如何在各种用例中与仓库进行交互。

检出/克隆单个项目，具有提交权限¶

当前¶

# direct SVN checkout
svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm
# or using the read-only Git view, with git-svn
git clone https://llvm.org/git/llvm.git
cd llvm
git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username>
git config svn-remote.svn.fetch :refs/remotes/origin/main
git svn rebase -l  # -l avoids fetching ahead of the git mirror.

提交使用 svn commit 或 git commit 和 git svn dcommit 序列执行。

Monorepo 变体¶

使用 monorepo 变体，根据您的约束，有几种选择。首先，您可以只克隆整个仓库

git clone https://github.com/llvm/llvm-project.git

此时，您拥有每个子项目（llvm、clang、lld、lldb、…），这并不意味着您必须构建所有这些项目。例如，您仍然可以只构建 compiler-rt。这样，它与今天使用 SVN 检出所有项目的人没有什么不同。

如果您想避免检出所有源代码，可以使用 Git 稀疏检出隐藏其他目录

git config core.sparseCheckout true
echo /compiler-rt > .git/info/sparse-checkout
git read-tree -mu HEAD

所有子项目的数据仍然在您的 .git 目录中，但在您的检出中，您只能看到 compiler-rt。在推送之前，您需要像往常一样获取和变基（git pull –rebase）。

请注意，当您获取时，您可能会拉取您不关心的子项目的更改。如果您正在使用稀疏检出，则来自其他项目的文件不会出现在您的磁盘上。唯一的影响是您的提交哈希值发生更改。

您可以通过运行以下命令来检查上次获取中的更改是否与您的提交相关

git log origin/main@{1}..origin/main -- libcxx

此命令可以隐藏在脚本中，以便 git llvmpush 将执行所有这些步骤，仅在存在此类依赖更改时失败，并立即显示阻止推送的更改。立即重复该命令（几乎）肯定会导致推送成功。请注意，在今天的 SVN 或 git-svn 中，此步骤是不可能的，因为 “rebase” 在提交时隐式发生（除非发生冲突）。

检出/克隆多个项目，具有提交权限¶

让我们看看如何在给定的修订版中组装 llvm+clang+libcxx。

当前¶

svn co https://llvm.net.cn/svn/llvm-project/llvm/trunk llvm -r $REVISION
cd llvm/tools
svn co https://llvm.net.cn/svn/llvm-project/clang/trunk clang -r $REVISION
cd ../projects
svn co https://llvm.net.cn/svn/llvm-project/libcxx/trunk libcxx -r $REVISION

或使用 git-svn

git clone https://llvm.net.cn/git/llvm.git
cd llvm/
git svn init https://llvm.net.cn/svn/llvm-project/llvm/trunk --username=<username>
git config svn-remote.svn.fetch :refs/remotes/origin/main
git svn rebase -l
git checkout `git svn find-rev -B r258109`
cd tools
git clone https://llvm.net.cn/git/clang.git
cd clang/
git svn init https://llvm.net.cn/svn/llvm-project/clang/trunk --username=<username>
git config svn-remote.svn.fetch :refs/remotes/origin/main
git svn rebase -l
git checkout `git svn find-rev -B r258109`
cd ../../projects/
git clone https://llvm.net.cn/git/libcxx.git
cd libcxx
git svn init https://llvm.net.cn/svn/llvm-project/libcxx/trunk --username=<username>
git config svn-remote.svn.fetch :refs/remotes/origin/main
git svn rebase -l
git checkout `git svn find-rev -B r258109`

请注意，如果子项目更多，则列表会更长。

Monorepo 变体¶

仓库本身包含每个子项目的源代码，并且修订版正确，这使得此操作非常简单

git clone https://github.com/llvm/llvm-project.git
cd llvm-projects
git checkout $REVISION

和以前一样，此时 clang、llvm 和 libcxx 存储在彼此相邻的目录中。

在 LLVM 中提交 API 更改并更新子项目¶

今天这是可能的，即使对于 subversion 用户和 git-svn 用户来说并不常见（至少没有文档记录）。例如，很少有 Git 用户尝试在更改 LLVM API 的同一提交中更新 LLD 或 Clang。

multirepo 变体没有解决这个问题：必须在每个单独的仓库中分别提交和推送。可以建立一个协议，用户可以在其提交消息中添加一个特殊令牌，使 umbrella 仓库的更新机器人将所有这些令牌分组到一个修订版中。

monorepo 变体本地处理此问题。

为本地开发或实验进行分支/暂存/更新¶

当前¶

SVN 不允许此用例，但当前正在使用 git-svn 的开发人员可以这样做。让我们在实践中看看处理多个子项目时这意味着什么。

将仓库更新到主干顶端

git pull
cd tools/clang
git pull
cd ../../projects/libcxx
git pull

创建新分支

git checkout -b MyBranch
cd tools/clang
git checkout -b MyBranch
cd ../../projects/libcxx
git checkout -b MyBranch

切换分支

git checkout AnotherBranch
cd tools/clang
git checkout AnotherBranch
cd ../../projects/libcxx
git checkout AnotherBranch

Monorepo 变体¶

常规 Git 命令就足够了，因为所有内容都在单个仓库中

将仓库更新到主干顶端

git pull

创建新分支

git checkout -b MyBranch

切换分支

git checkout AnotherBranch

二分查找¶

假设开发人员正在查找 clang（或 lld 或 lldb，…）中的错误。

当前¶

SVN 没有内置的二分查找支持，但跨子项目的单个修订版使得可以编写脚本来解决。

使用仓库的现有 Git 只读视图，可以使用 llvm 仓库上的本机 Git 二分查找脚本，并使用一些脚本来同步 clang 仓库以匹配 llvm 修订版。

Monorepo 变体¶

在 monorepo 上进行二分查找非常简单，并且与上述非常相似，只是二分查找脚本不需要包含 git submodule update 步骤。

相同的示例，查找哪个提交引入了 clang-3.9 崩溃但 clang-3.8 通过的回归，将如下所示

git bisect start releases/3.9.x releases/3.8.x
git bisect run ./bisect_script.sh

其中 bisect_script.sh 脚本是

#!/bin/sh
cd $BUILD_DIR

ninja clang || exit 125   # an exit code of 125 asks "git bisect"
                          # to "skip" the current commit

./bin/clang some_crash_test.cpp

此外，由于 monorepo 处理跨多个项目的提交更新，因此您不太可能遇到构建失败的情况，即一个提交更改了 LLVM 中的 API，而稍后的另一个提交 “修复” 了 clang 中的构建。

将本地分支移动到 Monorepo¶

假设您一直在针对现有的 LLVM git 镜像进行开发。您有一个或多个想要迁移到 “最终 monorepo” 的 git 分支。

迁移此类分支的最简单方法是使用 migrate-downstream-fork.py 工具，该工具位于 https://github.com/jyknight/llvm-git-migration。

基本迁移¶

migrate-downstream-fork.py 的基本说明在 Python 脚本中，并在下面扩展到更通用的配方

# Make a repository which will become your final local mirror of the
# monorepo.
mkdir my-monorepo
git -C my-monorepo init

# Add a remote to the monorepo.
git -C my-monorepo remote add upstream/monorepo https://github.com/llvm/llvm-project.git

# Add remotes for each git mirror you use, from upstream as well as
# your local mirror.  All projects are listed here but you need only
# import those for which you have local branches.
my_projects=( clang
              clang-tools-extra
              compiler-rt
              debuginfo-tests
              libcxx
              libcxxabi
              libunwind
              lld
              lldb
              llvm
              openmp
              polly )
for p in ${my_projects[@]}; do
  git -C my-monorepo remote add upstream/split/${p} https://github.com/llvm-mirror/${p}.git
  git -C my-monorepo remote add local/split/${p} https://my.local.mirror.org/${p}.git
done

# Pull in all the commits.
git -C my-monorepo fetch --all

# Run migrate-downstream-fork to rewrite local branches on top of
# the upstream monorepo.
(
   cd my-monorepo
   migrate-downstream-fork.py \
     refs/remotes/local \
     refs/tags \
     --new-repo-prefix=refs/remotes/upstream/monorepo \
     --old-repo-prefix=refs/remotes/upstream/split \
     --source-kind=split \
     --revmap-out=monorepo-map.txt
)

# Octopus-merge the resulting local split histories to unify them.

# Assumes local work on local split mirrors is on main (and
# upstream is presumably represented by some other branch like
# upstream/main).
my_local_branch="main"

git -C my-monorepo branch --no-track local/octopus/main \
  $(git -C my-monorepo merge-base refs/remotes/upstream/monorepo/main \
                                  refs/remotes/local/split/llvm/${my_local_branch})
git -C my-monorepo checkout local/octopus/${my_local_branch}

subproject_branches=()
for p in ${my_projects[@]}; do
  subproject_branch=${p}/local/monorepo/${my_local_branch}
  git -C my-monorepo branch ${subproject_branch} \
    refs/remotes/local/split/${p}/${my_local_branch}
  if [[ "${p}" != "llvm" ]]; then
    subproject_branches+=( ${subproject_branch} )
  fi
done

git -C my-monorepo merge ${subproject_branches[@]}

for p in ${my_projects[@]}; do
  subproject_branch=${p}/local/monorepo/${my_local_branch}
  git -C my-monorepo branch -d ${subproject_branch}
done

# Create local branches for upstream monorepo branches.
for ref in $(git -C my-monorepo for-each-ref --format="%(refname)" \
                 refs/remotes/upstream/monorepo); do
  upstream_branch=${ref#refs/remotes/upstream/monorepo/}
  git -C my-monorepo branch upstream/${upstream_branch} ${ref}
done

以上操作使您达到如下状态

U1 - U2 - U3 <- upstream/main
  \   \    \
   \   \    - Llld1 - Llld2 -
    \   \                    \
     \   - Lclang1 - Lclang2-- Lmerge <- local/octopus/main
      \                      /
       - Lllvm1 - Lllvm2-----

每个分支组件都将其分支重写在 monorepo 之上，并且所有组件都通过巨大的章鱼合并统一起来。

如果需要保留其他活动本地分支，则应该为每个分支完成上述在分配给 my_local_branch 之后的操作。需要更新 Ref 路径以将本地分支映射到相应的上游分支。如果本地分支没有相应的上游分支，则创建 local/octopus/<local branch> 不需要使用 git-merge-base 来精确定位其根提交；它可以简单地从相应的组件分支（例如，llvm/local_release_X）分支出来。

压缩本地历史记录¶

对于许多情况，章鱼合并都不是最优的，因为回溯一个组件的历史记录会将其他组件固定在可能使事物无法构建的历史记录中。

一些下游用户使用某种 “umbrella” 项目跟踪提交到子项目的顺序，该项目将项目 git 镜像作为子模块导入，类似于上面提出的 multirepo umbrella。这样的 umbrella 仓库看起来像这样

 UM1 ---- UM2 -- UM3 -- UM4 ---- UM5 ---- UM6 ---- UM7 ---- UM8 <- main
 |        |             |        |        |        |        |
Lllvm1   Llld1         Lclang1  Lclang2  Lllvm2   Llld2     Lmyproj1

竖线表示子模块更新到项目镜像中的特定本地提交。UM3 在这种情况下是某些本地 umbrella 仓库状态的提交，而不是子模块更新，可能是 README 或项目构建脚本更新。提交 UM8 更新本地项目 myproj 的子模块。

工具 zip-downstream-fork.py 在 https://github.com/greened/llvm-git-migration/tree/zip 中可用于将 umbrella 历史记录转换为基于 monorepo 的历史记录，提交顺序由子模块更新暗示

U1 - U2 - U3 <- upstream/main
 \    \    \
  \    -----\---------------                                    local/zip--.
   \         \              \                                               |
  - Lllvm1 - Llld1 - UM3 -  Lclang1 - Lclang2 - Lllvm2 - Llld2 - Lmyproj1 <-'

U* 提交表示对 monorepo 主分支的上游提交。本地 UM* 提交中的每个子模块更新都引入了本地提交中的子项目树。L*1 提交中的树表示来自上游的合并。这些导致从 U* 提交到其对应的重写 L*1 提交的边。L*2 提交未进行任何来自上游的合并。

请注意，从 U2 到 Lclang1 的合并看起来是多余的，但是，例如，如果 U3 更改了上游 clang 中的某些文件，则在 Llld1 提交之后出现的 Lclang1 提交实际上将表示更早上游 clang 历史记录中的 clang 树。我们希望 local/zip 分支准确地表示我们的 umbrella 历史记录的状态，因此边 U2 -> Lclang1 是 clang 树在 Lclang1 中实际外观的视觉提示。

即便如此，边 U3 -> Llld1 对于未来从上游合并可能会有问题。git 会认为我们已经从 U3 合并，而我们已经合并了，除了 clang 树的状态。一种可能的缓解策略是手动比较 U2 和 U3 之间的 clang，并将这些更新应用于 local/zip。另一种可能更简单的策略是冻结下游分支上的本地工作，并在运行 zip-downstream-fork.py 之前从最新的上游合并所有子模块。如果下游以锁步方式从上游合并每个项目，而没有任何中间本地提交，那么一切都应该没问题，而无需任何特殊操作。我们预计这将是常见情况。

clang 之外的 Lclang1 的树将表示 U3 的状态，因为所有未参与 umbrella 历史记录的上游项目都应处于尊重提交 U3 的状态。Lllvm1 和 Llld1 的树应分别正确表示提交 Lllvm1 和 Llld1。

提交 UM3 更改了与子模块无关的文件，我们需要将它们放在某个地方。通常将它们放在 monorepo 根目录中是不安全的，因为它们可能与 monorepo 中的文件冲突。假设我们希望将它们放在 monorepo 中的 local 目录中。

示例 1：Umbrella 看起来像 monorepo

对于此示例，我们将假设每个子项目都以其自己的顶层目录出现在 umbrella 中，就像它们在 monorepo 中一样。我们还假设我们希望 myproj 目录中的文件出现在 local/myproj 中。

给定上述 migrate-downstream-fork.py 的运行，以下是创建压缩历史记录的配方

# Import any non-LLVM repositories the umbrella references.
git -C my-monorepo remote add localrepo \
                              https://my.local.mirror.org/localrepo.git
git fetch localrepo

subprojects=( clang clang-tools-extra compiler-rt debuginfo-tests libclc
              libcxx libcxxabi libunwind lld lldb llgo llvm openmp
              parallel-libs polly pstl )

# Import histories for upstream split projects (this was probably
# already done for the ``migrate-downstream-fork.py`` run).
for project in ${subprojects[@]}; do
  git remote add upstream/split/${project} \
                 https://github.com/llvm-mirror/${subproject}.git
  git fetch umbrella/split/${project}
done

# Import histories for downstream split projects (this was probably
# already done for the ``migrate-downstream-fork.py`` run).
for project in ${subprojects[@]}; do
  git remote add local/split/${project} \
                 https://my.local.mirror.org/${subproject}.git
  git fetch local/split/${project}
done

# Import umbrella history.
git -C my-monorepo remote add umbrella \
                              https://my.local.mirror.org/umbrella.git
git fetch umbrella

# Put myproj in local/myproj
echo "myproj local/myproj" > my-monorepo/submodule-map.txt

# Rewrite history
(
  cd my-monorepo
  zip-downstream-fork.py \
    refs/remotes/umbrella \
    --new-repo-prefix=refs/remotes/upstream/monorepo \
    --old-repo-prefix=refs/remotes/upstream/split \
    --revmap-in=monorepo-map.txt \
    --revmap-out=zip-map.txt \
    --subdir=local \
    --submodule-map=submodule-map.txt \
    --update-tags
 )

 # Create the zip branch (assuming umbrella main is wanted).
 git -C my-monorepo branch --no-track local/zip/main refs/remotes/umbrella/main

请注意，如果 umbrella 具有指向非 LLVM 仓库的子模块，则 zip-downstream-fork.py 需要知道它们才能重写提交。这就是为什么上面的第一步是从此类仓库中获取提交。

使用 --update-tags，该工具将迁移指向已内联到压缩历史记录中的子模块提交的带注释的标签。如果 umbrella 拉入了一个碰巧具有指向它的标签的上游提交，则该标签将被迁移，这几乎肯定不是想要的。标签始终可以在重写后移回其原始提交，或者可以丢弃 --update-tags 选项，然后手动迁移任何本地标签。

示例 2：嵌套源布局

该工具处理嵌套子模块（例如，llvm 是 umbrella 中的子模块，而 clang 是 llvm 中的子模块）。文件 submodule-map.txt 是成对列表，每行一对。第一对项目描述了 umbrella 仓库中子模块的路径。第二对项目描述了应在压缩历史记录中写入该子模块的树的路径。

假设您的 umbrella 仓库实际上是 llvm 仓库，并且它在 “嵌套源” 布局中具有子模块（clang 在 tools/clang 中，等等）。还假设 projects/myproj 是指向某些下游仓库的子模块。子模块映射文件应如下所示（我们仍然希望 myproj 以与以前相同的方式映射）

tools/clang clang
tools/clang/tools/extra clang-tools-extra
projects/compiler-rt compiler-rt
projects/debuginfo-tests debuginfo-tests
projects/libclc libclc
projects/libcxx libcxx
projects/libcxxabi libcxxabi
projects/libunwind libunwind
tools/lld lld
tools/lldb lldb
projects/openmp openmp
tools/polly polly
projects/myproj local/myproj

如果子模块路径未出现在映射中，则该工具假定应将其放置在 monorepo 中的相同位置。这意味着如果您在 umrella 中使用 “嵌套源” 布局，则必须为 umbrella 中的所有项目（llvm 除外）提供映射条目。否则，来自子模块更新的树将出现在 zippped 历史记录中的 llvm 下方。

由于 llvm 本身就是 umbrella，因此我们使用 –subdir 将其内容写入 zippped 历史记录中的 llvm 中

# Import any non-LLVM repositories the umbrella references.
git -C my-monorepo remote add localrepo \
                              https://my.local.mirror.org/localrepo.git
git fetch localrepo

subprojects=( clang clang-tools-extra compiler-rt debuginfo-tests libclc
              libcxx libcxxabi libunwind lld lldb llgo llvm openmp
              parallel-libs polly pstl )

# Import histories for upstream split projects (this was probably
# already done for the ``migrate-downstream-fork.py`` run).
for project in ${subprojects[@]}; do
  git remote add upstream/split/${project} \
                 https://github.com/llvm-mirror/${subproject}.git
  git fetch umbrella/split/${project}
done

# Import histories for downstream split projects (this was probably
# already done for the ``migrate-downstream-fork.py`` run).
for project in ${subprojects[@]}; do
  git remote add local/split/${project} \
                 https://my.local.mirror.org/${subproject}.git
  git fetch local/split/${project}
done

# Import umbrella history.  We want this under a different refspec
# so zip-downstream-fork.py knows what it is.
git -C my-monorepo remote add umbrella \
                               https://my.local.mirror.org/llvm.git
git fetch umbrella

# Create the submodule map.
echo "tools/clang clang" > my-monorepo/submodule-map.txt
echo "tools/clang/tools/extra clang-tools-extra" >> my-monorepo/submodule-map.txt
echo "projects/compiler-rt compiler-rt" >> my-monorepo/submodule-map.txt
echo "projects/debuginfo-tests debuginfo-tests" >> my-monorepo/submodule-map.txt
echo "projects/libclc libclc" >> my-monorepo/submodule-map.txt
echo "projects/libcxx libcxx" >> my-monorepo/submodule-map.txt
echo "projects/libcxxabi libcxxabi" >> my-monorepo/submodule-map.txt
echo "projects/libunwind libunwind" >> my-monorepo/submodule-map.txt
echo "tools/lld lld" >> my-monorepo/submodule-map.txt
echo "tools/lldb lldb" >> my-monorepo/submodule-map.txt
echo "projects/openmp openmp" >> my-monorepo/submodule-map.txt
echo "tools/polly polly" >> my-monorepo/submodule-map.txt
echo "projects/myproj local/myproj" >> my-monorepo/submodule-map.txt

# Rewrite history
(
  cd my-monorepo
  zip-downstream-fork.py \
    refs/remotes/umbrella \
    --new-repo-prefix=refs/remotes/upstream/monorepo \
    --old-repo-prefix=refs/remotes/upstream/split \
    --revmap-in=monorepo-map.txt \
    --revmap-out=zip-map.txt \
    --subdir=llvm \
    --submodule-map=submodule-map.txt \
    --update-tags
 )

 # Create the zip branch (assuming umbrella main is wanted).
 git -C my-monorepo branch --no-track local/zip/main refs/remotes/umbrella/main

zip-downstream-fork.py 顶部的注释更详细地描述了该工具的工作原理及其操作的各种含义。

导入本地仓库¶

您可能还有其他与 LLVM 生态系统集成的仓库，本质上是使用新工具扩展它。如果此类仓库与 LLVM 紧密耦合，则将其导入到 monorepo 的本地镜像中可能是有意义的。

如果此类仓库参与了上面压缩过程中使用的 umbrella 仓库，则它们将自动添加到 monorepo 中。对于不参与 umbrella 设置的下游仓库，https://github.com/greened/llvm-git-migration/tree/import 中的 import-downstream-repo.py 工具可以帮助将它们放入 monorepo 中。以下是一个配方

# Import downstream repo history into the monorepo.
git -C my-monorepo remote add myrepo https://my.local.mirror.org/myrepo.git
git fetch myrepo

my_local_tags=( refs/tags/release
                refs/tags/hotfix )

(
  cd my-monorepo
  import-downstream-repo.py \
    refs/remotes/myrepo \
    ${my_local_tags[@]} \
    --new-repo-prefix=refs/remotes/upstream/monorepo \
    --subdir=myrepo \
    --tag-prefix="myrepo-"
 )

 # Preserve release branches.
 for ref in $(git -C my-monorepo for-each-ref --format="%(refname)" \
                refs/remotes/myrepo/release); do
   branch=${ref#refs/remotes/myrepo/}
   git -C my-monorepo branch --no-track myrepo/${branch} ${ref}
 done

 # Preserve main.
 git -C my-monorepo branch --no-track myrepo/main refs/remotes/myrepo/main

 # Merge main.
 git -C my-monorepo checkout local/zip/main  # Or local/octopus/main
 git -C my-monorepo merge myrepo/main

您可能想要合并其他相应的分支，例如 myrepo 发行分支，如果它们与 LLVM 项目发行版同步的话。

--tag-prefix 告诉 import-downstream-repo.py 使用给定的前缀重命名带注释的标签。由于 fast_filter_branch.py 的限制，无法重命名未注释的标签（fast_filter_branch.py 将它们视为分支，而不是标签）。由于上游 monorepo 的标签已使用 “llvmorg-” 前缀重写，因此名称冲突不应成为问题。--tag-prefix 可用于更清楚地指示哪些标签对应于各种导入的仓库。

给定此仓库历史记录

R1 - R2 - R3 <- main
     ^
     |
  release/1

上面的配方导致如下历史记录

U1 - U2 - U3 <- upstream/main
 \    \    \
  \    -----\---------------                                         local/zip--.
   \         \              \                                                    |
  - Lllvm1 - Llld1 - UM3 -  Lclang1 - Lclang2 - Lllvm2 - Llld2 - Lmyproj1 - M1 <-'
                                                                           /
                                                               R1 - R2 - R3  <-.
                                                                    ^           |
                                                                    |           |
                                                             myrepo-release/1   |
                                                                                |
                                                                   myrepo/main--'

提交 R1、R2 和 R3 的树仅包含来自 myrepo 的 blobs。如果需要将来自 myrepo 的提交与本地项目分支上的提交交错（例如，与上面的 llvm1、llvm2 等交错），并且 myrepo 未出现在伞形仓库中，则需要开发一个新工具。创建这样一个工具将涉及

修改 fast_filter_branch.py 以选择性地直接接受修订列表，而不是自己生成
创建一个工具，根据某些标准生成本地提交的交错顺序（zip-downstream-fork.py 使用伞形历史作为其标准）
生成这样的顺序并将其作为修订列表提供给 fast_filter_branch.py

可能还需要注意处理合并提交，以确保此类提交的父项正确迁移。

清理本地单体仓库¶

一旦完成所有迁移、压缩和导入，就该清理了。python 工具使用 git-fast-import，它会留下很多垃圾，我们希望尽可能缩小新的单体仓库镜像。这是一种方法：

git -C my-monorepo checkout main

# Delete branches we no longer need.  Do this for any other branches
# you merged above.
git -C my-monorepo branch -D local/zip/main || true
git -C my-monorepo branch -D local/octopus/main || true

# Remove remotes.
git -C my-monorepo remote remove upstream/monorepo

for p in ${my_projects[@]}; do
  git -C my-monorepo remote remove upstream/split/${p}
  git -C my-monorepo remote remove local/split/${p}
done

git -C my-monorepo remote remove localrepo
git -C my-monorepo remote remove umbrella
git -C my-monorepo remote remove myrepo

# Add anything else here you don't need.  refs/tags/release is
# listed below assuming tags have been rewritten with a local prefix.
# If not, remove it from this list.
refs_to_clean=(
  refs/original
  refs/remotes
  refs/tags/backups
  refs/tags/release
)

git -C my-monorepo for-each-ref --format="%(refname)" ${refs_to_clean[@]} |
  xargs -n1 --no-run-if-empty git -C my-monorepo update-ref -d

git -C my-monorepo reflog expire --all --expire=now

# fast_filter_branch.py might have gc running in the background.
while ! git -C my-monorepo \
  -c gc.reflogExpire=0 \
  -c gc.reflogExpireUnreachable=0 \
  -c gc.rerereresolved=0 \
  -c gc.rerereunresolved=0 \
  -c gc.pruneExpire=now \
  gc --prune=now; do
  continue
done

# Takes a LOOOONG time!
git -C my-monorepo repack -A -d -f --depth=250 --window=250

git -C my-monorepo prune-packed
git -C my-monorepo prune

现在您应该有一个精简的单体仓库。将其上传到您的 git 服务器，祝您编程愉快！

参考¶

[LattnerRevNum]

Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2011-July/041739.html

[TrickRevNum]

Andrew Trick, http://lists.llvm.org/pipermail/llvm-dev/2011-July/041721.html

[JSonnRevNum]

Joerg Sonnenberger, http://lists.llvm.org/pipermail/llvm-dev/2011-July/041688.html

[MatthewsRevNum] (1,2)

Chris Matthews, http://lists.llvm.org/pipermail/cfe-dev/2016-July/049886.html

[statuschecks]

GitHub 状态检查, https://help.github.com/articles/about-required-status-checks/