Re: [PATCH v2] rev-list docs: clarify --topo-order description

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 17, 2012, 17:18 UTC
Message-ID: <7v1uj5wi72.fsf@alter.siamese.dyndns.org>
In-Reply-To: <874no1hnfg.fsf@thomas.inf.ethz.ch>

Thomas Rast <trast@inf.ethz.ch> writes:

Show 13 quoted lines

> However, suppose we knew generation numbers.  I haven't actually looked
> into the old threads again, but my understanding was that they are
> numbers g(C) attached to each commit C such that
>
>   g(C) = 1 + max(g(P) for P a parent of C)   for non-root commits
>
>   g(C) = 0                                   for root commits
>
> They are invariant given the commit, so they can be cached.
> ...
> I hope I got that right.  The order of commits is still entirely
> determined by the choice of "any tentative source", but the algorithm
> should now stream nicely once the generation numbers are known.

That matches the definition of generation number I remember from the old discussion. Now look at the illustration in this discussion again:

      ---A---B---C---D
                      \
    ---1---2---3---4---* = HEAD

and an excerpt from the message you are respoding to:

  Think of the sample history above, and imagine
  that the numbered ones are based on the current 'master', but that
  the alphabet ones are based on an ancient maintenance release that
  is 1000 generations behind (think of me running the command after
  finishing the day's integration cycle, sitting at the tip of 'pu',
  where the last topic merged is meant to be eventually merged to
  maint-1.7.9).  All of the commits depicted in the picture will have
  the commit timestamps in the past few hours.  Ancestors of A and 1,
  not drawn in the picture, were made yesterday or before.

The numbered commits 1 2 3 4 are building on top of recent "master", while alphabetized A B C D are building on aged maintenance track. The difference in generation numbers between 1 and 2, 2 and 3,... A and B, B and C, C and D are all one, and HEAD (the tip of 'pu') would have generation number of commit 4 plus 1, as commit 4's generation number would be a thousand or more ahead of that of commit D. And there are a thousand ancestors of '1' with larger generation numbers than 'D'.

When the user runs "git log" (i.e. the casual "the last few commit" macthes), the expectation of the user is "I want to see what I did recently". If you substituted the commit timestamp with such a generation number, how would that expectation satisified?

Generation numbers is a clean solution to avoid giving an incorrect range result when there are clock skews (cf. the use of SLOP in revision.c::still_interesting()), but it is not a good substitute when the user is more interested in absolutely correct topology (in other words, the user is more interested in both rougly wallclock time order and seeing the result soon --- which brings us back to the original "short latency is vastly preferred _as long as_ it produces the result the user wants to see").