[PATCH] api-parse-options: add missing flags and macros

[PATCH] api-parse-options: add missing flags and macros

[Karthik Nayak]

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 <karthik.188@gmail.com>
---
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=<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=<commit>` 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=<commit>`.
+
+`OPT_WITH(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.
+
+`OPT_WITHOUT(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden
+	`--without=<commit>`.
+
+`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=<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

Re: [PATCH] api-parse-options: add missing flags and macros

[Cynthia Uche]

Hi Karthik,

On Thu, Nov 5, 2026 at 11:37 AM Karthik Nayak <karthik.188@gmail.com> wrote:

> Also add the follow missing macros:

nit: s/follow/following/.

> - OPT_NO_WITH

The message lists OPT_NO_WITH, but parse-options.h defines
OPT_WITHOUT, which is what the diff documents. The diff also adds
OPT_BITOP, OPT_STRVEC, OPT_UYN, OPT_NOOP_ARG and OPT_COLUMN, which
the message doesn't list.

I applied this on its base (8d1b215c01), built the docs with no
warnings, and compared the descriptions with the code on master
(0ffa3e35c7). OPT__VERBOSITY, OPT_UYN, OPT_BITOP, OPT_COLUMN,
OPT_CONTAINS, OPT_NOOP_ARG and the two new flags match
parse-options.c and parse-options-cb.c, and the git-add[1]
references resolve via diff-context-options.adoc.

OPT_ALIAS and OPT_ALIAS_F are still undocumented tho. I wonder if that
is on purpose.

-- 
Cynthia

Re: [PATCH] api-parse-options: add missing flags and macros

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 1263 bytes --]

Cynthia Uche <herroyalpriestess@gmail.com> writes:

> Hi Karthik,
>
> On Thu, Nov 5, 2026 at 11:37 AM Karthik Nayak <karthik.188@gmail.com> wrote:
>
>> Also add the follow missing macros:
>
> nit: s/follow/following/.
>

Will swap out.

>> - OPT_NO_WITH
>
> The message lists OPT_NO_WITH, but parse-options.h defines
> OPT_WITHOUT, which is what the diff documents. The diff also adds
> OPT_BITOP, OPT_STRVEC, OPT_UYN, OPT_NOOP_ARG and OPT_COLUMN, which
> the message doesn't list.
>

Ah right, let me fix all this up.

> I applied this on its base (8d1b215c01), built the docs with no
> warnings, and compared the descriptions with the code on master
> (0ffa3e35c7). OPT__VERBOSITY, OPT_UYN, OPT_BITOP, OPT_COLUMN,
> OPT_CONTAINS, OPT_NOOP_ARG and the two new flags match
> parse-options.c and parse-options-cb.c, and the git-add[1]
> references resolve via diff-context-options.adoc.

Seems like I forgot to update the commit message after making some
changes. Will update it.

Thanks for testing.

> OPT_ALIAS and OPT_ALIAS_F are still undocumented tho. I wonder if that
> is on purpose.
>

We don't add the '_F' versions as we talk about all such variants at the
top. But will add in `OPT_ALIAS`.

> --
> Cynthia

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH] api-parse-options: add missing flags and macros

[Cynthia Uche]

Karthik Nayak <karthik.188@gmail.com> writes:

> We don't add the '_F' versions as we talk about all such variants at
> the top. But will add in `OPT_ALIAS`.

Ah, right, I missed that paragraph when I wrote my reply. ^^;
Thanks for pointing it out. I'll take a look at v2 when it arrives.


-- 
Cynthia

[PATCH v2] api-parse-options: add missing flags and macros

[Karthik Nayak]

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 following missing macros:
  - OPT__SUPER_PREFIX
  - OPT__VERBOSITY
  - OPT_BITOP
  - OPT_STRVEC
  - OPT_UYN
  - OPT_NOOP_ARG
  - OPT_COLUMN
  - OPT_CONTAINS
  - OPT_NO_CONTAINS
  - OPT_WITH
  - OPT_WITHOUT
  - OPT_CLEANUP
  - OPT_PATHSPEC_FROM_FILE
  - OPT_PATHSPEC_FILE_NUL
  - OPT_AUTOSTASH
  - OPT_DIFF_UNIFIED
  - OPT_DIFF_INTERHUNK_CONTEXT
  - OPT_IPVERSION
  - OPT_ALIAS

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 <karthik.188@gmail.com>
---
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.
---
Changes in v2:
- Add OPT_ALIAS which was previously missing.
- Fix incorrect and missing flags in the commit message.
- Fix typo in the commit message.
- Link to v1: https://patch.msgid.link/20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com
---
 Documentation/technical/api-parse-options.adoc | 106 ++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 6dfea34220..b7ce616749 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=<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,64 @@ 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=<commit>` 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=<commit>`.
+
+`OPT_WITH(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.
+
+`OPT_WITHOUT(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden
+	`--without=<commit>`.
+
+`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=<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.
+
+`OPT_ALIAS(short, long, alias_source)`::
+	Introduced an alias to another existing `alias_source` option.
+
 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

Re: [PATCH v2] api-parse-options: add missing flags and macros

[Cynthia Uche]

Karthik Nayak <karthik.188@gmail.com> writes:

> +`OPT_ALIAS(short, long, alias_source)`::
> +	Introduced an alias to another existing `alias_source` option.

nit: s/Introduced/Introduce/, to match the other entries.

Also, parse-options.h names the third argument `source_long_name`,
which says what to pass; using that name here might be clearer.

Otherwise this looks good. Thank you! :)

-- 
Cynthia

Re: [PATCH v2] api-parse-options: add missing flags and macros

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 508 bytes --]

Cynthia Uche <herroyalpriestess@gmail.com> writes:

> Karthik Nayak <karthik.188@gmail.com> writes:
>
>> +`OPT_ALIAS(short, long, alias_source)`::
>> +	Introduced an alias to another existing `alias_source` option.
>
> nit: s/Introduced/Introduce/, to match the other entries.
>
> Also, parse-options.h names the third argument `source_long_name`,
> which says what to pass; using that name here might be clearer.
>
> Otherwise this looks good. Thank you! :)
>

Thanks, yeah, let me do that!

> --
> Cynthia

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

[PATCH v3] api-parse-options: add missing flags and macros

[Karthik Nayak]

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 following missing macros:
  - OPT__SUPER_PREFIX
  - OPT__VERBOSITY
  - OPT_BITOP
  - OPT_STRVEC
  - OPT_UYN
  - OPT_NOOP_ARG
  - OPT_COLUMN
  - OPT_CONTAINS
  - OPT_NO_CONTAINS
  - OPT_WITH
  - OPT_WITHOUT
  - OPT_CLEANUP
  - OPT_PATHSPEC_FROM_FILE
  - OPT_PATHSPEC_FILE_NUL
  - OPT_AUTOSTASH
  - OPT_DIFF_UNIFIED
  - OPT_DIFF_INTERHUNK_CONTEXT
  - OPT_IPVERSION
  - OPT_ALIAS

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 <karthik.188@gmail.com>
---
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.
---
Changes in v3:
- Fix typo and rename the variable
- Link to v2: https://patch.msgid.link/20261106-kn-parse-options-doc-v2-1-453ee7155348@gmail.com

Changes in v2:
- Add OPT_ALIAS which was previously missing.
- Fix incorrect and missing flags in the commit message.
- Fix typo in the commit message.
- Link to v1: https://patch.msgid.link/20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com
---
 Documentation/technical/api-parse-options.adoc | 106 ++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 6dfea34220..b20f74bc72 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=<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,64 @@ 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=<commit>` 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=<commit>`.
+
+`OPT_WITH(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.
+
+`OPT_WITHOUT(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden
+	`--without=<commit>`.
+
+`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=<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.
+
+`OPT_ALIAS(short, long, source_long_name)`::
+	Introduce an alias to another existing `source_long_name` option.
+
 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

Re: [PATCH v3] api-parse-options: add missing flags and macros

[Junio C Hamano]

Karthik Nayak <karthik.188@gmail.com> writes:

> 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 following missing macros:
>   - OPT__SUPER_PREFIX
>   - OPT__VERBOSITY
>   - OPT_BITOP
>   - OPT_STRVEC
>   - OPT_UYN
>   - OPT_NOOP_ARG
>   - OPT_COLUMN
>   - OPT_CONTAINS
>   - OPT_NO_CONTAINS
>   - OPT_WITH
>   - OPT_WITHOUT
>   - OPT_CLEANUP
>   - OPT_PATHSPEC_FROM_FILE
>   - OPT_PATHSPEC_FILE_NUL
>   - OPT_AUTOSTASH
>   - OPT_DIFF_UNIFIED
>   - OPT_DIFF_INTERHUNK_CONTEXT
>   - OPT_IPVERSION
>   - OPT_ALIAS
>
> 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 <karthik.188@gmail.com>
> ---
> 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.
> ---
> Changes in v3:
> - Fix typo and rename the variable

OK.  Matching the parameters of OPT_ALIAS() the documentation uses
to what is actually used in parse-options.h header makes sense.

Have we reached the point of diminishing returns now?

Thanks.

Re: [PATCH v3] api-parse-options: add missing flags and macros

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 749 bytes --]

Junio C Hamano <gitster@pobox.com> writes:

> Karthik Nayak <karthik.188@gmail.com> writes:
>
>> 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.
>> ---
>> Changes in v3:
>> - Fix typo and rename the variable
>
> OK.  Matching the parameters of OPT_ALIAS() the documentation uses
> to what is actually used in parse-options.h header makes sense.
>
> Have we reached the point of diminishing returns now?
>
> Thanks.

Yup. We can merge this and future improvements can be made as needed
with new patches :)

Thanks

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]