如何用 Git 合并两个库（合并历史记录，解决冲突／改写路径）

本来已经不写文字博客了，一般心得都录成了视频（这在我看来是更好的方式），但是今天遇到一个关于 Git 的问题不太好重现也不便于录制视频，加上它本身很具有代表性也很有用，所以还是记录于此。

背景

一个中型规模项目，开始规划时就打算采用 C/S 架构，后端是单纯的 API 服务，前端在 Web 上搞一个 SPA，之后再搞其他端也就顺理成章了。只可以第一次弄没经验，有些细节最初没有考虑到。

创建项目的时候前后端真是完全分离的，分成了两个目录，创建了两个 repos。一开始只有一个人干的时候倒也没什么，开两个窗口切来切去也就罢了，后来一是部署起来麻烦，二来主要是其他开发者加入后，代码的版本管理、提交、合并、审核等等等等都变得越来越繁琐。

后来一想：架构上分离而已，干嘛非要两个目录两个 repos？真是自找麻烦！于是就开始考虑整合。

要求

把两个目录并成一个倒不难，但是要完整保留双方的历史记录就有些麻烦了，这也是唯一一个必须要实现的目标。

过程

首先为了便于描述，约定整合前两个目录分别叫做 frontend 和 backend，合并后的结构与名称应当如下：

- project/                  => 即最开始的 frontend，整合完后更名
  - .gitignore              => 合并两个 repos 的忽略文件
  - .git/                   => 最终仅余一个 repo
  + client/                 => 对应 frontend
  + server/                 => 对应 backend

以下步骤是以 frontend 为基点，把 backend 移进来，实际上反过来也是一样的，自行替换对应的名称即可。在开始之前先清理两个 repos 里的工作记录，该提交的提交，该备份的备份，保持干净。

1. $ [~] cd frontend
2. $ [frontend] git remote add -f backend /fullpath/to/backend
3. $ [frontend] git merge --strategy ours --no-commit backend/master
4. $ [frontend] mkdir -p server
5. $ [frontend] git read-tree --prefix=server/ -u backend/master
6. $ [frontend] git commit --message '完成 backend 的迁移，新目录为 server'
7. $ [frontend] mkdir -p client
8. # 拷贝 frontend 的原始项目文件（除了 .git/ 和 .gitignore 以外）至 client/
9. $ [frontend] cd ..; mv frontend/ project/; cd project
10. $ [project] cat server/.gitignore >> .gitignore
11. # 整理合并后的 .gitignore，修复其中的路径缺失并保存；修复各种项目依赖的缺失，本地测试。
12. $ [project] git add --all; git commit --message '迁移整合完成！'

以上是完整的步骤先列出来方便参考，下面做一个详细的解释。

整个过程中主要用到的工具是 merge 和 read-tree，前者用于合并历史记录并且中断在最后提交之前，所产生的文件冲突不会被写入硬盘；然后利用后者重写整个文件树并把读取到的内容（读取的目标是 backend）写入新的路径下。最后提交以结束合并。

第2步里，我们把 backend 作为 remote server 添加到 frontend 库中。-f 的作用是在添加后立刻 fetch。要注意一定得使用绝对路径来引用 backend 库。

第3步里，--strategy ours 比较难以理解，且听我详细道来：一般来说当合并两个文件树时，如果遇到冲突我们是需要手动去解决它的，但是目前我们要做的不是解决冲突，而是在引入 backend 历史记录的前提下完整保留 frontend 的内容。冲突肯定是会有的，即使两个不同的项目也是如此，比方说两边都有 README.md、app/、config/ 等文件或目录，但是我们不关心冲突，我们只要保留 frontend 的文件树并且把 backend 的历史记录合并进来。

--strategy ours 会完成全部的合并解析，但是所有的冲突都以“我”为准，不允许外来的冲突覆盖“我”的文件内容。最终的结果就是：

1. backend 的历史记录被合并到 frontend 的历史记录中
2. backend 的文件树被读取并和 frontend 的文件树比对进行冲突解析：
   
   
   • 如果发现冲突，以 frontend 为准，丢弃所有内容变更
   • 没冲突的则保留（但是我们也不要的，见后面的内容）

这也是后面紧接着使用 --no-commit 的原因，该选项会在合并解析完成后中断，停留在最后的提交步骤之前。我们知道，只要你还没 commit，那么 merge 的结果就暂时保存在缓存区中，只有完成提交步骤合并才算彻底完成（文件树被正式改变）。这就给我们一个机会来重新读取 backend 的文件树，并改写其保存的位置。不过在此之前，第4步先要创建目标子目录（很重要！）。

第5步开始 read-tree 了，--prefix 用于指定文件树读取后保存的路径，相对于当前路径并且一定要追加 /。-u 是说在读取后更新 index，使得 working tree 与 index 保持同步。如果你不小心忘了加 -u，可以在这一步之后执行 git add --update，一样的效果。

这一步在背后有些细节比较抽象，之前的 merge 也曾读取过 backend 的文件树，但经过冲突解析之后已经面目全非，分析如下：

• 有冲突的被丢弃，因此一部分文件／目录其实已经不存在了
• 没冲突的被保留，但是路径还在 frontend 的根路径下

经过再次 read-tree，上面的“遗迹”得以修复，结果如下：

• 有冲突的因为已被丢弃，所以直接从本次读取中获得，且路径前面追加 --prefix 选项的值
• 没冲突的虽然被保留，但是由于本次读取追加了 prefix，所以它们的路径也被改变，相当于在缓存里做了一次 git mv

好了，重点就是这些，之后的步骤都很寻常，只要小心操作就没什么难理解的。