I used to use subversion both professionally and in my own projects and had really hard time figuring out what could be the benefit of git's apparent added complexity. This complexity reminded me of Clearcase which had done nothing but made my life miserable whenever I was forced to use it. Thus when I started contributing to both Malva and later Jato, which are both github based projects, one of the first challenges was to start using and, yes, even understanding Git.
Although the internet is full of more or less thorough git tutorials the truth is that because of its flexibility it can be a totally different beast from project to project and from developer to developer. Please keep this in mind when reading any git material, including this blog!
You should probably have a glance at some git tutorial first, but if you are like me, pass the dull reading and just start using it. Siberia teaches you!
So here is how I use git to develop Jato.
Setting up git to work with Jato
Install git.
Tell git your name, email and signature acknowledgement:
git config --global user.name "My Name"
git config --global user.email "my@email.address"
git config format.signoff true
You need to do this only once.
Then you need a copy of the Jato repository on your computer.
git clone https://github.com/penberg/jato.git
(you'll get the github project clone url from the project's front page).
By default you are now working in the master branch where you should never ever work in! Thus lets create a work branch and switch there with:
git checkout -b my_work_branch
You can check which branch you are in with:
git branch
and switch between branches with
git checkout branch_to_switch_to
Anyway lets stay in my_work_branch. Here you will do your changes, hopefully not that many. Why? Jato people prefers to develop in small clean increments. It makes the review process and synchronization between people a lot easier. For example when I refactored a 250+ function interface I did it in about ten independent separate batches of work over many weeks (Git calls these increments as patches but well get back to that in few moments). Just keep in mind that it is better to do the work in too small than in too large increments.
Once your have made the increment just throw the branch away, those are dirt cheap in git!
Doing the work
Where were we? Oh yes, so we are about to start work in my_work_branch. First make sure Jato build is green with
make check
If all tests pass you are green to go doing changes and adding new files. If you add a new file and want git to know about it just
git add *my_file.abc
When making changes you should periodically try to get the build to pass. Usually it is also a good point to make a commit to your local clone:
git commit -a -m "A brief but descriptive commit comment"
Repeat and rinse until you have achieved a small increment. Maybe you have added a single unit test and the piece of functionality that it tests, great! Time to throw it to the wolwes, i.e. to Jato maintainer.
Patch
As mentioned earlier git has a concept called patch. Forget any binary patches you might have encountered when updating applications or operating systems. In git world a patch is simply a textual output of diff your_version some_other_version and a few extra lines on top of that. Luckily git does most of the work for you.
To do a patch from the latest new commit in your branch first make sure that you have the latest changes from the github master:
git checkout master
git pull
git checkout my_work_branch
(and if there were any changes:)
git merge master
You must resolve and commit any merge conflicts. Once done and the build is green you are ready to create the patch:
git format-patch -s HEAD^
This creates a text file called something like your-commit-comment.patch. If you only did a single commit on top of master you are done. If there were more than one commit you must squash them into a single commit. There are many ways of doing this. I prefer this way:
git checkout master
git checkout -b my_merge_branch
git merge my_work_branch --squash
git commit -a -m "My only commits commit message"
And now you do the patch exactly the same way as previously shown:
git format-patch -s HEAD^
Now just email the patch to a Jato maintainer!
Looking back at this blog entry reminds me why I thought git was complex :). Fortunately and unfortunately the only way to learn git is to use it! In hindsight it didn't take that long to learn the essentials, although maybe the fact that I had a linux kernel maintainer helping me made it a little bit easier. Luckily all Jato developers have the same benefit!
Nuuksio National Park, Espoo, Finland, Dec 2009. The real Narnia
