On Fri, Jan 14 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes:
>
>>>> But when GNU came around its option parser was generally happy to accept
>>>> options and args in either order. E.g. these both work with GNU
>>>> coreutils, but the latter will fail on FreeBSD and various other
>>>> capital-U UNIX-es:
>>>>
>>>> touch foo; rm -v foo
>>>> touch foo; rm foo -v
>>
>> This is only an approximate list, but:
>
> Don't waste your time on this, and instead spend on something more
> useful. What I gave wrt gitcli.txt in an earlier message is final.
Whatever we do with git-ls-remote (which I don't really care all that
much about) gitcli should really be documenting how our tooling behaves.
Which is what I was mainly pointing out upthread, that your summary of
options before other types of args omitted that many utilities support
the reverse. Or perhaps you were only describing an asthetic choice
(which I don't think is worth debating). I'm just talking about what the
ground truth is.
What do you think about something like this to clear this up?:
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 92e4ba6a2fa..b1387c4fe68 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -19,6 +19,13 @@ Many commands take revisions (most often "commits", but sometimes
"tree-ish", depending on the context and command) and paths as their
arguments. Here are the rules:
+ * Options are (almost) universally accpted before other types of
+ arguments, e.g. `git cat-file -t HEAD` or `git push --dry-run
+ origin`, but in the case of those commands a GNU-style `git
+ cat-file HEAD -t` and `git push origin --dry-run` would work just
+ as well. The reverse is often not true, many commands do not accept
+ options after non-option arguments.
+
* Revisions come first and then paths.
E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
`v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`
