git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH 3/7] api-parse-options.adoc: document hidden and OPT_*_F option macros

From
Christian Couder <christian.couder@gmail.com>
Date
Jul 16, 2026, 16:55 UTC
Message-ID
<20260716165517.433849-4-christian.couder@gmail.com>
In-Reply-To
<20260716165517.433849-1-christian.couder@gmail.com>

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>
---
 Documentation/technical/api-parse-options.adoc | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index fb4580e755..0e10327d07 100644
--- a/Documentation/technical/api-parse-options.adoc
+++ b/Documentation/technical/api-parse-options.adoc
@@ -213,6 +213,13 @@ Macros
 
 There are some macros to easily define options:
 
+Many of the macros below have an `_F` variant (for example `OPT_BOOL_F`,
+`OPT_STRING_F`, `OPT_INTEGER_F`, `OPT_SET_INT_F`, `OPT_BIT_F` and
+`OPT_CALLBACK_F`) that takes an additional trailing `flags` argument.
+That argument is the bitwise-or of the per-option flags described in the
+"Option flags" section above; the non-`_F` macros are simply defined
+with `flags` set to `0`.
+
 `OPT__ABBREV(&int_var)`::
 	Add `--abbrev[=<n>]`.
 
@@ -236,10 +243,21 @@ There are some macros to easily define options:
 	describes the group or an empty string.
 	Start the description with an upper-case letter.
 
+`OPT_HIDDEN_GROUP(description)`::
+	Like `OPT_GROUP()`, but the group header carries
+	`PARSE_OPT_HIDDEN`, so it is only shown by `--help-all` and not
+	by `-h`. Use it to label a group that contains only hidden
+	options, which would otherwise show an empty header under `-h`.
+
 `OPT_BOOL(short, long, &int_var, description)`::
 	Introduce a boolean option. `int_var` is set to one with
 	`--option` and set to zero with `--no-option`.
 
+`OPT_HIDDEN_BOOL(short, long, &int_var, description)`::
+	Like `OPT_BOOL()`, but the option carries `PARSE_OPT_HIDDEN`,
+	so it is hidden from `-h` while still being shown by
+	`--help-all`.
+
 `OPT_COUNTUP(short, long, &int_var, description)`::
 	Introduce a count-up option.
 	Each use of `--option` increments `int_var`, starting from zero
-- 
2.55.0.185.g9120d2b5c0
Previous: Christian CouderNext: Christian Couder
Message 8 of 48 in “fast-import: standardize usage string and SYNOPSIS”
  1. 0/7 fast-import: standardize usage string and SYNOPSISChristian Couder, Jul 16, 2026
  2. 1/7 parse-options: introduce OPT_HIDDEN_GROUPChristian Couder, Jul 16, 2026
  3. Junio C HamanoJul 16, 2026
  4. .mailmap etiquette (was "Re: [PATCH 1/7] parse-options: introduce OPT_HIDDEN_GROUP")D. Ben Knoble, Jul 16, 2026
  5. Junio C HamanoJul 16, 2026
  6. Christian CouderAug 3, 2026
  7. 2/7 api-parse-options.adoc: document per-option flagsChristian Couder, Jul 16, 2026
  8. 3/7 api-parse-options.adoc: document hidden and OPT_*_F option macrosChristian Couder, Jul 16, 2026
  9. 4/7 fast-import: localize 'i' into the 'for' loops using itChristian Couder, Jul 16, 2026
  10. 5/7 fast-import: introduce 'struct fast_import_state'Christian Couder, Jul 16, 2026
  11. 6/7 fast-import: move command state globals into 'struct fast_import_state'Christian Couder, Jul 16, 2026
  12. 7/7 fast-import: use struct option for usage stringChristian Couder, Jul 16, 2026
  13. Junio C HamanoJul 16, 2026
  14. Christian CouderAug 3, 2026
  15. 00/12 fast-import: standardize usage string and SYNOPSISChristian Couder, Aug 4, 2026
  16. 01/12 parse-options: introduce OPT_HIDDEN_GROUPChristian Couder, Aug 4, 2026
  17. 02/12 api-parse-options.adoc: document per-option flagsChristian Couder, Aug 4, 2026
  18. Elijah NewrenAug 8, 2026
  19. Christian CouderAug 11, 2026
  20. 03/12 api-parse-options.adoc: document hidden and OPT_*_F option macrosChristian Couder, Aug 4, 2026
  21. 04/12 fast-import: localize 'i' into the 'for' loops using itChristian Couder, Aug 4, 2026
  22. 05/12 fast-import: use int for some bool flagsChristian Couder, Aug 4, 2026
  23. 06/12 fast-import: factor out option_*() functionsChristian Couder, Aug 4, 2026
  24. 07/12 fast-import: introduce 'struct fast_import_state'Christian Couder, Aug 4, 2026
  25. Elijah NewrenAug 8, 2026
  26. Christian CouderAug 11, 2026
  27. 08/12 fast-import: move command state globals into 'struct fast_import_state'Christian Couder, Aug 4, 2026
  28. 09/12 fast-import: use struct option for usage stringChristian Couder, Aug 4, 2026
  29. 10/12 fast-import: use callbacks to parse some optionsChristian Couder, Aug 4, 2026
  30. 11/12 fast-import: use parse_options() for command line optionsChristian Couder, Aug 4, 2026
  31. Elijah NewrenAug 8, 2026
  32. Christian CouderAug 11, 2026
  33. 12/12 fast-import: remove useless from_stream argumentChristian Couder, Aug 4, 2026
  34. Elijah NewrenAug 8, 2026
  35. 00/12 fast-import: standardize usage string and SYNOPSISChristian Couder, Aug 11, 2026
  36. 02/12 api-parse-options.adoc: document per-option flagsChristian Couder, Aug 11, 2026
  37. 03/12 api-parse-options.adoc: document hidden and OPT_*_F option macrosChristian Couder, Aug 11, 2026
  38. 04/12 fast-import: localize 'i' into the 'for' loops using itChristian Couder, Aug 11, 2026
  39. 05/12 fast-import: use int for some bool flagsChristian Couder, Aug 11, 2026
  40. 06/12 fast-import: factor out option_*() functionsChristian Couder, Aug 11, 2026
  41. 07/12 fast-import: introduce 'struct fast_import_state'Christian Couder, Aug 11, 2026
  42. 08/12 fast-import: move command state globals into 'struct fast_import_state'Christian Couder, Aug 11, 2026
  43. 09/12 fast-import: use struct option for usage stringChristian Couder, Aug 11, 2026
  44. 10/12 fast-import: use callbacks to parse some optionsChristian Couder, Aug 11, 2026
  45. 11/12 fast-import: use parse_options() for command line optionsChristian Couder, Aug 11, 2026
  46. 12/12 fast-import: remove useless from_stream argumentChristian Couder, Aug 11, 2026
  47. 01/12 parse-options: introduce OPT_HIDDEN_GROUPChristian Couder, Aug 11, 2026
  48. Elijah NewrenAug 12, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.