gitrevisions: be more chatty about shell metacharacter gotchas?

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Nov 28, 2024, 19:30 UTC
Message-ID: <702d88e9-c62d-482c-a457-6d6642e8488e@app.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?