I’m sold on Git. The branching feature alone was reason enough for me to move from Subversion. However, the decision to move was the easy part. Migrating my projects, while not too painful, wasn’t trivial. I found that my knowledge of svn was actually a disadvantage as it made it easy to assume things about Git that simply weren’t true. This is ultimately how I went about my migration.
First, some assumptions:
- My projects are small. By small I mean that everyone working on code has shell access to the servers involved. It’s not open sourced, public, or any of that cool stuff. If you need to do something for large scale access, consider GitHub or gitosis.
- I have a semi-centralized need. None of the people on my projects are co-located. There is a definite need for a place to post code for review that everyone can access.
- I have a functioning, in-production Subversion repository and the transition must be seamless.
- My apps are Rails applications deployed using Capistrano.
- All of my servers/clients are running Fedora 9
- You understand the basics of Git.
That said, let’s dive in.
Step 1: Install Git
This is the easy step:
[local]$ sudo yum install git git-svn
Step 2: Convert your Central Subversion Repository to a Local Git Repository
This is key step to wrap your mind around conceptually. With svn you would first make a central repository and import something into it to get started. We’re about to do quite the opposite. Remember that in Git every instance is a repository. When we grab the contents of your existing project, we will be building the new repository locally, not on your server (that will come later).
Build a text file list of your existing authors
In order to maintain some continuity with your existing svn logs, we need to peg the svn user names of people who have committed to your svn repository to git user names. This is quite easy to do. Just create a text file with lines that look like this:
markmcb = Mark A. McBride <mark@markmcb.com>
example = Example Person <person@example.com>
... etc.
Save this file. I’ll refer to it later as svn-to-git-authors. (If you have a lot of authors, check out Josh’s script to automate the creation of this file.)
Clone your Subversion database to a Git repository
This next step is so nice. With one command and the help of the file we just created, we’ll create an almost ready to use git repository. The command is simple: git clone “what” “where”. Or something like:
[local]$ cd /path/of/your/liking
[local]$ git svn clone svn+ssh://yourserver.example.com/path/to/your/repository \
./myrepos.git --authors-file=svn-to-git-authors
Hit return and relax as the magic happens. Depending on the size of your repository, this could take some time.
Set some basic configuration options
There are hundreds of configuration options for Git, but I’m only going to touch on a few critical ones. Specifically, let’s tell our new Git repository who we are and set the stage for working with a remote, semi-centralized repository.
[user]
name = Mark A. McBride
email = mark@markmcb.com
The user settings are pretty straightforward. Just ensure they match what you had before in the authors file and it’ll be very easy for you to keep track of who has done what. In addition, you may see a section relating to svn. Once you no longer need to pull data from that repository (which, unless your repository is busy, is right now), you can delete this section.
From here you’re ready to get to work. You have a functional repository. However, if you plan to work with anyone other than yourself, you may need to interact with a public repository.
Step 3: Setup a Public Repository
The steps to establish a repository that you can access over ssh are pretty simple. Just ssh to the public server and (you may need to setup permissions to write depending on the folder do the following in):
[publicsrv]$ cd /srv/git
[publicsrv]$ mkdir publicproject.git
[publicsrv]$ cd publicproject.git
[publicsrv]$ git --bare init
That’s all you need to do on the server. The critical thing to note is that bare reference. This tells Git that there is no working copy, i.e., the files you are coding. All this repository will track are the changes and not actually store the files (though anyone can clone this repository and get the files).
Point Your Repository to the Public One
Back on your local machine, you just need to run one command to make your repository aware of this newly created public version:
[local]$ git remote add origin ssh://publicsrv.example.com/srv/git/publicproject.git
Now you have a remote repository named origin from which your local repository can fetch all of its data from. Look in you .git/config file for details. The last step is simply to push the files you have in your local copy to the server.
[local]$ git push origin master
After running this, anyone on your team with an ssh account can clone the repository with:
[local]$ git clone ssh://publicsrv.example.com/srv/git/publicproject.git
If you’re lazy like me, and just want to be able to type git push/pull instead of typing out the public server’s name each time, add the following to your .git/config file:
[branch "master"]
remote = origin
merge = refs/heads/master
And with that, you’re done with the repository migration.
Step 4: Final Rails Tweaks
Your Git work is done. These last items are final notes to make your new repository play nice with your Rails app.
Tell Capistrano about Git
The very last thing you have to do is tell Capistrano to pull your Rails app out of a Git repository during deployment rather than from Subversion. This is quite simple. In your deploy.rb file, add this line:
set :scm, :git
Also, be sure to set your repository URL to the new location.
Ignore logs and temporary files
You may need to create some of the directories depending on how your svn repository was set up. Insert empty .gitignore files in them to ensure Git doesn’t ignore them.
[local]$ mkdir tmp
[local]$ mkdir log
[local]$ mkdir vendor
[local]$ touch tmp/.gitignore log/.gitignore vendor/.gitignore
Add the following to .gitignore in your root folder to ignore standard Rails files that you don’t want in your repository:
.DS_Store
log/*.log
tmp/**/*
config/database.yml
db/*.sqlite3
That’s it. Your Rails app is now ready to modify and deploy from Git.
References:
