# \[PATCH\] api-parse-options: add missing flags and macros - From: Karthik Nayak \ - Date: 2026-11-05 10:32:02 - List: git - Page: https://ratatoskr.run/git/2026/11/17869574 - Thread: https://ratatoskr.run/git/2026/11/17869574/t.md ```text The 'Documentation/technical/api-parse-options.adoc' contains documentation around the parse-options API. The document is missing some of the macros and flags provided by the API. Add the missing flags 'PARSE_OPT_ONE_SHOT' and 'PARSE_OPT_SHELL_EVAL' to the documentation. While 'PARSE_OPT_ONE_SHOT' was introduced in 202fbb3315 (parse-options: add one-shot mode, 2019-01-27) as a temporary flag, it is now 7 years and still exists. So let's document it, as when the time comes, it is always easy to remove the same. Also add the follow missing macros: - OPT__VERBOSITY - OPT__SUPER_PREFIX - OPT_CONTAINS - OPT_WITH - OPT_NO_CONTAINS - OPT_NO_WITH - OPT_CLEANUP - OPT_PATHSPEC_FROM_FILE - OPT_PATHSPEC_FILE_NUL - OPT_AUTOSTASH - OPT_DIFF_UNIFIED - OPT_DIFF_INTERHUNK_CONTEXT - OPT_IPVERSION This brings the technical documentation in line with the code in 'parse-options.h'. While here, add the missing `flags` argument to `OPT__FORCE`. Signed-off-by: Karthik Nayak --- I was reading the docs while reviewing another series and ended up finding some missing documentation. This patch tries to cover that. Some of these might be options/flags we rarely use, but I strongly feel its easier to make choices when there is adequate documentation. --- Documentation/technical/api-parse-options.adoc | 103 ++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc index 6dfea34220..8b7eeb7b9b 100644 --- a/Documentation/technical/api-parse-options.adoc +++ b/Documentation/technical/api-parse-options.adoc @@ -138,6 +138,16 @@ Flags are the bitwise-or of: turns it off and allows one to add custom handlers for these options, or to just leave them unknown. +`PARSE_OPT_ONE_SHOT`:: + Process only the first option (and its value, if any) and return + the number of arguments processed, leaving `argv[]` untouched. + `argv[0]` is taken to be the first option, not the program name. + An unknown option stops processing without an error. + +`PARSE_OPT_SHELL_EVAL`:: + Wrap the usage output in a heredoc followed by an `exit 0`, + so that a shell can `eval` it. + `PARSE_OPT_SUBCOMMAND_OPTIONAL`:: Don't error out when no subcommand is specified. @@ -230,15 +240,25 @@ with `flags` set to `0`. `OPT__DRY_RUN(&int_var, description)`:: Add `-n, --dry-run`. -`OPT__FORCE(&int_var, description)`:: +`OPT__FORCE(&int_var, description, flags)`:: Add `-f, --force`. `OPT__QUIET(&int_var, description)`:: Add `-q, --quiet`. +`OPT__SUPER_PREFIX(&str_var)`:: + Add hidden `--super-prefix=`, which stores the prefixed + path to the initial superproject in `str_var`. + `OPT__VERBOSE(&int_var, description)`:: Add `-v, --verbose`. +`OPT__VERBOSITY(&int_var)`:: + Add `-v, --verbose` and `-q, --quiet`, sharing `int_var`. + Each `-v` increments `int_var` (a `-v` after `-q` sets it to 1) + and each `-q` decrements it (a `-q` after `-v` sets it to -1). + `--no-verbose` and `--no-quiet` reset it to zero. + `OPT_GROUP(description)`:: Start an option group. `description` is a short string that describes the group or an empty string. @@ -273,6 +293,11 @@ with `flags` set to `0`. Introduce a boolean option. If used, `int_var` is bitwise-ored with `mask`. +`OPT_BITOP(short, long, &int_var, description, set, clear)`:: + Introduce a boolean option. + If used, `int_var` is bitwise-anded with the inverted `clear` and + then bitwise-ored with `set`. Cannot be used in the negated form. + `OPT_NEGBIT(short, long, &int_var, description, mask)`:: Introduce a boolean option. If used, `int_var` is bitwise-anded with the inverted `mask`. @@ -291,6 +316,16 @@ with `flags` set to `0`. The string argument is stored as an element in `string_list`. Use of `--no-option` will clear the list of preceding values. +`OPT_STRVEC(short, long, &struct strvec, arg_str, description)`:: + Introduce an option with string argument. + The string argument is appended to the provided `strvec`. + Use of `--no-option` will clear the list of preceding values. + +`OPT_UYN(short, long, &int_var, description)`:: + Introduce a ternary option. + `--option` sets `int_var` to `1` and `--no-option` sets it to `2`. + If neither is given, `int_var` is left unchanged. + `OPT_INTEGER(short, long, &int_var, description)`:: Introduce an option with integer argument. The argument must be a integer and may include a suffix of 'k', 'm' or 'g' to @@ -340,6 +375,17 @@ with `flags` set to `0`. Use it to hide deprecated options that are still to be recognized and ignored silently. +`OPT_NOOP_ARG(short, long)`:: + Introduce an option that takes one argument but has no effect. + Use it to hide deprecated options that are still to be recognized + and ignored silently. + +`OPT_COLUMN(short, long, &unsigned_int_var, description)`:: + Introduce an option that takes an optional argument and sets + `unsigned_int_var` as per the column layout modes specified in + linkgit:git-config[1]. `--option` and `--no-option` without + arguments are equivalent to `always` and `never` respectively. + `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: Introduce an option that will be reconstructed into a char* string, which must be initialized to NULL. This is useful when you need to @@ -366,6 +412,61 @@ with `flags` set to `0`. this subcommand is used. The subcommand is not listed in the usage output. +`OPT_CONTAINS(&commit_list_var, description)`:: + Introduce a `--contains=` option. The argument is parsed + as a commit and inserted into `commit_list_var`. If the option is + the last token on the command line and has no argument, `HEAD` + is used. Cannot be negated. + +`OPT_NO_CONTAINS(&commit_list_var, description)`:: + Like `OPT_CONTAINS()`, but introduces `--no-contains=`. + +`OPT_WITH(&commit_list_var, description)`:: + Like `OPT_CONTAINS()`, but introduces a hidden `--with=`. + +`OPT_WITHOUT(&commit_list_var, description)`:: + Like `OPT_CONTAINS()`, but introduces a hidden + `--without=`. + +`OPT_CLEANUP(&str_var)`:: + Introduce a string option with `--cleanup` long name. Commonly + used to parse cleanup mode as specified in linkgit:git-commit[1]. + The option does not do any parsing itself and simply stores the + argument in `str_var`. + +`OPT_PATHSPEC_FROM_FILE(&str_var)`:: + Introduce a `--pathspec-from-file=` option. Commonly used + to read the pathspec from a file instead of the command-line + arguments. See linkgit:git-commit[1] for more details. + +`OPT_PATHSPEC_FILE_NUL(&int_var)`:: + Introduce a boolean `--pathspec-file-nul` option. Commonly + accompanies `OPT_PATHSPEC_FROM_FILE()` to denote that the + pathspec elements are separated with `NUL` characters. + See linkgit:git-commit[1] for more details. + +`OPT_AUTOSTASH(&int_var)`:: + Introduce a boolean `--autostash` option. Commonly used to + automatically create a stash entry before the operation and + restore it after. See linkgit:git-merge[1] for more details. + +`OPT_DIFF_UNIFIED(&int_var)`:: + Introduce an integer option with `-U` short name and `--unified` + long name. Commonly used to denote lines of context for generating + diffs. Cannot be negated. See linkgit:git-add[1] for more details. + +`OPT_DIFF_INTERHUNK_CONTEXT(&int_var)`:: + Introduce an integer option with `--inter-hunk-context` long name. + Commonly used to show the context between diff hunks up to the + specified number. Cannot be negated. See linkgit:git-add[1] for + more details. + +`OPT_IPVERSION(&family_var)`:: + Introduce `-4, --ipv4` and `-6, --ipv6` for selecting the IP + protocol to use. Neither takes an argument or can be negated. + `family_var` (an `enum transport_family`) is set to + `TRANSPORT_FAMILY_IPV4` or `TRANSPORT_FAMILY_IPV6` respectively. + The last element of the array must be `OPT_END()`. If not stated otherwise, interpret the arguments as follows: --- base-commit: 8d1b215c01512b9658d4525c54ff9b9245f9a7e8 change-id: 20261103-kn-parse-options-doc-b4aa930ef250 Thanks - Karthik ```