parse-options: show negatability of options in short help
Add a "[no-]" prefix to options without the flag PARSE_OPT_NONEG to document the fact that you can negate them. This looks a bit strange for options that already start with "no-", e.g. for the option --no-name of git show-branch: --[no-]no-name suppress naming strings You can actually use --no-no-name as an alias of --name, so the short help is not wrong. If we strip off any of the "no-"s, we lose either the ability to see if the remaining one belongs to the documented variant or to see if it can be negated. Signed-off-by: René Scharfe <l.s.r@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
René Scharfe committed
Aug 5, 2023 at 16:40 UTC
e8e5d294dc6e3b6b32132cc8018d01ce35ad0af0
7 files changed
+58
-45
Documentation/git-rev-parse.txt
+4
-4
@@ -424,10 +424,10 @@ usage: some-command [<options>] <args>...
424
some-command does foo and bar!
425
426
-h, --help show the help
427
- --foo some nifty option --foo
428
- --bar ... some cool option --bar with an argument
429
- --baz <arg> another cool option --baz with a named argument
430
- --qux[=<path>] qux may take a path argument but has meaning by itself
427
+ --[no-]foo some nifty option --foo
428
+ --[no-]bar ... some cool option --bar with an argument
429
+ --[no-]baz <arg> another cool option --baz with a named argument
430
+ --[no-]qux[=<path>] qux may take a path argument but has meaning by itself
431
432
An option group Header
433
-C[...] option C with an optional argument
contrib/subtree/t/t7900-subtree.sh
+1
-1
@@ -71,7 +71,7 @@ test_expect_success 'shows short help text for -h' '
71
test_expect_code 129 git subtree -h >out 2>err &&
72
test_must_be_empty err &&
73
grep -e "^ *or: git subtree pull" out &&
74
- grep -e --annotate out
74
+ grep -F -e "--[no-]annotate" out
75
'
76
77
#
parse-options.c
+8
-2
@@ -1137,8 +1137,14 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
1137
}
1138
if (opts->long_name && opts->short_name)
1139
pos += fprintf(outfile, ", ");
1140
- if (opts->long_name)
1141
- pos += fprintf(outfile, "--%s", opts->long_name);
1140
+ if (opts->long_name) {
1141
+ const char *long_name = opts->long_name;
1142
+ if (opts->flags & PARSE_OPT_NONEG)
1143
+ pos += fprintf(outfile, "--%s", long_name);
1144
+ else
1145
+ pos += fprintf(outfile, "--[no-]%s", long_name);
1146
+ }
1147
+
1148
if (opts->type == OPTION_NUMBER)
1149
pos += utf8_fprintf(outfile, _("-NUM"));
1150
t/t0040-parse-options.sh
+25
-20
@@ -13,30 +13,34 @@ usage: test-tool parse-options <options>
13
14
A helper function for the parse-options API.
15
16
- --yes get a boolean
17
- -D, --no-doubt begins with 'no-'
16
+ --[no-]yes get a boolean
17
+ -D, --[no-]no-doubt begins with 'no-'
18
-B, --no-fear be brave
19
- -b, --boolean increment by one
20
- -4, --or4 bitwise-or boolean with ...0100
21
- --neg-or4 same as --no-or4
19
+ -b, --[no-]boolean increment by one
20
+ -4, --[no-]or4 bitwise-or boolean with ...0100
21
+ --[no-]neg-or4 same as --no-or4
22
23
- -i, --integer <n> get a integer
23
+ -i, --[no-]integer <n>
24
+ get a integer
25
-j <n> get a integer, too
26
-m, --magnitude <n> get a magnitude
26
- --set23 set integer to 23
27
+ --[no-]set23 set integer to 23
28
--mode1 set integer to 1 (cmdmode option)
29
--mode2 set integer to 2 (cmdmode option)
29
- -L, --length <str> get length of <str>
30
- -F, --file <file> set file to <file>
30
+ -L, --[no-]length <str>
31
+ get length of <str>
32
+ -F, --[no-]file <file>
33
+ set file to <file>
34
35
String options
33
- -s, --string <string> get a string
34
- --string2 <str> get another string
35
- --st <st> get another string (pervert ordering)
36
+ -s, --[no-]string <string>
37
+ get a string
38
+ --[no-]string2 <str> get another string
39
+ --[no-]st <st> get another string (pervert ordering)
40
-o <str> get another string
41
--longhelp help text of this entry
42
spans multiple lines
39
- --list <str> add str to list
43
+ --[no-]list <str> add str to list
44
45
Magic arguments
46
-NUM set integer to NUM
@@ -45,16 +49,17 @@ Magic arguments
49
--no-ambiguous negative ambiguity
50
51
Standard options
48
- --abbrev[=<n>] use <n> digits to display object names
49
- -v, --verbose be verbose
50
- -n, --dry-run dry run
51
- -q, --quiet be quiet
52
- --expect <string> expected output in the variable dump
52
+ --[no-]abbrev[=<n>] use <n> digits to display object names
53
+ -v, --[no-]verbose be verbose
54
+ -n, --[no-]dry-run dry run
55
+ -q, --[no-]quiet be quiet
56
+ --[no-]expect <string>
57
+ expected output in the variable dump
58
59
Alias
55
- -A, --alias-source <string>
60
+ -A, --[no-]alias-source <string>
61
get a string
57
- -Z, --alias-target <string>
62
+ -Z, --[no-]alias-target <string>
63
alias of --alias-source
64
65
EOF
t/t1502-rev-parse-parseopt.sh
+1
-1
@@ -111,7 +111,7 @@ test_expect_success 'test --parseopt help-all output hidden switches' '
111
|
112
| some-command does foo and bar!
113
|
114
-| --hidden1 A hidden switch
114
+| --[no-]hidden1 A hidden switch
115
|
116
|EOF
117
END_EXPECT
t/t1502/optionspec-neg.help
+2
-2
@@ -3,8 +3,8 @@ usage: some-command [options] <args>...
3
4
some-command does foo and bar!
5
6
- --foo can be negated
7
- --no-bar can be positivated
6
+ --[no-]foo can be negated
7
+ --[no-]no-bar can be positivated
8
--positive-only cannot be negated
9
--no-negative cannot be positivated
10
t/t1502/optionspec.help
+17
-15
@@ -4,31 +4,33 @@ usage: some-command [options] <args>...
4
some-command does foo and bar!
5
6
-h, --help show the help
7
- --foo some nifty option --foo
8
- --bar ... some cool option --bar with an argument
9
- -b, --baz a short and long option
7
+ --[no-]foo some nifty option --foo
8
+ --[no-]bar ... some cool option --bar with an argument
9
+ -b, --[no-]baz a short and long option
10
11
An option group Header
12
-C[...] option C with an optional argument
13
- -d, --data[=...] short and long option with an optional argument
13
+ -d, --[no-]data[=...] short and long option with an optional argument
14
15
Argument hints
16
-B <arg> short option required argument
17
- --bar2 <arg> long option required argument
18
- -e, --fuz <with-space>
17
+ --[no-]bar2 <arg> long option required argument
18
+ -e, --[no-]fuz <with-space>
19
short and long option required argument
20
-s[<some>] short option optional argument
21
- --long[=<data>] long option optional argument
22
- -g, --fluf[=<path>] short and long option optional argument
23
- --longest <very-long-argument-hint>
21
+ --[no-]long[=<data>] long option optional argument
22
+ -g, --[no-]fluf[=<path>]
23
+ short and long option optional argument
24
+ --[no-]longest <very-long-argument-hint>
25
a very long argument hint
25
- --pair <key=value> with an equals sign in the hint
26
- --aswitch help te=t contains? fl*g characters!`
27
- --bswitch <hint> hint has trailing tab character
28
- --cswitch switch has trailing tab character
29
- --short-hint <a> with a one symbol hint
26
+ --[no-]pair <key=value>
27
+ with an equals sign in the hint
28
+ --[no-]aswitch help te=t contains? fl*g characters!`
29
+ --[no-]bswitch <hint> hint has trailing tab character
30
+ --[no-]cswitch switch has trailing tab character
31
+ --[no-]short-hint <a> with a one symbol hint
32
33
Extras
32
- --extra1 line above used to cause a segfault but no longer does
34
+ --[no-]extra1 line above used to cause a segfault but no longer does
35
36
EOF