Blog | object.io

Easy local code-review with git

When multiple developers contribute to a project, keeping on top of the constant flow changes can be a challenge. The following simple review workflow assumes a shared git-repository with a fairly linear commit-history, that is, not having too many merge-commits.

So, assuming a fairly linear history of commits from multiple developers, how do you easily keep track of what you have already read through and reviewed? Easy, use a local branch as a bookmark. This tiny script makes it trivial to add or update such a branch:

#!/bin/sh
NEW_BASE=${1?"Usage: $0 <treeish>"}

git branch --force reviewed $NEW_BASE || exit 1

echo Marked as reviewed: `git rev-parse --short reviewed`

Save this as a new file called reviewed.sh in your PATH.

Usage is extremely simple:

reviewed.sh 369b5cc
reviewed.sh master
reviewed.sh v1.0.7
reviewed.sh HEAD~5

Running one of these commands will mark the given treeish as reviewed, and when you look at your commit-history in a visual tool such as git gui or gitx, the reviewed branch visually indicates how far you have gotten. Note how both commit-IDs, branch names, tags, and relative commit-IDs can be used as argument.

You can also utilize this review bookmark from the commandline. The following shows you all commits added to master since your last review:

git log reviewed..master --reverse

You can add a --patch to that command to see the full diff for each change. Adding --format=oneline just shows you the commit-IDs and first line of the commit-message.

Once you’ve read all the latest commits on master, simply do a

reviewed.sh master

and you’re done.

Why not use a tag?

I find it convenient to be able to do a push of all tags to the central repository with

git push --tags

and this would share such a private review-tag. As this is my private reminder of how far in the commit-history I have reviewed, sharing it is just confusing to other developers.

Notice: Any commits which are added only to the reviewed branch are unreferenced when you mark a new treeish as reviewed. Just something to keep in mind.

How do you keep track of the flow of changes?

Simple git workflow with hack and ship

I use git as my primary version control tool for all internal development, configuration files, and collaborative development. As branches are virtually free with git, it makes a lot of sense to create short-lived feature-branches for each new thing you start working on. This does mean a bit of shuffling back and forth to integrate changes from others in your local work, but this “pull changes and rebase my work” workflow can be greatly eased by these small scripts.

For more than a year I’ve been using two small shell-scripts called hack and ship to manage local feature-branches. Hat-tip goes to ReinH for the original version of these. Notice these shortcuts are only usable when you work on a feature branch based on master, not remote branches in general.

hack pulls down the latest changes from the central origin/master branch, and rebases your local feature-branch on this new master. The end result is all the latest changes are integrated, and you will be able to push your commits without adding an unnecessary merge-commit to the shared history.

#!/bin/sh -x
# Exit if any error is encountered:
set -o errexit
# git name-rev is fail
CURRENT=`git branch | grep '\*' | awk '{print $2}'`
git checkout master
git pull --rebase origin master
git checkout ${CURRENT}
git rebase master

ship is a quick way to merge your current branch to master, and push the result to the central repository branch called origin/master.

#!/bin/sh -x
# Exit if any error is encountered:
set -o errexit
# git name-rev is fail
CURRENT=`git branch | grep '\*' | awk '{print $2}'`
git checkout master
git merge ${CURRENT}
git push origin master
git checkout ${CURRENT}

Usually when a feature is completed, I run hack, run all code-tests for the project, the run ship. Taken together, the process is automated and looks like this:

hack && rake && ship

where rake runs all relevant tests, and exits with a non-zero error-code. If one or more tests fail, the changes are not shipped (due to the nature of && between the commands), and a fix can be committed before sharing the changes with other developers.

What is your process for managing feature branches in git?

Update: See also the chop script.