Re: [PATCH] fix revisions doc about quoting for ':/' notation
From: Junio C Hamano <hidden>
Date: 2017-08-16 18:49:37
ryenus [off-list ref] writes:
quoted hunk
To make sure the `<text>` in `:/<text>` is seen as one search string, one should quote/escape `<text>` properly. Especially, the example given in the manual `:/fix nasty bug` does not work because of missing quotes. The examples are now corrected, and a note about quoting/escaping is added as well. --- Documentation/revisions.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 61277469c..fdfdde0ad 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt@@ -169,14 +169,14 @@ existing tag object. and dereference the tag recursively until a non-tag object is found. -'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}':: +'<rev>{caret}{/<text>}', e.g. 'HEAD^{/"fix nasty bug"}'::
This made me scratch my head, as I rarely read the formatted result
but look at the documentation in the source form. The original
meant to quote the whole thing inside a single quote, but AsciiDoc
of course will strip that and instead makes the whole thing typeset
in monospace.
What you did is not wrong per-se, but I think quoting the whole
thing, instead of quoting just what is inside the braces, i.e.
'"HEAD^{/fix nasty bug}"' (or if you can manage it, using single
quote instead of double quote) would read better.
A suffix '{caret}' to a revision parameter, followed by a brace
pair that contains a text led by a slash,
is the same as the ':/fix nasty bug' syntax below except that
it returns the youngest matching commit which is reachable from
the '<rev>' before '{caret}'.
-':/<text>', e.g. ':/fix nasty bug'::
+':/<text>', e.g. ':/"fix nasty bug"'::Likewise.
quoted hunk
@@ -185,7 +185,8 @@ existing tag object. e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a literal '!' character, followed by 'foo'. Any other sequence beginning with - ':/!' is reserved for now. + ':/!' is reserved for now. And make sure to quote/escape for the text to be + seen as one search string.
Good. Please sign-off your work (cf. Documentation/SubmittingPatches). Thanks.