This guide covers a full SVN-to-Git migration path that preserves branch and tag structure while keeping history understandable for teams that still need to maintain old release lines. It is a practical migration and validation walkthrough based on multiple cutovers where the dangerous part was never the command itself, it was branch mapping assumptions and weak verification. We will cover repository audit, author maps, git svn import strategy, branch and tag reconstruction checks, dry-run method, and post-cutover hygiene, then connect to migration patterns for repeated use.

Migration goals to lock before touching data

Define these in writing first:

  • What counts as a successful migration
  • Which paths map to trunk, branches, and tags
  • How author identities are translated
  • How rollback works if validation fails

If this is not explicit, debates happen during cutover and risk spikes.

Step 1: Audit SVN layout and naming anomalies

Inspect repository structure and confirm conventions.

1
svn ls -R <repo-url>

Look for:

  • non-standard branch folders
  • tags that were edited after creation
  • vendor import paths mixed with active code

Step 2: Build author mapping file

Create authors.txt with stable identity mapping:

1
2
jdoe = Jane Doe <jane@example.com>
asmith = Alex Smith <alex@example.com>

If identities are incomplete, gather them before import. Post-import fixes are possible but painful.

Step 3: Run an initial git svn clone

1
2
git svn clone <repo-url> --stdlayout --authors-file=authors.txt project-git
cd project-git

For non-standard layouts, provide explicit trunk, branch, and tag paths.

Step 4: Convert and clean tag representation

SVN tags are directories. In Git they should become immutable refs.

Typical pattern:

  • identify imported remote refs
  • create local tags from expected tag points
  • remove accidental branch-like tag refs

Step 5: Validate branch topology and history

Use targeted comparisons, not visual guesswork.

1
2
git branch -a
git log --graph --decorate --oneline --all | head -n 200

Pick known milestones from SVN and confirm equivalent commits in Git.

Step 6: Dry run cutover with team workflow

Dry run should include:

  • clone from candidate Git remote
  • build and test from representative branches
  • CI trigger checks
  • merge flow rehearsal

If one team path fails in dry run, cutover is not ready.

Step 7: Final cutover checklist

  • Freeze SVN writes during final sync window.
  • Execute final fetch/import and validate counts.
  • Push to canonical Git remote.
  • Communicate new remote URLs and branch policy.
  • Keep SVN read-only for reference period.

Post-cutover hygiene

  • Remove obsolete SVN bridge scripts from active workflow.
  • Standardize branch naming rules.
  • Add protected branch settings in remote platform.
  • Document rollback and recovery strategy.

High-risk mistakes to avoid

  1. Assuming --stdlayout matches reality without audit.
  2. Ignoring rewritten tags that were mutable in SVN.
  3. Skipping author map review until after import.
  4. Declaring done before team workflow dry run.

FAQ

Should we migrate every historical branch?

No. Migrate branches with operational value, and archive the rest intentionally.

How long should SVN remain available?

Keep read-only access through a defined confidence window and audit period.

Can we rerun import if mapping is wrong?

Yes. Start from a clean Git repository and rerun with corrected mappings.

Filed under