| Message ID | 18c8ed70602271a28c93df922eb3da8fb7563e2e.1555913472.git.liu.denton@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | revisions.txt: mention <rev>~ form | expand |
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
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
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.
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.
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.
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
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 > > >
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
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(-)