{"thread":{"id":"66781","subject":"[PATCH] api-parse-options: add missing flags and macros","startedAt":"2026-11-05T10:31:55Z","lastAt":"2026-11-10T13:15:22Z","messageCount":10,"participants":["Karthik Nayak","Cynthia Uche","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"557536","messageId":"20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com","threadId":"66781","inReplyTo":null,"subject":"[PATCH] api-parse-options: add missing flags and macros","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-11-05T10:31:55Z","receivedAt":"2026-11-05T10:31:55Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'Documentation/technical/api-parse-options.adoc' contains\ndocumentation around the parse-options API. The document is missing some\nof the macros and flags provided by the API.\n\nAdd the missing flags 'PARSE_OPT_ONE_SHOT' and 'PARSE_OPT_SHELL_EVAL' to\nthe documentation. While 'PARSE_OPT_ONE_SHOT' was introduced in\n202fbb3315 (parse-options: add one-shot mode, 2019-01-27) as a temporary\nflag, it is now 7 years and still exists. So let's document it, as when\nthe time comes, it is always easy to remove the same.\n\nAlso add the follow missing macros:\n  - OPT__VERBOSITY\n  - OPT__SUPER_PREFIX\n  - OPT_CONTAINS\n  - OPT_WITH\n  - OPT_NO_CONTAINS\n  - OPT_NO_WITH\n  - OPT_CLEANUP\n  - OPT_PATHSPEC_FROM_FILE\n  - OPT_PATHSPEC_FILE_NUL\n  - OPT_AUTOSTASH\n  - OPT_DIFF_UNIFIED\n  - OPT_DIFF_INTERHUNK_CONTEXT\n  - OPT_IPVERSION\n\nThis brings the technical documentation in line with the code in\n'parse-options.h'.\n\nWhile here, add the missing `flags` argument to `OPT__FORCE`.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\nI was reading the docs while reviewing another series and ended\nup finding some missing documentation. This patch tries to cover\nthat. Some of these might be options/flags we rarely use, but I\nstrongly feel its easier to make choices when there is adequate\ndocumentation.\n---\n Documentation/technical/api-parse-options.adoc | 103 ++++++++++++++++++++++++-\n 1 file changed, 102 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc\nindex 6dfea34220..8b7eeb7b9b 100644\n--- a/Documentation/technical/api-parse-options.adoc\n+++ b/Documentation/technical/api-parse-options.adoc\n@@ -138,6 +138,16 @@ Flags are the bitwise-or of:\n \tturns it off and allows one to add custom handlers for these\n \toptions, or to just leave them unknown.\n \n+`PARSE_OPT_ONE_SHOT`::\n+\tProcess only the first option (and its value, if any) and return\n+\tthe number of arguments processed, leaving `argv[]` untouched.\n+\t`argv[0]` is taken to be the first option, not the program name.\n+\tAn unknown option stops processing without an error.\n+\n+`PARSE_OPT_SHELL_EVAL`::\n+\tWrap the usage output in a heredoc followed by an `exit 0`,\n+\tso that a shell can `eval` it.\n+\n `PARSE_OPT_SUBCOMMAND_OPTIONAL`::\n \tDon't error out when no subcommand is specified.\n \n@@ -230,15 +240,25 @@ with `flags` set to `0`.\n `OPT__DRY_RUN(&int_var, description)`::\n \tAdd `-n, --dry-run`.\n \n-`OPT__FORCE(&int_var, description)`::\n+`OPT__FORCE(&int_var, description, flags)`::\n \tAdd `-f, --force`.\n \n `OPT__QUIET(&int_var, description)`::\n \tAdd `-q, --quiet`.\n \n+`OPT__SUPER_PREFIX(&str_var)`::\n+\tAdd hidden `--super-prefix=<prefix>`, which stores the prefixed\n+\tpath to the initial superproject in `str_var`.\n+\n `OPT__VERBOSE(&int_var, description)`::\n \tAdd `-v, --verbose`.\n \n+`OPT__VERBOSITY(&int_var)`::\n+\tAdd `-v, --verbose` and `-q, --quiet`, sharing `int_var`.\n+\tEach `-v` increments `int_var` (a `-v` after `-q` sets it to 1)\n+\tand each `-q` decrements it (a `-q` after `-v` sets it to -1).\n+\t`--no-verbose` and `--no-quiet` reset it to zero.\n+\n `OPT_GROUP(description)`::\n \tStart an option group. `description` is a short string that\n \tdescribes the group or an empty string.\n@@ -273,6 +293,11 @@ with `flags` set to `0`.\n \tIntroduce a boolean option.\n \tIf used, `int_var` is bitwise-ored with `mask`.\n \n+`OPT_BITOP(short, long, &int_var, description, set, clear)`::\n+\tIntroduce a boolean option.\n+\tIf used, `int_var` is bitwise-anded with the inverted `clear` and\n+\tthen bitwise-ored with `set`. Cannot be used in the negated form.\n+\n `OPT_NEGBIT(short, long, &int_var, description, mask)`::\n \tIntroduce a boolean option.\n \tIf used, `int_var` is bitwise-anded with the inverted `mask`.\n@@ -291,6 +316,16 @@ with `flags` set to `0`.\n \tThe string argument is stored as an element in `string_list`.\n \tUse of `--no-option` will clear the list of preceding values.\n \n+`OPT_STRVEC(short, long, &struct strvec, arg_str, description)`::\n+\tIntroduce an option with string argument.\n+\tThe string argument is appended to the provided `strvec`.\n+\tUse of `--no-option` will clear the list of preceding values.\n+\n+`OPT_UYN(short, long, &int_var, description)`::\n+\tIntroduce a ternary option.\n+\t`--option` sets `int_var` to `1` and `--no-option` sets it to `2`.\n+\tIf neither is given, `int_var` is left unchanged.\n+\n `OPT_INTEGER(short, long, &int_var, description)`::\n \tIntroduce an option with integer argument. The argument must be a\n \tinteger and may include a suffix of 'k', 'm' or 'g' to\n@@ -340,6 +375,17 @@ with `flags` set to `0`.\n \tUse it to hide deprecated options that are still to be recognized\n \tand ignored silently.\n \n+`OPT_NOOP_ARG(short, long)`::\n+\tIntroduce an option that takes one argument but has no effect.\n+\tUse it to hide deprecated options that are still to be recognized\n+\tand ignored silently.\n+\n+`OPT_COLUMN(short, long, &unsigned_int_var, description)`::\n+\tIntroduce an option that takes an optional argument and sets\n+\t`unsigned_int_var` as per the column layout modes specified in\n+\tlinkgit:git-config[1]. `--option` and `--no-option` without\n+\targuments are equivalent to `always` and `never` respectively.\n+\n `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::\n \tIntroduce an option that will be reconstructed into a char* string,\n \twhich must be initialized to NULL. This is useful when you need to\n@@ -366,6 +412,61 @@ with `flags` set to `0`.\n \tthis subcommand is used. The subcommand is not listed in the\n \tusage output.\n \n+`OPT_CONTAINS(&commit_list_var, description)`::\n+\tIntroduce a `--contains=<commit>` option. The argument is parsed\n+\tas a commit and inserted into `commit_list_var`. If the option is\n+\tthe last token on the command line and has no argument, `HEAD`\n+\tis used. Cannot be negated.\n+\n+`OPT_NO_CONTAINS(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces `--no-contains=<commit>`.\n+\n+`OPT_WITH(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.\n+\n+`OPT_WITHOUT(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces a hidden\n+\t`--without=<commit>`.\n+\n+`OPT_CLEANUP(&str_var)`::\n+\tIntroduce a string option with `--cleanup` long name. Commonly\n+\tused to parse cleanup mode as specified in linkgit:git-commit[1].\n+\tThe option does not do any parsing itself and simply stores the\n+\targument in `str_var`.\n+\n+`OPT_PATHSPEC_FROM_FILE(&str_var)`::\n+\tIntroduce a `--pathspec-from-file=<file>` option. Commonly used\n+\tto read the pathspec from a file instead of the command-line\n+\targuments. See linkgit:git-commit[1] for more details.\n+\n+`OPT_PATHSPEC_FILE_NUL(&int_var)`::\n+\tIntroduce a boolean `--pathspec-file-nul` option. Commonly\n+\taccompanies `OPT_PATHSPEC_FROM_FILE()` to denote that the\n+\tpathspec elements are separated with `NUL` characters.\n+\tSee linkgit:git-commit[1] for more details.\n+\n+`OPT_AUTOSTASH(&int_var)`::\n+\tIntroduce a boolean `--autostash` option. Commonly used to\n+\tautomatically create a stash entry before the operation and\n+\trestore it after. See linkgit:git-merge[1] for more details.\n+\n+`OPT_DIFF_UNIFIED(&int_var)`::\n+\tIntroduce an integer option with `-U` short name and `--unified`\n+\tlong name. Commonly used to denote lines of context for generating\n+\tdiffs. Cannot be negated. See linkgit:git-add[1] for more details.\n+\n+`OPT_DIFF_INTERHUNK_CONTEXT(&int_var)`::\n+\tIntroduce an integer option with `--inter-hunk-context` long name.\n+\tCommonly used to show the context between diff hunks up to the\n+\tspecified number. Cannot be negated. See linkgit:git-add[1] for\n+\tmore details.\n+\n+`OPT_IPVERSION(&family_var)`::\n+\tIntroduce `-4, --ipv4` and `-6, --ipv6` for selecting the IP\n+\tprotocol to use. Neither takes an argument or can be negated.\n+\t`family_var` (an `enum transport_family`) is set to\n+\t`TRANSPORT_FAMILY_IPV4` or `TRANSPORT_FAMILY_IPV6` respectively.\n+\n The last element of the array must be `OPT_END()`.\n \n If not stated otherwise, interpret the arguments as follows:\n\n---\nbase-commit: 8d1b215c01512b9658d4525c54ff9b9245f9a7e8\nchange-id: 20261103-kn-parse-options-doc-b4aa930ef250\n\n\nThanks\n- Karthik\n\n\n"},{"id":"557540","messageId":"20261105122532.391-1-herroyalpriestess@gmail.com","threadId":"66781","inReplyTo":"20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com","subject":"Re: [PATCH] api-parse-options: add missing flags and macros","fromName":"Cynthia Uche","fromEmail":"herroyalpriestess@gmail.com","sentAt":"2026-11-05T12:25:31Z","receivedAt":"2026-11-05T12:25:31Z","isPatch":true,"sender":{"key":"herroyalpriestess@gmail.com","avatar":null},"body":"Hi Karthik,\n\nOn Thu, Nov 5, 2026 at 11:37 AM Karthik Nayak <karthik.188@gmail.com> wrote:\n\n> Also add the follow missing macros:\n\nnit: s/follow/following/.\n\n> - OPT_NO_WITH\n\nThe message lists OPT_NO_WITH, but parse-options.h defines\nOPT_WITHOUT, which is what the diff documents. The diff also adds\nOPT_BITOP, OPT_STRVEC, OPT_UYN, OPT_NOOP_ARG and OPT_COLUMN, which\nthe message doesn't list.\n\nI applied this on its base (8d1b215c01), built the docs with no\nwarnings, and compared the descriptions with the code on master\n(0ffa3e35c7). OPT__VERBOSITY, OPT_UYN, OPT_BITOP, OPT_COLUMN,\nOPT_CONTAINS, OPT_NOOP_ARG and the two new flags match\nparse-options.c and parse-options-cb.c, and the git-add[1]\nreferences resolve via diff-context-options.adoc.\n\nOPT_ALIAS and OPT_ALIAS_F are still undocumented tho. I wonder if that\nis on purpose.\n\n-- \nCynthia\n\n"},{"id":"557546","messageId":"CAOLa=ZSfNPt03R2F_xG930pBmXCJ-CcC-GnTTLA5AgWoZm8eaQ@mail.gmail.com","threadId":"66781","inReplyTo":"20261105122532.391-1-herroyalpriestess@gmail.com","subject":"Re: [PATCH] api-parse-options: add missing flags and macros","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-11-05T13:56:55Z","receivedAt":"2026-11-05T13:56:55Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Cynthia Uche <herroyalpriestess@gmail.com> writes:\n\n> Hi Karthik,\n>\n> On Thu, Nov 5, 2026 at 11:37 AM Karthik Nayak <karthik.188@gmail.com> wrote:\n>\n>> Also add the follow missing macros:\n>\n> nit: s/follow/following/.\n>\n\nWill swap out.\n\n>> - OPT_NO_WITH\n>\n> The message lists OPT_NO_WITH, but parse-options.h defines\n> OPT_WITHOUT, which is what the diff documents. The diff also adds\n> OPT_BITOP, OPT_STRVEC, OPT_UYN, OPT_NOOP_ARG and OPT_COLUMN, which\n> the message doesn't list.\n>\n\nAh right, let me fix all this up.\n\n> I applied this on its base (8d1b215c01), built the docs with no\n> warnings, and compared the descriptions with the code on master\n> (0ffa3e35c7). OPT__VERBOSITY, OPT_UYN, OPT_BITOP, OPT_COLUMN,\n> OPT_CONTAINS, OPT_NOOP_ARG and the two new flags match\n> parse-options.c and parse-options-cb.c, and the git-add[1]\n> references resolve via diff-context-options.adoc.\n\nSeems like I forgot to update the commit message after making some\nchanges. Will update it.\n\nThanks for testing.\n\n> OPT_ALIAS and OPT_ALIAS_F are still undocumented tho. I wonder if that\n> is on purpose.\n>\n\nWe don't add the '_F' versions as we talk about all such variants at the\ntop. But will add in `OPT_ALIAS`.\n\n> --\n> Cynthia\n"},{"id":"557623","messageId":"20261105213521.637-1-herroyalpriestess@gmail.com","threadId":"66781","inReplyTo":"CAOLa=ZSfNPt03R2F_xG930pBmXCJ-CcC-GnTTLA5AgWoZm8eaQ@mail.gmail.com","subject":"Re: [PATCH] api-parse-options: add missing flags and macros","fromName":"Cynthia Uche","fromEmail":"herroyalpriestess@gmail.com","sentAt":"2026-11-05T21:35:21Z","receivedAt":"2026-11-05T21:35:21Z","isPatch":true,"sender":{"key":"herroyalpriestess@gmail.com","avatar":null},"body":"Karthik Nayak <karthik.188@gmail.com> writes:\n\n> We don't add the '_F' versions as we talk about all such variants at\n> the top. But will add in `OPT_ALIAS`.\n\nAh, right, I missed that paragraph when I wrote my reply. ^^;\nThanks for pointing it out. I'll take a look at v2 when it arrives.\n\n\n-- \nCynthia\n\n"},{"id":"557646","messageId":"20261106-kn-parse-options-doc-v2-1-453ee7155348@gmail.com","threadId":"66781","inReplyTo":"20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com","subject":"[PATCH v2] api-parse-options: add missing flags and macros","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-11-06T08:50:01Z","receivedAt":"2026-11-06T08:50:01Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'Documentation/technical/api-parse-options.adoc' contains\ndocumentation around the parse-options API. The document is missing some\nof the macros and flags provided by the API.\n\nAdd the missing flags 'PARSE_OPT_ONE_SHOT' and 'PARSE_OPT_SHELL_EVAL' to\nthe documentation. While 'PARSE_OPT_ONE_SHOT' was introduced in\n202fbb3315 (parse-options: add one-shot mode, 2019-01-27) as a temporary\nflag, it is now 7 years and still exists. So let's document it, as when\nthe time comes, it is always easy to remove the same.\n\nAlso add the following missing macros:\n  - OPT__SUPER_PREFIX\n  - OPT__VERBOSITY\n  - OPT_BITOP\n  - OPT_STRVEC\n  - OPT_UYN\n  - OPT_NOOP_ARG\n  - OPT_COLUMN\n  - OPT_CONTAINS\n  - OPT_NO_CONTAINS\n  - OPT_WITH\n  - OPT_WITHOUT\n  - OPT_CLEANUP\n  - OPT_PATHSPEC_FROM_FILE\n  - OPT_PATHSPEC_FILE_NUL\n  - OPT_AUTOSTASH\n  - OPT_DIFF_UNIFIED\n  - OPT_DIFF_INTERHUNK_CONTEXT\n  - OPT_IPVERSION\n  - OPT_ALIAS\n\nThis brings the technical documentation in line with the code in\n'parse-options.h'.\n\nWhile here, add the missing `flags` argument to `OPT__FORCE`.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\nI was reading the docs while reviewing another series and ended\nup finding some missing documentation. This patch tries to cover\nthat. Some of these might be options/flags we rarely use, but I\nstrongly feel its easier to make choices when there is adequate\ndocumentation.\n---\nChanges in v2:\n- Add OPT_ALIAS which was previously missing.\n- Fix incorrect and missing flags in the commit message.\n- Fix typo in the commit message.\n- Link to v1: https://patch.msgid.link/20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com\n---\n Documentation/technical/api-parse-options.adoc | 106 ++++++++++++++++++++++++-\n 1 file changed, 105 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc\nindex 6dfea34220..b7ce616749 100644\n--- a/Documentation/technical/api-parse-options.adoc\n+++ b/Documentation/technical/api-parse-options.adoc\n@@ -138,6 +138,16 @@ Flags are the bitwise-or of:\n \tturns it off and allows one to add custom handlers for these\n \toptions, or to just leave them unknown.\n \n+`PARSE_OPT_ONE_SHOT`::\n+\tProcess only the first option (and its value, if any) and return\n+\tthe number of arguments processed, leaving `argv[]` untouched.\n+\t`argv[0]` is taken to be the first option, not the program name.\n+\tAn unknown option stops processing without an error.\n+\n+`PARSE_OPT_SHELL_EVAL`::\n+\tWrap the usage output in a heredoc followed by an `exit 0`,\n+\tso that a shell can `eval` it.\n+\n `PARSE_OPT_SUBCOMMAND_OPTIONAL`::\n \tDon't error out when no subcommand is specified.\n \n@@ -230,15 +240,25 @@ with `flags` set to `0`.\n `OPT__DRY_RUN(&int_var, description)`::\n \tAdd `-n, --dry-run`.\n \n-`OPT__FORCE(&int_var, description)`::\n+`OPT__FORCE(&int_var, description, flags)`::\n \tAdd `-f, --force`.\n \n `OPT__QUIET(&int_var, description)`::\n \tAdd `-q, --quiet`.\n \n+`OPT__SUPER_PREFIX(&str_var)`::\n+\tAdd hidden `--super-prefix=<prefix>`, which stores the prefixed\n+\tpath to the initial superproject in `str_var`.\n+\n `OPT__VERBOSE(&int_var, description)`::\n \tAdd `-v, --verbose`.\n \n+`OPT__VERBOSITY(&int_var)`::\n+\tAdd `-v, --verbose` and `-q, --quiet`, sharing `int_var`.\n+\tEach `-v` increments `int_var` (a `-v` after `-q` sets it to 1)\n+\tand each `-q` decrements it (a `-q` after `-v` sets it to -1).\n+\t`--no-verbose` and `--no-quiet` reset it to zero.\n+\n `OPT_GROUP(description)`::\n \tStart an option group. `description` is a short string that\n \tdescribes the group or an empty string.\n@@ -273,6 +293,11 @@ with `flags` set to `0`.\n \tIntroduce a boolean option.\n \tIf used, `int_var` is bitwise-ored with `mask`.\n \n+`OPT_BITOP(short, long, &int_var, description, set, clear)`::\n+\tIntroduce a boolean option.\n+\tIf used, `int_var` is bitwise-anded with the inverted `clear` and\n+\tthen bitwise-ored with `set`. Cannot be used in the negated form.\n+\n `OPT_NEGBIT(short, long, &int_var, description, mask)`::\n \tIntroduce a boolean option.\n \tIf used, `int_var` is bitwise-anded with the inverted `mask`.\n@@ -291,6 +316,16 @@ with `flags` set to `0`.\n \tThe string argument is stored as an element in `string_list`.\n \tUse of `--no-option` will clear the list of preceding values.\n \n+`OPT_STRVEC(short, long, &struct strvec, arg_str, description)`::\n+\tIntroduce an option with string argument.\n+\tThe string argument is appended to the provided `strvec`.\n+\tUse of `--no-option` will clear the list of preceding values.\n+\n+`OPT_UYN(short, long, &int_var, description)`::\n+\tIntroduce a ternary option.\n+\t`--option` sets `int_var` to `1` and `--no-option` sets it to `2`.\n+\tIf neither is given, `int_var` is left unchanged.\n+\n `OPT_INTEGER(short, long, &int_var, description)`::\n \tIntroduce an option with integer argument. The argument must be a\n \tinteger and may include a suffix of 'k', 'm' or 'g' to\n@@ -340,6 +375,17 @@ with `flags` set to `0`.\n \tUse it to hide deprecated options that are still to be recognized\n \tand ignored silently.\n \n+`OPT_NOOP_ARG(short, long)`::\n+\tIntroduce an option that takes one argument but has no effect.\n+\tUse it to hide deprecated options that are still to be recognized\n+\tand ignored silently.\n+\n+`OPT_COLUMN(short, long, &unsigned_int_var, description)`::\n+\tIntroduce an option that takes an optional argument and sets\n+\t`unsigned_int_var` as per the column layout modes specified in\n+\tlinkgit:git-config[1]. `--option` and `--no-option` without\n+\targuments are equivalent to `always` and `never` respectively.\n+\n `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::\n \tIntroduce an option that will be reconstructed into a char* string,\n \twhich must be initialized to NULL. This is useful when you need to\n@@ -366,6 +412,64 @@ with `flags` set to `0`.\n \tthis subcommand is used. The subcommand is not listed in the\n \tusage output.\n \n+`OPT_CONTAINS(&commit_list_var, description)`::\n+\tIntroduce a `--contains=<commit>` option. The argument is parsed\n+\tas a commit and inserted into `commit_list_var`. If the option is\n+\tthe last token on the command line and has no argument, `HEAD`\n+\tis used. Cannot be negated.\n+\n+`OPT_NO_CONTAINS(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces `--no-contains=<commit>`.\n+\n+`OPT_WITH(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.\n+\n+`OPT_WITHOUT(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces a hidden\n+\t`--without=<commit>`.\n+\n+`OPT_CLEANUP(&str_var)`::\n+\tIntroduce a string option with `--cleanup` long name. Commonly\n+\tused to parse cleanup mode as specified in linkgit:git-commit[1].\n+\tThe option does not do any parsing itself and simply stores the\n+\targument in `str_var`.\n+\n+`OPT_PATHSPEC_FROM_FILE(&str_var)`::\n+\tIntroduce a `--pathspec-from-file=<file>` option. Commonly used\n+\tto read the pathspec from a file instead of the command-line\n+\targuments. See linkgit:git-commit[1] for more details.\n+\n+`OPT_PATHSPEC_FILE_NUL(&int_var)`::\n+\tIntroduce a boolean `--pathspec-file-nul` option. Commonly\n+\taccompanies `OPT_PATHSPEC_FROM_FILE()` to denote that the\n+\tpathspec elements are separated with `NUL` characters.\n+\tSee linkgit:git-commit[1] for more details.\n+\n+`OPT_AUTOSTASH(&int_var)`::\n+\tIntroduce a boolean `--autostash` option. Commonly used to\n+\tautomatically create a stash entry before the operation and\n+\trestore it after. See linkgit:git-merge[1] for more details.\n+\n+`OPT_DIFF_UNIFIED(&int_var)`::\n+\tIntroduce an integer option with `-U` short name and `--unified`\n+\tlong name. Commonly used to denote lines of context for generating\n+\tdiffs. Cannot be negated. See linkgit:git-add[1] for more details.\n+\n+`OPT_DIFF_INTERHUNK_CONTEXT(&int_var)`::\n+\tIntroduce an integer option with `--inter-hunk-context` long name.\n+\tCommonly used to show the context between diff hunks up to the\n+\tspecified number. Cannot be negated. See linkgit:git-add[1] for\n+\tmore details.\n+\n+`OPT_IPVERSION(&family_var)`::\n+\tIntroduce `-4, --ipv4` and `-6, --ipv6` for selecting the IP\n+\tprotocol to use. Neither takes an argument or can be negated.\n+\t`family_var` (an `enum transport_family`) is set to\n+\t`TRANSPORT_FAMILY_IPV4` or `TRANSPORT_FAMILY_IPV6` respectively.\n+\n+`OPT_ALIAS(short, long, alias_source)`::\n+\tIntroduced an alias to another existing `alias_source` option.\n+\n The last element of the array must be `OPT_END()`.\n \n If not stated otherwise, interpret the arguments as follows:\n\n---\nbase-commit: 8d1b215c01512b9658d4525c54ff9b9245f9a7e8\nchange-id: 20261103-kn-parse-options-doc-b4aa930ef250\n\n\nThanks\n- Karthik\n\n\n"},{"id":"557731","messageId":"20261106195313.1015-1-herroyalpriestess@gmail.com","threadId":"66781","inReplyTo":"20261106-kn-parse-options-doc-v2-1-453ee7155348@gmail.com","subject":"Re: [PATCH v2] api-parse-options: add missing flags and macros","fromName":"Cynthia Uche","fromEmail":"herroyalpriestess@gmail.com","sentAt":"2026-11-06T19:53:13Z","receivedAt":"2026-11-06T19:53:13Z","isPatch":true,"sender":{"key":"herroyalpriestess@gmail.com","avatar":null},"body":"Karthik Nayak <karthik.188@gmail.com> writes:\n\n> +`OPT_ALIAS(short, long, alias_source)`::\n> +\tIntroduced an alias to another existing `alias_source` option.\n\nnit: s/Introduced/Introduce/, to match the other entries.\n\nAlso, parse-options.h names the third argument `source_long_name`,\nwhich says what to pass; using that name here might be clearer.\n\nOtherwise this looks good. Thank you! :)\n\n-- \nCynthia\n\n"},{"id":"557923","messageId":"CAOLa=ZRLqB72uJAhq2S5iSKSoWsEZX3zxn=nrJiBnEOEbBSckQ@mail.gmail.com","threadId":"66781","inReplyTo":"20261106195313.1015-1-herroyalpriestess@gmail.com","subject":"Re: [PATCH v2] api-parse-options: add missing flags and macros","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-11-09T11:30:02Z","receivedAt":"2026-11-09T11:30:02Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Cynthia Uche <herroyalpriestess@gmail.com> writes:\n\n> Karthik Nayak <karthik.188@gmail.com> writes:\n>\n>> +`OPT_ALIAS(short, long, alias_source)`::\n>> +\tIntroduced an alias to another existing `alias_source` option.\n>\n> nit: s/Introduced/Introduce/, to match the other entries.\n>\n> Also, parse-options.h names the third argument `source_long_name`,\n> which says what to pass; using that name here might be clearer.\n>\n> Otherwise this looks good. Thank you! :)\n>\n\nThanks, yeah, let me do that!\n\n> --\n> Cynthia\n"},{"id":"557924","messageId":"20261109-kn-parse-options-doc-v3-1-e60022942721@gmail.com","threadId":"66781","inReplyTo":"20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com","subject":"[PATCH v3] api-parse-options: add missing flags and macros","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-11-09T11:30:10Z","receivedAt":"2026-11-09T11:30:10Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'Documentation/technical/api-parse-options.adoc' contains\ndocumentation around the parse-options API. The document is missing some\nof the macros and flags provided by the API.\n\nAdd the missing flags 'PARSE_OPT_ONE_SHOT' and 'PARSE_OPT_SHELL_EVAL' to\nthe documentation. While 'PARSE_OPT_ONE_SHOT' was introduced in\n202fbb3315 (parse-options: add one-shot mode, 2019-01-27) as a temporary\nflag, it is now 7 years and still exists. So let's document it, as when\nthe time comes, it is always easy to remove the same.\n\nAlso add the following missing macros:\n  - OPT__SUPER_PREFIX\n  - OPT__VERBOSITY\n  - OPT_BITOP\n  - OPT_STRVEC\n  - OPT_UYN\n  - OPT_NOOP_ARG\n  - OPT_COLUMN\n  - OPT_CONTAINS\n  - OPT_NO_CONTAINS\n  - OPT_WITH\n  - OPT_WITHOUT\n  - OPT_CLEANUP\n  - OPT_PATHSPEC_FROM_FILE\n  - OPT_PATHSPEC_FILE_NUL\n  - OPT_AUTOSTASH\n  - OPT_DIFF_UNIFIED\n  - OPT_DIFF_INTERHUNK_CONTEXT\n  - OPT_IPVERSION\n  - OPT_ALIAS\n\nThis brings the technical documentation in line with the code in\n'parse-options.h'.\n\nWhile here, add the missing `flags` argument to `OPT__FORCE`.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\nI was reading the docs while reviewing another series and ended\nup finding some missing documentation. This patch tries to cover\nthat. Some of these might be options/flags we rarely use, but I\nstrongly feel its easier to make choices when there is adequate\ndocumentation.\n---\nChanges in v3:\n- Fix typo and rename the variable\n- Link to v2: https://patch.msgid.link/20261106-kn-parse-options-doc-v2-1-453ee7155348@gmail.com\n\nChanges in v2:\n- Add OPT_ALIAS which was previously missing.\n- Fix incorrect and missing flags in the commit message.\n- Fix typo in the commit message.\n- Link to v1: https://patch.msgid.link/20261105-kn-parse-options-doc-v1-1-403edda5947a@gmail.com\n---\n Documentation/technical/api-parse-options.adoc | 106 ++++++++++++++++++++++++-\n 1 file changed, 105 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc\nindex 6dfea34220..b20f74bc72 100644\n--- a/Documentation/technical/api-parse-options.adoc\n+++ b/Documentation/technical/api-parse-options.adoc\n@@ -138,6 +138,16 @@ Flags are the bitwise-or of:\n \tturns it off and allows one to add custom handlers for these\n \toptions, or to just leave them unknown.\n \n+`PARSE_OPT_ONE_SHOT`::\n+\tProcess only the first option (and its value, if any) and return\n+\tthe number of arguments processed, leaving `argv[]` untouched.\n+\t`argv[0]` is taken to be the first option, not the program name.\n+\tAn unknown option stops processing without an error.\n+\n+`PARSE_OPT_SHELL_EVAL`::\n+\tWrap the usage output in a heredoc followed by an `exit 0`,\n+\tso that a shell can `eval` it.\n+\n `PARSE_OPT_SUBCOMMAND_OPTIONAL`::\n \tDon't error out when no subcommand is specified.\n \n@@ -230,15 +240,25 @@ with `flags` set to `0`.\n `OPT__DRY_RUN(&int_var, description)`::\n \tAdd `-n, --dry-run`.\n \n-`OPT__FORCE(&int_var, description)`::\n+`OPT__FORCE(&int_var, description, flags)`::\n \tAdd `-f, --force`.\n \n `OPT__QUIET(&int_var, description)`::\n \tAdd `-q, --quiet`.\n \n+`OPT__SUPER_PREFIX(&str_var)`::\n+\tAdd hidden `--super-prefix=<prefix>`, which stores the prefixed\n+\tpath to the initial superproject in `str_var`.\n+\n `OPT__VERBOSE(&int_var, description)`::\n \tAdd `-v, --verbose`.\n \n+`OPT__VERBOSITY(&int_var)`::\n+\tAdd `-v, --verbose` and `-q, --quiet`, sharing `int_var`.\n+\tEach `-v` increments `int_var` (a `-v` after `-q` sets it to 1)\n+\tand each `-q` decrements it (a `-q` after `-v` sets it to -1).\n+\t`--no-verbose` and `--no-quiet` reset it to zero.\n+\n `OPT_GROUP(description)`::\n \tStart an option group. `description` is a short string that\n \tdescribes the group or an empty string.\n@@ -273,6 +293,11 @@ with `flags` set to `0`.\n \tIntroduce a boolean option.\n \tIf used, `int_var` is bitwise-ored with `mask`.\n \n+`OPT_BITOP(short, long, &int_var, description, set, clear)`::\n+\tIntroduce a boolean option.\n+\tIf used, `int_var` is bitwise-anded with the inverted `clear` and\n+\tthen bitwise-ored with `set`. Cannot be used in the negated form.\n+\n `OPT_NEGBIT(short, long, &int_var, description, mask)`::\n \tIntroduce a boolean option.\n \tIf used, `int_var` is bitwise-anded with the inverted `mask`.\n@@ -291,6 +316,16 @@ with `flags` set to `0`.\n \tThe string argument is stored as an element in `string_list`.\n \tUse of `--no-option` will clear the list of preceding values.\n \n+`OPT_STRVEC(short, long, &struct strvec, arg_str, description)`::\n+\tIntroduce an option with string argument.\n+\tThe string argument is appended to the provided `strvec`.\n+\tUse of `--no-option` will clear the list of preceding values.\n+\n+`OPT_UYN(short, long, &int_var, description)`::\n+\tIntroduce a ternary option.\n+\t`--option` sets `int_var` to `1` and `--no-option` sets it to `2`.\n+\tIf neither is given, `int_var` is left unchanged.\n+\n `OPT_INTEGER(short, long, &int_var, description)`::\n \tIntroduce an option with integer argument. The argument must be a\n \tinteger and may include a suffix of 'k', 'm' or 'g' to\n@@ -340,6 +375,17 @@ with `flags` set to `0`.\n \tUse it to hide deprecated options that are still to be recognized\n \tand ignored silently.\n \n+`OPT_NOOP_ARG(short, long)`::\n+\tIntroduce an option that takes one argument but has no effect.\n+\tUse it to hide deprecated options that are still to be recognized\n+\tand ignored silently.\n+\n+`OPT_COLUMN(short, long, &unsigned_int_var, description)`::\n+\tIntroduce an option that takes an optional argument and sets\n+\t`unsigned_int_var` as per the column layout modes specified in\n+\tlinkgit:git-config[1]. `--option` and `--no-option` without\n+\targuments are equivalent to `always` and `never` respectively.\n+\n `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::\n \tIntroduce an option that will be reconstructed into a char* string,\n \twhich must be initialized to NULL. This is useful when you need to\n@@ -366,6 +412,64 @@ with `flags` set to `0`.\n \tthis subcommand is used. The subcommand is not listed in the\n \tusage output.\n \n+`OPT_CONTAINS(&commit_list_var, description)`::\n+\tIntroduce a `--contains=<commit>` option. The argument is parsed\n+\tas a commit and inserted into `commit_list_var`. If the option is\n+\tthe last token on the command line and has no argument, `HEAD`\n+\tis used. Cannot be negated.\n+\n+`OPT_NO_CONTAINS(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces `--no-contains=<commit>`.\n+\n+`OPT_WITH(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.\n+\n+`OPT_WITHOUT(&commit_list_var, description)`::\n+\tLike `OPT_CONTAINS()`, but introduces a hidden\n+\t`--without=<commit>`.\n+\n+`OPT_CLEANUP(&str_var)`::\n+\tIntroduce a string option with `--cleanup` long name. Commonly\n+\tused to parse cleanup mode as specified in linkgit:git-commit[1].\n+\tThe option does not do any parsing itself and simply stores the\n+\targument in `str_var`.\n+\n+`OPT_PATHSPEC_FROM_FILE(&str_var)`::\n+\tIntroduce a `--pathspec-from-file=<file>` option. Commonly used\n+\tto read the pathspec from a file instead of the command-line\n+\targuments. See linkgit:git-commit[1] for more details.\n+\n+`OPT_PATHSPEC_FILE_NUL(&int_var)`::\n+\tIntroduce a boolean `--pathspec-file-nul` option. Commonly\n+\taccompanies `OPT_PATHSPEC_FROM_FILE()` to denote that the\n+\tpathspec elements are separated with `NUL` characters.\n+\tSee linkgit:git-commit[1] for more details.\n+\n+`OPT_AUTOSTASH(&int_var)`::\n+\tIntroduce a boolean `--autostash` option. Commonly used to\n+\tautomatically create a stash entry before the operation and\n+\trestore it after. See linkgit:git-merge[1] for more details.\n+\n+`OPT_DIFF_UNIFIED(&int_var)`::\n+\tIntroduce an integer option with `-U` short name and `--unified`\n+\tlong name. Commonly used to denote lines of context for generating\n+\tdiffs. Cannot be negated. See linkgit:git-add[1] for more details.\n+\n+`OPT_DIFF_INTERHUNK_CONTEXT(&int_var)`::\n+\tIntroduce an integer option with `--inter-hunk-context` long name.\n+\tCommonly used to show the context between diff hunks up to the\n+\tspecified number. Cannot be negated. See linkgit:git-add[1] for\n+\tmore details.\n+\n+`OPT_IPVERSION(&family_var)`::\n+\tIntroduce `-4, --ipv4` and `-6, --ipv6` for selecting the IP\n+\tprotocol to use. Neither takes an argument or can be negated.\n+\t`family_var` (an `enum transport_family`) is set to\n+\t`TRANSPORT_FAMILY_IPV4` or `TRANSPORT_FAMILY_IPV6` respectively.\n+\n+`OPT_ALIAS(short, long, source_long_name)`::\n+\tIntroduce an alias to another existing `source_long_name` option.\n+\n The last element of the array must be `OPT_END()`.\n \n If not stated otherwise, interpret the arguments as follows:\n\n---\nbase-commit: 8d1b215c01512b9658d4525c54ff9b9245f9a7e8\nchange-id: 20261103-kn-parse-options-doc-b4aa930ef250\n\n\nThanks\n- Karthik\n\n\n"},{"id":"557973","messageId":"xmqqse19zv8k.fsf@gitster.g","threadId":"66781","inReplyTo":"20261109-kn-parse-options-doc-v3-1-e60022942721@gmail.com","subject":"Re: [PATCH v3] api-parse-options: add missing flags and macros","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-09T18:59:39Z","receivedAt":"2026-11-09T18:59:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak <karthik.188@gmail.com> writes:\n\n> The 'Documentation/technical/api-parse-options.adoc' contains\n> documentation around the parse-options API. The document is missing some\n> of the macros and flags provided by the API.\n>\n> Add the missing flags 'PARSE_OPT_ONE_SHOT' and 'PARSE_OPT_SHELL_EVAL' to\n> the documentation. While 'PARSE_OPT_ONE_SHOT' was introduced in\n> 202fbb3315 (parse-options: add one-shot mode, 2019-01-27) as a temporary\n> flag, it is now 7 years and still exists. So let's document it, as when\n> the time comes, it is always easy to remove the same.\n>\n> Also add the following missing macros:\n>   - OPT__SUPER_PREFIX\n>   - OPT__VERBOSITY\n>   - OPT_BITOP\n>   - OPT_STRVEC\n>   - OPT_UYN\n>   - OPT_NOOP_ARG\n>   - OPT_COLUMN\n>   - OPT_CONTAINS\n>   - OPT_NO_CONTAINS\n>   - OPT_WITH\n>   - OPT_WITHOUT\n>   - OPT_CLEANUP\n>   - OPT_PATHSPEC_FROM_FILE\n>   - OPT_PATHSPEC_FILE_NUL\n>   - OPT_AUTOSTASH\n>   - OPT_DIFF_UNIFIED\n>   - OPT_DIFF_INTERHUNK_CONTEXT\n>   - OPT_IPVERSION\n>   - OPT_ALIAS\n>\n> This brings the technical documentation in line with the code in\n> 'parse-options.h'.\n>\n> While here, add the missing `flags` argument to `OPT__FORCE`.\n>\n> Signed-off-by: Karthik Nayak <karthik.188@gmail.com>\n> ---\n> I was reading the docs while reviewing another series and ended\n> up finding some missing documentation. This patch tries to cover\n> that. Some of these might be options/flags we rarely use, but I\n> strongly feel its easier to make choices when there is adequate\n> documentation.\n> ---\n> Changes in v3:\n> - Fix typo and rename the variable\n\nOK.  Matching the parameters of OPT_ALIAS() the documentation uses\nto what is actually used in parse-options.h header makes sense.\n\nHave we reached the point of diminishing returns now?\n\nThanks.\n\n"},{"id":"558079","messageId":"CAOLa=ZTakzuQQ87Znf9oPVBWd8NcqiGqqjwq2k2y-b=ZW5vMkw@mail.gmail.com","threadId":"66781","inReplyTo":"xmqqse19zv8k.fsf@gitster.g","subject":"Re: [PATCH v3] api-parse-options: add missing flags and macros","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-11-10T13:15:22Z","receivedAt":"2026-11-10T13:15:22Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Karthik Nayak <karthik.188@gmail.com> writes:\n>\n>> I was reading the docs while reviewing another series and ended\n>> up finding some missing documentation. This patch tries to cover\n>> that. Some of these might be options/flags we rarely use, but I\n>> strongly feel its easier to make choices when there is adequate\n>> documentation.\n>> ---\n>> Changes in v3:\n>> - Fix typo and rename the variable\n>\n> OK.  Matching the parameters of OPT_ALIAS() the documentation uses\n> to what is actually used in parse-options.h header makes sense.\n>\n> Have we reached the point of diminishing returns now?\n>\n> Thanks.\n\nYup. We can merge this and future improvements can be made as needed\nwith new patches :)\n\nThanks\n"}]}