SVN to GIT to GitHub - a story of a common migration path

Description of a common migration path - SVN to GIT to GitHub.


This article describes a common migration path - SVN to GIT to GitHub - that I've walked-in lately and can be used as a best-practice for many users even if not used as-is since each case have a different startup-status and different requirements.

The post can be useful for many of you since it contains the following content:

  • Analysis of the given startup status, requirements, main components and more.
  • Detailed technical information about steps to perfrom and other related information
  • Process flow description.
  • Insights of decision taken during the process.
  • Links to related information and resources I've used during the process.

yes I hope that the article would be useful for at least one of the readers. Comments will be most welcome.

In the beginning

First of all, I'll start by describing the trigger for this migration, the building blocks of it and all that is related to the initial process status.


Tikal Knowledge ALM group-members performs many ALM processes and projects for Tikal's customers.

One of those common processes is a migration from one source control system to another one.

In this case I've been requested to migrate an existing SVN-server-based-system to a GIT-based-system which will be supported by using the GitHub services.

I won't get into the reasons leading the certain customer on the decision to perform this migration, but these days it is a very common migration that contains 2 major paths:

  • Migration from SVN to GIT - there are many posts and articles trying to explain why one should perfrom it and you can google around it and get many of those posts. I recomment this simple comparison list as a start.
  • Using GitHub as the the main repository host - read this web page as a lead for choosing GitHub over other possible solutions.
  • Beside this top-level requirement, there were some other requirements that I'll describe later on.

Process startup-status and requirements

In this section I'll describe what were the status of the migrated-system and the migration-requirements.

Even that your system is probably not the exactly same and you may have different migration-requirements, I think that each one of you should prepare a similar list as a first step before starting to work on the migration.


Here's some information about the system-to-be-migrated and other related details, as I had for my case:

  • a company with a small development team (less than 10 developers that uses source contol system)
  • SVN server with:
  • 1 repository.
  • common SVN tree structure: trunk, branches and tags.
  • about 10 active branches and many legacy-non-active branches. The active branches were required to be migrated into the GIT system.
  • few tags which are not really needed.
  • less than 5000 revisions which were asked to be migrated into the git system - meaning: the commit-history is needed.
  • Many binary (too many) files committed into the repository including mp3 files, jar files, images and more.
  • trunk contains many deprecated projects and 2 active developement projects:
  • one is the major project that have all the branches.
  • another one that is valid only in its trunk version and can be migrated without saving the commit-history of it.
  • SVN-server that resides on an ubuntu-linux server.
  • The path to the repository root is http://svn/repo. This path will be referred to later on in the post and should be replaced with your repository root path in order to be used in your system.

The migration requirements:

  • Migrate from SVN to GIT preserving the 2 major developement projects only, while the other projects can not be migrated.
  • Main developement project migration of all active branches and trunk version (SVN-trunk ==> GIT-master-branch) including all commit-history.
  • One direction migration, meaning: once the migration is done, there is no need to merge GIT-commits back into SVN-repository.
  • Jenkins projects should be switched from SVN to GIT.
  • Once the migration is done, all clients should start working in GIT within a short time.
  • Each of the 2 major developement projects will have a separate GitHub/GIT-repository.
  • The work on the migration process will be parallel to the continous developement process, meaning: developers will continue committing changes to the SVN-repository during the whole process and the freeze-time - at the end of the process before switching to work in GIT - will be short as much as possible.

High-level description of the process flow

List of the migration-steps which - most of it - will be detailed in the following sections:

  • SVN repository backup - the first step before any other work is done!
  • SVN cleanup - for the best and smooth migration it is best to perform most of the cleanup in the SVN repository and leave only few cleanup actions to be done on the migrated GIT-repository.
  • Environment preparations - actions such as preparing a clean migration-folder, GitHub-company-account purchasing and GitHub-admin-user creation.
  • Migration-script preparation.
  • First migration from SVN to GIT and to GitHub.
  • End-to-end test of migration, client-side use-case and Jenkins-build.
  • SVN commit-freeze.
  • Team basic GIT and GitHub training short-session.
  • Jenkins-jobs migration from SVN to Git/GitHub.
  • SVN-related files cleanup and GIT-projects adjustment - meaning: remove all .svn folders and add build-products folders into gitignore files.

Working environment preparations

Before performing any migration-step, the working environment must be prepared in order to avoid delays in the process.

  • git command line should be installed on the working machine. See reference (2) for details about such installation.
  • svn should be installed as well for performing the cleanup mentioned earlier and for creating the authorized users file.
  • GitHub user should be created for you, be set as the company account owner and create a first repository. See reference (3) for details.
  • Generate SSH key in order for the machine you're running on to push repositories into the GitHub account. See reference (4) for instructions of how to perform it.

Migration preparation steps

Before starting to work on the migration you must create a text file (e.g. authors-transform.txt) containing all SVN users and their email and name information.

Run this command for creating the file: 

svn log -q | awk -F '|' '/^r/ {sub("^ ", "", $2); sub(" $", "", $2); print $2" = "$2" <"$2">"}' | sort -u > authors-transform.txt

and then fill it with the users real names and email addresses. Make sure you fill details even for users who are not working to the company anymore - don't delete it since the migration will fail for converting revisions that unknown user committed.


The second step I recommend to perform is to cleanup the SVN repository.

What I did was:

  • Backup SVN repository (using svnadmin dump utility)
  • I've created a special SVN tag which I've called it tags/legacy, I've created 3 sub-folders in it: trunk,  branches and tags and I've moved all depracated resources from all the SVN repository into it.
  • I've deleted all resources I was told specificly that I can delete safely


In my case there were a second sub-tree in trunk that I was allowed to move as is without the need to preserve the commit history, therefore I've created a new repository in GitHub, created a new local repository, SVN-exported the project into it, committed the files into the local repository and uploaded it to GitHub.

Main migration script

In order to perform a repeatable migration process - which were required because of the need to run it more than once during the migration process - I've created a shell script. I've even configure it to run using a jenkins job but this is not a must for the process.

First of all I'll describe the basic blocks of the script.

As first step I've created a new empty folder (in my case: /opt/svn2git but it can be anywhere as long that it is empty, have the needed permission and no-one is expected to access it and messup your work...)

SVN to GIT migration command

The basic command to use for that purpose is git svn. The format of the full command which I've used is:

git svn clone -s --no-metadata --prefix=svn/ --no-follow-parent --authors-file=transform.txt http://svn/repo <target-repository-name> --user=<SVN user> --ignore-paths=http://svn/repo/tags

The first time you run the command it can take hours to be done, depending on the size of the repository and network performance.

It is recommeneded to run it manually and see that it works OK.

Please notice that that command should run in the repository parent folder (e.g. /opt/svn2git) while all other git command should run in the root of the created local repository folder (e.g. /opt/svn2git/company-main).

Once it is done running, a new git repository is created which contains a replication of your SVN repository (e.g. for my case: /opt/svn2git/company-main).

The created git repository contains all the branches you had in SVN repository as remote branches with both svn/ and origin/ prefix.

You can see the list of all branches by running:

git branch -a

An example output can be:









Connect the local GIT repository with the matching GitHub repository

When you create a new repository in GitHub, you will see - on the repository web page - a list of command to perform for pushing the local repository into the GitHub one.

The command for connection the local GIT repository with the GItHub repository using SSH protocol is in the following format:

git remote add origin git://<company>/<target-repository-name>.git

Run it once and it won't be neccassary to inlcude it in the migration script.

Notice that this command should run in the local repository folder.

Local GIT to GitHub push command-sequance

For each branch in SVN you want to have a matching branch in GIT expect for one excetion which is trunk which in better renamed to be master for GIT and GitHub repositories.

I found out that the git push origin --all will not be good for my purposes therefore I've built a set of commands that is repeated for all branches but master (which has a bit different set of commands that I'll list as well).

For each branch add those command to the script:

rm -fr .git/rebase-apply

git checkout -f <branch-name>

git reset

git rebase svn/<branch-name>

git push -u origin <branch-name>

For the master/trunk migration, add those lines to the script: 

 rm -fr .git/rebase-apply

git checkout -f master

git reset

git rebase svn/trunk

git push -u origin master

Now that you have a script that perform 2 main actions:

  • migrate SVN repository to a local GIT repository.
  • Push all branches code from local GIT repository to GitHub repository.

You should run the script at least once in order to have the GitHub repository ready.

While the first run of the script may take a long time (took hours for me), each of the next run of it perform a delta-update of both the SVN-to-GIT migration (updates only the new SVN revisions since the last run) and the push to GitHub so it will be a very fast run. 

Migration story

Once the migration script was ready and I've got an approval for performing the actual migration, here are the final steps we performed:

  • I've make sure that all the developers performed the final SVN commits and I made them know that uncommitted files will force them to manually copy of those files into the GIT local repository without any SCM-merge-tool supporting it.
  • SVN commit freeze - this can be done using the SVN-ACL-mechanism but - in my case - we just annouced a commit-freeze.
  • I've run the SVN-to-GIT-to-GitHub script for the last time and validated that it runs with no errors and that I can see the latest commits in the GitHub repository.
  • We gave a short training session which included demonstatration of establishing a GIT/GItHub working environment and common developer-workflow along with basic git-concept explanation.
  • GIT cleanup from .svn folders and ignore-lists creation - the developers were instructed to help in performing that step. 

Beware of...

During the migration process I've encountered obsticles, so - in order to help you prevent getting into those issues - here are some warnings:

  • make sure that no one - but the user that you perform the migration with - have push privileges to the GitHub repository. Permit it only after the final migration. That includes company-account owners that have full privileges by-definition.
  • Inspect the migration log each time you perform any action. 

Last words

As I've already wrote in the preview of this article, it cannot be used as-is for migrating your company or project SCM in the same path, but it can help you in some aspects of it, whether it is a technical aspect or a conceptual one.

In any case, you're welcome to comment on it, ask questions that me or someone in Tikal's ALM team can answer or you can directly connect us.




Yoram Michaeli

Tikal ALM expert




DevOps Fullstack Tech Leader

DevOps Group