Re: Tilde spec - befuzzled

From: Jeff King <peff@peff.net>
Date: Feb 29, 2012, 07:34 UTC
Message-ID: <20120229073408.GA14181@sigill.intra.peff.net>
In-Reply-To: <CAH5451m=6XhRj1osN_Dw7zKvAW-jtru+EbCkRvo8aNRMbJS6bA@mail.gmail.com>

On Wed, Feb 29, 2012 at 12:18:07PM +1100, Andrew Ardill wrote:

Show 25 quoted lines

> >>>> '<rev>{tilde}<n>', e.g. 'master{tilde}3'::
> >>>> A suffix '{tilde}<n>' to a revision parameter means the commit
> >>>> object that is the <n>th generation grand-parent of the named
> >>>> commit object, following only the first parents.
> >>>>
> >>>> Hang on, *grand*-parents?
> >>>> ...
> >>
> >> Perhaps we should reword it as "n-th first-parent ancestor"?  Barring
> >> confusion about the position of the dashes, that leaves little room for
> >> error.
> >
> > I think we could either go "easier to read but not precise"
> >
> >        ... that is the <n>th generation (grand-)parent of ...
> >
> > or "may sound scary but correct"
> >
> >        the ancestor reached by walking the first-parent chain <n> times
> >
> > I am not sure which bucket "n-th first-parent ancestor" falls into.
> 
> The terms might be too technical, however my understanding was that
> HEAD^n takes <n> steps along a breadth-first traversal of the commit
> tree rooted at HEAD, while HEAD~n uses a depth-first traversal.

The term breadth-first has me confused, as it implies that we will traverse the breadth of the tree before descending to the next level of depth. As if foo^3 would mean "well, foo only has two parents, so go on to the next level of the tree". It is really a breadth-only traversal, and the tilde is a depth-only traversal.

Anyway, it seems to me the OP's confusion can be cleared up with s/grand-parent/ancestor/. Of course, while we are here, it might be worth expanding or improving the text if there are other confusing aspects (which I'm not sure there are).

-Peff