Tilde spec - befuzzled

Tilde spec - befuzzled

[Luke Diamand]

The documentation for caret and tilde specs is making my head hurt, even 
though they always _do_ exactly what I want. And I thought I understood 
them until I read more carefully.

   A suffix '{caret}' to a revision parameter means the first parent of
   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
   '<rev>{caret}'

So far, so good.

'<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?

So HEAD~1 won't give me the *parent* commit of HEAD, but the 
*grandparent* commit of HEAD (following only the first parents) ?

How do I get to the *parent* commit of HEAD?
Does that mean that HEAD~ != HEAD^
And why does HEAD~1 always look exactly what I would naively call the 
'parent' of HEAD?

I'm pretty sure I'm missing something very obvious. I think it must 
confuse other people as well though, as it's quite easy to find webpages 
around that claim that tildes give the _parent_ commit.

Thanks
Luke

Re: Tilde spec - befuzzled

[Andreas Ericsson]

On 02/28/2012 10:07 AM, Luke Diamand wrote:
> The documentation for caret and tilde specs is making my head hurt, even though they always _do_ exactly what I want. And I thought I understood them until I read more carefully.
> 
> A suffix '{caret}' to a revision parameter means the first parent of
> that commit object. '{caret}<n>' means the <n>th parent (i.e.
> '<rev>{caret}'
> 
> So far, so good.
> 
> '<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?
> 

Replace "grand-parent" with "ancestor" and your head might hurt a
little less. Caret only ever describes parent, while tilde can
describe either parent or n'th generation grand-parent. Since parent
and grand-parent are all ancestors, that would be a better term.

I believe this stems from the fact that most git-gurus use a single
caret to specify 'parent' and only go to the tilde when they want
grandparents. It might be because caret was implemented first, or
because of english keyboard layout. On swedish keyboards, using tilde
is far more convenient than using caret, so that's what I mostly use
when I want the parent of a single-parent commit (it requires only
one hand and no thumb-acrobatics even on my laptop).

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re: Tilde spec - befuzzled

[Thomas Rast]

Andreas Ericsson <ae@op5.se> writes:

> On 02/28/2012 10:07 AM, Luke Diamand wrote:
>> The documentation for caret and tilde specs is making my head hurt, even though they always _do_ exactly what I want. And I thought I understood them until I read more carefully.
>> 
>> A suffix '{caret}' to a revision parameter means the first parent of
>> that commit object. '{caret}<n>' means the <n>th parent (i.e.
>> '<rev>{caret}'
>> 
>> So far, so good.
>> 
>> '<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?
>> 
>
> Replace "grand-parent" with "ancestor" and your head might hurt a
> little less. Caret only ever describes parent, while tilde can
> describe either parent or n'th generation grand-parent. Since parent
> and grand-parent are all ancestors, that would be a better term.

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.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: Tilde spec - befuzzled

[Junio C Hamano]

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

>>> '<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.

Re: Tilde spec - befuzzled

[Andrew Ardill]

On 29 February 2012 06:20, Junio C Hamano <gitster@pobox.com> wrote:
> Thomas Rast <trast@inf.ethz.ch> writes:
>
>>>> '<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.

A better form for the description might come from that formulation of
the process, rather than the 'generational' formulation.

Regards,

Andrew Ardill

Re: Tilde spec - befuzzled

[Jeff King]

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

Re: Tilde spec - befuzzled

[Andreas Ericsson]

On 02/29/2012 02:18 AM, Andrew Ardill wrote:
> On 29 February 2012 06:20, Junio C Hamano<gitster@pobox.com>  wrote:
>> Thomas Rast<trast@inf.ethz.ch>  writes:
>>
>>>>> '<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.
> 
> A better form for the description might come from that formulation of
> the process, rather than the 'generational' formulation.
> 

I doubt it. Most non-programmers have no notion of the difference
between breadth-first and depth-first. You have to work with trees 
or graphs in some form before breadth and depth become intuitive
to read in tech docs.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re: Tilde spec - befuzzled

[Andreas Ericsson]

On 02/28/2012 08:20 PM, Junio C Hamano wrote:
> Thomas Rast<trast@inf.ethz.ch>  writes:
> 
>>>> '<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 ...
> 

(grand-)parent and ancestor are interchangeable while the parentheses
remain, although the former looks a bit clumsier in text.

> 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.


-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re*: Tilde spec - befuzzled

[Junio C Hamano]

Andreas Ericsson <ae@op5.se> writes:

> On 02/28/2012 08:20 PM, Junio C Hamano wrote:
>> Thomas Rast<trast@inf.ethz.ch>  writes:
>> 
>>>>> '<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 ...
>
> (grand-)parent and ancestor are interchangeable while the parentheses
> remain, although the former looks a bit clumsier in text.

Ok, then something like this...

-- >8 --
Subject: Documentation: do not assume that n > 1 in <rev>~$n

We explained <rev>~<n> as <n>th generation grand-parent, but a reader got
confused by the "grand-" part when <n> is 1.

Reword it with "ancestor"; with the "generation" and "following only the
first parents" around there, what we try to describe should be clear
enough now.

Noticed-by: Luke Diamand <luke@diamand.org>
Helped-by: Thomas Rast <trast@inf.ethz.ch>
Helped-by: Andreas Ericsson <ae@op5.se>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/revisions.txt |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index b290b61..1725661 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -101,7 +101,7 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
 
 '<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
+  object that is the <n>th generation ancestor of the named
   commit object, following only the first parents.  I.e. '<rev>{tilde}3' is
   equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to
   '<rev>{caret}1{caret}1{caret}1'.  See below for an illustration of

Re: Re*: Tilde spec - befuzzled

[Luke Diamand]

On 29/02/12 19:13, Junio C Hamano wrote:
> Andreas Ericsson<ae@op5.se>  writes:
>
>> On 02/28/2012 08:20 PM, Junio C Hamano wrote:
>>> Thomas Rast<trast@inf.ethz.ch>   writes:
>>>
>>>>>> '<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 ...
>>
>> (grand-)parent and ancestor are interchangeable while the parentheses
>> remain, although the former looks a bit clumsier in text.
>
> Ok, then something like this...

This change works for me. Ack.

Thanks,
Luke


>
> -- >8 --
> Subject: Documentation: do not assume that n>  1 in<rev>~$n
>
> We explained<rev>~<n>  as<n>th generation grand-parent, but a reader got
> confused by the "grand-" part when<n>  is 1.
>
> Reword it with "ancestor"; with the "generation" and "following only the
> first parents" around there, what we try to describe should be clear
> enough now.
>
> Noticed-by: Luke Diamand<luke@diamand.org>
> Helped-by: Thomas Rast<trast@inf.ethz.ch>
> Helped-by: Andreas Ericsson<ae@op5.se>
> Signed-off-by: Junio C Hamano<gitster@pobox.com>
> ---
>   Documentation/revisions.txt |    2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index b290b61..1725661 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -101,7 +101,7 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
>
>   '<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
> +  object that is the<n>th generation ancestor of the named
>     commit object, following only the first parents.  I.e. '<rev>{tilde}3' is
>     equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to
>     '<rev>{caret}1{caret}1{caret}1'.  See below for an illustration of