Migrate an existing repository from Subversion to Git on Windows with history intact

Chris Kirby -

To continue my quest of converting from CVCS to git, I figured I would do a short write-up on my recent experience with converting from Subversion in a Windows environment. The experience has been similar to my TFS conversion, though a bit more setup is involved. With that said, the process starts with a great open-source tool called svn2git. The tool aims to preserve all commit history, tags, and branches in a way that is meaningful in git. In my experience thus far, it does that job very well. So let's get started!

Step 1 - Install

Install Ruby for windows

choco install ruby

No Chocolatey? Head over to http://rubyinstaller.org/ to grab the installer for a manual install. Make sure to check "add ruby executables to your PATH".

Patch Ruby gems

Ruby gems is broken on Windows since 2.4.x was released, so we need to address that first to make the install process and future gem installs easier. Follow the instructions here https://gist.github.com/luislavena/f064211759ee0f806c88 to get things resolved. There is also a nice explanation there of the actual issue to give you some context.

** Alternatively, if you're running the latest version of Windows 10, you can install the Windows subsystem for Linux and follow the remaining steps via the Bash shell

  • Follow the installation guide and launch Bash
  • Install the packages you'll need sudo apt install subversion git git-svn ruby

-- Thanks to our local Linux guru Mike Bebej for reminding me that some things are just easier in Linux :)

Step 2 - Install svn2git

Now that the ruby package manager is installed, installation is simple.

cmd: gem install svn2git
bash: sudo gem install svn2git

Step 3 - Initiate Conversion

If you are using the default subversion layout, then the following command will kick things off: (http:// or svn://)

cmd/bash: svn2git http://svn.example.com/path/to/repo

For any non-standard repository structures or for a complete list of args, the svn2git readme has you covered.

AUTHOR MAPPING

Unlike converting from TFS to Git, commit author information when translating from SVN to Git does not map as easily. For the best possible results, you'll want to create an Author mapping file that will tell svn2git how to map each user in Git. It's a simple text file that you'll pass in with your conversion command. Each line in the file connects an svn username firstLastInitial to a git username/email first last <first.last@domain.com>.

cmd/bash: svn2git http://svn.example.com/path/to/repo --authors ~/svn2gitAuthors.txt

Step 4 - Prep & Cleanup

Now that you have a git version of your subversion repository, you'll want to clean up some files and add others to make things more git friendly.

  • If this is a Visual Studio solution, you may need to remove the Subversion source control bindings. Make a minor edit to your .sln files removing a section that resembles GlobalSection(SubversionScc) ... EndGlobalSection in your favorite text editor.
  • Add a .gitignore file. Your project or solution will likely have some files you won't want in your repository (packages, obj, etc) once your project is built. If this is a Visual Studio project, a near complete way to start is by copying everything from the standard VisualStudio.gitignore. For any other project or stack, these templates will get you started. This will ensure all of the build-generated files, packages, test results, etc., will not be tracked in your new repo.
  • Add a .gitattributes file to help git understand how to deal with project or stack-specific files. e.g., How should a .csproj file be treated? Here is a good collection of templates to get you started with yours https://github.com/Danimoth/gitattributes. You'll also find a similar attributes file created if you've ever initialized a git repo using the GitHub client for Windows.
  • Add an optional README.md file (markdown or text). A standard GitHub convention that I've become accustomed to, even for private repositories. Great way to quickly outline things about your project that would be useful at a glance, such as build instructions, usage docs, or any other helpful info.

Step 5 - Commit & Push

Now that I've git-ified the repository, it's time to commit the files, add the remote, and push the new branch out to your favorite hosted git repository. I recommend Github, but to save on cash, both Bitbucket and Gitlab are excellent choices for private repositories.

Credit to Troy Hunt, whose writeup helped me as well http://www.troyhunt.com/2014/08/migrating-from-subversion-to-git-with.html