|Last week we slowly migrated Structured Dynamics‘ Google Code Projects to GitHub.We have been thinking about moving to GitHub for some time now, but we only wanted to move projects to it if no prior history and commits were dropped in the process. One motivation for the possible change has been the seeming lack of support by Google for certain long-standing services: we are seeing disturbing trends across a number of existing services. We also needed a migration process that would work with all of our various projects, without losing a trunk, branch, tag or commits (and their related comments).|
It was not until recently that I found a workable process. Other people have successfully migrated Google Code SVN projects to GitHub, but I had yet to find a consolidated guide to do it. It is for this last reason that I write this blog post: to help people, if they desire, to move projects from Google Code to GitHub.
Moving from Google Code to GitHub
The protocol outlined below may appear complex, but it looks more intimidating than it really is. Moving a project takes about two to five minutes once your GitHub account and your migration computer is properly configured.
You need four things to move a Google Code SVN project to GitHub:
- A Google Code project to move
- A GitHub user account
- SSH keys, and
- A migration computer that is configured to migrate the project from Google Code to GitHub. (in this tutorial, we will use a Ubuntu server; but any other Linux/Windows/Mac computer, properly configured, should do the job)
Create GitHub Account
If you don’t already own a GitHub account, the first step is to create one here.
Create & Configure SSH Keys
Once your account has been created, you have to create and setup the SSH keys that you will use to commit the code into the Git Repository on GitHub:
- Go to the SSH Keys Registration page of your account
- If you already have a key, then add it to this page, otherwise read this manual to learn how to generate one
Configure Migration Server
The next step is to configure the computer that will be used to migrate the project. For this tutorial, I use a Ubuntu server to do the migration, but any Windows, Linux or Mac computer should do the job if properly configured.
The first step is to install Git and Ruby on that computer:
To perform the migration of a Google Code SVN project to GitHub, we are using a Ruby application called
svn2git that is now developed by Kevin Menard. The next step is to install
svn2git on that computer:
Before migrating your project, you have to link the Google Code committers to GitHub accounts. This is done by populating a simple text file that will be given as input to
authors.txt file into a temporary folder:
Then, for each author, you have to add the mapping between their Google Code and GitHub accounts. If a Google Code committer does not exist on GitHub, then you should map it to your own GitHub account.
The format of this
authors.txt file is:
Take note of the first Google Code committer
(no author) mapping. This link is required for every
authors.txt file. This placeholder is used to map the initial commit performed by the Google Code system. (When Google Code initializes a new project, it uses that username for creating the first commit of any project.)
When you are done, save the file.
Now that set up is complete, you are ready to migrate your project. First, let’s create the folder that will be used to checkout the SVN project on the server, and then to push it on GitHub.
In this tutorial, we have a normal migration scenario. However, your migration scenario may differ from this one. It is why I would suggest you check out the different scenarios that are supported by
svn2git document. Change the following command accordingly. Let’s migrate the Google Code SVN Project into the local Git repository:
Make sure that no errors have been reported during the process. If it is the case, then refer to the
Possible Errors and Fixes section below to troubleshoot your issue.
The next step is to create a new GitHub repository where to migrate the SVN project. Go to this GitHub page to create your new repository. Then you have to configure Git to add a remote link, from the local Git repository you created on your migration computer, to this remote GitHub repository:
Finally, let’s push the local Git repository master, branches and tags to GitHub. The first thing to push onto GitHub is the SVN’s trunk. It is done by running that command:
Then, if your project has multiple branches and tags, you can push them, one by one, using the same command. However, you will have to replace
master by the name of that branch or tag. If you don’t know what is the exact name of these branches or tags, you can easily list all of them using this Git command:
Once you have progressed through all branches and tags, you are done. If you take a look at your GitHub project’s page, you should see that the trunk, branches, tags and commits are now properly imported into that project.
Possible Errors And Fixes
Fatal Error: Not a valid object name
There are a few things that can go wrong while trying to migrate your project(s).
One of the errors I experienced is a
"fatal" error message
"Not a valid object name". To fix this, we have to fix a line of code in
svn2git. Open the
migration.rb file. Check around the
line 227 for the method
fix_branches(). Remove the first line of that method, and replace the second one by:
Error: author not existing
While running the
svn2git application, the process may finish prematurely. If you check the output, you may see that it can’t find the match for an author. What you will have to do is to add that author to your authors file and re-run
svn2git. Otherwise you won’t be able to fully migrate the project.
I’m not quite sure why these minor glitches occurred during my initial migrate, but with the simple fixes above you should be good to go.