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

Re: [PATCH v2 02/12] api-parse-options.adoc: document per-option flags

From
Elijah Newren <newren@gmail.com>
Date
Aug 8, 2026, 07:25 UTC
Message-ID
<CABPp-BGfeF1t+siEUuYgTtDG5LtfL5iskSHferbGwFj8axA+tA@mail.gmail.com>
In-Reply-To
<20260804100355.1299498-3-christian.couder@gmail.com>

On Tue, Aug 4, 2026 at 3:04 AM Christian Couder <christian.couder@gmail.com> wrote:

Show 64 quoted lines
>
> 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 <christian.couder@gmail.com>
> ---
>  .../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.
Is this accurate?  Sufficiently precise?  parse-options.h says
 *   PARSE_OPT_LASTARG_DEFAULT: says that this option will take the default
 *                value if no argument is given when the option
 *                is last on the command line. If the option is
 *                not last it will require an argument.
 *                Should not be used with PARSE_OPT_OPTARG.
If you want to reword that, maybe something like:
        The no-argument form is only accepted when the option is the
        last token on the command line; used earlier, it still
        requires an argument. Should not be combined with
        `PARSE_OPT_OPTARG`.
?
Show 25 quoted lines
> +
> +`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.
Thanks for adding this table; looks helpful.
Previous: Christian CouderNext: Christian Couder
Message 18 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.