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

Jeff King [off-list ref] writes:

On Fri, Nov 10, 2017 at 10:12:39AM -0800, Stefan Beller wrote:

quoted

On Fri, Nov 10, 2017 at 5:57 AM, Robert P. J. Day [off-list ref] wrote:

quoted

  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.

;-).