{"thread":{"id":"50968","subject":"[PATCH] revisions.txt: mention ~ form","startedAt":"2019-04-22T06:12:34Z","lastAt":"2019-05-03T08:13:59Z","messageCount":16,"participants":["Denton Liu","Junio C Hamano","Duy Nguyen","Andreas Heiduk"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"374226","messageId":"18c8ed70602271a28c93df922eb3da8fb7563e2e.1555913472.git.liu.denton@gmail.com","threadId":"50968","inReplyTo":null,"subject":"[PATCH] revisions.txt: mention ~ form","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-22T06:12:29Z","receivedAt":"2019-04-22T06:12:34Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"In revisions.txt, the '^' form is mentioned but the '~' form\nis missing. Although both forms are essentially equivalent (they each\nget the first parent of the specified revision), we should mention the\nlatter for completeness. Make this change.\n\nWhile we're at it, the brief form of '^' makes it seem as if no\nnumerical argument is accepted. Update documentation to make it obvious\nthat an optional numerical argument is accepted.\n\nSigned-off-by: Denton Liu \n---\n Documentation/revisions.txt | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 2337a995ec..4ba7b4416a 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,\n This suffix is also accepted when spelled in uppercase, and means the same\n thing no matter the case.\n \n-'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n+'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n A suffix '{caret}' to a revision parameter means the first parent of\n that commit object. '{caret}' means the th parent (i.e.\n '{caret}'\n@@ -139,7 +139,9 @@ thing no matter the case.\n '{caret}0' means the commit itself and is used when '' is the\n object name of a tag object that refers to a commit object.\n \n-'{tilde}', e.g. 'master{tilde}3'::\n+'{tilde}[]', e.g. 'HEAD~, master{tilde}3'::\n+ A suffix '{tilde}' to a revision parameter means the first parent of\n+ that commit object.\n A suffix '{tilde}' to a revision parameter means the commit\n object that is the th generation ancestor of the named\n commit object, following only the first parents. I.e. '{tilde}3' is\n-- \n2.21.0.1000.g11cd861522\n\n"},{"id":"374229","messageId":"xmqqv9z67doq.fsf@gitster-ct.c.googlers.com","threadId":"50968","inReplyTo":"18c8ed70602271a28c93df922eb3da8fb7563e2e.1555913472.git.liu.denton@gmail.com","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-22T06:32:21Z","receivedAt":"2019-04-22T06:32:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu writes:\n\n> @@ -139,7 +139,9 @@ thing no matter the case.\n> '{caret}0' means the commit itself and is used when '' is the\n> object name of a tag object that refers to a commit object.\n> \n> -'{tilde}', e.g. 'master{tilde}3'::\n> +'{tilde}[]', e.g. 'HEAD~, master{tilde}3'::\n\nWhy doesn't this example say \"HEAD{tilde}, master{tilde}3\" instead,\nI wonder?\n\n> + A suffix '{tilde}' to a revision parameter means the first parent of\n> + that commit object.\n> A suffix '{tilde}' to a revision parameter means the commit\n> object that is the th generation ancestor of the named\n> commit object, following only the first parents. I.e. '{tilde}3' is\n"},{"id":"374232","messageId":"20190422073935.GA7660@archbookpro.localdomain","threadId":"50968","inReplyTo":"xmqqv9z67doq.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-22T07:39:35Z","receivedAt":"2019-04-22T07:39:40Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"On Mon, Apr 22, 2019 at 03:32:21PM +0900, Junio C Hamano wrote:\n> Denton Liu writes:\n> \n> > @@ -139,7 +139,9 @@ thing no matter the case.\n> > '{caret}0' means the commit itself and is used when '' is the\n> > object name of a tag object that refers to a commit object.\n> > \n> > -'{tilde}', e.g. 'master{tilde}3'::\n> > +'{tilde}[]', e.g. 'HEAD~, master{tilde}3'::\n> \n> Why doesn't this example say \"HEAD{tilde}, master{tilde}3\" instead,\n> I wonder?\n\nAccording to the doc-diff, it doesn't really make a difference:\n\n\tdiff --git a/14c0f8d3ab6c36672189cd2dd217f4617d12ccba/home/denton/share/man/man7/gitrevisions.7 b/18c8ed70602271a28c93df922eb3da8fb7563e2e/home/denton/share/man/man7/gitrevisions.7\n\tindex 6f0dc7b8fb..ef23d49e00 100644\n\t--- a/14c0f8d3ab6c36672189cd2dd217f4617d12ccba/home/denton/share/man/man7/gitrevisions.7\n\t+++ b/18c8ed70602271a28c93df922eb3da8fb7563e2e/home/denton/share/man/man7/gitrevisions.7\n\t@@ -146,19 +146,20 @@ SPECIFYING REVISIONS\n\t\t\t\tThis suffix is also accepted when spelled in uppercase, and means\n\t\t\t\tthe same thing no matter the case.\n\t \n\t- ^, e.g. HEAD^, v1.5.1^0\n\t+ ^[], e.g. HEAD^, v1.5.1^0\n\t\t\t\tA suffix ^ to a revision parameter means the first parent of that\n\t\t\t\tcommit object. ^ means the th parent (i.e. ^ is\n\t\t\t\tequivalent to ^1). As a special rule, ^0 means the commit\n\t\t\t\titself and is used when is the object name of a tag object\n\t\t\t\tthat refers to a commit object.\n\t \n\t- ~, e.g. master~3\n\t- A suffix ~ to a revision parameter means the commit object that\n\t- is the th generation ancestor of the named commit object,\n\t- following only the first parents. I.e. ~3 is equivalent to\n\t- ^^^ which is equivalent to ^1^1^1. See below for an\n\t- illustration of the usage of this form.\n\t+ ~[], e.g. HEAD~, master~3\n\t+ A suffix ~ to a revision parameter means the first parent of that\n\t+ commit object. A suffix ~ to a revision parameter means the\n\t+ commit object that is the th generation ancestor of the named\n\t+ commit object, following only the first parents. I.e. ~3 is\n\t+ equivalent to ^^^ which is equivalent to ^1^1^1. See\n\t+ below for an illustration of the usage of this form.\n\t \n\t\t\t^{}, e.g. v0.99.8^{commit}\n\t\t\t\tA suffix ^ followed by an object type name enclosed in brace pair\n\nThat being said, this is a typo on my part and it should really say\n{tilde}.\n\n> \n> > + A suffix '{tilde}' to a revision parameter means the first parent of\n> > + that commit object.\n> > A suffix '{tilde}' to a revision parameter means the commit\n> > object that is the th generation ancestor of the named\n> > commit object, following only the first parents. I.e. '{tilde}3' is\n"},{"id":"374234","messageId":"CACsJy8DB3k=9PaQT4CBz-K3=yjQ1oJAtz6p00PAOjy047XvAyA@mail.gmail.com","threadId":"50968","inReplyTo":"18c8ed70602271a28c93df922eb3da8fb7563e2e.1555913472.git.liu.denton@gmail.com","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-04-22T09:59:43Z","receivedAt":"2019-04-22T10:00:12Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Apr 22, 2019 at 1:14 PM Denton Liu wrote:\n>\n> In revisions.txt, the '^' form is mentioned but the '~' form\n> is missing. Although both forms are essentially equivalent (they each\n> get the first parent of the specified revision), we should mention the\n> latter for completeness. Make this change.\n\nDo we really support this, or is it a bug in rev parsing code that\ntreats ~ like ~1?\n\nHmm.. digging... ah 621ff67594 (rev-parse: fix meaning of rev~ vs\nrev~0., 2008-03-14) at least it's not an unintended bahaviour.\n-- \nDuy\n"},{"id":"374238","messageId":"xmqqmuki70av.fsf@gitster-ct.c.googlers.com","threadId":"50968","inReplyTo":"20190422073935.GA7660@archbookpro.localdomain","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-22T11:21:28Z","receivedAt":"2019-04-22T11:21:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu writes:\n\n>> > -'{tilde}', e.g. 'master{tilde}3'::\n>> > +'{tilde}[]', e.g. 'HEAD~, master{tilde}3'::\n>> \n>> Why doesn't this example say \"HEAD{tilde}, master{tilde}3\" instead,\n>> I wonder?\n>\n> According to the doc-diff, it doesn't really make a difference:\n\nI was wondering if \"HEAD{tilde}, master{tilde}3\" gets formatted\nincorrectly and leaving one of them as literal \"~\" was a deliberate\nworkaround. I've seen a quirk like that in AsciiDoc before, where\none pair of some quote that behaves sensibly starts to misbehave\nwhen the second pair is added on the same line.\n\nThanks.\n"},{"id":"374357","messageId":"xmqqh8ao43gt.fsf@gitster-ct.c.googlers.com","threadId":"50968","inReplyTo":"CACsJy8DB3k=9PaQT4CBz-K3=yjQ1oJAtz6p00PAOjy047XvAyA@mail.gmail.com","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-24T01:05:54Z","receivedAt":"2019-04-24T01:11:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n> On Mon, Apr 22, 2019 at 1:14 PM Denton Liu wrote:\n>>\n>> In revisions.txt, the '^' form is mentioned but the '~' form\n>> is missing. Although both forms are essentially equivalent (they each\n>> get the first parent of the specified revision), we should mention the\n>> latter for completeness. Make this change.\n>\n> Do we really support this, or is it a bug in rev parsing code that\n> treats ~ like ~1?\n>\n> Hmm.. digging... ah 621ff67594 (rev-parse: fix meaning of rev~ vs\n> rev~0., 2008-03-14) at least it's not an unintended bahaviour.\n\ncommit 621ff6759414e2a723f61b6d8fc04b9805eb0c20\nAuthor: Linus Torvalds \nDate: Fri Mar 14 11:49:40 2008 -0700\n\n rev-parse: fix meaning of rev~ vs rev~0.\n \n I think it would make more sense for rev~ to have the same guarantees that\n rev^ has, namely to always return a commit. I would also suggest that not\n giving a number would have the same effect of defaulting to 1, not 0.\n\nYes, I remember that one: if rev^ means rev^1, rev~ should mean\nrev~1, not rev or rev~0.\n\n"},{"id":"374575","messageId":"1d84c3bc-4e18-450e-edc6-96ac34f61c7a@gmail.com","threadId":"50968","inReplyTo":"18c8ed70602271a28c93df922eb3da8fb7563e2e.1555913472.git.liu.denton@gmail.com","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2019-04-26T20:55:35Z","receivedAt":"2019-04-26T20:55:40Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Am 22.04.19 um 08:12 schrieb Denton Liu:\n> In revisions.txt, the '^' form is mentioned but the '~' form\n> is missing. Although both forms are essentially equivalent (they each\n> get the first parent of the specified revision), we should mention the\n> latter for completeness. Make this change.\n> \n> While we're at it, the brief form of '^' makes it seem as if no\n> numerical argument is accepted. Update documentation to make it obvious\n> that an optional numerical argument is accepted.\n> \n> Signed-off-by: Denton Liu \n> ---\n> Documentation/revisions.txt | 6 ++++--\n> 1 file changed, 4 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 2337a995ec..4ba7b4416a 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,\n> This suffix is also accepted when spelled in uppercase, and means the same\n> thing no matter the case.\n> \n> -'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n> +'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n\nThis\n\n> A suffix '{caret}' to a revision parameter means the first parent of\n> that commit object. '{caret}' means the th parent (i.e.\n> '{caret}'\n> @@ -139,7 +139,9 @@ thing no matter the case.\n> '{caret}0' means the commit itself and is used when '' is the\n> object name of a tag object that refers to a commit object.\n> \n> -'{tilde}', e.g. 'master{tilde}3'::\n> +'{tilde}[]', e.g. 'HEAD~, master{tilde}3'::\n\nand here: These would be the first and only places in revisions.txt\nwhere [] denote optional syntax. Since *exactly* this place is already\nriddled with special characters wich are either part of the syntax\n(e.g. @, {}) or not (e.g. ) this would be confusing.\n\nIn other places of the file optional syntax is *displayed* like this:\n\n @{upstream}, e.g. master@{upstream}, @{u}\n\nin that spirit somethind like this:\n\n\t~', e.g. 'HEAD~, master~3', master~\n\nwould be better to read.\n\n\n> + A suffix '{tilde}' to a revision parameter means the first parent of\n> + that commit object.\n> A suffix '{tilde}' to a revision parameter means the commit\n> object that is the th generation ancestor of the named\n> commit object, following only the first parents. I.e. '{tilde}3' is\n\n\n\n"},{"id":"374577","messageId":"20190426211613.GA23370@dev-l","threadId":"50968","inReplyTo":"1d84c3bc-4e18-450e-edc6-96ac34f61c7a@gmail.com","subject":"Re: [PATCH] revisions.txt: mention ~ form","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-26T21:16:13Z","receivedAt":"2019-04-26T21:16:19Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"On Fri, Apr 26, 2019 at 10:55:35PM +0200, Andreas Heiduk wrote:\n> Am 22.04.19 um 08:12 schrieb Denton Liu:\n> > In revisions.txt, the '^' form is mentioned but the '~' form\n> > is missing. Although both forms are essentially equivalent (they each\n> > get the first parent of the specified revision), we should mention the\n> > latter for completeness. Make this change.\n> > \n> > While we're at it, the brief form of '^' makes it seem as if no\n> > numerical argument is accepted. Update documentation to make it obvious\n> > that an optional numerical argument is accepted.\n> > \n> > Signed-off-by: Denton Liu \n> > ---\n> > Documentation/revisions.txt | 6 ++++--\n> > 1 file changed, 4 insertions(+), 2 deletions(-)\n> > \n> > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> > index 2337a995ec..4ba7b4416a 100644\n> > --- a/Documentation/revisions.txt\n> > +++ b/Documentation/revisions.txt\n> > @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,\n> > This suffix is also accepted when spelled in uppercase, and means the same\n> > thing no matter the case.\n> > \n> > -'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n> > +'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n> \n> This\n> \n> > A suffix '{caret}' to a revision parameter means the first parent of\n> > that commit object. '{caret}' means the th parent (i.e.\n> > '{caret}'\n> > @@ -139,7 +139,9 @@ thing no matter the case.\n> > '{caret}0' means the commit itself and is used when '' is the\n> > object name of a tag object that refers to a commit object.\n> > \n> > -'{tilde}', e.g. 'master{tilde}3'::\n> > +'{tilde}[]', e.g. 'HEAD~, master{tilde}3'::\n> \n> and here: These would be the first and only places in revisions.txt\n> where [] denote optional syntax. Since *exactly* this place is already\n> riddled with special characters wich are either part of the syntax\n> (e.g. @, {}) or not (e.g. ) this would be confusing.\n> \n> In other places of the file optional syntax is *displayed* like this:\n> \n> @{upstream}, e.g. master@{upstream}, @{u}\n\nIn that case, would it make more sense to add [] to optional parameters\nacross the whole file? The meaning of [] (like that of <>) is common\nknowledge across all of Git's documentation. As a result, since\n is optional, this would mislead a reader unless they were\nto further read the examples (which imo, they should not have to do to\nfully understand it). In addition to this, since [] is not used in any\nrev syntax, there would be no ambiguity.\n\nThus, we'd rewrite the above as\n\n\t[]@{upstream}, e.g. master@{upstream}, @{u}\n\nI'm not sure, what do you think?\n\n> \n> in that spirit somethind like this:\n> \n> \t~', e.g. 'HEAD~, master~3', master~\n> \n> would be better to read.\n> \n> \n> > + A suffix '{tilde}' to a revision parameter means the first parent of\n> > + that commit object.\n> > A suffix '{tilde}' to a revision parameter means the commit\n> > object that is the th generation ancestor of the named\n> > commit object, following only the first parents. I.e. '{tilde}3' is\n> \n> \n> \n"},{"id":"374595","messageId":"cover.1556367012.git.liu.denton@gmail.com","threadId":"50968","inReplyTo":"18c8ed70602271a28c93df922eb3da8fb7563e2e.1555913472.git.liu.denton@gmail.com","subject":"[PATCH v2 0/3] cleanup revisions.txt","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-27T12:15:55Z","receivedAt":"2019-04-27T12:16:01Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Thanks for the review, Andreas.\n\nI mulled over it for a bit and I think that marking optional arguments\nwith [] would increase the clarity of the documentation so I went ahead\nand made this change across the whole file.\n\nWhile I was at it, I found some instances of \"\" written as \"rev\" so\nI fixed those too.\n\n---\n\nChanges since v1:\n\n* Added patch to fix instances of \"rev\" to \"\"\n* Marked all optional rev arguments with []\n\nDenton Liu (3):\n revisions.txt: change \"rev\" to \"\"\n revisions.txt: mark optional rev arguments with []\n revisions.txt: mention ~ form\n\n Documentation/revisions.txt | 18 ++++++++++--------\n 1 file changed, 10 insertions(+), 8 deletions(-)\n\n-- \n2.21.0.1000.g11cd861522\n\n"},{"id":"374596","messageId":"e5b6d69eec80acab5b4b4c702011fc82a7367a79.1556367012.git.liu.denton@gmail.com","threadId":"50968","inReplyTo":"cover.1556367012.git.liu.denton@gmail.com","subject":"[PATCH v2 1/3] revisions.txt: change \"rev\" to \"\"","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-27T12:15:58Z","receivedAt":"2019-04-27T12:16:08Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"In revisions.txt, there were some instances of a rev argument being\nwritten as \"rev\". However, since they didn't mean the string literal,\nwrite \"\", instead.\n\nSigned-off-by: Denton Liu \n---\n Documentation/revisions.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 2337a995ec..e5f11691b1 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -159,12 +159,12 @@ thing no matter the case.\n '{caret}0'\n is a short-hand for '{caret}\\{commit\\}'.\n +\n-'rev{caret}\\{object\\}' can be used to make sure 'rev' names an\n-object that exists, without requiring 'rev' to be a tag, and\n-without dereferencing 'rev'; because a tag is already an object,\n+'{caret}\\{object\\}' can be used to make sure '' names an\n+object that exists, without requiring '' to be a tag, and\n+without dereferencing ''; because a tag is already an object,\n it does not have to be dereferenced even once to get to an object.\n +\n-'rev{caret}\\{tag\\}' can be used to ensure that 'rev' identifies an\n+'{caret}\\{tag\\}' can be used to ensure that '' identifies an\n existing tag object.\n \n '{caret}{}', e.g. 'v0.99.8{caret}{}'::\n-- \n2.21.0.1000.g11cd861522\n\n"},{"id":"374597","messageId":"90c787c219d25f38c1d53ae837160994a7bc6355.1556367012.git.liu.denton@gmail.com","threadId":"50968","inReplyTo":"cover.1556367012.git.liu.denton@gmail.com","subject":"[PATCH v2 2/3] revisions.txt: mark optional rev arguments with []","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-27T12:16:06Z","receivedAt":"2019-04-27T12:16:10Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"In revisions.txt, an optional rev argument was not distinguised.\nInstead, a user had to continue and read the description in order to\nlearn that the argument was optional.\n\nSince the [] notation for an optional argument is common-knowledge in\nthe Git documentation, mark optional arguments with [] so that it's more\nobvious for the reader.\n\nSigned-off-by: Denton Liu \n---\n Documentation/revisions.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex e5f11691b1..68cce2ca06 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.\n The construct '@{-}' means the th branch/commit checked out\n before the current one.\n \n-'@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n+'[]@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n The suffix '@\\{upstream\\}' to a branchname (short form '@\\{u\\}')\n refers to the branch that the branch specified by branchname is set to build on\n top of (configured with `branch..remote` and\n@@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.\n current one. These suffixes are also accepted when spelled in uppercase, and\n they mean the same thing no matter the case.\n \n-'@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n+'[]@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n The suffix '@\\{push}' reports the branch \"where we would push to\" if\n `git push` were run while `branchname` was checked out (or the current\n `HEAD` if no branchname is specified). Since our push destination is\n@@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,\n This suffix is also accepted when spelled in uppercase, and means the same\n thing no matter the case.\n \n-'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n+'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n A suffix '{caret}' to a revision parameter means the first parent of\n that commit object. '{caret}' means the th parent (i.e.\n '{caret}'\n-- \n2.21.0.1000.g11cd861522\n\n"},{"id":"374598","messageId":"9012ebc23c1053bfa544b2805338304a7cfa9b99.1556367012.git.liu.denton@gmail.com","threadId":"50968","inReplyTo":"cover.1556367012.git.liu.denton@gmail.com","subject":"[PATCH v2 3/3] revisions.txt: mention ~ form","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-04-27T12:16:09Z","receivedAt":"2019-04-27T12:16:13Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"In revisions.txt, the '^' form is mentioned but the '~' form\nis missing. Although both forms are essentially equivalent (they each\nget the first parent of the specified revision), we should mention the\nlatter for completeness. Make this change.\n\nSigned-off-by: Denton Liu \n---\n Documentation/revisions.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 68cce2ca06..372b286755 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -139,7 +139,9 @@ thing no matter the case.\n '{caret}0' means the commit itself and is used when '' is the\n object name of a tag object that refers to a commit object.\n \n-'{tilde}', e.g. 'master{tilde}3'::\n+'{tilde}[]', e.g. 'HEAD{tilde}, master{tilde}3'::\n+ A suffix '{tilde}' to a revision parameter means the first parent of\n+ that commit object.\n A suffix '{tilde}' to a revision parameter means the commit\n object that is the th generation ancestor of the named\n commit object, following only the first parents. I.e. '{tilde}3' is\n-- \n2.21.0.1000.g11cd861522\n\n"},{"id":"374854","messageId":"1684a040-ebc0-2567-225e-d26aa13951a2@gmail.com","threadId":"50968","inReplyTo":"90c787c219d25f38c1d53ae837160994a7bc6355.1556367012.git.liu.denton@gmail.com","subject":"Re: [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2019-05-03T07:17:53Z","receivedAt":"2019-05-03T07:17:58Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Am 27.04.19 um 14:16 schrieb Denton Liu:\n> In revisions.txt, an optional rev argument was not distinguised.\n> Instead, a user had to continue and read the description in order to\n> learn that the argument was optional.\n> \n> Since the [] notation for an optional argument is common-knowledge in\n> the Git documentation, mark optional arguments with [] so that it's more\n> obvious for the reader.\n> \n> Signed-off-by: Denton Liu \n> ---\n> Documentation/revisions.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index e5f11691b1..68cce2ca06 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n\nI think I found another one here:\n\n@@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8.\n '@'::\n '@' alone is a shortcut for `HEAD`.\n \n-'@{}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n+'[]@{}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n A ref followed by the suffix '@' with a date specification\n enclosed in a brace\n pair (e.g. '\\{yesterday\\}', '{1 month 2 weeks 3 days 1 hour 1\n\nThe doesn't give a hint that is optional but actually it is.\n\n> @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.\n> The construct '@{-}' means the th branch/commit checked out\n> before the current one.\n> \n> -'@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n> +'[]@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n> The suffix '@\\{upstream\\}' to a branchname (short form '@\\{u\\}')\n> refers to the branch that the branch specified by branchname is set to build on\n> top of (configured with `branch..remote` and\n> @@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.\n> current one. These suffixes are also accepted when spelled in uppercase, and\n> they mean the same thing no matter the case.\n> \n> -'@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n> +'[]@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n> The suffix '@\\{push}' reports the branch \"where we would push to\" if\n> `git push` were run while `branchname` was checked out (or the current\n> `HEAD` if no branchname is specified). Since our push destination is\n> @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,\n> This suffix is also accepted when spelled in uppercase, and means the same\n> thing no matter the case.\n> \n> -'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n> +'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n> A suffix '{caret}' to a revision parameter means the first parent of\n> that commit object. '{caret}' means the th parent (i.e.\n> '{caret}'\n\n"},{"id":"374855","messageId":"91924cb1-f1c5-eeb5-21d8-dc6123a223b1@gmail.com","threadId":"50968","inReplyTo":"1684a040-ebc0-2567-225e-d26aa13951a2@gmail.com","subject":"Re: [PATCH v2 2/3] revisions.txt: mark optional rev arguments with []","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2019-05-03T07:35:14Z","receivedAt":"2019-05-03T07:35:19Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Am 03.05.19 um 09:17 schrieb Andreas Heiduk:\n> Am 27.04.19 um 14:16 schrieb Denton Liu:\n>> In revisions.txt, an optional rev argument was not distinguised.\n>> Instead, a user had to continue and read the description in order to\n>> learn that the argument was optional.\n>>\n>> Since the [] notation for an optional argument is common-knowledge in\n>> the Git documentation, mark optional arguments with [] so that it's more\n>> obvious for the reader.\n>>\n>> Signed-off-by: Denton Liu \n>> ---\n>> Documentation/revisions.txt | 6 +++---\n>> 1 file changed, 3 insertions(+), 3 deletions(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index e5f11691b1..68cce2ca06 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n> \n> I think I found another one here:\n> \n> @@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8.\n> '@'::\n> '@' alone is a shortcut for `HEAD`.\n> \n> -'@{}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n> +'[]@{}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n> A ref followed by the suffix '@' with a date specification\n> enclosed in a brace\n> pair (e.g. '\\{yesterday\\}', '{1 month 2 weeks 3 days 1 hour 1\n> \n> The doesn't give a hint that is optional but actually it is.\n> \n>> @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.\n>> The construct '@{-}' means the th branch/commit checked out\n>> before the current one.\n>> \n>> -'@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n>> +'[]@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n>> The suffix '@\\{upstream\\}' to a branchname (short form '@\\{u\\}')\n>> refers to the branch that the branch specified by branchname is set to build on\n>> top of (configured with `branch..remote` and\n>> @@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.\n>> current one. These suffixes are also accepted when spelled in uppercase, and\n>> they mean the same thing no matter the case.\n>> \n>> -'@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n>> +'[]@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n>> The suffix '@\\{push}' reports the branch \"where we would push to\" if\n>> `git push` were run while `branchname` was checked out (or the current\n>> `HEAD` if no branchname is specified). Since our push destination is\n>> @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,\n>> This suffix is also accepted when spelled in uppercase, and means the same\n>> thing no matter the case.\n>> \n>> -'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n>> +'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n>> A suffix '{caret}' to a revision parameter means the first parent of\n>> that commit object. '{caret}' means the th parent (i.e.\n>> '{caret}'\n> \n\nAnd another one I've found after hitting \"Send\" :-(\n\n@@ -346,7 +346,7 @@ Revision Range Summary\n as giving commit '' and then all its parents prefixed with\n '{caret}' to exclude them (and their ancestors).\n \n-'{caret}-', e.g. 'HEAD{caret}-, HEAD{caret}-2'::\n+'{caret}-[]', e.g. 'HEAD{caret}-, HEAD{caret}-2'::\n \tEquivalent to '{caret}..', with '' = 1 if not\n \tgiven.\n"},{"id":"374856","messageId":"7e9ab65d-aee9-b900-c294-8810e0109721@gmail.com","threadId":"50968","inReplyTo":"cover.1556367012.git.liu.denton@gmail.com","subject":"Re: [PATCH v2 0/3] cleanup revisions.txt","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2019-05-03T08:01:08Z","receivedAt":"2019-05-03T08:01:13Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Am 27.04.19 um 14:15 schrieb Denton Liu:\n\nWhile reading/reviewing I stumbled across another case for marking optional\nclauses. But the solutions is not a one-liner. @Denton Would you please add\nthat one as Patch 4/4 to your series?\n\n----------------- 8< ----------------------------\nSubject: [PATCH] revisions.txt: remove ambibuity between : and :\n\nThe revision ':README' is mentioned as an example for ':'\nbut the explanation forwards to the '::' syntax. At the same\ntime '::' did not mark the ':' as optional.\n\nSigned-off-by: Andreas Heiduk \n---\n Documentation/revisions.txt | 7 ++-----\n 1 file changed, 2 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 372b286755..f11d1edc57 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -196,19 +196,16 @@ existing tag object.\n Depending on the given text, the shell's word splitting rules might\n require additional quoting.\n \n-':', e.g. 'HEAD:README', ':README', 'master:./README'::\n+':', e.g. 'HEAD:README', 'master:./README'::\n A suffix ':' followed by a path names the blob or tree\n at the given path in the tree-ish object named by the part\n before the colon.\n- ':path' (with an empty part before the colon)\n- is a special case of the syntax described next: content\n- recorded in the index at the given path.\n A path starting with './' or '../' is relative to the current working directory.\n The given path will be converted to be relative to the working tree's root directory.\n This is most useful to address a blob or tree from a commit or tree that has\n the same tree structure as the working tree.\n \n-'::', e.g. ':0:README', ':README'::\n+':[:]', e.g. ':0:README', ':README'::\n A colon, optionally followed by a stage number (0 to 3) and a\n colon, followed by a path, names a blob object in the\n index at the given path. A missing stage number (and the colon\n-- \n2.21.0\n"},{"id":"374857","messageId":"20190503081354.GA23442@archbookpro.localdomain","threadId":"50968","inReplyTo":"7e9ab65d-aee9-b900-c294-8810e0109721@gmail.com","subject":"Re: [PATCH v2 0/3] cleanup revisions.txt","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-03T08:13:54Z","receivedAt":"2019-05-03T08:13:59Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Hi Andreas,\n\nThanks for the earlier corrections on 2/3.\n\nOn Fri, May 03, 2019 at 10:01:08AM +0200, Andreas Heiduk wrote:\n> Am 27.04.19 um 14:15 schrieb Denton Liu:\n> \n> While reading/reviewing I stumbled across another case for marking optional\n> clauses. But the solutions is not a one-liner. @Denton Would you please add\n> that one as Patch 4/4 to your series?\n\nWill do.\n\nThanks,\n\nDenton\n\n> \n> ----------------- 8< ----------------------------\n> Subject: [PATCH] revisions.txt: remove ambibuity between : and :\n> \n> The revision ':README' is mentioned as an example for ':'\n> but the explanation forwards to the '::' syntax. At the same\n> time '::' did not mark the ':' as optional.\n> \n> Signed-off-by: Andreas Heiduk \n> ---\n> Documentation/revisions.txt | 7 ++-----\n> 1 file changed, 2 insertions(+), 5 deletions(-)\n> \n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 372b286755..f11d1edc57 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -196,19 +196,16 @@ existing tag object.\n> Depending on the given text, the shell's word splitting rules might\n> require additional quoting.\n> \n> -':', e.g. 'HEAD:README', ':README', 'master:./README'::\n> +':', e.g. 'HEAD:README', 'master:./README'::\n> A suffix ':' followed by a path names the blob or tree\n> at the given path in the tree-ish object named by the part\n> before the colon.\n> - ':path' (with an empty part before the colon)\n> - is a special case of the syntax described next: content\n> - recorded in the index at the given path.\n> A path starting with './' or '../' is relative to the current working directory.\n> The given path will be converted to be relative to the working tree's root directory.\n> This is most useful to address a blob or tree from a commit or tree that has\n> the same tree structure as the working tree.\n> \n> -'::', e.g. ':0:README', ':README'::\n> +':[:]', e.g. ':0:README', ':README'::\n> A colon, optionally followed by a stage number (0 to 3) and a\n> colon, followed by a path, names a blob object in the\n> index at the given path. A missing stage number (and the colon\n> -- \n> 2.21.0\n"}]}