Re: gitrevisions: be more chatty about shell metacharacter gotchas?
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Dec 2, 2024, 01:26 UTC
- Message-ID
- <xmqqttbmkh8h.fsf@gitster.g>
- In-Reply-To
- <702d88e9-c62d-482c-a457-6d6642e8488e@app.fastmail.com>
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 13 quoted lines
> 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: