Subject: Re: Pretty format specifier for commit count?

From: Jeff King <[email-masked]>
Date: Tue, 20 Jan 2015 16:49:53 -0500

On Mon, Jan 19, 2015 at 05:17:25PM -0800, Josh Triplett wrote:

> > Can you be a bit more specific about the type count that you are after?
> > "git describe" counts commits since the most recent tag (possibly within
> > a specific subset of all tags). Is that your desired format?
> 
> That might work, since the repository in question has no tags; I'd
> actually like "commits since root commit".

That's basically a generation number. But I'm not sure if that's really
what you want; in a non-linear history it's not unique (two children of
commit X are both X+1). It sounds like you really just want commits
counting up from the root, and with side branches to have their own
unique numbers. So something like:

       C
      /
  A--B--D

  A=1
  B=2
  C=3
  D=4

except the last two are assigned arbitrarily. You need some rules for
linearizing the commits.

Git's default output order is deterministic when walking backwards
through history from a specific set of starting points. We keep a queue
of commits to visit, sorted by timestamp, with ties in timestamps broken
by whichever was added "first" (so two parents of a merge get the first
parent added first, then the second). E.g. (and remember we're walking
backwards from the tip here, but you could do the backwards walk and
then reverse it, and start numbering from the other end):

       C--E
      /    \
  A--B--D---F

If we start at F, we might visit F, E, D, C, B, A. Or maybe C before D,
but only if its commit timestamp is newer (and if they tie, we
definitely visit D first, because it will have been queued first).

But that's not deterministic as you add more starting points (either new
ref tips, or just new merges we have to cross). For example, imagine
this:

         G--H
        /    \
       C--E   \
      /    \   \
  A--B--D---F---I

If we start at I, then we might visit H and G first, meaning we learn
about C much earlier than we otherwise would. Then we hit F, and get to
C from there. But now it it may be in a different position with respect
to D!

I suspect your problem statement may simply assume a linear history,
which makes this all much simpler. But we are not likely to add a
feature to git that will break badly once you have a non-linear history. :)

I think in the linear case that a generation number _would_ be correct,
and it is a useful concept by itself. So that may be the best thing to
add.

-Peff