Don’t do svn-to-git repository conversions with git-svn!

This is a public-service warning.

It has come to my attention that some help pages on the web are still recommending git-svn as a conversion tool for migrating Subversion repositories to git. DO NOT DO THIS. You may damage your history badly if you do.

Reminder: I am speaking as an expert, having done numerous large and messy repository conversions. I’ve probably done more Subversion-to-git lifts than anybody else, I’ve torture-tested all the major tools for this job, and I know their failure modes intimately. Rather more intimately than I want to…

There is a job git-svn is reasonably good at: live gatewaying to a Subversion repo, allowing you to pretend it’s actually in git. Even in that case it has some mysterious bugs, but the problems from these can usually be corrected after the fact.

The problem with git-svn as a full importer is that it is not robust in the presence of repository malformations and edge cases – and these are all too common, both as a result of operator errors and scar tissue left by previous conversions from CVS. If anyone on your project has ever done a plain cp rather than “svn cp” when creating a tag directory, or deleted a branch or tag and then recreated it, or otherwise offended against the gods of the Subversion data model, git-svn will cheerfully, silently seize on that flaw and amplify the hell out of it in your git translation.

The result is likely to be a repository that looks just right enough at the head end to hide damage further back in the history. People often fail to notice this because they don’t actually spend much time looking at old revisions after a repository conversion – but on the rare occasions when history damage bites you it’s going to bite hard.

Don’t get screwed. Use git-svn for live gatewaying if you must, remaining aware that it is not the safest tool in the world. But for a full conversion use a dedicated importing tool. There are around a half-dozen of these; beware the ones that are wrappers around git-svn, because while they may add a few features they can’t do that much to address its weaknesses.

Ideally you want an importer with good documentation, a comprehensive end-to-end test suite full of examples of common Subversion-repository malformations, a practice of warning you when it trips over weirdness, and a long track record of success on large, old, and nasty repositories. And if you learn of any tool with all those features other than reposurgeon please let me know about it.

Please share this and link to it so the warning gets as widely distributed as possible.

P.S.: It has been pionted out that I couls provide more positive guidance. Here it is: the DVCS Migration HOWTO.