On Fri, Apr 26, 2019 at 10:55:35PM +0200, Andreas Heiduk wrote:
> 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@xxxxxxxxx>
> > ---
> > 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?
>
> 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
>
>
>
