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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 25, 2017, 03:02 UTC
Message-ID: <xmqqpo87kqm3.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171124181254.GC29190@sigill>

Jeff King <peff@peff.net> writes:

Show 10 quoted lines

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

Yes, taken with "git log master" example where if we want to say "this truly cannot be ambiguous" and end up digging "git log HEAD --" to ensure there is no path that match 'master' ever existed, I would prefer not to say a lot more about "black magic" and yet still going into the precise details.

On the other hand, of course we do not want to cast in stone the precise details of the current "black magic" implementation that is subject to change.

A description of "black magic" that is without details, i.e. the one that focuses on the spirit and not the exact design, would be...

    Without "--", Git tries to find a point between two arguments on
    (or at the beginning or the end of) the command line, where
    every argument before it are likely to be a revision (and
    unlikely to be a path) and every argument after it are likely to
    be a path (and unlikely to be a revision) with "black magic".
    If there is no such point, you'd be asked to disambiguate.

    The "black magic" would use 4 combinations that results from
    two tests.

    A. Is it likely to be a revision (yes/no)?
    B. Is it likely to be a path (yes/no)?

    If both are true, it is am ambigous command line.  If neither is
    true, it is likely a typo (e.g. "git log naster" when the user
    meant 'master', or "git log Nakefile" when the user meant
    'Makefile').  If only one is true, Git thinks that the command
    line is unambigous and goes ahead with its decision.

    Git will not spend excess amount of cycles to make these two
    tests, so there can be misidentification.  Two easy to
    understand examples are:

    - If you have a file 'naster' in your working tree and said "git
      log naster", test A _could_ notice that there is a slightly
      different name 'master' that could be a revision that you
      meant, and ask you to disambiguate in case you made a typo.
      Because test A (deliberately) is not overly thorough, Git does
      not flag it as a possible ambiguity.

    - If you had a file whose name is "Nakefile" in HEAD but you
      just removed it, "git log Nakefile" may actually be a valid
      and unambigous request to use Nakefile as a path, but in order
      to notice that possibility, Git has to not just check if the
      working tree has such a path, but also in the index and HEAD
      (and if the removal was older, then it has to do an internal
      "git log" to see what paths ever existed in the past, which is
      ridiculous).  Because test B (deliberately) is not overly
      thorough, Git would refuse to use it as either a revision or a
      path without disambiguation.