commit count calculation in git-describe

Question

Can anyone explain why git describe uses a count as "the number of commits which would be shown by git log tag..input" [from git-describe(1)]?

Conceptually I had thought git-describe used the number of commits since the tag as a monotonically increasing counter. However, it seems it actually uses the number of commits reachable from 'input' minus those reachable by 'tag'. Why is that?

In this particular case, I've created a release tag ("1.0.0") and then a patch release ("1.0.1") on a branch ("1.0"). I've merged up [see http://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html] the branch changes to master. Yet when I git-describe a more recent commit on master the count matches the output of git log tag..input. I expected it to match git log --ancestry-path tag..input.

Thanks.

Answer 1

git describe is a way to communicate the HEAD in a meaningful way. It is a simple answer to the question "Where am I in the history?" or "What version of the code is this?"

So, when you run the command it starts where you currently are, whether that is the tip of master, some other tag, or just a random commit. From this starting point it counts backwards through commits until it finds a tag. From there it will print the tag, number of commits counted, then the short commit number.