Re: [PATCH] revisions.txt: mention <rev>~ form

From: Denton Liu <liu.denton@gmail.com>
Date: Apr 26, 2019, 21:16 UTC
Message-ID: <20190426211613.GA23370@dev-l>
In-Reply-To: <1d84c3bc-4e18-450e-edc6-96ac34f61c7a@gmail.com>

On Fri, Apr 26, 2019 at 10:55:35PM +0200, Andreas Heiduk wrote:

Show 46 quoted lines

> Am 22.04.19 um 08:12 schrieb Denton Liu:
> > In revisions.txt, the '<rev>^' form is mentioned but the '<rev>~' form
> > is missing. Although both forms are essentially equivalent (they each
> > get the first parent of the specified revision), we should mention the
> > latter for completeness. Make this change.
> > 
> > While we're at it, the brief form of '<rev>^' makes it seem as if no
> > numerical argument is accepted. Update documentation to make it obvious
> > that an optional numerical argument is accepted.
> > 
> > Signed-off-by: Denton Liu <liu.denton@gmail.com>
> > ---
> >  Documentation/revisions.txt | 6 ++++--
> >  1 file changed, 4 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> > index 2337a995ec..4ba7b4416a 100644
> > --- a/Documentation/revisions.txt
> > +++ b/Documentation/revisions.txt
> > @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,
> >  This suffix is also accepted when spelled in uppercase, and means the same
> >  thing no matter the case.
> >  
> > -'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
> > +'<rev>{caret}[<n>]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
> 
> This
> 
> >    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}'
> > @@ -139,7 +139,9 @@ thing no matter the case.
> >    '<rev>{caret}0' means the commit itself and is used when '<rev>' is the
> >    object name of a tag object that refers to a commit object.
> >  
> > -'<rev>{tilde}<n>', e.g. 'master{tilde}3'::
> > +'<rev>{tilde}[<n>]', e.g. 'HEAD~, master{tilde}3'::
> 
> and here: These would be the first and only places in revisions.txt
> where [] denote optional syntax. Since *exactly* this place is already
> riddled with special characters wich are either part of the syntax
> (e.g. @, {}) or not (e.g. <n>) this would be confusing.
> 
> In other places of the file optional syntax is *displayed* like this:
> 
>        <branchname>@{upstream}, e.g. master@{upstream}, @{u}

In that case, would it make more sense to add [] to optional parameters across the whole file? The meaning of [] (like that of <>) is common knowledge across all of Git's documentation. As a result, since <branchname> is optional, this would mislead a reader unless they were to further read the examples (which imo, they should not have to do to fully understand it). In addition to this, since [] is not used in any rev syntax, there would be no ambiguity.

Thus, we'd rewrite the above as

	[<branchname>]@{upstream}, e.g. master@{upstream}, @{u}

I'm not sure, what do you think?

Show 16 quoted lines

> 
> in that spirit somethind like this:
> 
> 	<rev>~<n>', e.g. 'HEAD~, master~3', master~
> 
> would be better to read.
> 
> 
> > +  A suffix '{tilde}' to a revision parameter means the first parent of
> > +  that commit object.
> >    A suffix '{tilde}<n>' to a revision parameter means the commit
> >    object that is the <n>th generation ancestor of the named
> >    commit object, following only the first parents.  I.e. '<rev>{tilde}3' is
> 
> 
>