threads / patch / 50968

patchrevisions.txt: mention <rev>~ form

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

## tl;dr

16 messages between Apr 22, 2019 and May 3, 2019. Diffs are folded; open one to read it.

replies: 15people: 4as markdown or json

Denton Liu· Apr 22, 2019, 06:12 UTC · lore

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

Show changes to Documentation/revisions.txt +4 −2

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

Junio C Hamano· Apr 22, 2019, 06:32 UTC · re: Denton Liu · lore

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

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

Show 6 quoted lines

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

Show 5 quoted lines

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

Denton Liu· Apr 22, 2019, 07:39 UTC · re: Junio C Hamano · lore

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

On Mon, Apr 22, 2019 at 03:32:21PM +0900, Junio C Hamano wrote:

Show 11 quoted lines

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

Show 6 quoted lines

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

Junio C Hamano· Apr 22, 2019, 11:21 UTC · re: Denton Liu · lore

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

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

Show 7 quoted lines

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

Duy Nguyen· Apr 22, 2019, 09:59 UTC · re: Denton Liu · lore

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

On Mon, Apr 22, 2019 at 1:14 PM Denton Liu <liu.denton@gmail.com> wrote:

Show 5 quoted lines

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

Junio C Hamano· Apr 24, 2019, 01:05 UTC · re: Duy Nguyen · lore

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

Duy Nguyen <pclouds@gmail.com> writes:

Show 12 quoted lines

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

Andreas Heiduk· Apr 26, 2019, 20:55 UTC · re: Denton Liu · lore

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

Am 22.04.19 um 08:12 schrieb Denton Liu:

Show 24 quoted lines

> 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

Show 9 quoted lines

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

Show 5 quoted lines

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

Denton Liu· Apr 26, 2019, 21:16 UTC · re: Andreas Heiduk · lore

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

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

Denton Liu· Apr 27, 2019, 12:15 UTC · re: Denton Liu · lore

[PATCH v2 0/3] cleanup revisions.txt

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

Denton Liu· Apr 27, 2019, 12:15 UTC · re: Denton Liu · lore

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

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

Show changes to Documentation/revisions.txt +4 −4

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

Denton Liu· Apr 27, 2019, 12:16 UTC · re: Denton Liu · lore

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

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

Show changes to Documentation/revisions.txt +3 −3

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

Andreas Heiduk· May 3, 2019, 07:17 UTC · re: Denton Liu · lore

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

Am 27.04.19 um 14:16 schrieb Denton Liu:

Show 17 quoted lines

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

Show changes to diff +1 −1

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

Andreas Heiduk· May 3, 2019, 07:35 UTC · re: Andreas Heiduk · lore

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

Am 03.05.19 um 09:17 schrieb Andreas Heiduk:

Show 61 quoted lines

> 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" :-(

Show changes to diff +1 −1

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

Denton Liu· Apr 27, 2019, 12:16 UTC · re: Denton Liu · lore

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

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

Show changes to Documentation/revisions.txt +3 −1

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

Andreas Heiduk· May 3, 2019, 08:01 UTC · re: Denton Liu · lore

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

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

Show changes to Documentation/revisions.txt +2 −5

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

Denton Liu· May 3, 2019, 08:13 UTC · re: Andreas Heiduk · lore

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

Hi Andreas,

Thanks for the earlier corrections on 2/3.

On Fri, May 03, 2019 at 10:01:08AM +0200, Andreas Heiduk wrote:

Show 5 quoted lines

> 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

Show 41 quoted lines

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