Git远程仓库迁移：从SVN迁移到Git的实战指南

为什么要从SVN迁移到Git？¶

如果你还在使用集中式版本控制工具SVN，可能已经感受到它的局限：每次提交都需要联网，分支管理不够灵活，团队协作时代码冲突频繁。而Git作为分布式版本控制工具，支持本地完整版本库、多分支并行开发、离线操作等优势，能极大提升团队效率。本文将手把手教你从SVN仓库迁移到Git，适合零基础的Git初学者。

一、准备工作¶

在开始迁移前，需要完成以下准备：

安装必要工具
- 安装Git：Windows用户可从Git官网下载安装；Mac用户用Homebrew brew install git；Linux用户用系统包管理器（如Ubuntu sudo apt install git）。
- 安装SVN工具：如果SVN仓库未本地安装，需额外安装（Ubuntu sudo apt install subversion，Mac brew install subversion）。
- 安装svn2git工具（推荐）：用于将SVN历史转换为Git格式。通过RubyGems安装：gem install svn2git（需先安装Ruby，Windows用户可通过RubyInstaller安装）。
创建Git远程仓库
在GitHub、GitLab或Gitee等平台新建一个空仓库（如命名为my-project），记住仓库地址（如https://github.com/your-username/my-project.git或SSH地址git@github.com:your-username/my-project.git）。
配置Git身份
确保Git提交时的用户信息与远程仓库一致：

   git config --global user.name "你的名字"
   git config --global user.email "你的邮箱"

二、迁移步骤（以GitHub为例）¶

假设你的SVN仓库地址为https://svn.example.com/svn/project，目标是迁移到新建的Git仓库。

步骤1：导出SVN仓库历史¶

使用svn2git工具将SVN仓库转换为Git格式，保留完整历史：

# 进入项目目录（建议先新建空目录）
mkdir git-migrate && cd git-migrate

# 执行转换命令，替换SVN仓库地址
svn2git https://svn.example.com/svn/project --trunk=trunk --branches=branches --tags=tags --authors=authors.txt

--trunk=trunk：指定SVN的主分支路径（通常对应Git的master分支）。
--branches=branches：指定SVN的分支目录（对应Git的branches/xxx）。
--tags=tags：指定SVN的标签目录（对应Git的tags/xxx）。
--authors=authors.txt：（可选）映射SVN作者到Git作者。若SVN作者与Git用户信息一致，可省略此参数。

步骤2：处理作者信息（可选）¶

如果SVN作者与Git用户信息不同，需创建authors.txt文件映射，格式为：

svn_old_author = Git 用户名 <Git 邮箱>

例如：

bob = Bob Smith <bob@example.com>
alice = Alice Wang <alice@example.com>

然后在svn2git命令中加入--authors=authors.txt参数。

步骤3：推送本地Git仓库到远程¶

转换完成后，进入生成的Git仓库目录（默认名为项目名），推送内容到远程仓库：

cd project
git remote add origin https://github.com/your-username/my-project.git  # 替换为你的Git仓库地址
git push -u origin --all  # 推送所有分支（包括trunk、branches）
git push -u origin --tags  # 推送所有标签

-u origin：设置origin为默认远程仓库，后续git push可省略origin。
--all：推送所有本地分支到远程。
--tags：推送所有标签。

步骤4：验证迁移结果¶

迁移完成后，检查以下内容是否正确：
1. 分支：执行git branch -a，确认远程分支与SVN分支对应（如remotes/origin/branches/feature-x）。
2. 历史：执行git log --oneline，查看提交记录是否完整（包含时间、作者、信息）。
3. 文件：打开项目文件，确认所有文件未丢失，目录结构与SVN一致。

三、常见问题与解决¶

权限问题：
- 若svn2git报错“拒绝访问”，检查SVN仓库URL是否正确，且你有读取权限。
- 若git push时要求输入密码，确认SSH密钥已配置（ssh -T git@github.com测试连接）。
提交信息不完整：
- 若转换后的提交信息缺少作者名，需检查authors.txt是否正确映射。
大文件导致转换失败：
- 若SVN仓库含大文件（如二进制文件），svn2git可能因缓存不足报错。此时可分批次迁移，或用git svn替代svn2git：

     # 克隆SVN仓库到Git（需Ruby环境）
     git svn clone https://svn.example.com/svn/project --stdlayout --authors-file=authors.txt

分支结构混乱：
- 若SVN分支非标准trunk/branches/tags，需手动调整：

     # 重命名主分支为master
     git branch -m master
     # 重命名分支
     git branch -r | grep -v '->' | while read remote; do git branch --track ${remote#origin/} $remote; done

四、总结¶

从SVN迁移到Git的核心是利用工具保留历史、映射分支结构，并验证完整性。迁移后，你可以享受Git的分布式优势：本地开发无需联网，分支管理更灵活，团队协作更高效。后续可基于Git Flow等工作流规范，提升项目管理效率。

如果迁移过程中遇到复杂问题，可参考svn2git官方文档或Git/SVN官方手册，逐步排查错误。