如何合并两个独立的 Git 仓库（Monorepo 实践）

(Updated: )
git
, ,

本文是一份将两个完全独立、无关联历史的 Git 仓库合并到一个新仓库（Monorepo）的完整操作指南。我们将把每个旧仓库的内容及其完整提交历史，迁移到新仓库的不同子目录中。

核心思路

我们的目标是创建一个全新的仓库 sushang-combined，并将 sushang-v1 和 sushang-v2 两个仓库的所有内容和历史记录，分别完整地移入 sushang-combined 下的 sushang-v1/ 和 sushang-v2/ 子目录中。

第一阶段：环境准备

首先，创建工作区，并克隆所有需要的仓库。

1
2
3
4
5
6
7
8
9
10
11
# 1. 创建一个专门的工作目录
mkdir git-merge-project && cd git-merge-project

# 2. 克隆你的两个源仓库 (请替换为你的实际URL)
git clone <URL_for_sushang-v1>
git clone <URL_for_sushang-v2>

# 3. 创建并初始化最终要合并到的目标仓库
mkdir sushang-combined
cd sushang-combined
git init

第二阶段：重构源仓库

此阶段是关键。我们需要在每个源仓库中，将所有文件移入一个与仓库同名的子目录。这个过程需要对 sushang-v1 和 sushang-v2 分别执行一次。

下面以 sushang-v1 为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 1. 进入 sushang-v1 的本地克隆目录
cd ../sushang-v1

# 2. 创建子目录
mkdir sushang-v1

# 3. 将所有文件和目录移动到新子目录中
# 使用 git mv 至关重要，它能让 Git 追踪文件移动，保留历史记录！
# -k 标志会忽略移动过程中可能出现的无关紧要的错误
git mv -k * sushang-v1/

# 4. 单独处理以点开头的隐藏文件（如 .gitignore, .github 等）
git mv .gitignore sushang-v1/

# 5. 提交这次结构调整
git commit -m "chore: Restructure repository for monorepo merge"

请返回上一级目录，对 sushang-v2 仓库重复上述 1-5 步。

第三阶段：执行合并

现在，所有准备工作就绪，可以开始真正的合并操作。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 1. 返回合并目标仓库
cd ../sushang-combined

# 2. 合并 sushang-v1
#    将本地重构后的 sushang-v1 仓库添加为名为 v1 的远程源
git remote add v1 ../sushang-v1
#    从 v1 拉取所有历史数据
git fetch v1
#    合并 v1 的主分支，--allow-unrelated-histories 是关键！
git merge v1/main --allow-unrelated-histories -m "feat: Merge sushang-v1 history"

# 3. 合并 sushang-v2
#    以同样的方式添加并合并 v2
git remote add v2 ../sushang-v2
git fetch v2
git merge v2/main --allow-unrelated-histories -m "feat: Merge sushang-v2 history"

# 4. 验证结果
#    执行 ls，应能看到 sushang-v1 和 sushang-v2 两个目录
#    执行 git log --graph --oneline --all 查看合并后的历史图谱
ls -la

第四阶段：发布到 GitHub

将本地合并好的新仓库推送到远程。

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 在 GitHub 上创建一个新的、空的仓库，例如 sushang-combined

# 2. 在本地 sushang-combined 目录中，关联到你刚创建的远程仓库
git remote add origin <URL_for_new_github_repo>

# 3. 将本地的完整历史推送到 GitHub
#    -u 选项会建立本地 main 分支与远程 origin/main 分支的追踪关系
git push -u origin main

# 4. (可选) 清理本地的临时远程源
git remote rm v1
git remote rm v2

第五阶段：归档旧仓库

为了避免混淆，并完整保留 Issues、Pull Requests 等宝贵信息，最佳实践是归档（Archive）而不是删除旧仓库。

对 sushang-v1 和 sushang-v2 在 GitHub 上的仓库，分别执行以下操作：

  1. 更新仓库描述：在仓库主页点击 “Edit”，修改描述，明确指出项目已归档，并提供新仓库 sushang-combined 的链接。例如：“**[ARCHIVED]** Development continues at [link to sushang-combined].”
  2. 更新 README：在 README.md 文件顶部添加醒目通知，引导访问者前往新仓库。
  3. 执行归档：
    • 进入仓库的 Settings 页面。
    • 滚动到底部的 Danger Zone（危险区域）。
    • 点击 Archive this repository（归档此仓库）。
    • 按提示输入仓库名称进行确认。

至此，您已成功将两个独立仓库完整地合并为一个，并完成了所有后续整理工作。