从 SVN 到 Git 迁移的完整方案：历史记录保留与团队协作切换

为什么迁移不是“换个工具”那么简单

很多团队决定从 SVN 转向 Git 时，第一反应往往是“把代码拉过来，提交上去就行”。真正执行后才发现：历史记录丢失、分支混乱、权限模型对不上、团队成员操作习惯冲突，甚至出现同一份代码在两个系统里并行维护的尴尬局面。

SVN 是集中式版本控制，Git 是分布式版本控制，两者在数据模型、协作方式和权限管理上有本质差异。迁移不是简单的代码搬运，而是一次工程流程的重构。本文给出一套可落地的完整方案，覆盖历史保留、协作切换和过渡期管理。

一、迁移前的准备工作

1. 明确迁移范围

先盘点仓库：哪些是活跃项目，哪些已归档，哪些包含二进制大文件。不是所有 SVN 仓库都值得迁移——已冻结的历史项目可以保留 SVN 只读访问，只迁移仍在迭代的仓库。

2. 统一人员映射

SVN 提交记录里只有用户名，Git 需要 姓名 <邮箱> 格式。提前整理一份 authors.txt 映射文件，例如：

zhangsan = Zhang San <zhangsan@company.com>
lisi = Li Si <lisi@company.com>

这份映射直接决定迁移后历史记录的归属是否准确，务必让每位成员确认自己的邮箱。

3. 选择迁移工具

主流方案是 git-svn 和 svn2git。git-svn 是 Git 自带工具，适合结构简单的仓库；svn2git 对分支和标签的处理更规范，推荐用于有标准 trunk/branches/tags 结构的仓库。

二、历史记录保留的实操步骤

1. 克隆 SVN 仓库

以 svn2git 为例：

svn2git https://svn.example.com/repo/project \
  --authors authors.txt \
  --trunk trunk --branches branches --tags tags

如果 SVN 结构不规范（分支直接放在根目录），需要调整参数或分批迁移。

2. 校验历史完整性

迁移完成后，重点检查三项：

• 提交数量：对比 SVN 的 svn log | grep -c "^r" 与 Git 的 git log --oneline | wc -l
• 关键节点：抽查几个重要版本的提交信息、作者、时间戳是否一致
• 分支与标签：确认 git branch -a 和 git tag 数量与 SVN 对应

3. 处理大文件与二进制资产

SVN 仓库中常混有设计稿、安装包等大文件。迁移前用 git-svn 的 --no-metadata 或 git filter-repo 清理，避免 Git 仓库体积膨胀。如果这些文件仍需保留，考虑迁移到 Git LFS 或独立的制品库。

三、团队协作模式的切换

1. 从“锁文件”到“分支协作”

SVN 用户习惯“锁定-修改-提交”，而 Git 鼓励“分支-提交-合并”。切换时必须明确新规范：

• 禁止直接向 main 推送，所有变更走合并请求
• 功能分支命名统一，如 feature/xxx、fix/xxx
• 合并前必须 rebase 或 squash，保持历史线性

2. 权限模型的重新设计

SVN 的路径级权限（谁能读写哪个目录）在 Git 中无法直接复制。Git 的权限粒度是仓库级，路径级控制需要借助平台功能（如 GitLab 的 protected branch、CODEOWNERS）或拆分为多个仓库。

建议按“仓库级权限 + 分支保护 + 代码评审”三层模型重建：

• 仓库级：决定谁能克隆和推送
• 分支保护：main 仅允许合并请求，禁止 force push
• 代码评审：通过 CODEOWNERS 指定模块负责人

3. 过渡期的双轨运行

完全切换前，建议保留 2–4 周的双轨期：

• SVN 设为只读，禁止新提交
• Git 作为唯一写入源
• 每日同步一次 SVN 的只读镜像，供未迁移的工具链使用

这样既避免数据分叉，又给团队缓冲时间。

四、常见坑与应对

坑一：提交信息中的中文乱码。 迁移前确认 SVN 仓库编码，必要时用 --encoding 参数指定。

坑二：空目录丢失。 Git 不跟踪空目录，如果项目依赖空目录结构，需添加 .gitkeep 占位文件。

坑三：外部引用（svn:externals）失效。 这是最容易被忽略的问题。Git 没有直接对应机制，需改为子模块或包管理依赖，并逐一验证。

坑四：成员误用 SVN 命令。 切换初期提供一页“SVN 到 Git 命令对照表”，比长篇文档更有效。

五、迁移后的验收清单

• 所有活跃仓库已迁移，历史提交完整
• 作者映射准确，无“unknown”提交
• 分支和标签与 SVN 一致
• 权限模型已配置并通过测试
• CI/CD 流水线已切换到 Git 触发
• 团队完成 Git 基础培训并签署协作规范
• SVN 仓库已归档为只读

结语

从 SVN 到 Git 的迁移，技术操作只占三成，七成是流程和人的切换。历史记录保留是底线，协作模式重建才是目标。建议采用“先试点、后推广”的策略：选一个中小型项目跑通全流程，沉淀出团队自己的迁移手册，再批量推进。这样既能控制风险，也能让团队在真实项目中完成从集中式到分布式的思维转变。

未经允许不得转载：任鹏个人博客 » 从 SVN 到 Git 迁移的完整方案：历史记录保留与团队协作切换