Migrating from VSS to Git with VSS2Git: A Step-by-Step Guide

Best Practices for Using VSS2Git in Large Legacy Repositories

1. Prepare and back up

• Backup: Make a full backup of the VSS database and work on a local copy.
• Analyze/repair: Run VSS Analyze.exe (use -f if needed) and repair CRC issues before migrating.

2. Plan scope and exclusions

• Migrate per project: Migrate one VSS project (and its subprojects) at a time rather than the entire DB.
• Exclude noise: Define filename/path exclusion patterns (wildcards supported) to skip build artifacts, large binaries, or irrelevant folders.

3. Environment and performance

• Local migration: Run vss2git against a local copy (not a network share) for speed and reliability.
• Temporarily disable scanners: Exclude the output path from antivirus/real‑time scanners to avoid Git index errors.
• Empty output dir: Start with an empty output directory; delete the directory (including .git) when re-running a migration.

4. Preserve and map metadata

• Authors mapping: Create an authors map (VSS username → Git name/email) so commits have correct authorship.
• Timestamps and messages: Verify commit dates, times, and messages after migration; vss2git formats dates as ISO 8601 to avoid locale issues.

5. Handle branching and tags carefully

• Understand VSS model: VSS tracks per-file revisions, not global changesets—expect reconstructed commits and potential noise.
• Tagging: Review and normalize tags/labels; vss2git strips illegal characters and can preserve annotated tags if configured.

6. Validate history and repository layout