SVN - Git migration complete guide

Although there are various articles about SVN-Git migration available, I could not find one that covers all topics that I needed, so here is my version.

Step 0 - Pre-requisites:

git-svn is a simple tool to synchronize change-sets between Subversion and Git. It is distributed within the Git installation for Windows which can be downloaded and installed from this site. I recommend using winget which is a package manager Windows similar to the Linux package managers like apt-get. Git-svn provides a bidirectional flow of changes between a Subversion and a Git repository, but we use it only in one direction.

Also, you will need a user file to map the SVN committer to Git. There are various articles providing a bash script to do this. Since the file was already prepared in my case, I am skipping this section.

It is helpful to have a high-level understanding of how the local git repository works, the information about this can be found here

Step 1 - Setting the local git repo:

1- To create a local git repo to use during migration, use the following command to set it up:

git svn init [SVN URL of repo] [folder name for local git repo] --stdlayout --username=[Your SVN username]

2- Navigate into the local git repo folder

3- Attach the users file to be used during conversion:

git config svn.authorsfile [Full path of your users file]

Step 2 - Configure the trunk, branches & tags to transfer:

1- Open .git\config file with a text editor and locate the lines under [svn-remote "svn"] group.

url is the base URL of the SVN repo.

for fetch, branches, and tags lines the format is [relative SVN folder path/s]:[git branch paths]

2- For trunk:

If you are using a non-standard trunk folder, update the first part of the fetch line.

3- For branches:

If you do not want to migrate the branches, remove the line

If you want to migrate specific branches, update the first part accordingly. E.g. if you want to migrate branchA and branchB under the branches folder, the first part should be branches/{branchA,branchB}.

4- For tags:

If you do not want to migrate the tags, remove the line

If you want to migrate specific tags, update the first part accordingly. E.g. if you want to migrate tagA and tagB under the tags folder, the first part should be tags/{tagA,tagB}.

5- Large Artifacts:

Git actually clones (almost) complete directory to the local file system, and if a large file is once committed in git, it will be pulled to a local file system/build machines on every location, therefore large files (build artifacts), should be avoided. Having a few dlls which rarely change and are frequently used is not a big deal, but having previous build artifacts is not a good idea ( but if you still must include large files please active git large file storage). To avoid migration of some paths you can add a line as below

ignore-paths = [Perl Regex]

Save and close the file.

Step 3 - Start the sync

Execute git svn fetch command. This command can crash or hang due to various reasons, if it happens ensure the process is killed and re-execute it. The operation will continue.

One common error that you can face is that “the User is not found” error. In this case add the user to the users file in the appropriate format (be careful SVN usernames are case-sensitive)

Ex. Eergin = E Ergin <EErgin@svn.company.com>

We are adding @svn in the domain name to specify that this is not a real email address but is created only for svn migration.

Step 4 - Backup

Create a backup of the local git folder at this point. If you have issues in the upcoming steps, you can restore the backup and start from this point again.

Step 5 - Converting tags

Since SVN does not have real support for tags (they are actually branches), those are created as branches during cloning. Some actions are needed to convert those to git tags.

1- Locate the tags: Run git branch -r and locate the lines starting with origin/tags/. Those are all the tags that are synced from SVN.

2- For each of the tags, locate the last part of the path (tag name) and execute git tag [tag name] origin/tags/[tag name]

3- Delete the tag branch with git branch -d -r origin/tags/[tag name]

Step 5 - Creating local branches

1- Locate the branches: Run git branch -r and locate the lines starting with origin/. The lines except for origin/trunk and origin/tags are the branches that are synced from SVN.

2- For each of the branches, locate the last part of the path (branch name) and execute git checkout -b [branch name] origin/[branch name]

Step 6 - Cleanup SVN stuff

1- Execute git branch -d -r origin/trunk

2- Execute git config --remove-section svn-remote.svn

3- Execute git config --remove-section svn

2- Delete .git\svn folder

2- Delete .git\refs\remotes folder

3- Delete .get\logs\refs\remotes folder

Step 7 - Add Github as Remote

Execute git remote add origin [git file address of the repo]

Ex. git remote add origin https://github.com/erdemergin/myRepo.git

Step 8 - Push the changes

1- Execute git push --all

2- Execute git push --tags