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

On Tue, Aug 4, 2026 at 3:04 AM Christian Couder
<[email protected]> wrote:
>
> 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 <[email protected]>
> ---
>  .../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`.

?

> +
> +`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.