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

From: Kevin Daudt <me@ikke.info>
Date: Nov 23, 2017, 20:55 UTC
Message-ID: <20171123205503.GE16418@alpha.vpn.ikke.info>
In-Reply-To: <20171123135155.GA8231@sigill>

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

Show 24 quoted lines

> On Thu, Nov 23, 2017 at 02:45:44AM -0500, Robert P. J. Day wrote:
> 
> > > 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