Complete Guide to Migrating from SVN to Git with Full Commit History

Introduction

In modern software development, migrating version control systems is a common yet complex process. Many teams wish to transition from Subversion (SVN) to Git to leverage Git's distributed nature and superior branch management capabilities. However, one of the biggest challenges in migration is preserving the complete commit history. This article provides a detailed migration guide based on the git-svn tool.

Basic Migration Command

git-svn is an official Git tool specifically designed for interacting with Subversion repositories. The most basic migration command is remarkably simple:

git svn clone http://svn/repo/here/trunk

This command creates a new Git repository and imports all historical records from the specified SVN path (typically trunk) into Git. Since Git and SVN differ significantly in architecture and operation, understanding how git-svn works is crucial for successful migration.

User Mapping Configuration

SVN and Git handle author information differently. SVN only records usernames, while Git requires full names and email addresses. Therefore, creating a user mapping file before migration is essential:

user1 = First Last Name <email@address.com>
user2 = First Last Name <email@address.com>

You can automatically generate a user list template from an existing SVN repository using:

svn log -q | awk -F '|' '/^r/ {gsub(/ /, "", $2); sub(" $", "", $2); print $2" = "$2" <"$2">"}' | sort -u > users.txt

Complete Repository Cloning

For standard SVN layouts (containing trunk, branches, and tags directories), use the --stdlayout parameter:

git svn clone --stdlayout --no-metadata --authors-file=users.txt svn://hostname/path dest_dir-tmp

The --no-metadata parameter prevents adding SVN-specific metadata to commit messages. For non-standard SVN repository layouts, use --trunk, --branches, and --tags parameters to specify paths separately.

Branch and Tag Handling

After migration completes, SVN branches exist as Git remote branches. View all remote branches using:

git branch -r

To convert remote branches to local branches, create corresponding local branches for each:

git checkout -b local_branch remote_branch

SVN tags are imported as branches in Git. Manually convert them to Git tags:

git checkout -b tag_v1 remotes/tags/v1
git checkout master
git tag v1 tag_v1
git branch -D tag_v1

Cleanup and Optimization

After migration, clone to a clean Git repository to remove SVN-related metadata:

git clone dest_dir-tmp dest_dir
rm -rf dest_dir-tmp
cd dest_dir

Then recreate local branches and remove temporary remote:

git checkout -b local_branch origin/remote_branch
git remote rm origin

Advanced Configuration Options

For complex SVN repository structures, additional parameters may be necessary:

git svn clone svn://svn.company.com/svnrepos --preserve-empty-dirs --prefix=svn/ --include-paths="^project1/trunk|^project2/trunk" --authors-file authors-transform.txt export_name

The --preserve-empty-dirs parameter preserves empty directories from SVN, which Git ignores by default. The --include-paths parameter allows specifying particular path patterns to include.

Post-Migration Verification

After migration completes, we recommend the following verifications:

• Check if commit history is complete
• Verify all branches and tags converted correctly
• Confirm file contents are not corrupted
• Test basic Git operations (commit, push, pull)

Best Practice Recommendations

Based on practical migration experience, we recommend:

• Back up original SVN repository before migration
• Perform small-scale migration in test environment first
• Consider using Git LFS for large files
• Clean up unnecessary binary files and historical records
• Train team members on basic Git operations

Conclusion

While the git svn clone command appears simple, successful migration requires careful planning and execution. By understanding the differences between SVN and Git, properly configuring migration parameters, and conducting thorough testing, teams can successfully complete version control system migration while preserving valuable historical records.