{"thread":{"id":"45707","subject":"[PATCH] doc/revisions: remove brackets from rev^-n shorthand","startedAt":"2017-04-16T04:08:18Z","lastAt":"2017-04-16T04:32:18Z","messageCount":2,"participants":["Kyle Meyer","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"316905","messageId":"20170416040757.32104-1-kyle@kyleam.com","threadId":"45707","inReplyTo":null,"subject":"[PATCH] doc/revisions: remove brackets from rev^-n shorthand","fromName":"Kyle Meyer","fromEmail":"kyle@kyleam.com","sentAt":"2017-04-16T04:07:57Z","receivedAt":"2017-04-16T04:08:18Z","isPatch":true,"sender":{"key":"kyle@kyleam.com","avatar":"https://avatars.githubusercontent.com/u/1297788?v=4"},"body":"Given that other instances of \"{...}\" in the revision documentation\nrepresent literal characters of revision specifications, describing\nthe rev^-n shorthand as \"<rev>^-{<n>}\" incorrectly suggests that\nsomething like \"master^-{1}\" is an acceptable form.\n\nSigned-off-by: Kyle Meyer <kyle@kyleam.com>\n---\n Documentation/revisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 75d211f1a..61277469c 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -295,7 +295,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@@ -337,7 +337,7 @@ Revision Range Summary\n   as giving commit '<rev>' and then all its parents prefixed with\n   '{caret}' to exclude them (and their ancestors).\n \n-'<rev>{caret}-{<n>}', e.g. 'HEAD{caret}-, HEAD{caret}-2'::\n+'<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2'::\n \tEquivalent to '<rev>{caret}<n>..<rev>', with '<n>' = 1 if not\n \tgiven.\n \n-- \n2.12.2\n\n"},{"id":"316908","messageId":"20170416043211.cctkxmjgijk3mtps@sigill.intra.peff.net","threadId":"45707","inReplyTo":"20170416040757.32104-1-kyle@kyleam.com","subject":"Re: [PATCH] doc/revisions: remove brackets from rev^-n shorthand","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-04-16T04:32:12Z","receivedAt":"2017-04-16T04:32:18Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Apr 16, 2017 at 12:07:57AM -0400, Kyle Meyer wrote:\n\n> Given that other instances of \"{...}\" in the revision documentation\n> represent literal characters of revision specifications, describing\n> the rev^-n shorthand as \"<rev>^-{<n>}\" incorrectly suggests that\n> something like \"master^-{1}\" is an acceptable form.\n\nI wondered at first if this was some weird asciidoc quoting thing. But\nno, the curly braces make it through to the rendered version. I agree\nthey are confusing.\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\nThis _could_ be:\n\n  <rev>^-[<n>]\n\nto show that the <n> parameter is optional. I think the extra\npunctuation in a situation like this just makes things harder to read,\nthough. The text already mentions the default for <n> and gives an\nexample that omits it, so I think the paragraph is clear as-is (well,\nafter your patch removes the confusing \"{}\").\n\n-Peff\n"}]}