Git for Gnome

This is not a “let’s use git” post. This is a “here’s how we’d use git, if we did” post. With all the recent git talk, I decided I’d try learning it with one of my on-again-off-again projects, Pulse. Caveat: I am not an SCM geek. I don’t enjoy learning SCM systems for the fun of it. I just want to be sure that whatever we use fits our needs. (Further disclaimer: I actually like CVS more than I like SVN. Infer what you will from that.)

If you go looking for documentation on git, you’ll find information on how to set up your own repository, how to clone other people’s repositories, how to make your own little personal branches (and why you should), and how to push/pull/merge. What they generally don’t discuss is how to work with a central repository.

So here’s my day-to-day Gnome SCM activities, translated into git. These instructions assume that Yelp is stored in the mythical git repository ssh://git.gnome.org/yelp.git. If any git people spot something braindead, point it out.

Checking Out

git clone ssh://git.gnome.org/yelp.git

This will clone the entire Yelp repository into a new directory called yelp. Initially, that directory will be working on a local branch called master, which is branched from the master branch on the server. The alias origin is created to refer to the repository on the server.

To get updates from the remote repository (the analog to cvs|svn update), run

git pull origin

If you’re using lots of remote branches, you may need to run somethinng like

git pull origin master

Committing

So you’ve made some changes to some files. To see what’s been changed, run

git diff

Without any options, this shows the differences between the data on your file system and the data in the index. The index is basically all those local changes that you’ve told git you want to commit. Let’s say you’ve modified yelp-document.[ch]. To add your changes to the index, run

git add src/yelp-document.c src/yelp-document.h

Now git diff shows no changes, because all the changes are in the index. But they haven’t actually been committed to the repository yet. To see the differences between the index and the repository, run

git diff --cached

To commit these changes, run

git commit

If you’re thinking there must be a way to skip the git add step, you’re right.

git commit -a

This will find all the differences between your local files and the repository, add them to the index, and commit them. Of course, you still need to use git add to add new files.

Committing Remotely

All you’ve done in the steps above is commit to your local repository. Git people will tell you you should do this early and often, and then push your local changes when a suitable chunk of work has been done. So to commit your work to the central repository, there’s one more step to take.

git push origin

Remember that git clone set up origin as an alias for the remote repository you cloned. Without any extra options, this will merge the changes on your local branch (master) to the branch of the same name on the remote repository.

Branching

Git people will tell you to create a new local branch for any set of changes you’re working on. If you’re working on fixing some bug, make a branch for that bug fix. If you’re implementing some whizbang feature, make another branch for that. You can easily switch between these branches. To create a new branch, run

git branch whizbang-feature

This creates a local branch, branched from whatever you currently have checked out. If you currently have the stupid-bug branch checked out, and you want whizbang-feature to branch from master instead, run

git branch whizbang-feature master

This just creates the branch. Your local copy is still a checkout of whatever it was before you called git branch. To start working on the new branch, you’ll want to check it out from your local repository:

git checkout whizbang-feature

You can always see your local branches by running

git branch

Remote Branches

If you check out Yelp and run git branch, you’ll only see your own local branch, master. But Yelp has lots of branches in the central repository. We make them for every stable release series. So where are they?

git branch -r

The -r argument causes git to show the branches on the remote repository you cloned from. You refer to the remote branches by prefixing them with origin/, which you’ll recall is the alias for the remote repository. If you want to look at the stable gnome-2-18 branch, you could run

git checkout origin/gnome-2-20

But if you want to make changes, you should really create your own local branch instead.

git branch gnome-2-20 origin/gnome-2-20

Now you can commit your changes to your local branch, then git push them to the remote branch.

Creating Remote Branches

In Gnome, we create branches for each stable release series. As a maintainer, you need to create branches in the central repository. So you can create a branch like this

git branch gnome-2-20

But that branch is just in your local repository. To push the branch to the central repository, run

git push origin gnome-2-20

Now other users will see this branch when they run git branch -r.

Tagging
In Gnome, we tag our central repository for releases. So if you release Yelp 2.20.0, you need to create the tag YELP_2_20_0. Creating a tag in your local repository is simple:

git tag YELP_2_20_0

But we need this tag to be in the central repository. To do this, we git push the tag up:

git push origin tag YELP_2_20_0

When you clone a repository, you get all its tags. To see all the tags in the repository, run

git tag -l

And So On

Obviously, there’s a lot more to learn to make really effective use of git. But most of that information is readily available elsewhere. I mosty wanted to address how to work with (and maintain) a central repository, because most git documentation doesn’t. Comments welcome.