threads / discuss / 29770

Tilde spec - befuzzled

Subject: Tilde spec - befuzzled

## tl;dr

10 messages between Feb 28, 2012 and Mar 2, 2012.

replies: 9people: 6as markdown or json

Luke Diamand· Feb 28, 2012, 09:07 UTC · lore

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

Andreas Ericsson· Feb 28, 2012, 09:50 UTC · re: Luke Diamand · lore

Re: Tilde spec - befuzzled

On 02/28/2012 10:07 AM, Luke Diamand wrote:
Show 15 quoted lines
> 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.
Thomas Rast· Feb 28, 2012, 11:34 UTC · re: Andreas Ericsson · lore

Re: Tilde spec - befuzzled

Andreas Ericsson <ae@op5.se> writes:
Show 21 quoted lines
> 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
Junio C Hamano· Feb 28, 2012, 19:20 UTC · re: Thomas Rast · lore

Re: Tilde spec - befuzzled

Thomas Rast <trast@inf.ethz.ch> writes:
Show 11 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.
Andrew Ardill· Feb 29, 2012, 01:18 UTC · re: Junio C Hamano · lore

Re: Tilde spec - befuzzled

On 29 February 2012 06:20, Junio C Hamano <gitster@pobox.com> wrote:
Show 23 quoted lines
> 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
Jeff King· Feb 29, 2012, 07:34 UTC · re: Andrew Ardill · lore

Re: Tilde spec - befuzzled

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
Andreas Ericsson· Feb 29, 2012, 09:30 UTC · re: Andrew Ardill · lore

Re: Tilde spec - befuzzled

On 02/29/2012 02:18 AM, Andrew Ardill wrote:
Show 32 quoted lines
> 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.
Andreas Ericsson· Feb 29, 2012, 09:32 UTC · re: Junio C Hamano · lore

Re: Tilde spec - befuzzled

On 02/28/2012 08:20 PM, Junio C Hamano wrote:
Show 18 quoted lines
> 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.

Show 5 quoted lines
> 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.
Junio C Hamano· Feb 29, 2012, 19:13 UTC · re: Andreas Ericsson · lore

Re*: Tilde spec - befuzzled

Andreas Ericsson <ae@op5.se> writes:
Show 21 quoted lines
> 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
Luke Diamand· Mar 2, 2012, 09:25 UTC · re: Junio C Hamano · lore

Re: Re*: Tilde spec - befuzzled

On 29/02/12 19:13, Junio C Hamano wrote:
Show 25 quoted lines
> 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

Show 32 quoted lines
>
> -- >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

← back to recent threads