Develop with Git on a Google Code Project

Tuesday, May 20, 2008

Do you often work offline? Wish you could make local commits that you can reorganize and upload later? Would you like to have your own copy of the entire history of the project which you can peruse at your leisure?

Do you want to serve code and its history to others? Have changes you want to share but it's too early for the public?

Working on several issues in parallel? Need to save some of those experimental changes after all? Need to create, merge, clone and otherwise manipulate branches cheaply and offline?

You can do all this, and more, with Git, a version control system rapidly growing in popularity. You can readily find Git tutorials, but since I'm writing this post, I'll shamelessly plug my own guide to Git!

Although Google Code natively speaks Subversion, you can easily use Git during development. Searching for "git svn" suggests this practice is widespread, and we too encourage you to experiment with it.

We focus on importing a complete Git repository from a Google Code project organized in the recommended fashion. The git-svn manpage thoroughly describes how to handle other cases such as nonstandard layouts, importing only a few revisions, sharing exported repositories, and so on.

1. Import

First we perform the equivalent of a svn checkout. In an empty subdirectory, run:
$ git svn clone --username your-name -s
# older versions of git: replace "-s" with "-Ttrunk -bbranches -ttags"
Like a Subversion checkout, you now have a local copy of your project. Unlike a Subversion checkout, you also have a local copy of the entire history of the project. Try:
$ git log          # print summary of history
$ git diff HEAD^^ # diff against two revisions ago
$ gitk # graphical history browser
$ qgit # Qt-based history browser
These read from local disk, and work even when you're offline.

2. Develop

You now have a fully fledged version control system at your fingertips. You can checkpoint locally. You can create, merge, and destroy branches cheaply. You can checkout long-lost ancient code. You can stockpile and reorganize your commits.

Any Git tutorial teaches these abilities. We'll content ourselves with simple examples.

First, the basics. Edit code as usual, but if you add or remove files, type:
$ git add FILENAME...
$ git rm FILENAME...
There's no need to inform Subversion as git-svn will do so later. In fact, we only talk to Subversion via git-svn, and never run pure svn commands.

The only other git command you must know is:
$ git commit -a
which saves the current state of your project locally. You can see them with git log. Commit early and commit often!

Now for a couple of tricks. Let's say you've made several commits and suppose you want to undo the last one:
$ git reset --hard HEAD^
Or suppose you want to get a certain file from five commits ago:
$ git checkout HEAD~5 foo.c
We've barely scratched the surface. There are countless other features worth learning, particularly Git's extraordinary lightweight branches.

3. Update

Periodically, you should get online and fetch the latest changes from Google Code with:
$ git svn rebase   # think "svn update"

4. Export

Submit your commits to Google Code with:
$ git svn dcommit  # think "svn commit"
This converts each of your Git commits into Subversion commits and uploads them, provided your repository is up-to-date. To keep working, go back to step 2.

Stay Tuned!

We've seen it's easy to setup Git with a Google Code project. If distributed version control systems sound intimidating, the above is a great way to get your feet wet. You can always delete the directory and go back to Subversion.

But what if you keep your project in a Git repository, and you want to export it to Google Code? So you'd have a canonical read-only Subversion mirror of your project?

Exporting a Git project to Google Code requires only a handful of commands. We'll show you how in a future post.