git 快速将 Git 仓库迁移至其他平台

前言

在项目开发或重构过程中，我们有时需要将代码仓库从一个平台（如 GitHub）迁移到另一个平台（如自建的 GitLab）。最近就遇到这样的需求，因此整理了一下迁移的相关知识。

准备工作：创建新仓库

在开始迁移之前，你需要在目标平台（例如 GitLab）上创建一个空仓库。

1. 仓库命名：建议新仓库的名称与旧仓库保持一致，例如 my-project。
2. 保持纯净：创建仓库时，请勿初始化任何文件。不要勾选创建 README.md、.gitignore 或 LICENSE 等选项。一个完全空的仓库是迁移成功的前提，可以避免后续推送时产生不必要的合并冲突。

迁移教程

我们提供两种迁移方法，你可以根据实际需求选择。

方法一：常规 Push 迁移（灵活但操作繁琐）

这种方法比较直观，适合只需要迁移部分特定分支，或者不关心历史标签（Tag）的简单场景。它赋予你完全的控制权，但操作步骤也相对较多。

第一步：克隆原始仓库到本地

如果本地还没有仓库副本，先从原始仓库克隆一份：

git clone <旧仓库地址>
cd my-project

核心概念：当你 clone 一个仓库时，默认只会在本地创建一个 main 或 master 分支。其他所有远程分支（如 develop, feature-x）仅作为“远程跟踪分支”（如 origin/develop, origin/feature-x）存在于你的本地数据库中，你必须先将它们“检出”（checkout）才能变成可操作的本地分支。

第二步：添加新的远程仓库地址

为本地仓库添加一个指向新平台的远程地址。我们将其命名为 new_origin。

git remote add new_origin https://gitlab.example.com/your-group/my-project.git

你可以通过 git remote -v 命令检查是否添加成功。

第三步：推送分支到新仓库

你有两种方式推送分支，但都基于一个前提：必须先确保要推送的分支在本地存在。

选项 A：逐一推送指定分支（精准控制）

这是最推荐的、最清晰的迁移方式。

1. 检出分支：如果要推送的分支（如 develop）在本地不存在，必须先 checkout 来创建它。

   # Git 会自动根据远程的 origin/develop 创建一个本地的 develop 分支
   git checkout develop

2. 推送分支：将创建好的本地分支推送到新仓库。

   # 格式: git push <新远程名称> <本地分支名>
   git push new_origin develop

你需要对每个想迁移的分支重复以上 “检出 -> 推送” 的步骤。对于默认存在的 main 分支，则可以直接推送：

git push new_origin main

选项 B：一次性推送所有本地分支（批量操作）

如果你想将所有远程分支都迁移过去，可以这样做：

1. 检出所有分支：你必须先把所有远程分支都在本地创建一遍。可以写个脚本，或者手动一个个 git checkout <分支名>。

2. 批量推送：当所有分支都在本地存在后，使用 --all 一次性推送它们。

   git push new_origin --all

   ⚠️ 警告：此方法操作繁琐且极易遗漏，因为你必须手动确保所有分支都已在本地创建。它只推送本地存在的分支。

第四步：推送所有标签

无论你使用选项 A 还是 B，标签（Tags）都需要单独推送。如果你的项目有版本标签，请务必执行此步骤。

git push new_origin --tags

小结：此方法非常灵活，但操作繁琐，特别是需要手动创建本地分支，容易出错和遗漏。

方法二：使用 --mirror 进行完整镜像迁移（强烈推荐）

这是最专业、最推荐的迁移方法。它能将原始仓库的所有内容，包括全部分支（无论本地是否存在）、全部标签和所有 Git 内部对象，一次性、原封不动地复制到新仓库，实现真正的“像素级”迁移。

第一步：以镜像模式克隆原始仓库

使用 git clone --mirror 命令，这会创建一个“裸仓库”（Bare Repository），它直接包含了所有远程分支和标签的引用，没有工作目录。

# git clone --mirror <旧仓库地址>
git clone --mirror https://github.com/user/my-project.git

执行后，你会得到一个名为 my-project.git 的目录。

第二步：进入裸仓库目录

cd my-project.git

第三步：以镜像模式推送到新仓库

这是最关键的一步。使用 git push --mirror 命令，将所有内容推送到新仓库。

# git push --mirror <新仓库地址>
git push --mirror https://gitlab.example.com/your-group/my-project.git

命令执行完毕，迁移就完成了！这个命令会自动处理所有分支和标签，无需手动干预。

第四步：清理临时文件

迁移完成后，本地的裸仓库目录就可以删除了。

cd ..
rm -rf my-project.git

windows 系统则直接右键删除目录即可。

总结

总而言之，如果你只想迁移一两个分支，可以使用方法一。对于绝大多数完整的项目迁移场景，请毫不犹豫地使用 方法二 (--mirror)，它更快速、更安全、更完整。

迁移完成后，建议团队成员删除旧的本地仓库，重新从新平台 clone 最新的代码，以避免混淆。