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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 24, 2017, 06:23 UTC
Message-ID: <xmqqo9nsnqk7.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <xmqqd148p8v4.fsf@gitster.mtv.corp.google.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 17 quoted lines

>> - * 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.
>>  ...
>
> 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.

So, here is my attempt (other than "the original reads clear enough to me, so I am not sure what's there to improve"):

    When the command line does not have the disambiguating `--`, Git
    needs to find where the revisions end and paths begin.  In order
    to make sure it does not guess incorrectly, Git errors out when
    it cannot cheaply determine that there is no ambiguity, and asks
    you to disambiguate with `--`.  If you have a file whose name is
    HEAD, "git diff HEAD" gets an error for this reason; you need to
    say "git diff -- HEAD" or "git diff HEAD --" to disambiguate.

    Also, if you do not have a file whose name is Nakefile and it is
    not a branch or tag name, "git log Nakefile" is flagged as an
    error.  If you know there used to be a file called Nakefile but
    not in the current working tree, "git log -- Nakefile" is how
    you tell Git that you did not make a typo and you mean to find
    commits that touch the path.

I briefly considered the following as a more technically correct description for "cheaply determine", but I am not sure if we want to go down to that level of detail:

    ... when it cannot determine that every argument before one
    point on the command line names a revision and does not have a
    file with that name in the working tree, and every argument
    after that point does have a file with that name and cannot be
    interpreted as a valid revision.

>>  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.

I forgot to mention in my earlier message, but this part of the patch is obviously good ;-)