{"thread":{"id":"46601","subject":"[PATCH] fix revisions doc about quoting for ':/' notation","startedAt":"2017-08-16T03:21:38Z","lastAt":"2017-08-17T07:01:32Z","messageCount":5,"participants":["ryenus","Junio C Hamano","Andreas Heiduk"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"326486","messageId":"CAKkAvazj28RR1nHEWNNeZeyE6mpkb3opk6kvrxP6Lau6tcCbJQ@mail.gmail.com","threadId":"46601","inReplyTo":null,"subject":"[PATCH] fix revisions doc about quoting for ':/' notation","fromName":"ryenus","fromEmail":"ryenus@gmail.com","sentAt":"2017-08-16T03:21:10Z","receivedAt":"2017-08-16T03:21:38Z","isPatch":true,"sender":{"key":"ryenus@gmail.com","avatar":"https://avatars.githubusercontent.com/u/610161?v=4"},"body":"To make sure the `<text>` in `:/<text>` is seen as one search string,\none should quote/escape `<text>` properly.\n\nEspecially, the example given in the manual `:/fix nasty bug` does not\nwork because of missing quotes. The examples are now corrected, and a\nnote about quoting/escaping is added as well.\n---\n Documentation/revisions.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 61277469c..fdfdde0ad 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -169,14 +169,14 @@ existing tag object.\n   and dereference the tag recursively until a non-tag object is\n   found.\n\n-'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::\n+'<rev>{caret}{/<text>}', e.g. 'HEAD^{/\"fix nasty bug\"}'::\n   A suffix '{caret}' to a revision parameter, followed by a brace\n   pair that contains a text led by a slash,\n   is the same as the ':/fix nasty bug' syntax below except that\n   it returns the youngest matching commit which is reachable from\n   the '<rev>' before '{caret}'.\n\n-':/<text>', e.g. ':/fix nasty bug'::\n+':/<text>', e.g. ':/\"fix nasty bug\"'::\n   A colon, followed by a slash, followed by a text, names\n   a commit whose commit message matches the specified regular expression.\n   This name returns the youngest matching commit which is\n@@ -185,7 +185,8 @@ existing tag object.\n   e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what\n   is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a\n   literal '!' character, followed by 'foo'. Any other sequence beginning with\n-  ':/!' is reserved for now.\n+  ':/!' is reserved for now. And make sure to quote/escape for the text to be\n+  seen as one search string.\n\n '<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::\n   A suffix ':' followed by a path names the blob or tree\n--\n2.14.1\n"},{"id":"326527","messageId":"xmqq7ey3l551.fsf@gitster.mtv.corp.google.com","threadId":"46601","inReplyTo":"CAKkAvazj28RR1nHEWNNeZeyE6mpkb3opk6kvrxP6Lau6tcCbJQ@mail.gmail.com","subject":"Re: [PATCH] fix revisions doc about quoting for ':/' notation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-08-16T18:49:30Z","receivedAt":"2017-08-16T18:49:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"ryenus <ryenus@gmail.com> writes:\n\n> To make sure the `<text>` in `:/<text>` is seen as one search string,\n> one should quote/escape `<text>` properly.\n>\n> Especially, the example given in the manual `:/fix nasty bug` does not\n> work because of missing quotes. The examples are now corrected, and a\n> note about quoting/escaping is added as well.\n> ---\n>  Documentation/revisions.txt | 7 ++++---\n>  1 file changed, 4 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 61277469c..fdfdde0ad 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -169,14 +169,14 @@ existing tag object.\n>    and dereference the tag recursively until a non-tag object is\n>    found.\n>\n> -'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::\n> +'<rev>{caret}{/<text>}', e.g. 'HEAD^{/\"fix nasty bug\"}'::\n\nThis made me scratch my head, as I rarely read the formatted result\nbut look at the documentation in the source form.  The original\nmeant to quote the whole thing inside a single quote, but AsciiDoc\nof course will strip that and instead makes the whole thing typeset\nin monospace.\n\nWhat you did is not wrong per-se, but I think quoting the whole\nthing, instead of quoting just what is inside the braces, i.e.\n'\"HEAD^{/fix nasty bug}\"' (or if you can manage it, using single\nquote instead of double quote) would read better.\n\n>    A suffix '{caret}' to a revision parameter, followed by a brace\n>    pair that contains a text led by a slash,\n>    is the same as the ':/fix nasty bug' syntax below except that\n>    it returns the youngest matching commit which is reachable from\n>    the '<rev>' before '{caret}'.\n>\n> -':/<text>', e.g. ':/fix nasty bug'::\n> +':/<text>', e.g. ':/\"fix nasty bug\"'::\n\nLikewise.\n\n> @@ -185,7 +185,8 @@ existing tag object.\n>    e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what\n>    is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a\n>    literal '!' character, followed by 'foo'. Any other sequence beginning with\n> -  ':/!' is reserved for now.\n> +  ':/!' is reserved for now. And make sure to quote/escape for the text to be\n> +  seen as one search string.\n\nGood.\n\nPlease sign-off your work (cf. Documentation/SubmittingPatches).\n\nThanks.\n"},{"id":"326559","messageId":"956ccc83-c291-4217-795c-fcef33fac35b@gmail.com","threadId":"46601","inReplyTo":"CAKkAvazj28RR1nHEWNNeZeyE6mpkb3opk6kvrxP6Lau6tcCbJQ@mail.gmail.com","subject":"Re: [PATCH] fix revisions doc about quoting for ':/' notation","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2017-08-16T21:15:47Z","receivedAt":"2017-08-16T21:15:56Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Am 16.08.2017 um 05:21 schrieb ryenus:\n> To make sure the `<text>` in `:/<text>` is seen as one search string,\n> one should quote/escape `<text>` properly.\n> \n> Especially, the example given in the manual `:/fix nasty bug` does not\n> work because of missing quotes. The examples are now corrected, and a\n> note about quoting/escaping is added as well.\n\nRight now the documentation describes the syntax as git sees the\nparameters. This is agnostic of the shell or other UI with their\ndifferent quoting rules.  For example users of fish must quote\n`rev@{2}`. A GUI might require no quoting at all. In that case `:/\"fix\nnasty bugs\"` would be given to git verbatim and hence not find the revision.\n\nAlso: Other examples like `HEAD@{5 minutes ago}` need the same quoting.\n\nSo my suggestion is to not use quoting in the examples and provide only\na hint in the text. Example:\n\n <rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::\n    A suffix '{caret}' to a revision parameter, followed by a brace\n    pair that contains a text led by a slash,\n    is the same as the ':/fix nasty bug' syntax below except that\n    it returns the youngest matching commit which is reachable from\n    the '<rev>' before '{caret}'.\n+   Depending on the given text the shell's word splitting rules\n+   might require additional quoting.\n"},{"id":"326565","messageId":"xmqqo9rfi3b2.fsf@gitster.mtv.corp.google.com","threadId":"46601","inReplyTo":"956ccc83-c291-4217-795c-fcef33fac35b@gmail.com","subject":"Re: [PATCH] fix revisions doc about quoting for ':/' notation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-08-16T21:57:21Z","receivedAt":"2017-08-16T21:57:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Heiduk <asheiduk@gmail.com> writes:\n\n> Am 16.08.2017 um 05:21 schrieb ryenus:\n>> To make sure the `<text>` in `:/<text>` is seen as one search string,\n>> one should quote/escape `<text>` properly.\n>> \n>> Especially, the example given in the manual `:/fix nasty bug` does not\n>> work because of missing quotes. The examples are now corrected, and a\n>> note about quoting/escaping is added as well.\n>\n> Right now the documentation describes the syntax as git sees the\n> parameters. This is agnostic of the shell or other UI with their\n> different quoting rules.  For example users of fish must quote\n> `rev@{2}`. A GUI might require no quoting at all. In that case `:/\"fix\n> nasty bugs\"` would be given to git verbatim and hence not find the revision.\n\nThese are all good points that I didn't consider when responding.\n\n> Also: Other examples like `HEAD@{5 minutes ago}` need the same quoting.\n>\n> So my suggestion is to not use quoting in the examples and provide only\n> a hint in the text. Example:\n>\n>  <rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::\n>     A suffix '{caret}' to a revision parameter, followed by a brace\n>     pair that contains a text led by a slash,\n>     is the same as the ':/fix nasty bug' syntax below except that\n>     it returns the youngest matching commit which is reachable from\n>     the '<rev>' before '{caret}'.\n> +   Depending on the given text the shell's word splitting rules\n> +   might require additional quoting.\n\nThat sounds like a very safe change to adopt, regardless of what we\ndecide to do to the other part of the proposed change.\n\nThanks.\n"},{"id":"326584","messageId":"CAKkAvay1gJTLJrGLb3aFMJmnyQjPhSD9cx0DRAAN3Mh5NAhfiQ@mail.gmail.com","threadId":"46601","inReplyTo":"xmqqo9rfi3b2.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] fix revisions doc about quoting for ':/' notation","fromName":"ryenus","fromEmail":"ryenus@gmail.com","sentAt":"2017-08-17T07:01:06Z","receivedAt":"2017-08-17T07:01:32Z","isPatch":true,"sender":{"key":"ryenus@gmail.com","avatar":"https://avatars.githubusercontent.com/u/610161?v=4"},"body":"On 17 August 2017 at 05:57, Junio C Hamano <gitster@pobox.com> wrote:\n> Andreas Heiduk <asheiduk@gmail.com> writes:\n>\n>> Am 16.08.2017 um 05:21 schrieb ryenus:\n>>> To make sure the `<text>` in `:/<text>` is seen as one search string,\n>>> one should quote/escape `<text>` properly.\n>>>\n>>> Especially, the example given in the manual `:/fix nasty bug` does not\n>>> work because of missing quotes. The examples are now corrected, and a\n>>> note about quoting/escaping is added as well.\n>>\n>> Right now the documentation describes the syntax as git sees the\n>> parameters. This is agnostic of the shell or other UI with their\n>> different quoting rules.  For example users of fish must quote\n>> `rev@{2}`. A GUI might require no quoting at all. In that case `:/\"fix\n>> nasty bugs\"` would be given to git verbatim and hence not find the revision.\n>\n> These are all good points that I didn't consider when responding.\n>\n\nMakes sense for me, too. I've just sent a v2 patch, which leaves the original\nexample as-is, meanwhile added a example inside the explanation.\n\nThanks!\n"}]}