Git仓库完整迁移到GitHub的实践指南-三亩地-编程学习日记

1. 项目背景与核心需求

作为开发者，我们经常面临代码仓库迁移的需求。最近我就遇到了一个典型场景：需要将自建的Git服务（如Gitea/GitLab）中的项目完整迁移到GitHub SaaS平台。这种迁移不仅涉及代码本身，还包括所有分支、标签和提交历史。

迁移的主要动机通常包括：

利用GitHub更完善的CI/CD生态
需要与开源社区更紧密协作
企业内部代码管理策略调整
减少自建Git服务的维护成本

2. 迁移前的准备工作

2.1 环境检查与工具准备

在开始迁移前，需要确保：

本地已安装Git客户端（建议版本2.30+）
拥有源仓库的管理员权限
在GitHub上已创建目标组织/账号
网络连接稳定（特别是大仓库需要良好带宽）

提示：对于超过1GB的大型仓库，建议在非高峰时段操作，并准备好重试机制。

2.2 源仓库分析

使用以下命令检查源仓库状态：

git count-objects -vH # 查看仓库体积 git branch -a # 查看所有分支 git tag # 查看所有标签 git remote -v # 查看远程配置

3. 完整迁移步骤详解

3.1 创建裸仓库克隆

这是保证完整迁移的关键第一步：

git clone --bare https://your-git-server.com/user/repo.git cd repo.git

--bare参数会创建一个不包含工作目录的纯仓库副本，包含所有历史数据但体积更小。

3.2 在GitHub创建目标仓库

登录GitHub网页端
点击"+ New repository"
输入与源仓库相同的名称（推荐）
选择公开/私有设置
不要初始化README/.gitignore（避免冲突）

3.3 镜像推送至GitHub

在本地裸仓库目录执行：

git push --mirror https://github.com/user/new-repo.git

--mirror参数会推送：

所有分支（包括隐藏的）
所有标签
所有引用和配置
完整的提交历史

3.4 验证迁移完整性

推送完成后，进行以下检查：

分支数量是否匹配：
```
git ls-remote --heads origin | wc -l
```
提交历史是否完整：
```
git log --oneline | wc -l
```
检查最近提交的SHA值是否一致

4. 高级场景处理

4.1 大型仓库迁移优化

对于超过5GB的仓库：

使用浅克隆减少初始传输量：

git clone --bare --depth=1 https://source/repo.git

分批次获取完整历史：
```
git fetch --unshallow
```
使用SSH协议提高传输稳定性

4.2 LFS文件迁移

如果仓库包含Git LFS文件：

确保已安装git-lfs
在源仓库执行：
```
git lfs fetch --all
```
推送后验证LFS文件：
```
git lfs ls-files
```

4.3 权限与协作设置

迁移后需要：

设置团队访问权限
配置分支保护规则
转移issue和PR（需使用GitHub API或第三方工具）
更新CI/CD流水线中的仓库地址

5. 常见问题与解决方案

问题现象	可能原因	解决方案
推送时报错"remote: Permission denied"	认证失败	检查PAT令牌或SSH密钥配置
部分分支缺失	非标准分支名	使用`git show-ref`检查所有引用
历史提交显示不同	邮箱映射问题	配置`.mailmap`文件统一提交者信息
推送速度极慢	网络限制	尝试更换SSH协议或使用GitHub CLI
LFS文件显示指针	LFS未正确推送	重新执行`git lfs push --all`

6. 迁移后的优化建议

更新本地克隆的远程地址：

git remote set-url origin https://github.com/user/repo.git

清理旧的远程分支引用：
```
git remote prune origin
```
设置GitHub Actions自动同步（如需保留源仓库）
在README中添加迁移说明

我在实际迁移中发现，对于包含子模块的仓库，需要额外执行：

git submodule update --init --recursive cd submodule_dir git push --mirror new-submodule-url

7. 替代方案比较

除了--mirror方法，还有其他迁移方式：

GitHub导入工具：
- 优点：网页操作简单
- 缺点：不支持私有仓库的完整历史
手动分支推送：
```
git push origin branch1 branch2 git push --tags
```
- 优点：选择性迁移
- 缺点：容易遗漏内容
第三方迁移工具：
- 如git-mirror等专用工具
- 适合企业级批量迁移

对于大多数场景，--mirror方法仍然是保留完整Git历史的最可靠选择。

日记详情

Git仓库完整迁移到GitHub的实践指南