Jeff King <p...@peff.net> writes:
> 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.
