Re: is there a stylistic preference for a trailing "--" on a command?

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> writes:

> On Fri, Nov 10, 2017 at 10:12:39AM -0800, Stefan Beller wrote:
>
>> On Fri, Nov 10, 2017 at 5:57 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>> >
>> >   just noticed these examples in "man git-bisect":
>> >
>> > EXAMPLES
>> >   $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
>> >   ...
>> >   $ git bisect start HEAD origin --    # HEAD is bad, origin is good
>> >   ...
>> >   $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
>> >
>> > is there some rationale or stylistic significance to those trailing
>> > "--" on those commands? i assume they have no effect, just curious as
>> > to why they're there.
>> 
>> By having the -- there, it is clear that the strings are ref specs and not files
>> of such a name. (Who would want to store a file named HEAD~10 in their
>> repo?)
>
> Just to be explicit, that makes it not just clear to the user but clear
> to Git. Without a "--" there heuristics that kick in. The first section
> of the "gitcli" manpage talks about this, though I don't know that we
> explicitly document the heuristics anywhere (and I think that is
> intentional -- we promise only to try to do what you meant, and scripts
> that want exact behavior should use a disambiguating "--").

It is funny that your "Just to be explicit" reads two ways, and both
readings turn out to be correct ;-)

Yes, the use of these "--" in the examples are just to be explicit
that the arguments that come before "--" are revisions (and not
pathspecs); doing so prevents Git from complaining of ambiguity even
when a file whose name is HEAD happens to be in your working tree.

And it is good that you explicitly teach that these are not to
clarify for the end users' who read the examples, but to encourage
users to get into the habit of using them to make their intention
clear when writing their scripts.

;-).