api-parse-options.adoc: document hidden and OPT_*_F option macros
In "Documentation/technical/api-parse-options.adoc", the list of option macros does not mention the `OPT_*_F()` macro variants that take a trailing `flags` argument, nor the `OPT_HIDDEN_GROUP()` and `OPT_HIDDEN_BOOL()` convenience macros. Now that a previous commit documents the per-option flags, let's document these macros too: - Add a paragraph explaining the `OPT_*_F` convention and how it relates to the per-option flags. - Document `OPT_HIDDEN_GROUP()`, introduced in a previous commit, right after `OPT_GROUP()`. - Document `OPT_HIDDEN_BOOL()` right after `OPT_BOOL()`. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Christian Couder committed
Jul 16, 2026 at 18:55 UTC
1589064f3301e7a7066a08063469da7e4014c128
1 file changed
+18
Documentation/technical/api-parse-options.adoc
+18
@@ -213,6 +213,13 @@ Macros
213
214
There are some macros to easily define options:
215
216
+Many of the macros below have an `_F` variant (for example `OPT_BOOL_F`,
217
+`OPT_STRING_F`, `OPT_INTEGER_F`, `OPT_SET_INT_F`, `OPT_BIT_F` and
218
+`OPT_CALLBACK_F`) that takes an additional trailing `flags` argument.
219
+That argument is the bitwise-or of the per-option flags described in the
220
+"Option flags" section above; the non-`_F` macros are simply defined
221
+with `flags` set to `0`.
222
+
223
`OPT__ABBREV(&int_var)`::
224
Add `--abbrev[=<n>]`.
225
@@ -236,10 +243,21 @@ There are some macros to easily define options:
243
describes the group or an empty string.
244
Start the description with an upper-case letter.
245
246
+`OPT_HIDDEN_GROUP(description)`::
247
+ Like `OPT_GROUP()`, but the group header carries
248
+ `PARSE_OPT_HIDDEN`, so it is only shown by `--help-all` and not
249
+ by `-h`. Use it to label a group that contains only hidden
250
+ options, which would otherwise show an empty header under `-h`.
251
+
252
`OPT_BOOL(short, long, &int_var, description)`::
253
Introduce a boolean option. `int_var` is set to one with
254
`--option` and set to zero with `--no-option`.
255
256
+`OPT_HIDDEN_BOOL(short, long, &int_var, description)`::
257
+ Like `OPT_BOOL()`, but the option carries `PARSE_OPT_HIDDEN`,
258
+ so it is hidden from `-h` while still being shown by
259
+ `--help-all`.
260
+
261
`OPT_COUNTUP(short, long, &int_var, description)`::
262
Introduce a count-up option.
263
Each use of `--option` increments `int_var`, starting from zero