My git workflow

08 September 2011

Somehow, I find myself writing the same email to introduce people to git over and over again. But no more ! Now, I will only send out links to this blog entry.

Git can be intimidating at first, even though it is probably the most forgiving source control system out there. There are plenty of great tutorials on git these days. I assume that you have read enough of them to understand the absolute basics of cloning a repo, pulling to update your repo, and how to commit. In other words, you’ve run git clone, git pull and git commit before.

The key to working with git happily is to use branches liberally; if in doubt, branch. And the key to working with branches is understanding git rebase. In particular, git rebase -i will make you fall in love with git. It lets you not just edit committed patches, it also lets you combine patches, reorganize them etc. Once the initial excitement over interactive rebase wanes, try out interactive add (git add -i) to renew the bliss.

Once the basics are out of the way, you will want to implement some extension to whatever you’ve cloned and pulled, and then submit that back upstream for inclusion. That usually involves working on your own for a bit, and then generating and sending out patches of your work for review and merging upstream. Changes you make should always go onto private (‘topic’) branches; create a new branch for each piece of distinct work. The overall workflow for this is

    git checkout master
    git pull # make sure we have the latest bits
    git checkout -b dev/feature
    ... edit/add/commit until happy, with an eye towards having your
    branch constitute an easily reviewable patch series; when
    working on the branch for longer, pull master repeatedly and
    rebase your branch ...

Once your work is ready to be shared with the rest of the world, do the following to generate and mail out patches

    git checkout master
    git pull
    git rebase master dev/feature
    git format-patch -o /tmp/patches master
    git send-email --to=hackers@example.org --compose --subject 'Awesome feature' --thread /tmp/patches

When changes need to be made to address review comments, work them into your dev/feature branch, using interactive rebase to add them where needed in the patch series, then repost.