Git 托管平台间迁移

学完这篇你会掌握什么

• 理解 Git 托管平台间迁移 的核心作用和适用场景
• 掌握 Git 托管平台间迁移 的基本用法和常用参数
• 在 GitHub、GitLab、Bitbucket 等 Git 托管平台之间迁移仓库，保留完整提交历史和所有引用。
• 理解 概述 相关的概念
• 掌握 核心迁移方式 相关的操作
• 知道在什么场景下使用该命令，什么场景下避免使用

先想一个问题

你的团队正在从其他版本控制系统迁移到 Git，或者需要在不同 Git 平台之间迁移代码和历史。你担心迁移过程中会不会丢失提交记录或作者信息。

概述

在不同 Git 托管平台之间迁移仓库的核心原理是一样的——因为底层都是 Git。迁移的关键在于完整搬运所有引用（分支、标签、PR/MR 元数据）。

核心迁移方式

方式一：裸仓库镜像（推荐）

# 1. 从源平台制作裸镜像
git clone --mirror https://github.com/old-org/repo.git
cd repo.git

# 2. 推送到目标平台
git remote set-url origin https://gitlab.com/new-org/repo.git
git push --mirror origin

# 3. 验证
git log --oneline --all  # 确认所有引用都在

--mirror 会克隆所有引用（包括分支、标签、notes 等），是保留最完整的方式。

方式二：直接推送

# 如果已有完整的本地仓库，直接推送
git remote add new-origin https://gitlab.com/new-org/repo.git
git push --all new-origin       # 推送所有分支
git push --tags new-origin      # 推送所有标签

方式三：多平台同步（长期）

# 配置多 remote 实现自动同步
git remote add github https://github.com/org/repo.git
git remote add gitlab https://gitlab.com/org/repo.git
git remote add bitbucket https://bitbucket.org/org/repo.git

# 推送到所有远端
git push --all github
git push --all gitlab
git push --all bitbucket

迁移 PR / Merge Request

PR/MR 是平台级的元数据，不属于 Git 对象，不能通过 git push --mirror 搬运。

GitHub → GitHub

# 使用 GitHub 官方迁移工具
gh repo migrate <source-repo> --target-owner <target-org>

GitHub → GitLab

1. 在 GitLab 创建新项目
2. 选择 Import project → GitHub
3. 授权 GitLab 访问 GitHub
4. 选择要导入的仓库

GitLab → GitHub

1. 在 GitHub 导入仓库：+ → Import repository
2. 输入 GitLab 仓库的 Git URL
3. GitHub 会自动导入历史

元数据迁移对照

迁移后检查清单

# 1. 验证引用完整性
git for-each-ref --format='%(refname)' | sort

# 2. 检查关键分支
git branch -a

# 3. 验证标签
git tag -l

# 4. 确认本地仓库已关联新的远端
git remote -v

继续学习

1. migration/svn-to-git — SVN 迁移到 Git
2. migration/hg-to-git — Mercurial 迁移到 Git
3. hosting/platform-comparison — 托管平台对比

给你的练习

1. 在一个测试仓库中练习该命令的基本用法，观察执行前后的状态变化
2. 尝试该命令的不同参数选项，对比输出结果的差异
3. 模拟一个需要使用该命令的实际场景，完整走一遍操作流程

延伸阅读

沿着同一主题继续深入：

• Mercurial 到 Git 迁移指南
• 代码仓库迁移策略指南
• SVN 到 Git 迁移指南