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

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

[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'::
   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'::
+  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
-- 
2.21.0.1000.g11cd861522

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

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> @@ -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'::

Why doesn't this example say "HEAD{tilde}, master{tilde}3" instead,
I wonder?

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

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

[Denton Liu]

On Mon, Apr 22, 2019 at 03:32:21PM +0900, Junio C Hamano wrote:
> Denton Liu <liu.denton@gmail.com> writes:
> 
> > @@ -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'::
> 
> Why doesn't this example say "HEAD{tilde}, master{tilde}3" instead,
> I wonder?

According to the doc-diff, it doesn't really make a difference:

	diff --git a/14c0f8d3ab6c36672189cd2dd217f4617d12ccba/home/denton/share/man/man7/gitrevisions.7 b/18c8ed70602271a28c93df922eb3da8fb7563e2e/home/denton/share/man/man7/gitrevisions.7
	index 6f0dc7b8fb..ef23d49e00 100644
	--- a/14c0f8d3ab6c36672189cd2dd217f4617d12ccba/home/denton/share/man/man7/gitrevisions.7
	+++ b/18c8ed70602271a28c93df922eb3da8fb7563e2e/home/denton/share/man/man7/gitrevisions.7
	@@ -146,19 +146,20 @@ SPECIFYING REVISIONS
				This suffix is also accepted when spelled in uppercase, and means
				the same thing no matter the case.
	 
	-       <rev>^, e.g. HEAD^, v1.5.1^0
	+       <rev>^[<n>], e.g. HEAD^, v1.5.1^0
				A suffix ^ to a revision parameter means the first parent of that
				commit object.  ^<n> means the <n>th parent (i.e.  <rev>^ is
				equivalent to <rev>^1). As a special rule, <rev>^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>~<n>, e.g. master~3
	-           A suffix ~<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>~3 is equivalent to
	-           <rev>^^^ which is equivalent to <rev>^1^1^1. See below for an
	-           illustration of the usage of this form.
	+       <rev>~[<n>], e.g. HEAD~, master~3
	+           A suffix ~ to a revision parameter means the first parent of that
	+           commit object. A suffix ~<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>~3 is
	+           equivalent to <rev>^^^ which is equivalent to <rev>^1^1^1. See
	+           below for an illustration of the usage of this form.
	 
			<rev>^{<type>}, e.g. v0.99.8^{commit}
				A suffix ^ followed by an object type name enclosed in brace pair

That being said, this is a typo on my part and it should really say
{tilde}.

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

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

[Duy Nguyen]

On Mon, Apr 22, 2019 at 1:14 PM Denton Liu <liu.denton@gmail.com> wrote:
>
> 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.

Do we really support this, or is it a bug in rev parsing code that
treats <rev>~ like <rev>~1?

Hmm.. digging... ah 621ff67594 (rev-parse: fix meaning of rev~ vs
rev~0., 2008-03-14) at least it's not an unintended bahaviour.
-- 
Duy

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

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

>> > -'<rev>{tilde}<n>', e.g. 'master{tilde}3'::
>> > +'<rev>{tilde}[<n>]', e.g. 'HEAD~, master{tilde}3'::
>> 
>> Why doesn't this example say "HEAD{tilde}, master{tilde}3" instead,
>> I wonder?
>
> According to the doc-diff, it doesn't really make a difference:

I was wondering if "HEAD{tilde}, master{tilde}3" gets formatted
incorrectly and leaving one of them as literal "~" was a deliberate
workaround.  I've seen a quirk like that in AsciiDoc before, where
one pair of some quote that behaves sensibly starts to misbehave
when the second pair is added on the same line.

Thanks.

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

[Junio C Hamano]

Duy Nguyen <pclouds@gmail.com> writes:

> On Mon, Apr 22, 2019 at 1:14 PM Denton Liu <liu.denton@gmail.com> wrote:
>>
>> 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.
>
> Do we really support this, or is it a bug in rev parsing code that
> treats <rev>~ like <rev>~1?
>
> Hmm.. digging... ah 621ff67594 (rev-parse: fix meaning of rev~ vs
> rev~0., 2008-03-14) at least it's not an unintended bahaviour.

commit 621ff6759414e2a723f61b6d8fc04b9805eb0c20
Author: Linus Torvalds <torvalds@linux-foundation.org>
Date:   Fri Mar 14 11:49:40 2008 -0700

    rev-parse: fix meaning of rev~ vs rev~0.
    
    I think it would make more sense for rev~ to have the same guarantees that
    rev^ has, namely to always return a commit. I would also suggest that not
    giving a number would have the same effect of defaulting to 1, not 0.

Yes, I remember that one: if rev^ means rev^1, rev~ should mean
rev~1, not rev or rev~0.

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

[Andreas Heiduk]

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

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

[Denton Liu]

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

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

[PATCH v2 0/3] cleanup revisions.txt

[Denton Liu]

Thanks for the review, Andreas.

I mulled over it for a bit and I think that marking optional arguments
with [] would increase the clarity of the documentation so I went ahead
and made this change across the whole file.

While I was at it, I found some instances of "<rev>" written as "rev" so
I fixed those too.

---

Changes since v1:

* Added patch to fix instances of "rev" to "<rev>"
* Marked all optional rev arguments with []

Denton Liu (3):
  revisions.txt: change "rev" to "<rev>"
  revisions.txt: mark optional rev arguments with []
  revisions.txt: mention <rev>~ form

 Documentation/revisions.txt | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

-- 
2.21.0.1000.g11cd861522

[PATCH v2 1/3] revisions.txt: change "rev" to "<rev>"

[Denton Liu]

In revisions.txt, there were some instances of a rev argument being
written as "rev". However, since they didn't mean the string literal,
write "<rev>", instead.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/revisions.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 2337a995ec..e5f11691b1 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -159,12 +159,12 @@ thing no matter the case.
   '<rev>{caret}0'
   is a short-hand for '<rev>{caret}\{commit\}'.
 +
-'rev{caret}\{object\}' can be used to make sure 'rev' names an
-object that exists, without requiring 'rev' to be a tag, and
-without dereferencing 'rev'; because a tag is already an object,
+'<rev>{caret}\{object\}' can be used to make sure '<rev>' names an
+object that exists, without requiring '<rev>' to be a tag, and
+without dereferencing '<rev>'; because a tag is already an object,
 it does not have to be dereferenced even once to get to an object.
 +
-'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an
+'<rev>{caret}\{tag\}' can be used to ensure that '<rev>' identifies an
 existing tag object.
 
 '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::
-- 
2.21.0.1000.g11cd861522

[PATCH v2 2/3] revisions.txt: mark optional rev arguments with []

[Denton Liu]

In revisions.txt, an optional rev argument was not distinguised.
Instead, a user had to continue and read the description in order to
learn that the argument was optional.

Since the [] notation for an optional argument is common-knowledge in
the Git documentation, mark optional arguments with [] so that it's more
obvious for the reader.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/revisions.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index e5f11691b1..68cce2ca06 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.
   The construct '@{-<n>}' means the <n>th branch/commit checked out
   before the current one.
 
-'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
+'[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
   The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}')
   refers to the branch that the branch specified by branchname is set to build on
   top of (configured with `branch.<name>.remote` and
@@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.
   current one. These suffixes are also accepted when spelled in uppercase, and
   they mean the same thing no matter the case.
 
-'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
+'[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
   The suffix '@\{push}' reports the branch "where we would push to" if
   `git push` were run while `branchname` was checked out (or the current
   `HEAD` if no branchname is specified). Since our push destination is
@@ -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'::
   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}'
-- 
2.21.0.1000.g11cd861522

[PATCH v2 3/3] revisions.txt: mention <rev>~ form

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

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/revisions.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 68cce2ca06..372b286755 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -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{tilde}, master{tilde}3'::
+  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
-- 
2.21.0.1000.g11cd861522

Re: [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []

[Andreas Heiduk]

Am 27.04.19 um 14:16 schrieb Denton Liu:
> In revisions.txt, an optional rev argument was not distinguised.
> Instead, a user had to continue and read the description in order to
> learn that the argument was optional.
> 
> Since the [] notation for an optional argument is common-knowledge in
> the Git documentation, mark optional arguments with [] so that it's more
> obvious for the reader.
> 
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  Documentation/revisions.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index e5f11691b1..68cce2ca06 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt

I think I found another one here:

@@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8.
 '@'::
   '@' alone is a shortcut for `HEAD`.
 
-'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
+'[<refname>]@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
   A ref followed by the suffix '@' with a date specification
   enclosed in a brace
   pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1

The doesn't give a hint that <refname> is optional but actually it is.

> @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.
>    The construct '@{-<n>}' means the <n>th branch/commit checked out
>    before the current one.
>  
> -'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
> +'[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
>    The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}')
>    refers to the branch that the branch specified by branchname is set to build on
>    top of (configured with `branch.<name>.remote` and
> @@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.
>    current one. These suffixes are also accepted when spelled in uppercase, and
>    they mean the same thing no matter the case.
>  
> -'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
> +'[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
>    The suffix '@\{push}' reports the branch "where we would push to" if
>    `git push` were run while `branchname` was checked out (or the current
>    `HEAD` if no branchname is specified). Since our push destination is
> @@ -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'::
>    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}'

Re: [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []

[Andreas Heiduk]

Am 03.05.19 um 09:17 schrieb Andreas Heiduk:
> Am 27.04.19 um 14:16 schrieb Denton Liu:
>> In revisions.txt, an optional rev argument was not distinguised.
>> Instead, a user had to continue and read the description in order to
>> learn that the argument was optional.
>>
>> Since the [] notation for an optional argument is common-knowledge in
>> the Git documentation, mark optional arguments with [] so that it's more
>> obvious for the reader.
>>
>> Signed-off-by: Denton Liu <liu.denton@gmail.com>
>> ---
>>  Documentation/revisions.txt | 6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index e5f11691b1..68cce2ca06 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
> 
> I think I found another one here:
> 
> @@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8.
>  '@'::
>    '@' alone is a shortcut for `HEAD`.
>  
> -'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
> +'[<refname>]@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
>    A ref followed by the suffix '@' with a date specification
>    enclosed in a brace
>    pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1
> 
> The doesn't give a hint that <refname> is optional but actually it is.
> 
>> @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.
>>    The construct '@{-<n>}' means the <n>th branch/commit checked out
>>    before the current one.
>>  
>> -'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
>> +'[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
>>    The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}')
>>    refers to the branch that the branch specified by branchname is set to build on
>>    top of (configured with `branch.<name>.remote` and
>> @@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.
>>    current one. These suffixes are also accepted when spelled in uppercase, and
>>    they mean the same thing no matter the case.
>>  
>> -'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
>> +'[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
>>    The suffix '@\{push}' reports the branch "where we would push to" if
>>    `git push` were run while `branchname` was checked out (or the current
>>    `HEAD` if no branchname is specified). Since our push destination is
>> @@ -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'::
>>    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}'
> 

And another one I've found after hitting "Send" :-(

@@ -346,7 +346,7 @@ Revision Range Summary
   as giving commit '<rev>' and then all its parents prefixed with
   '{caret}' to exclude them (and their ancestors).
 
-'<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2'::
+'<rev>{caret}-[<n>]', e.g. 'HEAD{caret}-, HEAD{caret}-2'::
 	Equivalent to '<rev>{caret}<n>..<rev>', with '<n>' = 1 if not
 	given.

Re: [PATCH v2 0/3] cleanup revisions.txt

[Andreas Heiduk]

Am 27.04.19 um 14:15 schrieb Denton Liu:

While reading/reviewing I stumbled across another case for marking optional
clauses. But the solutions is not a one-liner. @Denton Would you please add
that one as Patch 4/4 to your series?

----------------- 8< ----------------------------
Subject: [PATCH] revisions.txt: remove ambibuity between <rev>:<path> and :<path>

The revision ':README' is mentioned as an example for '<rev>:<path>'
but the explanation forwards to the ':<n>:<path>' syntax. At the same
time ':<n>:<path>' did not mark the '<n>:' as optional.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/revisions.txt | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 372b286755..f11d1edc57 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -196,19 +196,16 @@ existing tag object.
   Depending on the given text, the shell's word splitting rules might
   require additional quoting.
 
-'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
+'<rev>:<path>', e.g. 'HEAD:README', 'master:./README'::
   A suffix ':' followed by a path names the blob or tree
   at the given path in the tree-ish object named by the part
   before the colon.
-  ':path' (with an empty part before the colon)
-  is a special case of the syntax described next: content
-  recorded in the index at the given path.
   A path starting with './' or '../' is relative to the current working directory.
   The given path will be converted to be relative to the working tree's root directory.
   This is most useful to address a blob or tree from a commit or tree that has
   the same tree structure as the working tree.
 
-':<n>:<path>', e.g. ':0:README', ':README'::
+':[<n>:]<path>', e.g. ':0:README', ':README'::
   A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path, names a blob object in the
   index at the given path. A missing stage number (and the colon
-- 
2.21.0

Re: [PATCH v2 0/3] cleanup revisions.txt

[Denton Liu]

Hi Andreas,

Thanks for the earlier corrections on 2/3.

On Fri, May 03, 2019 at 10:01:08AM +0200, Andreas Heiduk wrote:
> Am 27.04.19 um 14:15 schrieb Denton Liu:
> 
> While reading/reviewing I stumbled across another case for marking optional
> clauses. But the solutions is not a one-liner. @Denton Would you please add
> that one as Patch 4/4 to your series?

Will do.

Thanks,

Denton

> 
> ----------------- 8< ----------------------------
> Subject: [PATCH] revisions.txt: remove ambibuity between <rev>:<path> and :<path>
> 
> The revision ':README' is mentioned as an example for '<rev>:<path>'
> but the explanation forwards to the ':<n>:<path>' syntax. At the same
> time ':<n>:<path>' did not mark the '<n>:' as optional.
> 
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/revisions.txt | 7 ++-----
>  1 file changed, 2 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 372b286755..f11d1edc57 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -196,19 +196,16 @@ existing tag object.
>    Depending on the given text, the shell's word splitting rules might
>    require additional quoting.
>  
> -'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
> +'<rev>:<path>', e.g. 'HEAD:README', 'master:./README'::
>    A suffix ':' followed by a path names the blob or tree
>    at the given path in the tree-ish object named by the part
>    before the colon.
> -  ':path' (with an empty part before the colon)
> -  is a special case of the syntax described next: content
> -  recorded in the index at the given path.
>    A path starting with './' or '../' is relative to the current working directory.
>    The given path will be converted to be relative to the working tree's root directory.
>    This is most useful to address a blob or tree from a commit or tree that has
>    the same tree structure as the working tree.
>  
> -':<n>:<path>', e.g. ':0:README', ':README'::
> +':[<n>:]<path>', e.g. ':0:README', ':README'::
>    A colon, optionally followed by a stage number (0 to 3) and a
>    colon, followed by a path, names a blob object in the
>    index at the given path. A missing stage number (and the colon
> -- 
> 2.21.0