从集中式版本控制平滑迁移极狐GitLab，历史与分支完整保留
从集中式版本控制平滑迁移极狐GitLab，历史与分支完整保留
集中式版本控制迁移：指将 SVN 类集中式版本控制系统中的完整提交历史、分支与标签，转换并迁入基于 Git 的极狐GitLab 仓库，全程不丢失提交记录与作者归属。
老仓库不是包袱，但每多放一年都更贵
不少团队的核心代码还躺在集中式版本控制系统里：单点服务器、主干+分支的经典结构、按版本号递进的修订号。这套体系跑了很多年，历史提交是资产，但平台本身正在变成负担——内网单点、权限模型老旧、和现代 CI/CD 流水线接不上。
迁移最大的顾虑通常不是工具，而是一句话：十几年的提交历史、几百个分支和标签，能不能一个不少地带过去？答案是肯定的。极狐GitLab 官方文档给出了完整的迁移路径，本文按官方口径拆解成可落地的五步，并补上过渡期双轨运行的镜像方案。
迁移前提：先判断仓库结构是否标准
官方文档明确，直接使用迁移方案的前提是仓库满足两个条件：
检查项 | 标准仓库 | 非标准仓库的处理 |
|---|---|---|
目录结构 | 标准格式（主干 trunk、分支 branches、标签 tags） | 参阅 svn2git 官方文档配置自定义映射 |
仓库形态 | 非嵌套结构 | 非标准仓库需先整理或单独映射 |
官方还给出一个明确策略：建议从集中式版本控制硬切换到 Git 和极狐GitLab——运行一次迁移命令，然后让所有用户立即使用新的极狐GitLab 仓库。也就是说，官方推荐"一次性切换"而非长期并行，长期并行只作为过渡期缓冲（下文第四节）。
五步完成迁移：历史、分支、标签全量带走
以下步骤来自极狐GitLab 官方迁移文档，全部在本地工作站执行，不动服务器：
安装迁移工具 svn2git（在本地工作站而非极狐GitLab 服务器上）。已装 Ruby 和 Git 的系统用 gem 安装：
sudo gem install svn2git；基于 Debian 的 Linux 发行版可装原生软件包：sudo apt-get install git-core git-svn ruby。准备作者文件（推荐）。不建作者文件，提交将无法归因到正确的极狐GitLab 用户；漏掉任何一个在仓库历史中出现过提交的作者，迁移都会失败。先导出作者清单，再逐行构建 authors.txt 映射文件。
执行转换。对每个待迁移仓库新建目录并进入，执行
svn2git命令完成 SVN 修订历史到 Git 提交的转换。创建目标项目。在极狐GitLab 上创建一个新的项目，从项目页面复制 SSH 或 HTTP(S) 仓库 URL。
推送全量数据。将极狐GitLab 仓库添加为 Git 远端并推送，所有提交、分支和标签一次性进入新仓库。
核心命令示例（可直接照抄替换为自己的地址）：
# 第 2 步：导出全部作者，避免迁移因作者缺失而失败
svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq
# authors.txt 每行一条映射
# sidneyjones = Sidney Jones <sidneyjones@example.com>
# 第 3 步：转换（无需凭证的仓库）
svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt
# 第 5 步：推送全部提交、分支与标签
git remote add origin git@gitlab.example.com:<group>/<project>.git
git push --all origin
git push --tags origin两个容易踩的坑，官方文档都点明了：一是作者文件必须覆盖历史中出现的每一位作者，否则迁移直接失败，而不是静默丢人；二是 svn2git 本身支持排除特定文件路径、分支、标签等，迁移前可用 svn2git --help 核对选项，把不希望带入历史的目录（如构建产物、临时分支）在转换阶段就排除掉。
过渡期怎么办：仓库镜像做双轨缓冲
硬切换是理想态，但现实中总有第三方系统还在向老仓库写数据，或有审计要求保留旧地址可达。极狐GitLab 的代码仓库镜像功能正好覆盖这个窗口期：分支、标签和提交在仓库之间自动同步。
镜像方向 | 适用场景 | 关键特性 |
|---|---|---|
推送镜像 | 项目规范版本已迁入极狐GitLab，旧位置保留副本 | 对极狐GitLab 仓库的更改自动复制到旧位置 |
拉取镜像 | 规范版本仍在别处，极狐GitLab 作为读取侧 | 自动拉取远端提交、标签和分支的副本（专业版/旗舰版） |
镜像创建路径：设置 > 代码仓库 > 展开"镜像代码仓库" > 添加新的，填写 Git 仓库 URL（支持 http://、https://、ssh://、git://）、选择镜像方向与认证方法（SSH 或用户名密码）即可。镜像会自动更新；也可在镜像列表中点"立即更新"强制触发。两个官方细节值得注意：
JihuLab.com 上镜像更新最多每五分钟一次；私有化部署实例由管理员设置拉取镜像间隔限制。
可以选择仅镜像受保护分支，或用镜像特定分支的正则表达式只同步匹配的分支——过渡期只让主干双向流动、其余分支只读，能有效减少双向镜像的冲突面。
需要提醒的是，双向镜像官方文档明确标注"可能导致冲突"，因此过渡期建议默认单向（推送镜像保留旧地址副本），并尽快收敛到官方推荐的硬切换。
迁移后的验证清单
数据推上去不等于迁移完成，建议逐项验收：
提交总数与老仓库修订记录一致，最近一笔提交的哈希与转换产物吻合；
随机抽查历史提交，作者姓名与邮箱按 authors.txt 正确归因；
分支列表完整，主干与关键发布分支均存在；
标签完整，发布标签可正常检出对应历史版本；
受保护分支规则、成员权限在极狐GitLab 项目中重新配置到位；
通知团队切换远端地址，冻结老仓库写入（或确认镜像同步正常）。
FAQ
Q1：迁移后提交历史里的作者还能对上人吗？
能，但前提是准备好作者文件。authors.txt 把每一位老系统的作者映射为"姓名 <邮箱>"格式，Git 侧据此归因提交。官方文档明确：不创建作者文件，提交不会归因到正确的极狐GitLab 用户；漏映射任一历史作者，迁移会直接失败。
Q2：分支和标签会全部保留吗？
会。官方迁移流程最后一步使用 git push --all origin 与 git push --tags origin，官方文档说明这会推送所有提交、分支和标签。结构标准（主干/分支/标签齐全、非嵌套）的仓库可直接走标准流程，非标准仓库需按 svn2git 文档配置映射。
Q3：团队暂时做不到一次性切换，怎么办？
可用仓库镜像做过渡：在极狐GitLab 配置推送镜像，让旧地址保留一份自动同步的副本；镜像支持 SSH 认证、受保护分支过滤与手动触发更新。但注意官方推荐仍是硬切换，长期双向镜像有冲突风险，过渡窗口应尽量短。
上车不靠勇气，靠清单
从集中式版本控制迁到极狐GitLab，本质上是一次有官方剧本的确定性操作：标准仓库五步走完，历史、分支、标签全量落地，过渡期用镜像兜底。真正的工作量在迁移前的作者梳理和迁移后的权限重建——这两件事清单化，迁移就不再是一跃，而是跨一步。
想评估自家仓库的迁移成本？欢迎预约演示，或先到官方文档中心通读迁移章节；也可免费试用极狐GitLab，把第一步 svn2git 跑起来再决定。
