1. 项目概述：为什么“仓库迁移”不是简单的复制粘贴？
干了这么多年开发，团队合并、项目重构、代码资产转移，这些事儿几乎每隔一阵子就会遇到。最近又帮一个团队做了一次完整的Git仓库迁移，从老旧的内部GitLab迁到新的云托管平台。听起来就是把代码从一个地方搬到另一个地方，对吧？但如果你真把它当成“复制-粘贴”来操作，那踩坑的几率几乎是百分之百。权限丢失、提交历史断裂、分支混乱、子模块失效……任何一个环节出问题，都够你折腾半天。
所以，今天我想系统性地聊聊“从一个Git仓库迁移到另一个Git仓库”这件事。它远不止是几条git命令的堆砌，而是一个需要明确目标、评估现状、选择策略并谨慎执行的系统工程。无论你是要将个人项目从GitHub搬到Gitee，还是公司内部进行代码平台的统一迁移，这篇文章里总结的步骤、踩过的坑和验证方法，应该都能给你提供一个清晰的路线图。我们不仅要“搬过去”，更要“搬得完整、搬得正确、搬得可追溯”。
2. 迁移前的核心评估与策略选择
在动手敲下任何命令之前，冷静下来做一次全面的评估，是避免后续灾难的关键。迁移不是目的，安全、完整、可用的迁移才是。
2.1 评估源仓库：你到底拥有什么？
首先，你得像盘点仓库一样，彻底搞清楚你要迁移的“资产”清单。
- 提交历史（Commit History）：这是版本控制的灵魂。使用
git log --oneline --all --graph可以直观地看到所有分支的提交图谱。你需要确认历史是否完整、线性，有没有需要清理的混乱合并记录。 - 分支（Branches）：除了默认的
main或master，还有哪些活跃分支、特性分支、发布分支？用git branch -a查看所有本地和远程跟踪分支。特别要注意那些只有远程存在而本地未检出的分支。 - 标签（Tags）：发布版本标签是重要的里程碑。使用
git tag -l列出所有标签。区分轻量标签（lightweight）和附注标签（annotated），后者包含更多元信息，迁移时必须保留。 - 子模块（Submodules）：如果项目使用了子模块，那复杂度直接升级。你需要检查
.gitmodules文件，并确认每个子模块指向的仓库地址和提交ID。 - 大文件与LFS：仓库里是否有被错误提交的大文件（如图片、视频、压缩包）？是否已经使用了Git LFS（大文件存储）？用
git lfs ls-files或查找大文件的命令（如git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print substr($0,6)}' | sort --numeric-sort --key=2 | tail -10）来评估。 - 钩子与配置（Hooks & Config）：自定义的Git钩子（
.git/hooks/）和特殊的仓库配置（.git/config）通常不随代码迁移，但你需要知道它们的存在，因为可能影响到工作流。
注意：评估时，最好克隆一份源仓库的裸副本（
git clone --mirror <源仓库URL>）到本地一个临时目录进行操作。这样既能获取完整数据，又不会影响源仓库的正常使用。
2.2 明确迁移目标：你要搬到哪？怎么搬？
评估完资产，就要规划目的地和路线。
- 目标平台选择：是GitHub、GitLab、Gitee，还是内部搭建的Gitea？不同平台对仓库大小、LFS支持、API接口和权限模型有不同限制，需提前了解。
- 迁移策略选择：这是核心决策点。
- 镜像迁移（Mirror）：保留一切，包括所有分支、标签、提交历史。这是最彻底、最常用的方式，适用于大多数场景。使用
--mirror参数。 - 浅层迁移：只迁移最近的一部分历史（如最近100次提交）。适用于历史极其庞大、只想保留近期有效历史的仓库。使用
--depth参数。慎用，因为这会丢失早期历史，且迁移后难以补全。 - 筛选迁移：通过
git filter-repo等工具，在迁移前清理历史，比如删除误提交的大文件、敏感信息等。这属于“搬家前先断舍离”，操作复杂但能优化新仓库。
- 镜像迁移（Mirror）：保留一切，包括所有分支、标签、提交历史。这是最彻底、最常用的方式，适用于大多数场景。使用
- 权限与协作规划：目标仓库的权限如何设置？是公开、私有还是内部？团队成员如何重新授权？CI/CD流水线（如GitHub Actions、GitLab CI）的配置需要如何更新？这些非代码因素往往决定迁移后的协作效率。
2.3 工具准备与环境检查
工欲善其事，必先利其器。
- Git版本：确保你的Git是最新或较新的稳定版。一些高级功能（如
git filter-repo）可能需要新版本支持。 - 认证方式：目标仓库的访问权限准备好了吗？是HTTPS密码（可能已淘汰）、个人访问令牌（Token），还是SSH密钥？确保本地Git已配置好对应的认证信息（
git config --global credential.helper或~/.ssh/config）。 - 网络与存储空间：迁移大量历史或LFS文件需要稳定网络和足够的本地磁盘空间。对于超大仓库，考虑在服务器或网络稳定的环境中操作。
3. 标准操作流程：一步步完成镜像迁移
这里以最常见的完整镜像迁移为例，演示从旧仓库（OldRepo）到新仓库（NewRepo）的全过程。假设我们都使用SSH协议进行认证。
3.1 第一步：创建目标空仓库
首先，在你的目标平台（如GitHub）上，通过网页界面创建一个全新的、空的仓库。这一步非常重要，不要初始化README、.gitignore或License文件，确保它是一个纯粹的空白仓库。记下它的SSH地址，例如git@github.com:yourname/NewRepo.git。
3.2 第二步：本地克隆裸镜像仓库
我们不直接操作源仓库，而是先为它创建一个完整的镜像副本。打开终端，找一个临时工作目录。
# 克隆源仓库的裸镜像到本地，这会包含所有分支、标签和引用。 git clone --mirror git@old-site.com:yourname/OldRepo.git # 进入克隆下来的裸仓库目录 cd OldRepo.git这个OldRepo.git目录是一个“裸仓库”，它没有工作区（你看不到项目文件），但包含了Git数据库中的所有对象和历史，是仓库最本质的数据。
3.3 第三步：推送到目标仓库
现在，将这个完整的镜像推送到你刚刚创建的空目标仓库。
# 将本地镜像仓库的所有内容，强制推送到新的远程仓库。 git push --mirror git@github.com:yourname/NewRepo.git--mirror参数是关键，它会推送所有引用（refs）下的所有对象，包括远程跟踪分支（refs/remotes/origin/*）等。这确保了目标仓库成为源仓库的完美复制品。
操作意图解析：为什么用--mirror而不用简单的git push origin --all？因为--all只推送refs/heads下的分支，而--mirror会推送refs/下的所有内容，包括标签（refs/tags）和备注等，迁移更彻底。
3.4 第四步：验证迁移结果
推送完成后，不要急着删除旧仓库，立刻进行验证。
- 克隆验证：在一个全新的目录，克隆你刚推送的目标仓库。
git clone git@github.com:yourname/NewRepo.git cd NewRepo - 检查分支和标签：
git branch -a # 查看所有分支，应该和源仓库一致 git tag -l # 查看所有标签 - 检查提交历史：
git log --oneline --graph -10 # 查看最近的提交图谱 - 检查特定文件或提交：随机找几个历史上的关键提交ID，用
git show <commit-id>查看内容是否完整。 - 运行测试（如果项目有）：这是检验代码是否可用的最终标准。
3.5 第五步：更新本地开发环境
验证无误后，通知所有团队成员，并更新你们的本地开发环境。
- 更新远程地址：对于已经在开发此项目的成员，他们需要将本地仓库的远程地址指向新仓库。
# 进入已有的本地仓库目录 git remote -v # 查看当前远程地址，通常是 origin git remote set-url origin git@github.com:yourname/NewRepo.git git remote -v # 再次确认已更新 - 首次拉取：由于远程历史是全新的，建议先执行一次拉取。
git fetch --all # 获取所有远程分支和标签 git pull origin main # 根据你的默认分支名拉取
4. 处理特殊场景与进阶操作
标准流程能覆盖80%的场景，但剩下的20%才是真正体现经验的地方。
4.1 迁移包含子模块的仓库
如果源仓库使用了子模块，镜像迁移只会迁移子模块的引用（即.gitmodules文件和记录的提交ID），而不会迁移子模块仓库内部的代码。你需要额外处理。
推荐方案：迁移后初始化并更新子模块
- 按照标准流程完成主仓库的镜像迁移。
- 在新位置克隆主仓库后，执行：
这条命令会根据更新后的git submodule sync # 可选，确保.gitmodules中的URL对新仓库有效 git submodule update --init --recursive.gitmodules文件（如果子模块仓库地址也需要变更，你需要先修改此文件并提交），递归地初始化和拉取所有子模块的代码。
更复杂的场景：如果子模块仓库本身也需要迁移，那么你需要先递归地迁移每一个子模块仓库，然后修改主仓库中.gitmodules文件指向新的子模块地址，再提交这个更改，最后推送到新主仓库。
4.2 迁移使用Git LFS的仓库
如果仓库使用了Git LFS管理大文件，确保目标平台支持LFS（现在主流平台都支持）。镜像迁移会迁移LFS的指针文件，但LFS对象本身可能不会被--mirror推送。
安全做法：使用git lfs fetch --all和git lfs push
- 克隆裸镜像后，进入目录，先获取所有LFS对象：
git lfs fetch --all - 然后，在推送镜像时，同时推送所有LFS对象到新远程：
git lfs push --all git@github.com:yourname/NewRepo.git - 最后再执行
git push --mirror ...。
有些第三方工具或平台（如GitHub、GitLab）的导入功能能更好地处理LFS迁移，可以优先查阅目标平台的文档。
4.3 仅迁移特定分支或清理历史
有时你不想迁移所有分支，或者想清理历史中的垃圾文件。
- 迁移特定分支：不要用
--mirror，而是正常克隆后，只推送需要的分支。git clone -b main --single-branch git@old-site.com:yourname/OldRepo.git cd OldRepo git remote add new-origin git@github.com:yourname/NewRepo.git git push -u new-origin main # 推送main分支 # 如果需要推送其他分支，先git checkout切过去，再git push - 使用git filter-repo清理历史：这是一个强大但危险的工具。例如，要删除历史中所有包含
passwords.txt的文件记录：# 首先安装git-filter-repo: `pip install git-filter-repo` git clone --mirror git@old-site.com:yourname/OldRepo.git cd OldRepo.git git filter-repo --path passwords.txt --invert-paths # 清理后，再推送到新仓库 git push --mirror git@github.com:yourname/NewRepo.git警告：
git filter-repo会重写提交历史，改变所有提交的哈希值。这会导致基于旧历史的所有分支、拉取请求和协作完全断裂。仅用于尚未广泛协作的个人仓库或确定所有协作者都能重置仓库的情况。
5. 迁移后的收尾与常见问题排查
迁移完成并验证后，还有一些收尾工作，并且要知道如何排查可能出现的问题。
5.1 收尾工作清单
- 更新文档：所有项目文档、README、贡献指南中提到的仓库链接，都需要更新为新地址。
- 切换CI/CD流水线：在GitHub Actions、GitLab CI、Jenkins等配置中，更新仓库的URL和认证信息。
- 通知所有相关人员：明确告知团队、合作伙伴或社区成员，仓库已迁移，并提供新地址和更新本地仓库的指引。
- 归档或设置重定向：如果旧仓库不再使用，可以在原平台将其设置为归档（Archived）状态，或在README最顶部添加显著的重定向说明。一些平台（如GitHub）支持重定向，可以配置旧仓库URL自动跳转到新仓库。
- 观察期：保持旧仓库一段时间（如一周）的只读访问，以备不时之需。
5.2 常见问题与解决方案实录
即使准备充分，迁移过程中也可能遇到意外。以下是我遇到过的几个典型问题及解决办法。
问题1：推送时出现“远程分支已存在”错误
- 现象：
error: failed to push some refs to '...' hint: Updates were rejected because the remote contains work that you do not have locally... - 原因：目标仓库不是真正的空仓库（例如创建时勾选了初始化文件）。
- 解决：（谨慎操作）如果目标仓库可以清空，可以强制覆盖。但更推荐删除目标仓库，重新创建一个绝对空白的仓库，然后再次执行推送。或者，如果你确定要覆盖，使用
git push --mirror --force，但这会永久删除目标仓库原有的内容。
问题2：迁移后标签（Tags）不见了
- 现象：代码和分支都在，但
git tag -l显示为空。 - 原因：可能使用了
git push --all而不是git push --mirror，或者标签是附注标签但推送时未包含。 - 解决：单独推送所有标签：
git push origin --tags。确保从镜像仓库操作。
问题3：LFS文件显示为指针，无法下载
- 现象：迁移后，大文件显示为几KB的文本指针文件，内容类似
version https://git-lfs.github.com/spec/v1 oid sha256:...。 - 原因：LFS对象没有成功推送到新仓库的LFS存储中。
- 解决：进入从新仓库克隆的项目，尝试
git lfs pull。如果失败，可能需要回到镜像仓库，执行git lfs push --all <新仓库URL>来补推LFS对象。
问题4：子模块目录是空的
- 现象：迁移后，子模块目录存在，但里面是空的。
- 原因：没有初始化（init）和更新（update）子模块。
- 解决：执行
git submodule update --init --recursive。如果子模块地址也需要变更，先编辑.gitmodules文件，更新URL，提交后再执行上述命令。
问题5：历史提交者信息混乱
- 现象：迁移后，提交历史中的作者（Author）和提交者（Committer）信息是乱码或不对。
- 原因：源仓库的提交信息本身不规范，或者迁移过程中编码问题。
- 预防：迁移前可以用
git log --pretty=full检查一下历史记录。如果问题严重，可以考虑在迁移前使用git filter-repo进行邮件映射，统一修正提交者信息，但这属于历史重写，需谨慎评估。
最后，我个人最深刻的一个体会是：对于核心或大型仓库，在正式迁移前，务必在一个测试用的空仓库上完整演练一遍整个流程。这能帮你提前发现平台差异、网络问题或命令疏漏，最大程度降低对生产开发的影响。迁移本身不复杂，但周全的准备和清晰的沟通，才是保证平滑过渡的关键。