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

[PATCH 2/7] api-parse-options.adoc: document per-option flags

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

The "Flags" section in "Documentation/technical/api-parse-options.adoc" documents the flags that can be passed to parse_options() itself. It does not, however, document the flags that can be set on individual options through the `flags` member of `struct option` (and through the `OPT_*_F()` macro variants).

These per-option flags are used throughout the codebase (for example `PARSE_OPT_HIDDEN` is used to hide an option from `-h` while still showing it with `--help-all`), but a reader currently has to dig into "parse-options.h" to find them.

To remediate that, let's add an "Option flags" subsection to the "Data Structure" section, just before the list of option macros.

Let's also make it explicit that these are distinct from the parse_options() flags described earlier, and let's describe the `-h` versus `--help-all` behavior for `PARSE_OPT_HIDDEN`.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 .../technical/api-parse-options.adoc          | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)
diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 880eb94642..fb4580e755 100644
--- a/Documentation/technical/api-parse-options.adoc
+++ b/Documentation/technical/api-parse-options.adoc
@@ -150,6 +150,67 @@ Data Structure
 
 The main data structure is an array of the `option` struct,
 say `static struct option builtin_add_options[]`.
+
+Option flags
+~~~~~~~~~~~~
+
+Each option can carry flags in the `flags` field of its `option`
+struct. These are per-option flags and are distinct from the
+`parse_options()` flags described above; they are usually set through
+the `OPT_*_F()` macro variants (see below) rather than by hand. They
+are the bitwise-or of:
+
+`PARSE_OPT_OPTARG`::
+	The option's argument is optional, i.e. both `--option` and
+	`--option=<value>` are accepted.
+
+`PARSE_OPT_NOARG`::
+	The option takes no argument at all. Using `--option=<value>`
+	is rejected.
+
+`PARSE_OPT_NONEG`::
+	Disable the automatically generated negated `--no-option`
+	form.
+
+`PARSE_OPT_HIDDEN`::
+	Hide the option: it is omitted from the usage shown by
+	`git <cmd> -h`, but is still shown by `git <cmd> --help-all`.
+	The option is parsed as usual either way. This is meant for
+	deprecated, advanced or otherwise uncommon options.
+
+`PARSE_OPT_LASTARG_DEFAULT`::
+	Use the default value (`defval`) when the option is used
+	without an argument, even for an option that normally requires
+	one. Only the last argument on the command line takes effect.
+
+`PARSE_OPT_NODASH`::
+	The option is a single character without a leading dash, such
+	as the `+` used by some commands.
+
+`PARSE_OPT_LITERAL_ARGHELP`::
+	Use the argument help string (`argh`) verbatim in the usage
+	output instead of surrounding it with `<>` or `[]`. Useful when
+	`argh` already contains a hand-formatted description.
+
+`PARSE_OPT_FROM_ALIAS`::
+	Internal flag, set on options that were expanded from a
+	configured alias. It should not be set by callers.
+
+`PARSE_OPT_NOCOMPLETE`::
+	Do not offer this option for completion.
+
+`PARSE_OPT_COMP_ARG`::
+	The option's argument, rather than the option itself, is what
+	should be completed.
+
+`PARSE_OPT_CMDMODE`::
+	The option is one of several mutually exclusive "command mode"
+	options that share the same variable. Using more than one of
+	them at once is rejected.
+
+Macros
+~~~~~~
+
 There are some macros to easily define options:
 
 `OPT__ABBREV(&int_var)`::
-- 
2.55.0.185.g9120d2b5c0
Previous: Christian CouderNext: Christian Couder
Message 7 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.