Category: git

Now that you know more or less how things in git work, it’s time to set up your repositories to contribute with gnome. First thing you want to do is to get the latest source code, but jhbuild does that for you (see https://wiki.gnome.org/GnomeLove/JhbuildIntroduction). Acutally, for me, jhbuild was getting the latest stable branch (i.e. gnome-3.12 at the moment) and not master, which is the most recent development branch. In order to force jhbuild to get the master branch for evince (which is the project I am working on) I had to add this line to my jhbuildrc:

branches[‘evince’] = ‘master’

So jhbuild downloaded the source to the ‘checkoutroot‘ set in jhbuildrc. You can go there and type ‘git status‘ to see that it is a git repository. After building, I get this:

# On branch master
# Untracked files:
#   (use “git add …” to include in what will be committed)
#
# test-driver
nothing added to commit but untracked files present (use “git add” to track)

Don’t worry about this untracked file. It’s always there (at least for me!).

If you are very brave, you can start making changes right there and then, but it is probably better to create a branch on which you can test and develop stuff without messing up the stable code. To see the existing branches, just type

‘git branch‘ or ‘git branch -v‘.

The -v option will inform you what was the latest commit on each branch. I think it’s useful. You will probably see only one branch, called ‘master’ marked with a *. The * is there to show you that this is the branch you’re at. Go ahead and create another branch with

‘git branch dev‘.

You can replace ‘dev’ with a better name. In my case it is called annotations, since this is evince’s feature I will work on. Check the branches again. See the new one? You can change to this branch using:

‘git checkout dev‘.

So far so good. Let’s say you change something there, and it’s ready to be committed:

‘git commit -a‘.

The -a option will include all the changes to all the previously existing files. Make sure that the code still compiles and runs with the new commit! Check the log:

‘git log‘.

See the commit there? So everything is good. Now what? Well, I doubt you will have permission to push this directly to gnome’s git. Someone needs to revise the changes you made and, at least for the first few changes, you will receive a lot of feedback. But how can they revise your changes if your commit is local? If you are fixing a bug, you can create a patch from your commit and attach it there. For creating a patch from one commit, you need to run:

‘git format-patch -1 sha‘.

Where “sha” is a big string with numbers and letters that appears right after the word ‘commit’ when you see the log. Now, if you are a gsoc student like me, you wouldn’t like to flood your mentor with patches every time you make a change. My solution was to create a github account and push my commits there. So every time my mentor wants to check what’s new, he can take a look there. (Here goes a big thank you to jaliste, my mentor, and gpoo, my sub-mentor, for helping me organize this!!)

Github has instructions on how to set up a repository (https://help.github.com/articles/create-a-repo). You can follow this until step 1. Don’t create the readme file, you already have files. Instead, go straight to step 3. What you need to do is add the github rep as a remote repository, in parallel with gnome’s git. If you go to the directory where your project is and type

‘git remote -v‘

you will see that you have one remote entry, called origin, that points to gnome’s git. Now create another entry:

‘git remote add github https://github.com/username/yourprojectname.git‘

Since I had to start programming for gnome, I had to start learning how to use git. I had heard of git before, about all its wonders… but I was ok with svn, I knew how to work with it and all the other projects I was working on were using svn. Of course these projects did not have hundreds or thousands of collaborators 😉

It was a rough patch in the beginning, and I still struggle with conflicts and rebasing and such from time to time, but it’s getting better. I decided to write this for svn users that suddenly had to change to git, since the shift, at least for me, was not so straightforward as some people claim.

This need to be *really* clear:

Now let me show a picture of how I see the cycle of information on svn and on git.

While commits in svn will send your changes to the server (and keep them safe there), git commits are just “checkpoints” which help you keep changes related to some task together. I had a lot of troubles with this in the beginning, probably because I also use svn as a backup system. If I am working on something on one machine, and need to change to another, I would commit my work to svn and then update the code on the other side. You might imagine that they were not the cleanest commits… In git this would not work. My commit will only stay local, unless I push it to the server. Of course you can push this to the server, but then when someone wants a patch from your changes you will need to reorganize the commits by rebasing and squashing and editing until you get a clean one. Trust me, you don’t want to keep rebasing all the time… specially if these commits are not the latest ones. The lesson I learned from this was: git is *not* a backup system. A commit should be a clean, self-contained, change in the code for a specific purpose. It goes without saying that the change must compile and run!

Now about the checkout. The equivalent of an svn checkout in git is clone. This command will get the source from the server and create a copy on your machine. Git’s checkout is a completely different thing. It is related to branches. While svn branches are created on the server from where you can check them out, git branches are local or on the server. And these are not necessarily in 1:1 correspondence. You can have 5 local branches and the server can have 3, and you can push commits of any of your local branches to any of the server’s branches (although it is safer if you keep a 1:1 correspondence for pushes). Git checkout will only change the local branch you are working on (quite fast actually, so you can do this all the time). Currently I am keeping three branches, one “master” which is always in sync with Gnome’s, one “multiscreen” with some commits I had regarding multiscreen support, and one “annotations” with the commits related to annotations.

I hope this is more or less helpful to understand some of git’s semantic.