如何将外网 Git 仓库完整迁移到本地仓库并保留提交历史（附原理详解）
背景
最近在迁移第三方Git仓库到本地私有仓库时，发现了一种简单高效的方法，可以完整保留原仓库的提交日志。本文将详细解析操作步骤及其背后的Git原理，帮助开发者理解这一过程的本质。
我需要将第三方开源仓库（如GitHub仓库A，默认分支master）迁移到私有仓库（如 GitLab/Gerrit 仓库B，默认分支master）。直接克隆推送会导致：
- 历史断层：简单
git clone --depth=1会丢失历史提交 - 分支污染：同名master分支冲突导致强制覆盖风险
- 溯源困难：无法通过
git blame查看原始作者贡献记录
通过给 B 仓库创建中间分支 aa（承载仓库 A master 分支完整历史），既能避免分支冲突，又能实现历史溯源（如git log aa-branch --author="原开发者"）
一、完整迁移三步法
先下好 A 仓库：
git clone A仓库
1. 修改远程仓库地址（核心操作）
cd 仓库A目录
git remote set-url origin 内部仓库B的URL
这一步将原本指向外网仓库A的地址，替换为本地私有仓库B的地址（如GitLab或GitHub私有库地址）
2. 创建本地新分支
git checkout -b aa-branch
由于原仓库默认分支通常为master/main，创建新分支可避免与目标仓库的默认分支产生冲突。这里的分支命名aa-branch可根据实际需求调整。
3. 推送到目标仓库
git push -u origin aa-branch
通过-u参数建立本地分支与远程分支的追踪关系，此时会将原仓库的完整提交历史推送到新仓库
二、原理深度剖析
1. Git的对象不可变性
每个commit生成后，其SHA-1哈希值由以下要素加密计算：
• 父commit哈希
• 文件树（tree）哈希
• 作者信息
• 提交信息
• 时间戳
修改远程地址如同更换快递公司，但货物（commit对象）本身未被篡改
2. 分支的本质
分支只是指向某个commit的可变指针，创建aa-branch相当于：
- 在本地仓库新建指针
refs/heads/aa-branch - 将该指针关联的commit链推送到远程仓库
refs/heads/aa-branch
3. 日志保留验证
# 查看跨仓库历史衔接点
git log aa-branch --oneline -n 5
# 验证作者信息完整性
git log --pretty="%h - %an, %ad : %s"
# 回退验证
git reset --hard commit-id
三、扩展方案对比
此外还有其他方法实现历史提交保留到另一仓库。
方案A：git filter-repo（历史重写）
git clone 仓库A && cd 仓库A
git filter-repo --path src/ # 只保留指定目录
git remote add origin 仓库B
git push origin master --force
特点：
• 核弹级工具，可删除敏感文件/修改提交者信息
• 破坏性操作，需提前备份仓库
• 适合需要清洗历史的场景
方案B：git subtree（子仓库融合）
git remote add 仓库A别名 仓库A的URL
git subtree add --prefix=subdir 仓库A别名 master
特点：
• 将仓库A作为子目录合并到当前仓库
• 保留历史但提交者信息会携带原仓库标记
• 适合第三方库长期同步更新
方案对比表
| 特性 | 分支迁移法 | filter-repo | subtree |
|---|---|---|---|
| 保留原始提交者信息 | ✔️ | 可修改 | ✔️ |
| 存储库独立性 | ✔️ | ❌ | ❌ |
| 支持后续同步更新 | ❌ | ❌ | ✔️ |
四、企业级操作建议
1. 自动化迁移脚本
#!/bin/bash
REPO_URL=$1
TARGET_URL=$2
BRANCH_NAME=${3:-external}
git clone $REPO_URL temp_repo && cd temp_repo
git remote set-url origin $TARGET_URL
git checkout -b $BRANCH_NAME --no-track
git push origin $BRANCH_NAME --follow-tags
cd .. && rm -rf temp_repo
2. 安全防护措施
• 使用git ls-remote origin验证远程连接
• 推送前执行git diff origin/master...aa-branch对比差异
• 配置仓库B的分支保护规则，禁止直接修改aa-branch
3. 可视化监控
通过GitLab CI/CD或GitHub Actions添加自动化检查：
check_history:
script:
- git log --pretty=format:"%h|%an|%ad" aa-branch > history.csv
- '[[ $(wc -l history.csv | awk "{print $1}") -gt 1 ]] || exit 1'
通过这种"分支隔离迁移法"，我们既保留了完整的技术考古线索，又实现了代码资产的合规管控。无论是对遗留系统的交接审计，还是对开源组件的二次开发，这都是值得掌握的工程化实践。