Why Migrate from SVN to Git?¶

If you’re still using the centralized version control tool SVN, you may have felt its limitations: every commit requires an internet connection, branch management is inflexible, and code conflicts are frequent in team collaboration. As a distributed version control tool, Git supports local full repositories, multi-branch parallel development, offline operations, and other advantages, which can significantly improve team efficiency. This article will guide you through migrating from an SVN repository to Git, suitable for Git beginners with zero foundation.

I. Preparation¶

Before starting the migration, complete the following preparations:

1. Install Necessary Tools
   - Install Git: Windows users can download from the Git official website; Mac users use Homebrew brew install git; Linux users use the system package manager (e.g., Ubuntu sudo apt install git).
   - Install SVN tools: If the SVN repository is not locally installed, install it additionally (Ubuntu sudo apt install subversion, Mac brew install subversion).
   - Install the svn2git tool (recommended): For converting SVN history to Git format. Install via RubyGems: gem install svn2git (Ruby must be installed first; Windows users can install via RubyInstaller).

2. Create a Git Remote Repository
   Create an empty repository on platforms like GitHub, GitLab, or Gitee (e.g., named my-project), and remember the repository URL (e.g., https://github.com/your-username/my-project.git or SSH address git@github.com:your-username/my-project.git).

3. Configure Git Identity
   Ensure Git user information is consistent with the remote repository:

   git config --global user.name "Your Name"
   git config --global user.email "your.email@example.com"

II. Migration Steps (Taking GitHub as an Example)¶

Assume your SVN repository URL is https://svn.example.com/svn/project, and the goal is to migrate to the newly created Git repository.

Step 1: Export SVN Repository History¶

Use the svn2git tool to convert the SVN repository to Git format, preserving full history:

# Enter project directory (recommended to create an empty directory first)
mkdir git-migrate && cd git-migrate

# Execute the conversion command, replace the SVN repository URL
svn2git https://svn.example.com/svn/project --trunk=trunk --branches=branches --tags=tags --authors=authors.txt

• --trunk=trunk: Specify the main branch path in SVN (usually corresponds to Git’s master branch).
• --branches=branches: Specify the SVN branch directory (corresponds to branches/xxx in Git).
• --tags=tags: Specify the SVN tag directory (corresponds to tags/xxx in Git).
• --authors=authors.txt: (Optional) Map SVN authors to Git authors. Omit if SVN and Git user information are consistent.

Step 2: Handle Author Information (Optional)¶

If SVN authors differ from Git user information, create an authors.txt file for mapping, formatted as:

svn_old_author = Git Username <Git Email>

Example:

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

Add the --authors=authors.txt parameter in the svn2git command.

Step 3: Push Local Git Repository to Remote¶

After conversion, enter the generated Git repository directory (default name is the project name), and push content to the remote repository:

cd project
git remote add origin https://github.com/your-username/my-project.git  # Replace with your Git repository URL
git push -u origin --all  # Push all branches (including trunk, branches)
git push -u origin --tags  # Push all tags

• -u origin: Set origin as the default remote repository; subsequent git push can omit origin.
• --all: Push all local branches to the remote.
• --tags: Push all tags.

Step 4: Verify Migration Result¶

After migration, check the following to confirm correctness:
1. Branches: Run git branch -a to ensure remote branches correspond to SVN branches (e.g., remotes/origin/branches/feature-x).
2. History: Run git log --oneline to check if commit records are complete (include time, author, message).
3. Files: Open project files to confirm no files are missing and directory structure matches SVN.

III. Common Issues and Solutions¶

1. Permission Issues
   - If svn2git reports “access denied”, verify the SVN repository URL is correct and you have read permissions.
   - If git push requires password entry, confirm SSH keys are configured (ssh -T git@github.com to test connection).

2. Incomplete Commit Messages
   - If commit messages lack author names after conversion, check if authors.txt is correctly mapped.

3. Large File Conversion Failure
   - If the SVN repository contains large files (e.g., binaries), svn2git may fail due to insufficient cache. Migrate in batches or use git svn instead:

     # Clone SVN repository to Git (requires Ruby environment)
     git svn clone https://svn.example.com/svn/project --stdlayout --authors-file=authors.txt

4. Messy Branch Structure
   - If SVN branches are non-standard trunk/branches/tags, adjust manually:

     # Rename the main branch to master
     git branch -m master
     # Rename branches
     git branch -r | grep -v '->' | while read remote; do git branch --track ${remote#origin/} $remote; done

IV. Summary¶

The core of migrating from SVN to Git is using tools to preserve history, map branch structures, and verify completeness. After migration, you can enjoy Git’s distributed advantages: local development without internet, flexible branch management, and more efficient team collaboration. For subsequent workflows, follow Git Flow or similar practices to enhance project management efficiency.

For complex issues during migration, refer to the svn2git official documentation or Git/SVN official manuals to troubleshoot step by step.