bill and his blog

git revision numbers as refs (note to self)


Credit goes to tazjin@ for this idea :)


Using git revisions to pin versions is nice, but git SHAs aren't very human-friendly:


Let's assign monotonically increasing natural numbers to each of our repo's mainline commits and create git refs so we can use references like [r/123]( instead of 2911fcd.


Let's start-off by assigning "revision numbers" as refs for each of the mainline commits:

for commit in $(git rev-list --first-parent HEAD); do
  git update-ref "refs/r/$(git rev-list --count --first-parent $commit)" $commit

We can verify with:

λ git log --first-parent --oneline

If everything looks good, we can publish the refs to the remote:

λ git push origin 'refs/r/*:refs/r/*'

Staying Current

In order to make sure that any newly merged commits have an associated revision number as a ref, add something like the following to your CI system to run on the builds of your repo's mainline branch:

λ git push origin "HEAD:refs/r/$(git rev-list --count --first-parent HEAD)"


To verify that the remote now has the expected refs, we can use:

λ git ls-remote origin | less # grep for refs/r

If that looks good, you should now be able to manually fetch the refs with:

λ git fetch origin 'refs/r/*:refs/r/*'

Or you can use git config to automate this:

λ git config --add remote.origin.fetch '+refs/r/*:refs/r/*'
λ git fetch origin

Now you can run fun commands like:

λ git show [r/1234](
λ git diff [r/123]({4,8} # see changes from 1234 -> 1238

Thanks for reading!