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

Kevin Daudt [off-list ref] writes:

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.