Migrating from SVN to Git

Understanding the Migration from SVN to Git

Migrating from Subversion (SVN) to Git is the process of converting an existing SVN repository—complete with its full commit history, branches, and tags—into a Git repository. This transformation allows development teams to move away from a centralized version control model and adopt a distributed workflow that has become the industry standard. A successful migration preserves every revision, author, and log message so that the project’s entire history remains intact and searchable.

Why Migrating Matters

SVN served many teams well for years, but Git offers fundamental advantages that directly impact daily productivity and code quality:

• Distributed model – Every developer has a full copy of the repository, enabling offline work, fast local operations, and built-in redundancy.
• Branching and merging – Git branches are lightweight and cheap, encouraging feature branches, pull requests, and continuous integration without the pain of SVN’s directory-based branches.
• Speed – Commands like git log, git diff, and git commit run locally in milliseconds, compared to network-bound SVN operations.
• Modern ecosystem – Platforms like GitHub, GitLab, and Bitbucket are built around Git, offering code review, CI/CD pipelines, and collaboration tools that expect a Git repository.
• Better handling of large projects – Git’s storage model and compression are often more efficient, and with Git LFS you can manage binary assets without bloating the repository.

By migrating, you unlock these benefits while retaining the valuable history that provides context for every change ever made.

How to Migrate from SVN to Git: A Complete Step-by-Step Guide

The migration process can be broken down into five clear stages. The examples below assume you have access to a typical SVN repository with a standard layout (trunk, branches, tags) and are running the commands on a Unix-like system with Git installed.

Prerequisites

• Install Git (version 2.20 or later) – includes the git-svn tool by default.
• Ensure the svn command-line client is available and that you can access the SVN repository (via file://, https://, or svn://).
• Prepare an authors file to map SVN usernames to Git’s expected format: Name <email>.
• Decide on a target Git remote (e.g., GitHub, GitLab, or a self-hosted server).

Step 1: Create the Authors Mapping File

Git records committers as Full Name <email>, while SVN often stores only a username. An authors file maps each SVN username to the corresponding Git identity. First, extract all unique SVN usernames from the repository’s log:

svn log -q https://svn.example.com/repo | awk -F '|' '/^r/ {print $2}' | sort -u > authors.txt

Then open authors.txt and edit every line to follow this format:

svn_username = Full Name <email@domain.com>

For example:

jdoe = John Doe <john.doe@example.com>
msmith = Mary Smith <mary.smith@example.com>

Save this file—it will be used by git svn to rewrite commit metadata.

Step 2: Clone the SVN Repository with git svn

The git svn clone command imports the entire SVN history into a new Git repository. For a standard layout, use:

git svn clone --authors-file=authors.txt \
  --trunk=trunk --branches=branches --tags=tags \
  https://svn.example.com/repo project-git

What this does:

• --authors-file=authors.txt – applies your identity mapping to every commit.
• --trunk=trunk – tells Git that trunk corresponds to the main branch (which will become master).
• --branches=branches – imports all branches under the branches directory as remote references.
• --tags=tags – imports tags (which are just branches in SVN) as remote references under refs/remotes/origin/tags/.

If your repository uses a non-standard layout (e.g., /project/trunk, /project/branches/...), you can specify the paths explicitly:

git svn clone --authors-file=authors.txt \
  --trunk=project/trunk --branches=project/branches/* --tags=project/tags/* \
  https://svn.example.com/repo project-git

Important: Cloning a large SVN repository can take hours. Run this on a machine with a fast connection and plenty of disk space. If the process is interrupted, you can resume with git svn fetch inside the created directory.

Step 3: Convert SVN Tags into Real Git Tags

After cloning, SVN tags exist as remote branches (e.g., refs/remotes/origin/tags/v1.0). To turn them into proper Git tags, first move them to local tags and then delete the remote references:

cd project-git
# Create a proper Git tag for each SVN tag
git for-each-ref refs/remotes/origin/tags | cut -d / -f 5- | \
  grep -v @ | while read tag; do
    git tag "$tag" "refs/remotes/origin/tags/$tag"
    git branch -d -r "origin/tags/$tag"
done
# Remove the empty tags directory reference
git branch -d -r origin/tags

This script iterates over every SVN tag reference, creates a lightweight Git tag, and then removes the remote branch that represented it. The grep -v @ excludes any internal SVN revisions.

Step 4: Convert Remote Branches into Local Branches

SVN branches are similarly stored as remote references. You’ll want them as actual local Git branches (except for trunk, which is already master):

git for-each-ref refs/remotes/origin | cut -d / -f 4- | \
  grep -v @ | while read branch; do
    if [ "$branch" != "trunk" ]; then
      git branch "$branch" "origin/$branch"
    fi
done

Now git branch will show all your local branches, each preserving the history from SVN.

Step 5: Push to a Git Remote Server

With a clean Git repository containing all history, branches, and tags, the final step is to push everything to a remote Git host. Add your remote URL and push:

git remote add origin https://github.com/your-org/your-repo.git
git push origin --all
git push origin --tags

The --all flag pushes every branch, and --tags pushes all tags. Your team can now clone from this remote and start working with Git immediately.

Alternative Tools and Advanced Scenarios

While git svn is built-in and reliable for most repositories, some migrations benefit from dedicated tools:

• svn2git – A Ruby-based utility that often handles complex branch/tag renames and merges better than git svn. Use it when your SVN history contains intricate branch copies.
• git-filter-repo – After migration, you may want to clean up unwanted files, remove large binaries, or rewrite commit metadata. This tool is faster and safer than git filter-branch.

For example, to remove a directory of large binary assets after migration:

git filter-repo --path old-binaries/ --invert-paths

Always run such cleaning operations before sharing the repository with the team.

Best Practices for a Smooth Migration

• Clean up the SVN repository beforehand – Remove stale branches, unused tags, and large binaries that don’t belong in version control. This reduces clone time and keeps the Git history lean.
• Verify the authors mapping thoroughly – A single missing entry can cause commits to show up with raw SVN usernames. Run git log --format='%an %ae' | sort -u after cloning to confirm all identities look correct.
• Perform a test migration first – Clone the repository into a temporary location, validate branch structures, tag integrity, and commit counts. Compare git log output with svn log to ensure no history was lost.
• Keep the SVN repository read-only after migration – Once the Git remote is live, make the SVN server read-only to prevent accidental commits. Point all CI/CD jobs and documentation to Git immediately.
• Plan a cutover window – Coordinate with the team to stop all SVN commits, perform the final migration, and push to Git. Provide training or cheat sheets for common Git equivalents of SVN commands.
• Consider Git LFS for large files – If your project includes many binary assets (images, videos, datasets), set up Git LFS before the initial push to keep the repository fast and manageable.
• Preserve the SVN revision references – git svn adds a git-svn-id line to every commit message, linking back to the original SVN revision. Retain these unless you have a strong reason to strip them.
• Document the new workflow – Write a short guide explaining how branching, merging, and pushing work in Git compared to SVN. This reduces confusion and accelerates adoption.

Conclusion

Migrating from SVN to Git is a strategic investment that pays off through faster development cycles, more robust collaboration, and access to a vast ecosystem of modern tools. By following the step-by-step process outlined here—mapping authors, cloning with git svn, converting tags and branches, and pushing to a remote—you preserve your entire project history while opening the door to powerful Git workflows. Plan the migration carefully, validate the result, and equip your team with the knowledge they need to thrive in a distributed version control world. The effort you put into a clean, well-structured migration will be repaid many times over in everyday development speed and flexibility.