On Wed, Feb 29, 2012 at 12:18:07PM +1100, Andrew Ardill wrote:
> >>>> '<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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html