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

On Thu, Nov 23, 2017 at 08:51:55AM -0500, Jeff King wrote:

On Thu, Nov 23, 2017 at 02:45:44AM -0500, Robert P. J. Day wrote:

quoted

quoted

It's pretty clear to me as it is, but maybe we can write it differently.
Like:

  Without a disambiguating `--`, Git makes a reasonable guess. If it
  cannot guess (because your request is ambiguous), then it will error
  out.

  ok, i'll give this another try, given that there are two independent
points to be made here:

1) even without the "--", git can generally parse the command and do
the right thing (or do a *valid* thing, given its heuristics)

2) occasionally, without the "--", the command is really and truly
ambiguous, at which point git will fail and tell you to disambiguate

  not the wording i will use, but can we agree that those are the two
points to be made here?

Yep, I think so.

-Peff

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.

Might be worth documenting this.

Kevin