[PATCH v2] update revisions doc for quoting in ':/' notation

[PATCH v2] update revisions doc for quoting in ':/' notation

[ryenus]

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 when used in shell. A note about
quoting/escaping is added along with a working example, however, the
original example is left-as-is to be consistent with other examples.

Signed-off-by: ryenus <ryenus@gmail.com>
---
 Documentation/revisions.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 61277469c..d2862d55d 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -185,7 +185,9 @@ 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
+  interpreted as the expected search string/pattern, e.g., for a commit whose
+  message matches a literal \'`$`', use `git show :/\\\$` or `git show ':/\$'`.

 '<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
   A suffix ':' followed by a path names the blob or tree
-- 
2.14.1

Re: [PATCH v2] update revisions doc for quoting in ':/' notation

[Junio C Hamano]

ryenus <ryenus@gmail.com> writes:

> 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 when used in shell. A note about
> quoting/escaping is added along with a working example, however, the
> original example is left-as-is to be consistent with other examples.
>
> Signed-off-by: ryenus <ryenus@gmail.com>
> ---
>  Documentation/revisions.txt | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 61277469c..d2862d55d 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -185,7 +185,9 @@ 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
> +  interpreted as the expected search string/pattern, e.g., for a commit whose
> +  message matches a literal \'`$`', use `git show :/\\\$` or `git show ':/\$'`.

Hmph.  

This seems to miss the most important point Andreas raised, which is
that the way to quote them is entirely up to the shell and other UI
machinery the user is using.

And I am not sure if those who are using CUI should be told about
shell's quoting rules when they are learning about :/ syntax.  There
are tons of other ways that the user needs to pass a string with
whitespace in it as a single argument to commands, many of which may
not even be related to Git at all.  I was actually expecting a much
milder text, perhaps literal copy of what Andreas gave you in his
message <956ccc83-c291-4217-795c-fcef33fac35b@gmail.com>.

By the way, I do not mean to dictate what name and address you use
to communicate with other people, but especially with something that
is supposed to hopefully have some legal value down the line if
somebody starts making SCO noises, it really would be nice to have a
real person to associate things with recorded as the author of a
change and the person who signed off the patch.  It would be
embarrassing later if there is no way to even look you up somehow.

Thanks.