git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* [PATCH] revisions.txt: mention <rev>~ form
@ 2019-04-22  6:12 Denton Liu
  2019-04-22  6:32 ` Junio C Hamano
                   ` (3 more replies)
  0 siblings, 4 replies; 16+ messages in thread
From: Denton Liu @ 2019-04-22  6:12 UTC (permalink / raw)
  To: Git Mailing List

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


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-22  6:12 [PATCH] revisions.txt: mention <rev>~ form Denton Liu
@ 2019-04-22  6:32 ` Junio C Hamano
  2019-04-22  7:39   ` Denton Liu
  2019-04-22  9:59 ` Duy Nguyen
                   ` (2 subsequent siblings)
  3 siblings, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2019-04-22  6:32 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-22  6:32 ` Junio C Hamano
@ 2019-04-22  7:39   ` Denton Liu
  2019-04-22 11:21     ` Junio C Hamano
  0 siblings, 1 reply; 16+ messages in thread
From: Denton Liu @ 2019-04-22  7:39 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-22  6:12 [PATCH] revisions.txt: mention <rev>~ form Denton Liu
  2019-04-22  6:32 ` Junio C Hamano
@ 2019-04-22  9:59 ` Duy Nguyen
  2019-04-24  1:05   ` Junio C Hamano
  2019-04-26 20:55 ` Andreas Heiduk
  2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
  3 siblings, 1 reply; 16+ messages in thread
From: Duy Nguyen @ 2019-04-22  9:59 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-22  7:39   ` Denton Liu
@ 2019-04-22 11:21     ` Junio C Hamano
  0 siblings, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2019-04-22 11:21 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-22  9:59 ` Duy Nguyen
@ 2019-04-24  1:05   ` Junio C Hamano
  0 siblings, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2019-04-24  1:05 UTC (permalink / raw)
  To: Duy Nguyen; +Cc: Denton Liu, Git Mailing List

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.


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-22  6:12 [PATCH] revisions.txt: mention <rev>~ form Denton Liu
  2019-04-22  6:32 ` Junio C Hamano
  2019-04-22  9:59 ` Duy Nguyen
@ 2019-04-26 20:55 ` Andreas Heiduk
  2019-04-26 21:16   ` Denton Liu
  2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
  3 siblings, 1 reply; 16+ messages in thread
From: Andreas Heiduk @ 2019-04-26 20:55 UTC (permalink / raw)
  To: Denton Liu, Git Mailing List

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




^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH] revisions.txt: mention <rev>~ form
  2019-04-26 20:55 ` Andreas Heiduk
@ 2019-04-26 21:16   ` Denton Liu
  0 siblings, 0 replies; 16+ messages in thread
From: Denton Liu @ 2019-04-26 21:16 UTC (permalink / raw)
  To: Andreas Heiduk; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH v2 0/3] cleanup revisions.txt
  2019-04-22  6:12 [PATCH] revisions.txt: mention <rev>~ form Denton Liu
                   ` (2 preceding siblings ...)
  2019-04-26 20:55 ` Andreas Heiduk
@ 2019-04-27 12:15 ` Denton Liu
  2019-04-27 12:15   ` [PATCH v2 1/3] revisions.txt: change "rev" to "<rev>" Denton Liu
                     ` (3 more replies)
  3 siblings, 4 replies; 16+ messages in thread
From: Denton Liu @ 2019-04-27 12:15 UTC (permalink / raw)
  To: Git Mailing List; +Cc: Andreas Heiduk, Duy Nguyen, Junio C Hamano

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


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH v2 1/3] revisions.txt: change "rev" to "<rev>"
  2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
@ 2019-04-27 12:15   ` Denton Liu
  2019-04-27 12:16   ` [PATCH v2 2/3] revisions.txt: mark optional rev arguments with [] Denton Liu
                     ` (2 subsequent siblings)
  3 siblings, 0 replies; 16+ messages in thread
From: Denton Liu @ 2019-04-27 12:15 UTC (permalink / raw)
  To: Git Mailing List; +Cc: Andreas Heiduk, Duy Nguyen, Junio C Hamano

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


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []
  2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
  2019-04-27 12:15   ` [PATCH v2 1/3] revisions.txt: change "rev" to "<rev>" Denton Liu
@ 2019-04-27 12:16   ` Denton Liu
  2019-05-03  7:17     ` Andreas Heiduk
  2019-04-27 12:16   ` [PATCH v2 3/3] revisions.txt: mention <rev>~ form Denton Liu
  2019-05-03  8:01   ` [PATCH v2 0/3] cleanup revisions.txt Andreas Heiduk
  3 siblings, 1 reply; 16+ messages in thread
From: Denton Liu @ 2019-04-27 12:16 UTC (permalink / raw)
  To: Git Mailing List; +Cc: Andreas Heiduk, Duy Nguyen, Junio C Hamano

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


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH v2 3/3] revisions.txt: mention <rev>~ form
  2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
  2019-04-27 12:15   ` [PATCH v2 1/3] revisions.txt: change "rev" to "<rev>" Denton Liu
  2019-04-27 12:16   ` [PATCH v2 2/3] revisions.txt: mark optional rev arguments with [] Denton Liu
@ 2019-04-27 12:16   ` Denton Liu
  2019-05-03  8:01   ` [PATCH v2 0/3] cleanup revisions.txt Andreas Heiduk
  3 siblings, 0 replies; 16+ messages in thread
From: Denton Liu @ 2019-04-27 12:16 UTC (permalink / raw)
  To: Git Mailing List; +Cc: Andreas Heiduk, Duy Nguyen, Junio C Hamano

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


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []
  2019-04-27 12:16   ` [PATCH v2 2/3] revisions.txt: mark optional rev arguments with [] Denton Liu
@ 2019-05-03  7:17     ` Andreas Heiduk
  2019-05-03  7:35       ` Andreas Heiduk
  0 siblings, 1 reply; 16+ messages in thread
From: Andreas Heiduk @ 2019-05-03  7:17 UTC (permalink / raw)
  To: Denton Liu, Git Mailing List; +Cc: Duy Nguyen, Junio C Hamano

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


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []
  2019-05-03  7:17     ` Andreas Heiduk
@ 2019-05-03  7:35       ` Andreas Heiduk
  0 siblings, 0 replies; 16+ messages in thread
From: Andreas Heiduk @ 2019-05-03  7:35 UTC (permalink / raw)
  To: Denton Liu, Git Mailing List; +Cc: Duy Nguyen, Junio C Hamano

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.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH v2 0/3] cleanup revisions.txt
  2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
                     ` (2 preceding siblings ...)
  2019-04-27 12:16   ` [PATCH v2 3/3] revisions.txt: mention <rev>~ form Denton Liu
@ 2019-05-03  8:01   ` Andreas Heiduk
  2019-05-03  8:13     ` Denton Liu
  3 siblings, 1 reply; 16+ messages in thread
From: Andreas Heiduk @ 2019-05-03  8:01 UTC (permalink / raw)
  To: Denton Liu, Git Mailing List; +Cc: Duy Nguyen, Junio C Hamano

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH v2 0/3] cleanup revisions.txt
  2019-05-03  8:01   ` [PATCH v2 0/3] cleanup revisions.txt Andreas Heiduk
@ 2019-05-03  8:13     ` Denton Liu
  0 siblings, 0 replies; 16+ messages in thread
From: Denton Liu @ 2019-05-03  8:13 UTC (permalink / raw)
  To: Andreas Heiduk; +Cc: Git Mailing List, Duy Nguyen, Junio C Hamano

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2019-05-03  8:13 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-04-22  6:12 [PATCH] revisions.txt: mention <rev>~ form Denton Liu
2019-04-22  6:32 ` Junio C Hamano
2019-04-22  7:39   ` Denton Liu
2019-04-22 11:21     ` Junio C Hamano
2019-04-22  9:59 ` Duy Nguyen
2019-04-24  1:05   ` Junio C Hamano
2019-04-26 20:55 ` Andreas Heiduk
2019-04-26 21:16   ` Denton Liu
2019-04-27 12:15 ` [PATCH v2 0/3] cleanup revisions.txt Denton Liu
2019-04-27 12:15   ` [PATCH v2 1/3] revisions.txt: change "rev" to "<rev>" Denton Liu
2019-04-27 12:16   ` [PATCH v2 2/3] revisions.txt: mark optional rev arguments with [] Denton Liu
2019-05-03  7:17     ` Andreas Heiduk
2019-05-03  7:35       ` Andreas Heiduk
2019-04-27 12:16   ` [PATCH v2 3/3] revisions.txt: mention <rev>~ form Denton Liu
2019-05-03  8:01   ` [PATCH v2 0/3] cleanup revisions.txt Andreas Heiduk
2019-05-03  8:13     ` Denton Liu

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).