* [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 related [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 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 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 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 related [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 related [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
* [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 related [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 related [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 public 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).