Re: gitrevisions: be more chatty about shell metacharacter gotchas?

[Junio C Hamano <gitster@pobox.com>]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> Part of why my eyes might have glazed over (I think) is that this is very
> technical phrasing.  Yes, technical phrasing in a technical manual.  To be
> expected.  But the topic is the revision syntax; all of us Git users of
> varying levels might be primed for less terse but more evident paragraphs
> like
>
>     Keep in mind that you probably should quote the search string.  A search
>     string like `:/fix nasty bug` could be interpreted as just `:/fix`
>     depending on how your shell splits words.  Try to stick to
>     `:/'fix nasty bug'` or `:/"fix nasty bug"` (whichever is better in your
>     shell) for that reason.
>
> Because this leads with what the gotcha and remedy is about.

I am very much sympathetic to the cause to help people avoid making
mistakes, and reminding of the basic rules of command line syntax
"as needed" may be a good idea.

Any arguments and options you give from the command line are subject
to the same shell quoting rules, and we at least need one single
place to say exactly that to help beginners.

On top of that, there are probably arguments and options that more
often contain shell metacharacters (like '*' and ' ') than other
arguments and options, and it may be helpful to beginners to remind
the need for quoting.  But "as needed" is relative to the level of
reader, and if we overdo it, it would make it less readable for
other readers.

There already is a note about '*'; we can add another note about
whitespace next to it, perhaps here.

 Documentation/gitcli.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
index 7c709324ba..0a67005fc6 100644
--- c/Documentation/gitcli.txt
+++ w/Documentation/gitcli.txt
@@ -57,6 +57,16 @@ When writing a script that is expected to handle random user-input, it is
 a good practice to make it explicit which arguments are which by placing
 disambiguating `--` at appropriate places.
 
+ * Arguments, options, and option values given on the shell command
+   line follow the usual shell syntax rules.  You'd need to quote
+   your string with whitespace in it appropriately if you do not
+   want it to be split by the shell, for example.
++
+--------------------------------
+$ git commit -m "my message with whitespace"
+$ git show "HEAD^{/^my message with whitespace}"
+--------------------------------
+
  * Many commands allow wildcards in paths, but you need to protect
    them from getting globbed by the shell.  These two mean different
    things: