Using git-heads for branch summaries

When merging code in Git, I often want to see an overview of the branches in my local clone, and the branches on the origin (remote). Some of the questions that I ask:

  • Which local branches are out of date with their upstream branches?
  • What topic branches are available on the remote (candidates to merge)?
  • What is the oldest, or newest, topic branch in terms of most recent commit?

I've been getting answers to these questions using gitk, git log and git branch. But when I started wanting to see a list of branch heads ordered by last author date, the tools at my disposal weren't getting the job done. git branch -vv is close, but it doesn't order the branches by date, and always links tracking branches to their upstream branches.

Enter git-heads. This is a great little utility, essentially generating output like git log but filtering to show only branch head commits.

Default git-heads output

Ran with no arguments, git-heads produces output like the following:

Default git-heads output

Considering git-heads as a filter for git log, this output is perfectly reasonable.

Customized git-heads output

For my use cases, I typically want a list of branch heads that is more terse, and ordered by author date. git-heads supports a flexible set of options, so my desired output format was easy to achieve:

git-heads -a --author-date-order --format='format:%C(auto)%ad %h%d'

The above command generates output like the following. Notice that the branch head commits are ordered newest first, by author date in this case. I think of this format as a variant of git branch -vv.

Terse git-heads output

This output form makes easy work of my original questions.

  • Which local branches are out of date? After git fetch, out of date branches are shown by the local branch and the remote branch having different commits, with the newer of the two showing above the other in the output.

  • Which topic branches are on the remote? Just pipe the git-heads output to grep origin/topic/. I usually pipe instead to grep topic/ so local topic branches are also shown.

Changing git-heads default output format

My preferred output format from git-heads requires an inconvenient command line. The simple solution is to place the command in a shell script. Instead, I chose to make a small change to git-heads so that if it were executed with no arguments, default arguments would be retrieved the git config property heads.dfltargs, if present. This is this property in my ~/.gitconfig file:

$ git config heads.dfltargs
-a --author-date-order "--format=format:%C(auto)%ad %h%d"

The change to git-heads is small and self contained:

diff --git c/git-heads w/git-heads
index 5d8a78f..288895b 100755
--- c/git-heads
+++ w/git-heads
@@ -157,5 +157,15 @@ main() {

+if test "$#" -eq 0; then
+    # Set a nice default args in .gitconfig, like:
+    # [heads]
+    #     dfltargs = -a --author-date-order \"--format=format:%C(auto)%ad %h%d\"
+    dfltargs=$(git config heads.dfltargs)
+    if test -n "$dfltargs"; then
+        eval main $dfltargs
+        exit 0
+    fi
 main "$@"