"brian m. carlson" <sandals@xxxxxxxxxxxxxxxxxxxx> writes:
> This is indeed a subtle incompatibility in command-line option parsing,
> but it's not really avoidable and it does occur in pretty much any case
> where a short option learns to take an optional argument (for any
> software, not just Git).
Perhaps we'd want something along this line? While it is not really
avoidable if we have to add an optional value to an existing option,
"not really avoidable" is not a very satisfactory explanation to
please those whose established use cases they have, or their
scripts, have got broken.
--- >8 ------ >8 ------ >8 ---
Subject: gitcli: explain why short options are better spelled separately
When the "--track" option of "git checkout" command learned to take
an optional value a few years ago at d3115660 (branch: add flags and
config to inherit tracking, 2021-12-20), "git checkout -tb foo" got
broken, as it is no longer two options "--track" and "--branch=foo"
given together, but "--track=b" and a regular argument "foo". The
command parser dies upon seeing "-tb" saying "b" is not a valid
optional value to "-t".
We already discourage users to spell short options in stuck form,
and if they spelled "-t -b foo", they would not have noticed this
breakage. Add a bit more words to "git help cli" to explain why
we discourage the stuck form.
We might also want to add a note to ourselves (perhaps next to the
Documentation/CodingGuidelines, we'd want design guidelines) to
think very carefully before considering to introduce an option that
takes an optional value, and refrain from adding an optional value
to an existing option. It would save the end users from confusion.
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
Documentation/gitcli.txt | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
index bd62cbd043..dcc0aa5bf7 100644
--- c/Documentation/gitcli.txt
+++ w/Documentation/gitcli.txt
@@ -82,7 +82,9 @@ Here are the rules regarding the "flags" that you should follow when you are
scripting Git:
* Splitting short options to separate words (prefer `git foo -a -b`
- to `git foo -ab`, the latter may not even work).
+ to `git foo -ab`, the latter may not even work, and even if it
+ worked, it will change the meaning once the '-a' option starts
+ taking an optional value).
* When a command-line option takes an argument, use the 'stuck' form. In
other words, write `git foo -oArg` instead of `git foo -o Arg` for short
