Re: [PATCH] fix revisions doc about quoting for ':/' notation

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 16, 2017, 18:49 UTC
Message-ID: <xmqq7ey3l551.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAKkAvazj28RR1nHEWNNeZeyE6mpkb3opk6kvrxP6Lau6tcCbJQ@mail.gmail.com>

ryenus <ryenus@gmail.com> writes:

Show 20 quoted lines

> 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.

Show 8 quoted lines

>    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.

Show 7 quoted lines

> @@ -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.