gitrevisions: be more chatty about shell metacharacter gotchas?

gitrevisions: be more chatty about shell metacharacter gotchas?

[Kristoffer Haugsbakk]

See this question from today (+CC):

https://stackoverflow.com/q/79232719/1725151

The problem turned out to be:

> You are using the Windows command line CMD. This beast treats ^
> specially (it > is some sort of escape character). You have to type it
> twice for every occurrence where you need one of them: [...]

Now gitrevisions(7) already has this:

    Note
    This document shows the "raw" syntax as seen by git. The shell and
    other UIs might require additional quoting to protect special characters
    and to avoid word splitting.

All bases covered.

But, and I don’t know why I didn’t realize this sooner than I did, but
this part:

    :/<text>, e.g. :/fix nasty bug
    [...]
    Depending on the given text, the shell’s word splitting rules might require
    additional quoting.

I don’t recall reading this part (only glazing over it).  I did eventually
guess that I needed to

    :/'fix nasty bug'

because that part needs to be “one word”.  Or something.  It can’t be split.

I think I’m a low-intermediate shell user.  I get by.  In a wider
perspective, git(1) (i.e. in a terminal context, mostly) is used by people
from a wide range of skill levels.  Many seem to (based on the question I
stumble over) mostly be using a terminal because they need to use git(1) and
that’s about it.

So would it make sense to be a bit more chatty about these metacharacter
gotchas on this page?  Maybe add a “Note” on e.g. `^` that these here (?)
popular shells use `^` as a metacharacter?

That would for sure be redundant.  But IMO good documentation finds a
balance between redundancy and other concerns.  Like in the form
of reminders and localized hints.

Also back to this paragraph:

    Depending on the given text, the shell’s word splitting rules might require
    additional quoting.

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.

Thoughts?

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

[Junio C Hamano]

"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:

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

[Kristoffer Haugsbakk]

On Mon, Dec 2, 2024, at 02:26, Junio C Hamano wrote:
> 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:

This is a good addition. Including a couple of good examples.

-- 
Kristoffer Haugsbakk