{"thread":{"id":"51037","subject":"[PATCH v3 0/4] cleanup revisions.txt","startedAt":"2019-05-05T16:07:02Z","lastAt":"2019-05-07T15:16:17Z","messageCount":8,"participants":["Denton Liu","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":4},"messages":[{"id":"374910","messageId":"cover.1557072286.git.liu.denton@gmail.com","threadId":"51037","inReplyTo":"cover.1557071877.git.liu.denton@gmail.com","subject":"[PATCH v3 0/4] cleanup revisions.txt","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-05T16:06:54Z","receivedAt":"2019-05-05T16:07:02Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Thanks again for the comments, Andreas! I've incorporated all of them\ninto this reroll.\n\n---\n\nChanges since v2:\n\n* Marked more optional arguments with []\n* Added Andreas' \"revisions.txt: remove ambibuity between <rev>:<path>\n  and :<path>\" patch\n\nChanges since v1:\n\n* Added patch to fix instances of \"rev\" to \"<rev>\"\n* Marked all optional rev arguments with []\n\n\nAndreas Heiduk (1):\n  revisions.txt: remove ambibuity between <rev>:<path> and :<path>\n\nDenton Liu (3):\n  revisions.txt: change \"rev\" to \"<rev>\"\n  revisions.txt: mark optional rev arguments with []\n  revisions.txt: mention <rev>~ form\n\n Documentation/revisions.txt | 29 ++++++++++++++---------------\n 1 file changed, 14 insertions(+), 15 deletions(-)\n\n-- \n2.21.0.1049.geb646f7864\n\n"},{"id":"374911","messageId":"e5b6d69eec80acab5b4b4c702011fc82a7367a79.1557072286.git.liu.denton@gmail.com","threadId":"51037","inReplyTo":"cover.1557072286.git.liu.denton@gmail.com","subject":"[PATCH v3 1/4] revisions.txt: change \"rev\" to \"<rev>\"","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-05T16:06:59Z","receivedAt":"2019-05-05T16:07:06Z","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 \"<rev>\", instead.\n\nSigned-off-by: Denton Liu <liu.denton@gmail.com>\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   '<rev>{caret}0'\n   is a short-hand for '<rev>{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+'<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 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+'<rev>{caret}\\{tag\\}' can be used to ensure that '<rev>' identifies an\n existing tag object.\n \n '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::\n-- \n2.21.0.1049.geb646f7864\n\n"},{"id":"374912","messageId":"27379aaea940385a7569c1b8a4ff1aac3fc2c05f.1557072286.git.liu.denton@gmail.com","threadId":"51037","inReplyTo":"cover.1557072286.git.liu.denton@gmail.com","subject":"[PATCH v3 2/4] revisions.txt: mark optional rev arguments with []","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-05T16:07:03Z","receivedAt":"2019-05-05T16:07:09Z","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\nHelped-by: Andreas Heiduk <asheiduk@gmail.com>\nSigned-off-by: Denton Liu <liu.denton@gmail.com>\n---\n Documentation/revisions.txt | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex e5f11691b1..dd99770c47 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\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-'<refname>@{<date>}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n+'[<refname>]@{<date>}', 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@@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.\n   The construct '@{-<n>}' means the <n>th branch/commit checked out\n   before the current one.\n \n-'<branchname>@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n+'[<branchname>]@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n   The suffix '@\\{upstream\\}' to a branchname (short form '<branchname>@\\{u\\}')\n   refers to the branch that the branch specified by branchname is set to build on\n   top of (configured with `branch.<name>.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-'<branchname>@\\{push\\}', e.g. 'master@\\{push\\}', '@\\{push\\}'::\n+'[<branchname>]@\\{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-'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::\n+'<rev>{caret}[<n>]', 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}<n>' means the <n>th parent (i.e.\n   '<rev>{caret}'\n@@ -302,7 +302,7 @@ The 'r1{caret}@' notation means all parents of 'r1'.\n The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n By itself, this notation denotes the single commit 'r1'.\n \n-The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th\n+The '<rev>{caret}-[<n>]' notation includes '<rev>' but excludes the <n>th\n parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if\n not given. This is typically useful for merge commits where you\n can just pass '<commit>{caret}-' to get all the commits in the branch\n-- \n2.21.0.1049.geb646f7864\n\n"},{"id":"374913","messageId":"1ba823024edddfb0e6ccb92647137eccf5d4c7d0.1557072286.git.liu.denton@gmail.com","threadId":"51037","inReplyTo":"cover.1557072286.git.liu.denton@gmail.com","subject":"[PATCH v3 3/4] revisions.txt: mention <rev>~ form","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-05T16:07:07Z","receivedAt":"2019-05-05T16:07:13Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"In revisions.txt, the '<rev>^' form is mentioned but the '<rev>~' 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 <liu.denton@gmail.com>\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 dd99770c47..a38ec7fb52 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -139,7 +139,9 @@ thing no matter the case.\n   '<rev>{caret}0' means the commit itself and is used when '<rev>' is the\n   object name of a tag object that refers to a commit object.\n \n-'<rev>{tilde}<n>', e.g. 'master{tilde}3'::\n+'<rev>{tilde}[<n>]', 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}<n>' to a revision parameter means the commit\n   object that is the <n>th generation ancestor of the named\n   commit object, following only the first parents.  I.e. '<rev>{tilde}3' is\n-- \n2.21.0.1049.geb646f7864\n\n"},{"id":"374914","messageId":"e765c0c7b89fc9c6eb00ca4afef094c9c1e46a38.1557072286.git.liu.denton@gmail.com","threadId":"51037","inReplyTo":"cover.1557072286.git.liu.denton@gmail.com","subject":"[PATCH v3 4/4] revisions.txt: remove ambibuity between <rev>:<path> and :<path>","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-05T16:07:10Z","receivedAt":"2019-05-05T16:07:16Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"From: Andreas Heiduk <asheiduk@gmail.com>\n\nThe revision ':README' is mentioned as an example for '<rev>:<path>'\nbut the explanation forwards to the ':<n>:<path>' syntax. At the same\ntime ':<n>:<path>' did not mark the '<n>:' as optional.\n\nSigned-off-by: Andreas Heiduk <asheiduk@gmail.com>\nSigned-off-by: Denton Liu <liu.denton@gmail.com>\n---\nJust for clarification, the correct procedure is to include my sign-off\non top of Andreas' when I'm forwarding patches, correct? If it's not,\nJunio, please take my sign-off for me.\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 a38ec7fb52..82c1e5754e 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-'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::\n+'<rev>:<path>', 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-':<n>:<path>', e.g. ':0:README', ':README'::\n+':[<n>:]<path>', 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.1049.geb646f7864\n\n"},{"id":"374915","messageId":"20190505161027.GA6683@archbookpro.localdomain","threadId":"51037","inReplyTo":"cover.1557072286.git.liu.denton@gmail.com","subject":"Re: [PATCH v3 0/4] cleanup revisions.txt","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-05T16:10:27Z","receivedAt":"2019-05-05T16:10:33Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Sorry, I specified the wrong --in-reply-to. The correct parent message\nshould be this[1].\n\n[1]: https://public-inbox.org/git/cover.1556367012.git.liu.denton@gmail.com/\n\nOn Sun, May 05, 2019 at 12:06:54PM -0400, Denton Liu wrote:\n> Thanks again for the comments, Andreas! I've incorporated all of them\n> into this reroll.\n> \n> ---\n> \n> Changes since v2:\n> \n> * Marked more optional arguments with []\n> * Added Andreas' \"revisions.txt: remove ambibuity between <rev>:<path>\n>   and :<path>\" patch\n> \n> Changes since v1:\n> \n> * Added patch to fix instances of \"rev\" to \"<rev>\"\n> * Marked all optional rev arguments with []\n> \n> \n> Andreas Heiduk (1):\n>   revisions.txt: remove ambibuity between <rev>:<path> and :<path>\n> \n> Denton Liu (3):\n>   revisions.txt: change \"rev\" to \"<rev>\"\n>   revisions.txt: mark optional rev arguments with []\n>   revisions.txt: mention <rev>~ form\n> \n>  Documentation/revisions.txt | 29 ++++++++++++++---------------\n>  1 file changed, 14 insertions(+), 15 deletions(-)\n> \n> -- \n> 2.21.0.1049.geb646f7864\n> \n"},{"id":"375033","messageId":"20190507142938.GA3769@archbookpro.localdomain","threadId":"51037","inReplyTo":"cover.1557072286.git.liu.denton@gmail.com","subject":"Re: [PATCH v3 0/4] cleanup revisions.txt","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-05-07T14:29:38Z","receivedAt":"2019-05-07T14:29:54Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Hi Junio,\n\nI noticed that there are both `dl/rev-tilde-doc-clarify` and\n`dl/revisions-doc-update` branches. The latter comes from this patchset\nand is a complete replacement for the former.\n\nThanks,\n\nDenton\n\nOn Sun, May 05, 2019 at 12:06:54PM -0400, Denton Liu wrote:\n> Thanks again for the comments, Andreas! I've incorporated all of them\n> into this reroll.\n> \n> ---\n> \n> Changes since v2:\n> \n> * Marked more optional arguments with []\n> * Added Andreas' \"revisions.txt: remove ambibuity between <rev>:<path>\n>   and :<path>\" patch\n> \n> Changes since v1:\n> \n> * Added patch to fix instances of \"rev\" to \"<rev>\"\n> * Marked all optional rev arguments with []\n> \n> \n> Andreas Heiduk (1):\n>   revisions.txt: remove ambibuity between <rev>:<path> and :<path>\n> \n> Denton Liu (3):\n>   revisions.txt: change \"rev\" to \"<rev>\"\n>   revisions.txt: mark optional rev arguments with []\n>   revisions.txt: mention <rev>~ form\n> \n>  Documentation/revisions.txt | 29 ++++++++++++++---------------\n>  1 file changed, 14 insertions(+), 15 deletions(-)\n> \n> -- \n> 2.21.0.1049.geb646f7864\n> \n"},{"id":"375039","messageId":"xmqqv9ymjnwn.fsf@gitster-ct.c.googlers.com","threadId":"51037","inReplyTo":"20190507142938.GA3769@archbookpro.localdomain","subject":"Re: [PATCH v3 0/4] cleanup revisions.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-05-07T15:16:08Z","receivedAt":"2019-05-07T15:16:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu <liu.denton@gmail.com> writes:\n\n> I noticed that there are both `dl/rev-tilde-doc-clarify` and\n> `dl/revisions-doc-update` branches. The latter comes from this patchset\n> and is a complete replacement for the former.\n\nThanks for spotting.  Will replace the former with the updated\npatches.\n\nThanks.\n"}]}