Why migrate

SVN works. It has worked for two decades. But its centralised model, slow branching, and difficulty integrating with modern tooling push most teams towards Git eventually. The migration is a one-time cost; the workflow improvements are permanent.

Two migration paths

• git-svn - bridges the two systems; teams can use either side during transition.
• One-shot conversion - export SVN history to Git, freeze SVN, switch.

Most successful migrations use a one-shot conversion after a brief co-existence period. Long-running git-svn bridges accumulate weirdness.

Preparing

Build an authors file mapping SVN usernames to Git author lines:

# authors.txt
jdoe = Jane Doe <[email protected]>
bsmith = Bob Smith <[email protected]>

Discover all unique SVN authors:

svn log --xml https://svn.example.com/repo \
  | grep author | sort -u \
  | sed -E 's/.*>(.+)<.*/\1 = \1 <\[email protected]>/'

One-shot conversion with git-svn

git svn clone \
    --stdlayout \
    --authors-file=authors.txt \
    https://svn.example.com/repo \
    repo.git

cd repo.git
# Convert SVN tags into real Git tags
git for-each-ref refs/remotes/origin/tags --format='%(refname:short)' \
  | while read ref; do
    tag="${ref#origin/tags/}"
    git tag "$tag" "$ref"
    git branch -d -r "$ref"
  done
# Convert SVN branches
git for-each-ref refs/remotes/origin --format='%(refname:short)' \
  | while read ref; do
    git branch "${ref#origin/}" "$ref"
    git branch -d -r "$ref"
  done

--stdlayout assumes the standard trunk/, branches/, tags/ layout. For non-standard layouts, use --trunk, --branches, --tags explicitly.

Pushing to a Git host

git remote add origin https://gitlab.example.com/team/repo.git
git push -u origin --all
git push origin --tags

Verifying the migration

• Compare commit counts: svn log -q | grep -c '^r' vs git log --oneline | wc -l.
• Spot-check authors and dates on representative commits.
• Tag and branch counts should match.
• Do a content checksum of HEAD on both systems.

Handling externals

SVN externals do not translate directly. Options:

• Vendor the external code into the repo.
• Use Git submodules.
• Use language package managers (npm, pip, etc.).

Branching model migration

SVN branches are heavyweight. Teams often have one or two long-lived branches. After migrating, encourage Git's lightweight branching - feature branches, PRs, the works. Document the new workflow before training the team.

Training

The conceptual leaps SVN-to-Git users find hardest: the staging area, distributed history, fast-forward versus merge commits, and the reality that local commits are not "saved" until pushed. Schedule a workshop, write a cheat sheet, and pair with veterans for a week.

Decommissioning SVN

After verifying, freeze the SVN repo (read-only). Keep it accessible for audit; do not delete. The migration is complete when nobody has needed SVN for a quarter.