Re: [PATCH v3] doc: tweak "man gitcli" for clarity

[Junio C Hamano <gitster@pobox.com>]

"Robert P. J. Day" <rpjday@crashcourse.ca> 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@gitster.mtv.corp.google.com> 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.