gitrevisions: be more chatty about shell metacharacter gotchas?

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

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?