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

[Jeff King <peff@peff.net>]

On Thu, Nov 23, 2017 at 09:55:03PM +0100, Kevin Daudt wrote:

> > > >   Without a disambiguating `--`, Git makes a reasonable guess. If it
> > > >   cannot guess (because your request is ambiguous), then it will error
> > > >   out.
> [...]
> > > 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
> [...]
> 
> 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:

Right, I was focused on what the sentence _currently_ said, and didn't
think about other cases. The "cannot guess" case is not just due to
ambiguity, but may be due to other heuristics.

I _think_ the only one is the "does it exist in the working tree" rule
you found, but I'm not sure we'd want to commit ourselves to never
changing that.

You could make my suggestion correct by putting "e.g.," or "for example"
at the front of the parentheses. ;)

There is an open question of how carefully we want to document it, but I
think the strategy so far has been:

 - if you want to be careful, use "--"

 - if you don't, git will use black magic to guess, but that magic is
   subject to change, so don't rely on it

I don't mind documenting the current magic as long as the "don't rely on
it" part is made clear.

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

For that command, yes. But when the command is "git log", do we really
want to dig through all of history to see if anybody ever mentions
"deleted_file"?

I'm not sure if we want to get into having different rules for different
contexts. Not to mention that this really mixes up the layers; you
cannot know what the whole command line means until you decide what
abc123 means and examine it, which may in turn be influenced by other
options. E.g., given:

  git log --no-merges A..B deleted_file.txt

we have to actually do the no-merges log of A..B to see if
deleted_file.txt is in there.

-Peff