Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 24, 2017, 01:01 UTC
Message-ID: <xmqq7eugqykq.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171123205503.GE16418@alpha.vpn.ikke.info>

Kevin Daudt <me@ikke.info> writes:

Show 15 quoted lines

> Just for completeness, as it is somewhat covered by point 1 already, but
> there are cases where there is no real ambiguity but you are required to
> add '--' to tell git that it should not look for the file in the working
> tree:
>
>   $ git show abc123 deleted_file.txt
>   fatal: ambiguous argument 'deleted_file.txt':
>   unknown revision or path not in the working tree.
>   Use '--' to separate paths from revisions, like this:
>   'git <command> [<revision>...] -- [<file>...]'
>
> There might be good reasons why this is, but I don't consider this to be
> actually ambiguous: there is no branch called 'deleted_file.txt' and git
> could know that the files exists in the mentioned commit, so it should
> be pretty clear what is meant.

I know you understand all of this, but your "git could" needs to be examined carefully.

The same can be said for "git log master deleted_file.txt" whose intention is to refer to a file that the user _thinks_ existed once in the past but may never have been there.

Surely, "git could" know if it runs "git log master" to the root of the history to see if it ever existed. Also, against "git log master next deleted_file.txt", "git could" do the same traversal from two tips of the history to check that. But it requires us to do the same work twice to materialize that "git could".

Actually the second example is a lot worse (and that is why I am bringing it up). If git does spend cycles to realize that "git could", for consistency, it must also check if "next" is unambiguous between a path or a rev, i.e. it must dig history from "master" and see if "next" appears as a path ever in the history, and if so, die with "ambiguous argument".

The message "unknown revision or path not in the working tree." clearly shows why we decided to ask. Even if deleted_file.txt could have been a valid path somewhere in the history, "not in the working tree" is the condition we check to see if it is unambiguous. And we stop and ask when it cannot be proven cheaply that it is not.

"git stops and asks when ambiguous" is a white lie to explain the safety feature in a way that is easier to understand. If somebody wants to make the documentation more "technically correct", the condition is not "when ambiguous", but "when git cannot prove it is not unambiguous with inexpensive tests".

IIRC, I think Peff mentioned in this or nearby thread that we do not want to spell out the implementation details and leave the exact conditions vague on purpose, and that principle probably would apply here, too. We might later discover that checking not just the working tree but also for the index to see if user meant by deleted_file.txt a path and not a revision is not overly expensive, for example, and at that point, we are still trying to prove that it is unambiguously a path and not a rev with inexpensive tests.