"Robert P. J. Day" <rpjday@xxxxxxxxxxxxxx> writes: > -This manual describes the convention used throughout Git CLI. > +This manual describes the conventions used throughout Git CLI. OK. > Many commands take revisions (most often "commits", but sometimes > "tree-ish", depending on the context and command) and paths as their > @@ -32,32 +32,35 @@ arguments. Here are the rules: > between the HEAD commit and the work tree as a whole". You can say > `git diff HEAD --` to ask for the latter. > > - * Without disambiguating `--`, Git makes a reasonable guess, but errors > - out and asking you to disambiguate when ambiguous. E.g. if you have a > - file called HEAD in your work tree, `git diff HEAD` is ambiguous, and > + * In cases where a Git command is truly ambiguous, Git will error out > + and ask you to disambiguate the command. E.g. if you have a file > + called HEAD in your work tree, `git diff HEAD` is ambiguous, and > you have to say either `git diff HEAD --` or `git diff -- HEAD` to > disambiguate. > + > 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. > +a disambiguating `--` at appropriate places. The above "truly" is misleading by giving the information the other way around. We ask to disambiguate when we cannot readily say the command line is *not* unambiguous. That is different from asking when we know it is truly ambiguous. Also see <xmqq7eugqykq.fsf@xxxxxxxxxxxxxxxxxxxxxxxxxxx> if you want to know more. > * Many commands allow wildcards in paths, but you need to protect > - them from getting globbed by the shell. These two mean different > - things: > + them from getting globbed by the shell. The following commands have > + two different meanings: > + > -------------------------------- > $ git checkout -- *.c > + > $ git checkout -- \*.c > +$ git checkout -- "*.c" > +$ git checkout -- '*.c' I do not think these two additional ones add any value. And if you do not add these two, you do not need any of the change we see before or after this example. The changes you made to these paragraphs are primarily there because you need to explain that the latter three are equivalent to each other now because of these two extra ones, while the original did not have to say anything like that. Because this is not a tutorial for shell scripting and its quoting rules, highlighting the difference between the case where Git sees the asterisk and you let shell to expand asterisk and do not let Git see the asterisk _is_ important, but the fact that you can quote the asterisk in different ways from the shell is *not* important. We shouldn't clutter the description with the latter, I would think. I would however be receptive if the change were to only replace the backslash quoting of asterisk with the one that uses a single quote pair (and with no changes in the surrounding paragraphs). That change could be justified by saying that a pair of single (or double) quotes would be more familiar for people new to the shell. Thanks.
