Wouldn’t it be great if git had a revision number that always went up so that you could look at two of them and figure out which one was later than the other? svn, cvs, hg all have numeric commits that you can refer to, so why can’t git? It turns out that git does, it’s called git describe.

At its simplest git describe will output something that looks similar to this: v1.5.5.1-178-g1f8115b. In fact, now that I’ve given you this identifier, you could find exactly where I was in the git history when I ran git describe.

The identifier tells you that I was at the 178th commit after the v1.5.5.1 tag. Just in case history gets rewritten and the 178th commit changes or there are multiple 178th commits, we can use the hash g1f8115b to make sure it’s the right one.

Using git describe in this way you can create identifiers that work well in places where increasing version numbers are used (development snapshots, for example), but this wouldn’t be git-fu if there wasn’t more it could do.

If you use the –contains option, git describe can tell you where a commit is relative to a future tag. For example, the output of git describe --contains HEAD~90 is v1.5.5~7. It’s just as easy to refer to a revision after a tag as it is to refer to a revision before a tag.

You can also use things other than tags by using git describe --all which looks at any ref found in .git/refs/ (common directories in .git/refs/ are heads, remotes, and tags). These can be less helpful in the long run because heads and remotes often change. If you want to tell someone which commit you’re referring to without giving them an entire sha1, –all can be useful.