Qugstart
Journal note about branch and tag mapping validation.

Journal

Branch and tag mapping review before SVN-to-Git cutover

Operational notes on branch reconciliation, author map completeness, and final sync verification before declaring SVN-to-Git migration complete.

This entry documents the branch and tag reconciliation process before SVN-to-Git migration cutover. Everything up to this point has been exploratory — cutover is the point of no easy return, so the pre-flight sequence matters.

What can go wrong at cutover

The most common failures at migration cutover:

  • Branch names that do not map cleanly to Git refs (spaces, special characters, branch names that collide with tags)
  • Author maps that are incomplete, producing commits with malformed or placeholder author metadata
  • Tags that were created from trunk rather than from a branch, producing unexpected tag ancestry
  • A merge window left open during migration that creates divergence between the SVN state and the converted Git history

Pre-cutover validation sequence

Run this sequence before declaring migration complete:

  1. Freeze SVN writes. No commits during the cutover window.
  2. Final sync: git svn fetch — pull in all commits since the last sync.
  3. Branch count: confirm the number of remote branches in the Git clone matches the expected branch set from SVN.
  4. Tag check: git tag -l compared against the SVN tags directory listing.
  5. Author map audit: run git log --format="%an <%ae>" | sort -u and look for any placeholder values indicating the author map was incomplete.
  6. Spot-check commits: verify author name, commit message, and timestamp accuracy on 3–5 commits spread across the history.
  7. Merge graph: run git log --oneline --graph on a few branches to confirm merge history is coherent.

Common branch name cleanup

SVN repositories sometimes have branches with names that are problematic in Git. Spaces and forward slashes in branch names (beyond the standard branches/ prefix) are the most common issues. Rename these before migration using svn mv rather than trying to rewrite refs after the fact in Git.

Post-cutover verification

After the migration is declared complete:

  • Set the SVN repository to read-only or take it offline entirely
  • Confirm all developers have cloned from the Git remote, not from any intermediate local copies
  • Run a final diff on a representative sample of commits against known SVN revision content
  • Update any CI/CD configuration that referenced SVN paths
  • Archive the SVN repository at a documented final revision number