SVN2SVN Troubleshooting: Fix Common Migration Pitfalls

SVN2SVN Best Practices: Preserving History and Branches

Migrating or syncing Subversion (SVN) repositories while preserving full history and branch structure is essential for maintaining project continuity, auditability, and developer productivity. This guide outlines practical best practices to perform SVN-to-SVN transfers—whether consolidating repositories, splitting projects, or creating mirrors—while minimizing data loss and disruption.

1. Plan the migration strategy

• Scope: Decide whether you’re migrating the entire repository, specific paths (trunk/branches/tags), or a subset of revisions.
• Goals: Define success criteria (preserve all revisions, keep UUID, maintain author mapping, downtime limits).
• Timeline: Schedule during low-activity windows and notify stakeholders.

2. Preserve repository UUID and revision history

• Use svnadmin dump/load: Create a full dump to retain all revisions and metadata.
  • Export: svnadmin dump /path/to/repos > repo.dump (use –incremental for partial dumps).
  • Import: svnadmin create /path/to/newrepos then svnadmin load /path/to/newrepos < repo.dump.
• Keep UUID if needed: By default svnadmin load preserves the original UUID; avoid –force-uuid unless intentionally changing it.
• Filter carefully: If pruning history, use svndumpfilter to remove paths, but test thoroughly—filtering can rewrite revision numbers and break copies/renames.

3. Preserve branches and tags semantics

• Maintain layout conventions: Keep or document the standard trunk/branches/tags structure.
• Handle tags as copies: Remember tags in SVN are cheap copies; ensure copy history is kept by using full dump/load or a tool that preserves copy ancestry.
• Retain copyfrom info: Tools that preserve copyfrom metadata maintain branch lineage—important for merges and blame accuracy.

4. Map users and authors consistently

• Create an author map file: If usernames differ between systems, map old usernames to new ones to keep authorship clear.
• Apply mapping during conversions: Use conversion tools’ author-mapping options (or rewrite authors in the dump file) before loading.

5. Use recommended tools and options

• svnadmin (dump/load): Best for full repository moves and preserving all metadata.
• svndumpfilter: For path exclusions; always test since it can break history when paths are copied across the tree.
• svnsync: For creating read-only mirrors while keeping history and revision numbers intact. Use for ongoing replication.
• svk (legacy) or third-party scripts: Only if they suit special needs—prefer standard Subversion tools for fidelity.

6. Test thoroughly on a staging server

• Dry run: Restore the dump to a staging repo and verify history, branches, tags, and copy history.
• Run common workflows: Check out trunk/branches, perform merges, run svn blame, and inspect revision properties.
• Compare revisions: Use svn log, svn diff -r, and tree comparisons to ensure parity.

7. Handle hooks and configuration

• Transfer hook scripts: Move pre-commit, post-commit hooks and adapt paths/permissions. Test hook behavior in staging.
• Recreate server config: Reapply authz, passwd, and Apache/HTTPD or svnserve configuration. Ensure access controls match expectations.

8. Minimize downtime and synchronize final changes

• Two-step sync: 1) Perform an initial dump/load to copy the bulk history. 2) During cutover, either replay recent revisions or use svnsync to catch up and freeze writes on source.
• Communicate lock windows: Inform teams to stop commits or switch to maintenance mode during final sync.

9. Validate after migration

• Run integrity checks: svnadmin verify on the new repo.
• Spot-check history and branches: Confirm key tags, branch merges, and revision authors.
• Monitor user reports: Be ready to address missing files, broken merges, or access issues.

10. Keep backups and rollback plans

• Retain original dumps: Store original repository dump files offline until migration acceptance.
• Document rollback steps: Include how to restore the old repo and revert DNS/URL changes if needed.

Quick Troubleshooting Tips

• Broken copy history after filtering: Re-run with inclusive filters or avoid svndumpfilter for repos with cross-tree copies.
• Author mismatches: Rebuild dump with corrected author mappings or edit revision properties before load.
• Hook script failures: Check executable permissions and environment variables; run scripts manually to see errors.

Following these practices will help ensure your SVN2SVN migration preserves history, maintains branch integrity, and minimizes disruption.