{"thread":{"id":"66434","subject":"[PATCH 1/3] parse-options: fix completion format when first option is skipped","startedAt":"2026-10-01T10:13:46Z","lastAt":"2026-10-02T08:10:01Z","messageCount":14,"participants":["Patrick Steinhardt","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"553825","messageId":"20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im","threadId":"66434","inReplyTo":null,"subject":"[PATCH 0/3] builtin/refs: introduce subcommand groups","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-01T10:13:27Z","receivedAt":"2026-10-01T10:13:45Z","isPatch":true,"body":"Hi,\n\nthe git-refs(1) command has grown quite a bunch of different subcommands\nby now. These subcommands can easily be grouped into three categories:\n\n  - Operations that span across the whole reference database (migrate,\n    verify, optimize).\n\n  - Operations that read references (list, exists).\n\n  - Operations that write references (create, delete, update, rename).\n\nThis patch series thus adapts the parse-options subsystem to support\ngrouping subcommands and then introduces the grouping for git-refs(1).\nThis results in the following output:\n\n  usage: git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]\n     or: git refs verify [--strict] [--verbose]\n     or: git refs list [--count=<count>] [--shell|--perl|--python|--tcl]\n                                  [(--sort=<key>)...] [--format=<format>]\n                                  [--include-root-refs] [--points-at=<object>]\n                                  [--merged[=<object>]] [--no-merged[=<object>]]\n                                  [--contains[=<object>]] [--no-contains[=<object>]]\n                                  [(--exclude=<pattern>)...] [--start-after=<marker>]\n                                  [ --stdin | (<pattern>...)]\n     or: git refs exists <ref>\n     or: git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]\n     or: git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value>\n     or: git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>]\n     or: git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>]\n     or: git refs rename [--message=<reason>] <old-ref> <new-ref>\n\n  Reference database\n      migrate               migrate the reference database to a different format\n      verify                verify the consistency of the reference database\n      optimize              optimize the reference database\n\n  Reading references\n      list                  list references\n      exists                check whether a reference exists\n\n  Writing references\n      create                create a new reference\n      delete                delete a reference\n      update                update an existing reference\n      rename                rename a reference\n\nI expect that going forward, we'll probably have more use cases where we\ncan use these new capabilities (e.g. an upcoming git-objects(1) command,\nwhich is going to be the equivalent to git-refs(1)).\n\nThanks!\n\nPatrick\n\n---\nPatrick Steinhardt (3):\n      parse-options: fix completion format when first option is skipped\n      parse-options: allow grouping subcommands\n      builtin/refs: introduce subcommand groups\n\n Documentation/git-refs.adoc                    |  2 +-\n Documentation/technical/api-parse-options.adoc | 10 ++++-\n builtin/refs.c                                 | 32 ++++++++-----\n parse-options.c                                | 62 ++++++++++++++------------\n parse-options.h                                |  7 +++\n t/helper/test-parse-options.c                  |  4 +-\n t/t0040-parse-options.sh                       | 16 +++++++\n 7 files changed, 92 insertions(+), 41 deletions(-)\n\n\n---\nbase-commit: a018953688f1b10bddf91bff8747068f5f4746a4\nchange-id: 20261001-b4-pks-parse-options-subcommand-groups-59b3f27da06c\n\n"},{"id":"553823","messageId":"20261001-b4-pks-parse-options-subcommand-groups-v1-1-01eb2f4a4c32@pks.im","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im","subject":"[PATCH 1/3] parse-options: fix completion format when first option is skipped","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-01T10:13:28Z","receivedAt":"2026-10-01T10:13:46Z","isPatch":true,"body":"The \"--git-completion-helper\" option can be passed to any command or\nsubcommand that uses the parse-options interface. The output it\ngenerates is a space-separated list of subcommands or options understood\nby the command.\n\nThe format is slightly broken though in the case where the first option\nis not being printed, like for example a group or a hidden option. In\nthat case, `show_gitcomp()` will of course skip that first entry. But\nwhen printing the next option it checks for `opts == original_opts` to\nverify whether we're printing the first option. The check will evaluate\nto false though as we have skipped it, and thus we'll print a leading\nspace even though we have printed nothing else yet.\n\nFix that bug by tracking whether we have already printed anything via a\nlocal variable.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n parse-options.c               | 4 +++-\n t/helper/test-parse-options.c | 1 +\n 2 files changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/parse-options.c b/parse-options.c\nindex 4519ead9dc..356eeff016 100644\n--- a/parse-options.c\n+++ b/parse-options.c\n@@ -845,6 +845,7 @@ static int show_gitcomp(const struct option *opts, int show_all)\n {\n \tconst struct option *original_opts = opts;\n \tint nr_noopts = 0;\n+\tbool first = true;\n \n \tfor (; opts->type != OPTION_END; opts++) {\n \t\tconst char *prefix = \"--\";\n@@ -882,8 +883,9 @@ static int show_gitcomp(const struct option *opts, int show_all)\n \t\t\tsuffix = \"=\";\n \t\tif (starts_with(opts->long_name, \"no-\"))\n \t\t\tnr_noopts++;\n-\t\tprintf(\"%s%s%s%s\", opts == original_opts ? \"\" : \" \",\n+\t\tprintf(\"%s%s%s%s\", first ? \"\" : \" \",\n \t\t       prefix, opts->long_name, suffix);\n+\t\tfirst = false;\n \t}\n \tshow_negated_gitcomp(original_opts, show_all, -1);\n \tshow_negated_gitcomp(original_opts, show_all, nr_noopts);\ndiff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c\nindex f181f0c02d..fbafd67756 100644\n--- a/t/helper/test-parse-options.c\n+++ b/t/helper/test-parse-options.c\n@@ -351,6 +351,7 @@ static int parse_subcommand__cmd(int argc, const char **argv,\n \tparse_opt_subcommand_fn *fn = NULL;\n \tint opt = 0;\n \tstruct option options[] = {\n+\t\tOPT_GROUP(\"Subcommands\"),\n \t\tOPT_SUBCOMMAND(\"subcmd-one\", &fn, subcmd_one),\n \t\tOPT_SUBCOMMAND(\"subcmd-two\", &fn, subcmd_two),\n \t\tOPT_INTEGER('o', \"opt\", &opt, \"an integer option\"),\n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"},{"id":"553824","messageId":"20261001-b4-pks-parse-options-subcommand-groups-v1-2-01eb2f4a4c32@pks.im","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im","subject":"[PATCH 2/3] parse-options: allow grouping subcommands","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-01T10:13:29Z","receivedAt":"2026-10-01T10:13:46Z","isPatch":true,"body":"The `OPT_GROUP()` macro can be used to create a new group. These groups\ncan only be used to group options though, they do not have any effect\nwhen used in combination with subcommands. As our use of subcommands\ngrows though it can be quite useful to group these, as well.\n\nExtend the parse-options interfaces to support this use case: the new\n`OPT_SUBCOMMAND_H()` macro can be used to specify a subcommand that has\na description attached to it, and subcommands like these are now being\nconsidered for `OPT_GROUP()`.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/technical/api-parse-options.adoc | 10 ++++-\n parse-options.c                                | 58 ++++++++++++++------------\n parse-options.h                                |  7 ++++\n t/helper/test-parse-options.c                  |  3 +-\n t/t0040-parse-options.sh                       | 16 +++++++\n 5 files changed, 65 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc\nindex 95b7924e84..38dff82f72 100644\n--- a/Documentation/technical/api-parse-options.adoc\n+++ b/Documentation/technical/api-parse-options.adoc\n@@ -243,6 +243,8 @@ with `flags` set to `0`.\n \tStart an option group. `description` is a short string that\n \tdescribes the group or an empty string.\n \tStart the description with an upper-case letter.\n+\tGroups apply to options and subcommands defined with\n+\t`OPT_SUBCOMMAND_H()`.\n \n `OPT_HIDDEN_GROUP(description)`::\n \tLike `OPT_GROUP()`, but the group header carries\n@@ -362,7 +364,13 @@ with `flags` set to `0`.\n \n `OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::\n \tDefine a subcommand.  `subcommand_fn` is put into `fn_ptr` when\n-\tthis subcommand is used.\n+\tthis subcommand is used. The subcommand is not listed in the\n+\tusage output.\n+\n+`OPT_SUBCOMMAND_H(long, &fn_ptr, subcommand_fn, description)`::\n+\tLike `OPT_SUBCOMMAND()`, but the subcommand is listed in the usage\n+\toutput together with its `description`. This can be used together with\n+\t`OPT_GROUP()` to group together subcommands.\n \n The last element of the array must be `OPT_END()`.\n \ndiff --git a/parse-options.c b/parse-options.c\nindex 356eeff016..75f14b9767 100644\n--- a/parse-options.c\n+++ b/parse-options.c\n@@ -1414,7 +1414,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t\n \t\tconst char *cp, *np;\n \t\tconst char *positive_name = NULL;\n \n-\t\tif (opts->type == OPTION_SUBCOMMAND)\n+\t\tif (opts->type == OPTION_SUBCOMMAND && !opts->help)\n \t\t\tcontinue;\n \t\tif (!full && (opts->flags & PARSE_OPT_HIDDEN))\n \t\t\tcontinue;\n@@ -1432,35 +1432,39 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t\n \t\t}\n \n \t\tpos = usage_indent(outfile);\n-\t\tif (opts->short_name) {\n-\t\t\tif (opts->flags & PARSE_OPT_NODASH)\n-\t\t\t\tpos += fprintf(outfile, \"%c\", opts->short_name);\n-\t\t\telse\n-\t\t\t\tpos += fprintf(outfile, \"-%c\", opts->short_name);\n-\t\t}\n-\t\tif (opts->long_name && opts->short_name)\n-\t\t\tpos += fprintf(outfile, \", \");\n-\t\tif (opts->long_name) {\n-\t\t\tconst char *long_name = opts->long_name;\n-\t\t\tif ((opts->flags & PARSE_OPT_NONEG) ||\n-\t\t\t    skip_prefix(long_name, \"no-\", &positive_name))\n-\t\t\t\tpos += fprintf(outfile, \"--%s\", long_name);\n-\t\t\telse\n-\t\t\t\tpos += fprintf(outfile, \"--[no-]%s\", long_name);\n-\t\t}\n+\t\tif (opts->type == OPTION_SUBCOMMAND) {\n+\t\t\tpos += fprintf(outfile, \"%s\", opts->long_name);\n+\t\t} else {\n+\t\t\tif (opts->short_name) {\n+\t\t\t\tif (opts->flags & PARSE_OPT_NODASH)\n+\t\t\t\t\tpos += fprintf(outfile, \"%c\", opts->short_name);\n+\t\t\t\telse\n+\t\t\t\t\tpos += fprintf(outfile, \"-%c\", opts->short_name);\n+\t\t\t}\n+\t\t\tif (opts->long_name && opts->short_name)\n+\t\t\t\tpos += fprintf(outfile, \", \");\n+\t\t\tif (opts->long_name) {\n+\t\t\t\tconst char *long_name = opts->long_name;\n+\t\t\t\tif ((opts->flags & PARSE_OPT_NONEG) ||\n+\t\t\t\t    skip_prefix(long_name, \"no-\", &positive_name))\n+\t\t\t\t\tpos += fprintf(outfile, \"--%s\", long_name);\n+\t\t\t\telse\n+\t\t\t\t\tpos += fprintf(outfile, \"--[no-]%s\", long_name);\n+\t\t\t}\n \n-\t\tif (opts->type == OPTION_NUMBER)\n-\t\t\tpos += utf8_fprintf(outfile, _(\"-NUM\"));\n+\t\t\tif (opts->type == OPTION_NUMBER)\n+\t\t\t\tpos += utf8_fprintf(outfile, _(\"-NUM\"));\n \n-\t\tif ((opts->flags & PARSE_OPT_LITERAL_ARGHELP) ||\n-\t\t    !(opts->flags & PARSE_OPT_NOARG))\n-\t\t\tpos += usage_argh(opts, outfile);\n+\t\t\tif ((opts->flags & PARSE_OPT_LITERAL_ARGHELP) ||\n+\t\t\t    !(opts->flags & PARSE_OPT_NOARG))\n+\t\t\t\tpos += usage_argh(opts, outfile);\n \n-\t\tif (opts->type == OPTION_ALIAS) {\n-\t\t\tusage_padding(outfile, pos);\n-\t\t\tfprintf_ln(outfile, _(\"alias of --%s\"),\n-\t\t\t\t   (const char *)opts->value);\n-\t\t\tcontinue;\n+\t\t\tif (opts->type == OPTION_ALIAS) {\n+\t\t\t\tusage_padding(outfile, pos);\n+\t\t\t\tfprintf_ln(outfile, _(\"alias of --%s\"),\n+\t\t\t\t\t   (const char *)opts->value);\n+\t\t\t\tcontinue;\n+\t\t\t}\n \t\t}\n \n \t\tfor (cp = opts->help ? _(opts->help) : \"\"; *cp; cp = np) {\ndiff --git a/parse-options.h b/parse-options.h\nindex d7f896a933..5249404b46 100644\n--- a/parse-options.h\n+++ b/parse-options.h\n@@ -401,6 +401,13 @@ static char *parse_options_noop_ignored_value MAYBE_UNUSED;\n \t.subcommand_fn = (fn), \\\n }\n #define OPT_SUBCOMMAND(l, v, fn)    OPT_SUBCOMMAND_F((l), (v), (fn), 0)\n+#define OPT_SUBCOMMAND_H(l, v, fn, h) { \\\n+\t.type = OPTION_SUBCOMMAND, \\\n+\t.long_name = (l), \\\n+\t.value = (v), \\\n+\t.help = (h), \\\n+\t.subcommand_fn = (fn), \\\n+}\n \n /*\n  * parse_options() will filter out the processed options and leave the\ndiff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c\nindex fbafd67756..4a146bd016 100644\n--- a/t/helper/test-parse-options.c\n+++ b/t/helper/test-parse-options.c\n@@ -352,8 +352,9 @@ static int parse_subcommand__cmd(int argc, const char **argv,\n \tint opt = 0;\n \tstruct option options[] = {\n \t\tOPT_GROUP(\"Subcommands\"),\n-\t\tOPT_SUBCOMMAND(\"subcmd-one\", &fn, subcmd_one),\n+\t\tOPT_SUBCOMMAND_H(\"subcmd-one\", &fn, subcmd_one, \"the first subcommand\"),\n \t\tOPT_SUBCOMMAND(\"subcmd-two\", &fn, subcmd_two),\n+\t\tOPT_GROUP(\"Options\"),\n \t\tOPT_INTEGER('o', \"opt\", &opt, \"an integer option\"),\n \t\tOPT_END()\n \t};\ndiff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh\nindex 449fff4d34..ec55bb1414 100755\n--- a/t/t0040-parse-options.sh\n+++ b/t/t0040-parse-options.sh\n@@ -629,6 +629,22 @@ test_expect_success 'KEEP_UNKNOWN_OPT | NO_INTERNAL_HELP works' '\n \ttest_cmp expect actual\n '\n \n+test_expect_success 'subcommand - usage lists subcommands with help text under their group' '\n+\ttest-tool parse-subcommand cmd -h >actual &&\n+\tcat >expect <<-\\EOF &&\n+\tusage: <...> cmd subcmd-one\n+\t   or: <...> cmd subcmd-two\n+\n+\tSubcommands\n+\t    subcmd-one            the first subcommand\n+\n+\tOptions\n+\t    -o, --[no-]opt <n>    an integer option\n+\n+\tEOF\n+\ttest_cmp expect actual\n+'\n+\n test_expect_success 'subcommand - no subcommand shows error and usage' '\n \ttest_expect_code 129 test-tool parse-subcommand cmd 2>err &&\n \ttest_grep \"^error: need a subcommand\" err &&\n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"},{"id":"553826","messageId":"20261001-b4-pks-parse-options-subcommand-groups-v1-3-01eb2f4a4c32@pks.im","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im","subject":"[PATCH 3/3] builtin/refs: introduce subcommand groups","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-01T10:13:30Z","receivedAt":"2026-10-01T10:13:51Z","isPatch":true,"body":"The git-refs(1) command nowadays has a bunch of different subcommands,\nwhich makes it hard to figure out what's what at a glance. Now that the\nparse-options subsystem supports grouping subcommands though we can do\nbetter. The commands roughly fall into the following categories:\n\n  - Operations that span across the whole reference database.\n\n  - Operations that read references.\n\n  - Operations that write references.\n\nIntroduce these groups accordingly, which results in the following help\noutput:\n\n  Reference database\n      migrate               migrate the reference database to a different format\n      verify                verify the consistency of the reference database\n      optimize              optimize the reference database\n\n  Reading references\n      list                  list references\n      exists                check whether a reference exists\n\n  Writing references\n      create                create a new reference\n      delete                delete a reference\n      update                update an existing reference\n      rename                rename a reference\n\nReorder the usage strings to match the new grouping.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/git-refs.adoc |  2 +-\n builtin/refs.c              | 32 ++++++++++++++++++++++----------\n 2 files changed, 23 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 9dc08cbca9..da7260c416 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -11,6 +11,7 @@ SYNOPSIS\n [synopsis]\n git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]\n git refs verify [--strict] [--verbose]\n+git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]\n git refs list [--count=<count>] [--shell|--perl|--python|--tcl]\n \t\t   [(--sort=<key>)...] [--format=<format>]\n \t\t   [--include-root-refs] [--points-at=<object>]\n@@ -19,7 +20,6 @@ git refs list [--count=<count>] [--shell|--perl|--python|--tcl]\n \t\t   [(--exclude=<pattern>)...] [--start-after=<marker>]\n \t\t   [ --stdin | (<pattern>...)]\n git refs exists <ref>\n-git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]\n git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value>\n git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>]\n git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>]\ndiff --git a/builtin/refs.c b/builtin/refs.c\nindex 5cd21c25fe..f46abd6268 100644\n--- a/builtin/refs.c\n+++ b/builtin/refs.c\n@@ -382,9 +382,9 @@ int cmd_refs(int argc,\n \tconst char * const refs_usage[] = {\n \t\tREFS_MIGRATE_USAGE,\n \t\tREFS_VERIFY_USAGE,\n+\t\tREFS_OPTIMIZE_USAGE,\n \t\t\"git refs list \" COMMON_USAGE_FOR_EACH_REF,\n \t\tREFS_EXISTS_USAGE,\n-\t\tREFS_OPTIMIZE_USAGE,\n \t\tREFS_CREATE_USAGE,\n \t\tREFS_DELETE_USAGE,\n \t\tREFS_UPDATE_USAGE,\n@@ -393,15 +393,27 @@ int cmd_refs(int argc,\n \t};\n \tparse_opt_subcommand_fn *fn = NULL;\n \tstruct option opts[] = {\n-\t\tOPT_SUBCOMMAND(\"migrate\", &fn, cmd_refs_migrate),\n-\t\tOPT_SUBCOMMAND(\"verify\", &fn, cmd_refs_verify),\n-\t\tOPT_SUBCOMMAND(\"list\", &fn, cmd_refs_list),\n-\t\tOPT_SUBCOMMAND(\"exists\", &fn, cmd_refs_exists),\n-\t\tOPT_SUBCOMMAND(\"optimize\", &fn, cmd_refs_optimize),\n-\t\tOPT_SUBCOMMAND(\"create\", &fn, cmd_refs_create),\n-\t\tOPT_SUBCOMMAND(\"delete\", &fn, cmd_refs_delete),\n-\t\tOPT_SUBCOMMAND(\"update\", &fn, cmd_refs_update),\n-\t\tOPT_SUBCOMMAND(\"rename\", &fn, cmd_refs_rename),\n+\t\tOPT_GROUP(N_(\"Reference database\")),\n+\t\tOPT_SUBCOMMAND_H(\"migrate\", &fn, cmd_refs_migrate,\n+\t\t\t\t N_(\"migrate the reference database to a different format\")),\n+\t\tOPT_SUBCOMMAND_H(\"verify\", &fn, cmd_refs_verify,\n+\t\t\t\t N_(\"verify the consistency of the reference database\")),\n+\t\tOPT_SUBCOMMAND_H(\"optimize\", &fn, cmd_refs_optimize,\n+\t\t\t\t N_(\"optimize the reference database\")),\n+\t\tOPT_GROUP(N_(\"Reading references\")),\n+\t\tOPT_SUBCOMMAND_H(\"list\", &fn, cmd_refs_list,\n+\t\t\t\t N_(\"list references\")),\n+\t\tOPT_SUBCOMMAND_H(\"exists\", &fn, cmd_refs_exists,\n+\t\t\t\t N_(\"check whether a reference exists\")),\n+\t\tOPT_GROUP(N_(\"Writing references\")),\n+\t\tOPT_SUBCOMMAND_H(\"create\", &fn, cmd_refs_create,\n+\t\t\t\t N_(\"create a new reference\")),\n+\t\tOPT_SUBCOMMAND_H(\"delete\", &fn, cmd_refs_delete,\n+\t\t\t\t N_(\"delete a reference\")),\n+\t\tOPT_SUBCOMMAND_H(\"update\", &fn, cmd_refs_update,\n+\t\t\t\t N_(\"update an existing reference\")),\n+\t\tOPT_SUBCOMMAND_H(\"rename\", &fn, cmd_refs_rename,\n+\t\t\t\t N_(\"rename a reference\")),\n \t\tOPT_END(),\n \t};\n \n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"},{"id":"553854","messageId":"xmqqik3l5njz.fsf@gitster.g","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-1-01eb2f4a4c32@pks.im","subject":"Re: [PATCH 1/3] parse-options: fix completion format when first option is skipped","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-01T17:38:08Z","receivedAt":"2026-10-01T17:38:11Z","isPatch":true,"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> The \"--git-completion-helper\" option can be passed to any command or\n> subcommand that uses the parse-options interface. The output it\n> generates is a space-separated list of subcommands or options understood\n> by the command.\n>\n> The format is slightly broken though in the case where the first option\n> is not being printed, like for example a group or a hidden option. In\n> that case, `show_gitcomp()` will of course skip that first entry. But\n> when printing the next option it checks for `opts == original_opts` to\n> verify whether we're printing the first option. The check will evaluate\n> to false though as we have skipped it, and thus we'll print a leading\n> space even though we have printed nothing else yet.\n>\n> Fix that bug by tracking whether we have already printed anything via a\n> local variable.\n\nVery clearly articulated.  I would have chosen 'shown' as the\nvariable name to so do, but 'first' may also be OK.\n\n>\n> Signed-off-by: Patrick Steinhardt <ps@pks.im>\n> ---\n>  parse-options.c               | 4 +++-\n>  t/helper/test-parse-options.c | 1 +\n>  2 files changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git a/parse-options.c b/parse-options.c\n> index 4519ead9dc..356eeff016 100644\n> --- a/parse-options.c\n> +++ b/parse-options.c\n> @@ -845,6 +845,7 @@ static int show_gitcomp(const struct option *opts, int show_all)\n>  {\n>  \tconst struct option *original_opts = opts;\n>  \tint nr_noopts = 0;\n> +\tbool first = true;\n>  \n>  \tfor (; opts->type != OPTION_END; opts++) {\n>  \t\tconst char *prefix = \"--\";\n> @@ -882,8 +883,9 @@ static int show_gitcomp(const struct option *opts, int show_all)\n>  \t\t\tsuffix = \"=\";\n>  \t\tif (starts_with(opts->long_name, \"no-\"))\n>  \t\t\tnr_noopts++;\n> -\t\tprintf(\"%s%s%s%s\", opts == original_opts ? \"\" : \" \",\n> +\t\tprintf(\"%s%s%s%s\", first ? \"\" : \" \",\n>  \t\t       prefix, opts->long_name, suffix);\n> +\t\tfirst = false;\n>  \t}\n>  \tshow_negated_gitcomp(original_opts, show_all, -1);\n>  \tshow_negated_gitcomp(original_opts, show_all, nr_noopts);\n> diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c\n> index f181f0c02d..fbafd67756 100644\n> --- a/t/helper/test-parse-options.c\n> +++ b/t/helper/test-parse-options.c\n> @@ -351,6 +351,7 @@ static int parse_subcommand__cmd(int argc, const char **argv,\n>  \tparse_opt_subcommand_fn *fn = NULL;\n>  \tint opt = 0;\n>  \tstruct option options[] = {\n> +\t\tOPT_GROUP(\"Subcommands\"),\n>  \t\tOPT_SUBCOMMAND(\"subcmd-one\", &fn, subcmd_one),\n>  \t\tOPT_SUBCOMMAND(\"subcmd-two\", &fn, subcmd_two),\n>  \t\tOPT_INTEGER('o', \"opt\", &opt, \"an integer option\"),\n"},{"id":"553856","messageId":"xmqqcxtt5n67.fsf@gitster.g","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-2-01eb2f4a4c32@pks.im","subject":"Re: [PATCH 2/3] parse-options: allow grouping subcommands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-01T17:46:24Z","receivedAt":"2026-10-01T17:46:29Z","isPatch":true,"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> @@ -1432,35 +1432,39 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t\n>  \t\t}\n>  \n>  \t\tpos = usage_indent(outfile);\n> -\t\tif (opts->short_name) {\n> -\t\t\tif (opts->flags & PARSE_OPT_NODASH)\n> -\t\t\t\tpos += fprintf(outfile, \"%c\", opts->short_name);\n> -\t\t\telse\n> -\t\t\t\tpos += fprintf(outfile, \"-%c\", opts->short_name);\n> -\t\t}\n> -\t\tif (opts->long_name && opts->short_name)\n> -\t\t\tpos += fprintf(outfile, \", \");\n> -\t\tif (opts->long_name) {\n> -\t\t\tconst char *long_name = opts->long_name;\n> -\t\t\tif ((opts->flags & PARSE_OPT_NONEG) ||\n> -\t\t\t    skip_prefix(long_name, \"no-\", &positive_name))\n> -\t\t\t\tpos += fprintf(outfile, \"--%s\", long_name);\n> -\t\t\telse\n> -\t\t\t\tpos += fprintf(outfile, \"--[no-]%s\", long_name);\n> -\t\t}\n\nIt may have made it easier to follow if a preliminary step pushed\nthe above to a helper function.  It would have also prevented the\nnesting becoming too deep as we see below.\n\n> +\t\tif (opts->type == OPTION_SUBCOMMAND) {\n> +\t\t\tpos += fprintf(outfile, \"%s\", opts->long_name);\n> +\t\t} else {\n> +\t\t\tif (opts->short_name) {\n> +\t\t\t\tif (opts->flags & PARSE_OPT_NODASH)\n> +\t\t\t\t\tpos += fprintf(outfile, \"%c\", opts->short_name);\n> +\t\t\t\telse\n> +\t\t\t\t\tpos += fprintf(outfile, \"-%c\", opts->short_name);\n> +\t\t\t}\n> +\t\t\tif (opts->long_name && opts->short_name)\n> +\t\t\t\tpos += fprintf(outfile, \", \");\n> +\t\t\tif (opts->long_name) {\n> +\t\t\t\tconst char *long_name = opts->long_name;\n> +\t\t\t\tif ((opts->flags & PARSE_OPT_NONEG) ||\n> +\t\t\t\t    skip_prefix(long_name, \"no-\", &positive_name))\n> +\t\t\t\t\tpos += fprintf(outfile, \"--%s\", long_name);\n> +\t\t\t\telse\n\n> diff --git a/parse-options.h b/parse-options.h\n> index d7f896a933..5249404b46 100644\n> --- a/parse-options.h\n> +++ b/parse-options.h\n> @@ -401,6 +401,13 @@ static char *parse_options_noop_ignored_value MAYBE_UNUSED;\n>  \t.subcommand_fn = (fn), \\\n>  }\n>  #define OPT_SUBCOMMAND(l, v, fn)    OPT_SUBCOMMAND_F((l), (v), (fn), 0)\n> +#define OPT_SUBCOMMAND_H(l, v, fn, h) { \\\n> +\t.type = OPTION_SUBCOMMAND, \\\n> +\t.long_name = (l), \\\n> +\t.value = (v), \\\n> +\t.help = (h), \\\n> +\t.subcommand_fn = (fn), \\\n> +}\n\nAs presented, _F does not allow you to give it a help, and _H does\nnot allow you to give it a flag word.  I would have preferred to see\nOPT_SUBCOMMAND_F to be extended to also take the help text, as we\nonly have two existing users in *.c code, rather than adding _H\nvariant that is incomplete and keeping _F incomplete.\n"},{"id":"553857","messageId":"xmqq8q4h5n5o.fsf@gitster.g","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-3-01eb2f4a4c32@pks.im","subject":"Re: [PATCH 3/3] builtin/refs: introduce subcommand groups","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-01T17:46:43Z","receivedAt":"2026-10-01T17:46:46Z","isPatch":true,"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> The git-refs(1) command nowadays has a bunch of different subcommands,\n> which makes it hard to figure out what's what at a glance. Now that the\n> parse-options subsystem supports grouping subcommands though we can do\n> better. The commands roughly fall into the following categories:\n>\n>   - Operations that span across the whole reference database.\n>\n>   - Operations that read references.\n>\n>   - Operations that write references.\n>\n> Introduce these groups accordingly, which results in the following help\n> output:\n>\n>   Reference database\n>       migrate               migrate the reference database to a different format\n>       verify                verify the consistency of the reference database\n>       optimize              optimize the reference database\n>\n>   Reading references\n>       list                  list references\n>       exists                check whether a reference exists\n>\n>   Writing references\n>       create                create a new reference\n>       delete                delete a reference\n>       update                update an existing reference\n>       rename                rename a reference\n\nNice.\n"},{"id":"553898","messageId":"ar9bDza3ImB71AIN@pks.im","threadId":"66434","inReplyTo":"xmqqik3l5njz.fsf@gitster.g","subject":"Re: [PATCH 1/3] parse-options: fix completion format when first option is skipped","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T07:19:43Z","receivedAt":"2026-10-02T07:19:53Z","isPatch":true,"body":"On Thu, Oct 01, 2026 at 10:38:08AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> \n> > The \"--git-completion-helper\" option can be passed to any command or\n> > subcommand that uses the parse-options interface. The output it\n> > generates is a space-separated list of subcommands or options understood\n> > by the command.\n> >\n> > The format is slightly broken though in the case where the first option\n> > is not being printed, like for example a group or a hidden option. In\n> > that case, `show_gitcomp()` will of course skip that first entry. But\n> > when printing the next option it checks for `opts == original_opts` to\n> > verify whether we're printing the first option. The check will evaluate\n> > to false though as we have skipped it, and thus we'll print a leading\n> > space even though we have printed nothing else yet.\n> >\n> > Fix that bug by tracking whether we have already printed anything via a\n> > local variable.\n> \n> Very clearly articulated.  I would have chosen 'shown' as the\n> variable name to so do, but 'first' may also be OK.\n\nThat's a fair point. We explicitly _don't_ care whether it's the first\nentry or not, as that would match the old logic that caused this bug in\nthe first place. So `shown` is a better name indeed.\n\nPatrick\n"},{"id":"553899","messageId":"ar9bGF9NqIcol256@pks.im","threadId":"66434","inReplyTo":"xmqqcxtt5n67.fsf@gitster.g","subject":"Re: [PATCH 2/3] parse-options: allow grouping subcommands","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T07:19:52Z","receivedAt":"2026-10-02T07:19:56Z","isPatch":true,"body":"On Thu, Oct 01, 2026 at 10:46:24AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> \n> > @@ -1432,35 +1432,39 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t\n> >  \t\t}\n> >  \n> >  \t\tpos = usage_indent(outfile);\n> > -\t\tif (opts->short_name) {\n> > -\t\t\tif (opts->flags & PARSE_OPT_NODASH)\n> > -\t\t\t\tpos += fprintf(outfile, \"%c\", opts->short_name);\n> > -\t\t\telse\n> > -\t\t\t\tpos += fprintf(outfile, \"-%c\", opts->short_name);\n> > -\t\t}\n> > -\t\tif (opts->long_name && opts->short_name)\n> > -\t\t\tpos += fprintf(outfile, \", \");\n> > -\t\tif (opts->long_name) {\n> > -\t\t\tconst char *long_name = opts->long_name;\n> > -\t\t\tif ((opts->flags & PARSE_OPT_NONEG) ||\n> > -\t\t\t    skip_prefix(long_name, \"no-\", &positive_name))\n> > -\t\t\t\tpos += fprintf(outfile, \"--%s\", long_name);\n> > -\t\t\telse\n> > -\t\t\t\tpos += fprintf(outfile, \"--[no-]%s\", long_name);\n> > -\t\t}\n> \n> It may have made it easier to follow if a preliminary step pushed\n> the above to a helper function.  It would have also prevented the\n> nesting becoming too deep as we see below.\n\nWill do.\n\n> > diff --git a/parse-options.h b/parse-options.h\n> > index d7f896a933..5249404b46 100644\n> > --- a/parse-options.h\n> > +++ b/parse-options.h\n> > @@ -401,6 +401,13 @@ static char *parse_options_noop_ignored_value MAYBE_UNUSED;\n> >  \t.subcommand_fn = (fn), \\\n> >  }\n> >  #define OPT_SUBCOMMAND(l, v, fn)    OPT_SUBCOMMAND_F((l), (v), (fn), 0)\n> > +#define OPT_SUBCOMMAND_H(l, v, fn, h) { \\\n> > +\t.type = OPTION_SUBCOMMAND, \\\n> > +\t.long_name = (l), \\\n> > +\t.value = (v), \\\n> > +\t.help = (h), \\\n> > +\t.subcommand_fn = (fn), \\\n> > +}\n> \n> As presented, _F does not allow you to give it a help, and _H does\n> not allow you to give it a flag word.  I would have preferred to see\n> OPT_SUBCOMMAND_F to be extended to also take the help text, as we\n> only have two existing users in *.c code, rather than adding _H\n> variant that is incomplete and keeping _F incomplete.\n\nI was a bit torn here because I honestly wasn't quite sure whether the\n_F suffix stands for \"full\" or \"flag\". But okay, let's not introduce a\nnew macro then.\n\nPatrick\n"},{"id":"553908","messageId":"20261002-b4-pks-parse-options-subcommand-groups-v2-0-3299bee52dea@pks.im","threadId":"66434","inReplyTo":"20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im","subject":"[PATCH v2 0/4] builtin/refs: introduce subcommand groups","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T08:09:45Z","receivedAt":"2026-10-02T08:09:53Z","isPatch":true,"body":"Hi,\n\nthe git-refs(1) command has grown quite a bunch of different subcommands\nby now. These subcommands can easily be grouped into three categories:\n\n  - Operations that span across the whole reference database (migrate,\n    verify, optimize).\n\n  - Operations that read references (list, exists).\n\n  - Operations that write references (create, delete, update, rename).\n\nThis patch series thus adapts the parse-options subsystem to support\ngrouping subcommands and then introduces the grouping for git-refs(1).\nThis results in the following output:\n\n  usage: git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]\n     or: git refs verify [--strict] [--verbose]\n     or: git refs list [--count=<count>] [--shell|--perl|--python|--tcl]\n                                  [(--sort=<key>)...] [--format=<format>]\n                                  [--include-root-refs] [--points-at=<object>]\n                                  [--merged[=<object>]] [--no-merged[=<object>]]\n                                  [--contains[=<object>]] [--no-contains[=<object>]]\n                                  [(--exclude=<pattern>)...] [--start-after=<marker>]\n                                  [ --stdin | (<pattern>...)]\n     or: git refs exists <ref>\n     or: git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]\n     or: git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value>\n     or: git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>]\n     or: git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>]\n     or: git refs rename [--message=<reason>] <old-ref> <new-ref>\n\n  Reference database\n      migrate               migrate the reference database to a different format\n      verify                verify the consistency of the reference database\n      optimize              optimize the reference database\n\n  Reading references\n      list                  list references\n      exists                check whether a reference exists\n\n  Writing references\n      create                create a new reference\n      delete                delete a reference\n      update                update an existing reference\n      rename                rename a reference\n\nI expect that going forward, we'll probably have more use cases where we\ncan use these new capabilities (e.g. an upcoming git-objects(1) command,\nwhich is going to be the equivalent to git-refs(1)).\n\nChanges in v2:\n  - Add a preliminary refactoring for `usage_with_options_internal()` so\n    that we don't have to reindent a bunch of its code.\n  - Drop `OPT_SUBCOMMAND_H()` and extend `OPT_SUBCOMMAND_F()` instead.\n  - Rename `bool first` to `bool shown`.\n  - Link to v1: https://patch.msgid.link/20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im\n\nThanks!\n\nPatrick\n\n---\nPatrick Steinhardt (4):\n      parse-options: fix completion format when first option is skipped\n      parse-options: extract functions to print single option\n      parse-options: allow grouping subcommands\n      builtin/refs: introduce subcommand groups\n\n Documentation/git-refs.adoc                    |   2 +-\n Documentation/technical/api-parse-options.adoc |   4 +-\n builtin/refs.c                                 |  32 +++--\n builtin/remote.c                               |   2 +-\n builtin/stash.c                                |   2 +-\n parse-options.c                                | 176 ++++++++++++++-----------\n parse-options.h                                |   5 +-\n t/helper/test-parse-options.c                  |   4 +-\n t/t0040-parse-options.sh                       |  16 +++\n 9 files changed, 150 insertions(+), 93 deletions(-)\n\nRange-diff versus v1:\n\n1:  7ba8a5ca15 ! 1:  10b2249fa6 parse-options: fix completion format when first option is skipped\n    @@ parse-options.c: static int show_gitcomp(const struct option *opts, int show_all\n      {\n      \tconst struct option *original_opts = opts;\n      \tint nr_noopts = 0;\n    -+\tbool first = true;\n    ++\tbool shown = false;\n      \n      \tfor (; opts->type != OPTION_END; opts++) {\n      \t\tconst char *prefix = \"--\";\n    @@ parse-options.c: static int show_gitcomp(const struct option *opts, int show_all\n      \t\tif (starts_with(opts->long_name, \"no-\"))\n      \t\t\tnr_noopts++;\n     -\t\tprintf(\"%s%s%s%s\", opts == original_opts ? \"\" : \" \",\n    -+\t\tprintf(\"%s%s%s%s\", first ? \"\" : \" \",\n    ++\t\tprintf(\"%s%s%s%s\", shown ? \" \" : \"\",\n      \t\t       prefix, opts->long_name, suffix);\n    -+\t\tfirst = false;\n    ++\t\tshown = true;\n      \t}\n      \tshow_negated_gitcomp(original_opts, show_all, -1);\n      \tshow_negated_gitcomp(original_opts, show_all, nr_noopts);\n2:  8176cf838d < -:  ---------- parse-options: allow grouping subcommands\n-:  ---------- > 2:  31e5f08cdb parse-options: extract functions to print single option\n-:  ---------- > 3:  20da51f904 parse-options: allow grouping subcommands\n3:  9599245895 ! 4:  11cfbe5cae builtin/refs: introduce subcommand groups\n    @@ builtin/refs.c: int cmd_refs(int argc,\n     -\t\tOPT_SUBCOMMAND(\"update\", &fn, cmd_refs_update),\n     -\t\tOPT_SUBCOMMAND(\"rename\", &fn, cmd_refs_rename),\n     +\t\tOPT_GROUP(N_(\"Reference database\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"migrate\", &fn, cmd_refs_migrate,\n    -+\t\t\t\t N_(\"migrate the reference database to a different format\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"verify\", &fn, cmd_refs_verify,\n    -+\t\t\t\t N_(\"verify the consistency of the reference database\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"optimize\", &fn, cmd_refs_optimize,\n    -+\t\t\t\t N_(\"optimize the reference database\")),\n    ++\t\tOPT_SUBCOMMAND_F(\"migrate\", &fn, cmd_refs_migrate,\n    ++\t\t\t\t N_(\"migrate the reference database to a different format\"), 0),\n    ++\t\tOPT_SUBCOMMAND_F(\"verify\", &fn, cmd_refs_verify,\n    ++\t\t\t\t N_(\"verify the consistency of the reference database\"), 0),\n    ++\t\tOPT_SUBCOMMAND_F(\"optimize\", &fn, cmd_refs_optimize,\n    ++\t\t\t\t N_(\"optimize the reference database\"), 0),\n     +\t\tOPT_GROUP(N_(\"Reading references\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"list\", &fn, cmd_refs_list,\n    -+\t\t\t\t N_(\"list references\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"exists\", &fn, cmd_refs_exists,\n    -+\t\t\t\t N_(\"check whether a reference exists\")),\n    ++\t\tOPT_SUBCOMMAND_F(\"list\", &fn, cmd_refs_list,\n    ++\t\t\t\t N_(\"list references\"), 0),\n    ++\t\tOPT_SUBCOMMAND_F(\"exists\", &fn, cmd_refs_exists,\n    ++\t\t\t\t N_(\"check whether a reference exists\"), 0),\n     +\t\tOPT_GROUP(N_(\"Writing references\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"create\", &fn, cmd_refs_create,\n    -+\t\t\t\t N_(\"create a new reference\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"delete\", &fn, cmd_refs_delete,\n    -+\t\t\t\t N_(\"delete a reference\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"update\", &fn, cmd_refs_update,\n    -+\t\t\t\t N_(\"update an existing reference\")),\n    -+\t\tOPT_SUBCOMMAND_H(\"rename\", &fn, cmd_refs_rename,\n    -+\t\t\t\t N_(\"rename a reference\")),\n    ++\t\tOPT_SUBCOMMAND_F(\"create\", &fn, cmd_refs_create,\n    ++\t\t\t\t N_(\"create a new reference\"), 0),\n    ++\t\tOPT_SUBCOMMAND_F(\"delete\", &fn, cmd_refs_delete,\n    ++\t\t\t\t N_(\"delete a reference\"), 0),\n    ++\t\tOPT_SUBCOMMAND_F(\"update\", &fn, cmd_refs_update,\n    ++\t\t\t\t N_(\"update an existing reference\"), 0),\n    ++\t\tOPT_SUBCOMMAND_F(\"rename\", &fn, cmd_refs_rename,\n    ++\t\t\t\t N_(\"rename a reference\"), 0),\n      \t\tOPT_END(),\n      \t};\n      \n\n---\nbase-commit: a018953688f1b10bddf91bff8747068f5f4746a4\nchange-id: 20261001-b4-pks-parse-options-subcommand-groups-59b3f27da06c\n\n"},{"id":"553909","messageId":"20261002-b4-pks-parse-options-subcommand-groups-v2-1-3299bee52dea@pks.im","threadId":"66434","inReplyTo":"20261002-b4-pks-parse-options-subcommand-groups-v2-0-3299bee52dea@pks.im","subject":"[PATCH v2 1/4] parse-options: fix completion format when first option is skipped","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T08:09:46Z","receivedAt":"2026-10-02T08:09:54Z","isPatch":true,"body":"The \"--git-completion-helper\" option can be passed to any command or\nsubcommand that uses the parse-options interface. The output it\ngenerates is a space-separated list of subcommands or options understood\nby the command.\n\nThe format is slightly broken though in the case where the first option\nis not being printed, like for example a group or a hidden option. In\nthat case, `show_gitcomp()` will of course skip that first entry. But\nwhen printing the next option it checks for `opts == original_opts` to\nverify whether we're printing the first option. The check will evaluate\nto false though as we have skipped it, and thus we'll print a leading\nspace even though we have printed nothing else yet.\n\nFix that bug by tracking whether we have already printed anything via a\nlocal variable.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n parse-options.c               | 4 +++-\n t/helper/test-parse-options.c | 1 +\n 2 files changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/parse-options.c b/parse-options.c\nindex 4519ead9dc..8bb30ec116 100644\n--- a/parse-options.c\n+++ b/parse-options.c\n@@ -845,6 +845,7 @@ static int show_gitcomp(const struct option *opts, int show_all)\n {\n \tconst struct option *original_opts = opts;\n \tint nr_noopts = 0;\n+\tbool shown = false;\n \n \tfor (; opts->type != OPTION_END; opts++) {\n \t\tconst char *prefix = \"--\";\n@@ -882,8 +883,9 @@ static int show_gitcomp(const struct option *opts, int show_all)\n \t\t\tsuffix = \"=\";\n \t\tif (starts_with(opts->long_name, \"no-\"))\n \t\t\tnr_noopts++;\n-\t\tprintf(\"%s%s%s%s\", opts == original_opts ? \"\" : \" \",\n+\t\tprintf(\"%s%s%s%s\", shown ? \" \" : \"\",\n \t\t       prefix, opts->long_name, suffix);\n+\t\tshown = true;\n \t}\n \tshow_negated_gitcomp(original_opts, show_all, -1);\n \tshow_negated_gitcomp(original_opts, show_all, nr_noopts);\ndiff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c\nindex f181f0c02d..fbafd67756 100644\n--- a/t/helper/test-parse-options.c\n+++ b/t/helper/test-parse-options.c\n@@ -351,6 +351,7 @@ static int parse_subcommand__cmd(int argc, const char **argv,\n \tparse_opt_subcommand_fn *fn = NULL;\n \tint opt = 0;\n \tstruct option options[] = {\n+\t\tOPT_GROUP(\"Subcommands\"),\n \t\tOPT_SUBCOMMAND(\"subcmd-one\", &fn, subcmd_one),\n \t\tOPT_SUBCOMMAND(\"subcmd-two\", &fn, subcmd_two),\n \t\tOPT_INTEGER('o', \"opt\", &opt, \"an integer option\"),\n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"},{"id":"553910","messageId":"20261002-b4-pks-parse-options-subcommand-groups-v2-2-3299bee52dea@pks.im","threadId":"66434","inReplyTo":"20261002-b4-pks-parse-options-subcommand-groups-v2-0-3299bee52dea@pks.im","subject":"[PATCH v2 2/4] parse-options: extract functions to print single option","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T08:09:47Z","receivedAt":"2026-10-02T08:09:57Z","isPatch":true,"body":"The logic to print a single option has grown somewhat long. Extract the\nlogic into two functions to print a single option and a flag,\nspecifically. This refactoring makes a subsequent change easier to\nimplement.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n parse-options.c | 169 +++++++++++++++++++++++++++++++-------------------------\n 1 file changed, 94 insertions(+), 75 deletions(-)\n\ndiff --git a/parse-options.c b/parse-options.c\nindex 8bb30ec116..fdcb29f2a1 100644\n--- a/parse-options.c\n+++ b/parse-options.c\n@@ -1323,6 +1323,97 @@ static const struct option *find_option_by_long_name(const struct option *opts,\n \treturn NULL;\n }\n \n+static int usage_print_flag(const struct option *opt,\n+\t\t\t    FILE *outfile,\n+\t\t\t    const char **positive_name)\n+{\n+\tint off = 0;\n+\n+\tif (opt->short_name) {\n+\t\tif (opt->flags & PARSE_OPT_NODASH)\n+\t\t\toff += fprintf(outfile, \"%c\", opt->short_name);\n+\t\telse\n+\t\t\toff += fprintf(outfile, \"-%c\", opt->short_name);\n+\t}\n+\tif (opt->long_name && opt->short_name)\n+\t\toff += fprintf(outfile, \", \");\n+\tif (opt->long_name) {\n+\t\tconst char *long_name = opt->long_name;\n+\t\tif ((opt->flags & PARSE_OPT_NONEG) ||\n+\t\t    skip_prefix(long_name, \"no-\", positive_name))\n+\t\t\toff += fprintf(outfile, \"--%s\", long_name);\n+\t\telse\n+\t\t\toff += fprintf(outfile, \"--[no-]%s\", long_name);\n+\t}\n+\n+\tif (opt->type == OPTION_NUMBER)\n+\t\toff += utf8_fprintf(outfile, _(\"-NUM\"));\n+\n+\tif ((opt->flags & PARSE_OPT_LITERAL_ARGHELP) ||\n+\t    !(opt->flags & PARSE_OPT_NOARG))\n+\t\toff += usage_argh(opt, outfile);\n+\n+\treturn off;\n+}\n+\n+static void usage_print_option(const struct option *opt,\n+\t\t\t       const struct option *all_opts,\n+\t\t\t       int full,\n+\t\t\t       int *need_newline,\n+\t\t\t       FILE *outfile)\n+{\n+\tconst char *positive_name = NULL;\n+\tconst char *cp, *np;\n+\tsize_t pos;\n+\n+\tif (opt->type == OPTION_SUBCOMMAND)\n+\t\treturn;\n+\tif (!full && (opt->flags & PARSE_OPT_HIDDEN))\n+\t\treturn;\n+\tif (opt->type == OPTION_GROUP) {\n+\t\tfputc('\\n', outfile);\n+\t\t*need_newline = 0;\n+\t\tif (*opt->help)\n+\t\t\tfprintf(outfile, \"%s\\n\", _(opt->help));\n+\t\treturn;\n+\t}\n+\n+\tif (*need_newline) {\n+\t\tfputc('\\n', outfile);\n+\t\t*need_newline = 0;\n+\t}\n+\n+\tpos = usage_indent(outfile);\n+\tpos += usage_print_flag(opt, outfile, &positive_name);\n+\n+\tif (opt->type == OPTION_ALIAS) {\n+\t\tusage_padding(outfile, pos);\n+\t\tfprintf_ln(outfile, _(\"alias of --%s\"),\n+\t\t\t   (const char *)opt->value);\n+\t\treturn;\n+\t}\n+\n+\tfor (cp = opt->help ? _(opt->help) : \"\"; *cp; cp = np) {\n+\t\tnp = strchrnul(cp, '\\n');\n+\t\tif (*np)\n+\t\t\tnp++;\n+\t\tusage_padding(outfile, pos);\n+\t\tfwrite(cp, 1, np - cp, outfile);\n+\t\tpos = 0;\n+\t}\n+\tfputc('\\n', outfile);\n+\n+\tif (positive_name) {\n+\t\tif (find_option_by_long_name(all_opts, positive_name))\n+\t\t\treturn;\n+\t\tpos = usage_indent(outfile);\n+\t\tpos += fprintf(outfile, \"--%s\", positive_name);\n+\t\tusage_padding(outfile, pos);\n+\t\tfprintf_ln(outfile, _(\"opposite of --no-%s\"),\n+\t\t\t   positive_name);\n+\t}\n+}\n+\n static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t *ctx,\n \t\t\t\t\t\t\t const char * const *usagestr,\n \t\t\t\t\t\t\t const struct option *opts,\n@@ -1408,81 +1499,9 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t\n \t}\n \n \tneed_newline = 1;\n-\n-\tfor (; opts->type != OPTION_END; opts++) {\n-\t\tsize_t pos;\n-\t\tconst char *cp, *np;\n-\t\tconst char *positive_name = NULL;\n-\n-\t\tif (opts->type == OPTION_SUBCOMMAND)\n-\t\t\tcontinue;\n-\t\tif (!full && (opts->flags & PARSE_OPT_HIDDEN))\n-\t\t\tcontinue;\n-\t\tif (opts->type == OPTION_GROUP) {\n-\t\t\tfputc('\\n', outfile);\n-\t\t\tneed_newline = 0;\n-\t\t\tif (*opts->help)\n-\t\t\t\tfprintf(outfile, \"%s\\n\", _(opts->help));\n-\t\t\tcontinue;\n-\t\t}\n-\n-\t\tif (need_newline) {\n-\t\t\tfputc('\\n', outfile);\n-\t\t\tneed_newline = 0;\n-\t\t}\n-\n-\t\tpos = usage_indent(outfile);\n-\t\tif (opts->short_name) {\n-\t\t\tif (opts->flags & PARSE_OPT_NODASH)\n-\t\t\t\tpos += fprintf(outfile, \"%c\", opts->short_name);\n-\t\t\telse\n-\t\t\t\tpos += fprintf(outfile, \"-%c\", opts->short_name);\n-\t\t}\n-\t\tif (opts->long_name && opts->short_name)\n-\t\t\tpos += fprintf(outfile, \", \");\n-\t\tif (opts->long_name) {\n-\t\t\tconst char *long_name = opts->long_name;\n-\t\t\tif ((opts->flags & PARSE_OPT_NONEG) ||\n-\t\t\t    skip_prefix(long_name, \"no-\", &positive_name))\n-\t\t\t\tpos += fprintf(outfile, \"--%s\", long_name);\n-\t\t\telse\n-\t\t\t\tpos += fprintf(outfile, \"--[no-]%s\", long_name);\n-\t\t}\n-\n-\t\tif (opts->type == OPTION_NUMBER)\n-\t\t\tpos += utf8_fprintf(outfile, _(\"-NUM\"));\n-\n-\t\tif ((opts->flags & PARSE_OPT_LITERAL_ARGHELP) ||\n-\t\t    !(opts->flags & PARSE_OPT_NOARG))\n-\t\t\tpos += usage_argh(opts, outfile);\n-\n-\t\tif (opts->type == OPTION_ALIAS) {\n-\t\t\tusage_padding(outfile, pos);\n-\t\t\tfprintf_ln(outfile, _(\"alias of --%s\"),\n-\t\t\t\t   (const char *)opts->value);\n-\t\t\tcontinue;\n-\t\t}\n-\n-\t\tfor (cp = opts->help ? _(opts->help) : \"\"; *cp; cp = np) {\n-\t\t\tnp = strchrnul(cp, '\\n');\n-\t\t\tif (*np)\n-\t\t\t\tnp++;\n-\t\t\tusage_padding(outfile, pos);\n-\t\t\tfwrite(cp, 1, np - cp, outfile);\n-\t\t\tpos = 0;\n-\t\t}\n-\t\tfputc('\\n', outfile);\n-\n-\t\tif (positive_name) {\n-\t\t\tif (find_option_by_long_name(all_opts, positive_name))\n-\t\t\t\tcontinue;\n-\t\t\tpos = usage_indent(outfile);\n-\t\t\tpos += fprintf(outfile, \"--%s\", positive_name);\n-\t\t\tusage_padding(outfile, pos);\n-\t\t\tfprintf_ln(outfile, _(\"opposite of --no-%s\"),\n-\t\t\t\t   positive_name);\n-\t\t}\n-\t}\n+\tfor (; opts->type != OPTION_END; opts++)\n+\t\tusage_print_option(opts, all_opts, full,\n+\t\t\t\t   &need_newline, outfile);\n \tfputc('\\n', outfile);\n \n \tif (!err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)\n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"},{"id":"553911","messageId":"20261002-b4-pks-parse-options-subcommand-groups-v2-3-3299bee52dea@pks.im","threadId":"66434","inReplyTo":"20261002-b4-pks-parse-options-subcommand-groups-v2-0-3299bee52dea@pks.im","subject":"[PATCH v2 3/4] parse-options: allow grouping subcommands","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T08:09:48Z","receivedAt":"2026-10-02T08:09:58Z","isPatch":true,"body":"The `OPT_GROUP()` macro can be used to create a new group. These groups\ncan only be used to group options though, they do not have any effect\nwhen used in combination with subcommands. As our use of subcommands\ngrows though it can be quite useful to group these, as well.\n\nExtend `OPT_SUBCOMMAND_F()` to take an optional help string. If given,\nsuch subcommands will be considered as part of `OPT_GROUP()` and printed\nwith that help string.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/technical/api-parse-options.adoc |  4 +++-\n builtin/remote.c                               |  2 +-\n builtin/stash.c                                |  2 +-\n parse-options.c                                |  7 +++++--\n parse-options.h                                |  5 +++--\n t/helper/test-parse-options.c                  |  3 ++-\n t/t0040-parse-options.sh                       | 16 ++++++++++++++++\n 7 files changed, 31 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc\nindex 95b7924e84..6dfea34220 100644\n--- a/Documentation/technical/api-parse-options.adoc\n+++ b/Documentation/technical/api-parse-options.adoc\n@@ -243,6 +243,7 @@ with `flags` set to `0`.\n \tStart an option group. `description` is a short string that\n \tdescribes the group or an empty string.\n \tStart the description with an upper-case letter.\n+\tGroups apply to options and subcommands that have a help string.\n \n `OPT_HIDDEN_GROUP(description)`::\n \tLike `OPT_GROUP()`, but the group header carries\n@@ -362,7 +363,8 @@ with `flags` set to `0`.\n \n `OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::\n \tDefine a subcommand.  `subcommand_fn` is put into `fn_ptr` when\n-\tthis subcommand is used.\n+\tthis subcommand is used. The subcommand is not listed in the\n+\tusage output.\n \n The last element of the array must be `OPT_END()`.\n \ndiff --git a/builtin/remote.c b/builtin/remote.c\nindex de989ea3ba..fb7e5b114f 100644\n--- a/builtin/remote.c\n+++ b/builtin/remote.c\n@@ -1940,7 +1940,7 @@ int cmd_remote(int argc,\n \t\tOPT__VERBOSE(&verbose, N_(\"be verbose; must be placed before a subcommand\")),\n \t\tOPT_SUBCOMMAND(\"add\", &fn, add),\n \t\tOPT_SUBCOMMAND(\"rename\", &fn, mv),\n-\t\tOPT_SUBCOMMAND_F(\"rm\", &fn, rm, PARSE_OPT_NOCOMPLETE),\n+\t\tOPT_SUBCOMMAND_F(\"rm\", &fn, rm, NULL, PARSE_OPT_NOCOMPLETE),\n \t\tOPT_SUBCOMMAND(\"remove\", &fn, rm),\n \t\tOPT_SUBCOMMAND(\"set-head\", &fn, set_head),\n \t\tOPT_SUBCOMMAND(\"set-branches\", &fn, set_branches),\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 7a9843413b..8d606ee11d 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -2475,7 +2475,7 @@ int cmd_stash(int argc,\n \t\tOPT_SUBCOMMAND(\"push\", &fn, push_stash_unassumed),\n \t\tOPT_SUBCOMMAND(\"export\", &fn, export_stash),\n \t\tOPT_SUBCOMMAND(\"import\", &fn, import_stash),\n-\t\tOPT_SUBCOMMAND_F(\"save\", &fn, save_stash, PARSE_OPT_NOCOMPLETE),\n+\t\tOPT_SUBCOMMAND_F(\"save\", &fn, save_stash, NULL, PARSE_OPT_NOCOMPLETE),\n \t\tOPT_END()\n \t};\n \tconst char **args_copy;\ndiff --git a/parse-options.c b/parse-options.c\nindex fdcb29f2a1..2b59932d2c 100644\n--- a/parse-options.c\n+++ b/parse-options.c\n@@ -1366,7 +1366,7 @@ static void usage_print_option(const struct option *opt,\n \tconst char *cp, *np;\n \tsize_t pos;\n \n-\tif (opt->type == OPTION_SUBCOMMAND)\n+\tif (opt->type == OPTION_SUBCOMMAND && !opt->help)\n \t\treturn;\n \tif (!full && (opt->flags & PARSE_OPT_HIDDEN))\n \t\treturn;\n@@ -1384,7 +1384,10 @@ static void usage_print_option(const struct option *opt,\n \t}\n \n \tpos = usage_indent(outfile);\n-\tpos += usage_print_flag(opt, outfile, &positive_name);\n+\tif (opt->type == OPTION_SUBCOMMAND)\n+\t\tpos += fprintf(outfile, \"%s\", opt->long_name);\n+\telse\n+\t\tpos += usage_print_flag(opt, outfile, &positive_name);\n \n \tif (opt->type == OPTION_ALIAS) {\n \t\tusage_padding(outfile, pos);\ndiff --git a/parse-options.h b/parse-options.h\nindex d7f896a933..99c12c77cb 100644\n--- a/parse-options.h\n+++ b/parse-options.h\n@@ -393,14 +393,15 @@ static char *parse_options_noop_ignored_value MAYBE_UNUSED;\n \t.value = (char *)(source_long_name), \\\n }\n \n-#define OPT_SUBCOMMAND_F(l, v, fn, f) { \\\n+#define OPT_SUBCOMMAND_F(l, v, fn, h, f) { \\\n \t.type = OPTION_SUBCOMMAND, \\\n \t.long_name = (l), \\\n \t.value = (v), \\\n+\t.help = (h), \\\n \t.flags = (f), \\\n \t.subcommand_fn = (fn), \\\n }\n-#define OPT_SUBCOMMAND(l, v, fn)    OPT_SUBCOMMAND_F((l), (v), (fn), 0)\n+#define OPT_SUBCOMMAND(l, v, fn)    OPT_SUBCOMMAND_F((l), (v), (fn), NULL, 0)\n \n /*\n  * parse_options() will filter out the processed options and leave the\ndiff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c\nindex fbafd67756..950db78673 100644\n--- a/t/helper/test-parse-options.c\n+++ b/t/helper/test-parse-options.c\n@@ -352,8 +352,9 @@ static int parse_subcommand__cmd(int argc, const char **argv,\n \tint opt = 0;\n \tstruct option options[] = {\n \t\tOPT_GROUP(\"Subcommands\"),\n-\t\tOPT_SUBCOMMAND(\"subcmd-one\", &fn, subcmd_one),\n+\t\tOPT_SUBCOMMAND_F(\"subcmd-one\", &fn, subcmd_one, \"the first subcommand\", 0),\n \t\tOPT_SUBCOMMAND(\"subcmd-two\", &fn, subcmd_two),\n+\t\tOPT_GROUP(\"Options\"),\n \t\tOPT_INTEGER('o', \"opt\", &opt, \"an integer option\"),\n \t\tOPT_END()\n \t};\ndiff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh\nindex 449fff4d34..ec55bb1414 100755\n--- a/t/t0040-parse-options.sh\n+++ b/t/t0040-parse-options.sh\n@@ -629,6 +629,22 @@ test_expect_success 'KEEP_UNKNOWN_OPT | NO_INTERNAL_HELP works' '\n \ttest_cmp expect actual\n '\n \n+test_expect_success 'subcommand - usage lists subcommands with help text under their group' '\n+\ttest-tool parse-subcommand cmd -h >actual &&\n+\tcat >expect <<-\\EOF &&\n+\tusage: <...> cmd subcmd-one\n+\t   or: <...> cmd subcmd-two\n+\n+\tSubcommands\n+\t    subcmd-one            the first subcommand\n+\n+\tOptions\n+\t    -o, --[no-]opt <n>    an integer option\n+\n+\tEOF\n+\ttest_cmp expect actual\n+'\n+\n test_expect_success 'subcommand - no subcommand shows error and usage' '\n \ttest_expect_code 129 test-tool parse-subcommand cmd 2>err &&\n \ttest_grep \"^error: need a subcommand\" err &&\n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"},{"id":"553912","messageId":"20261002-b4-pks-parse-options-subcommand-groups-v2-4-3299bee52dea@pks.im","threadId":"66434","inReplyTo":"20261002-b4-pks-parse-options-subcommand-groups-v2-0-3299bee52dea@pks.im","subject":"[PATCH v2 4/4] builtin/refs: introduce subcommand groups","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-02T08:09:49Z","receivedAt":"2026-10-02T08:10:01Z","isPatch":true,"body":"The git-refs(1) command nowadays has a bunch of different subcommands,\nwhich makes it hard to figure out what's what at a glance. Now that the\nparse-options subsystem supports grouping subcommands though we can do\nbetter. The commands roughly fall into the following categories:\n\n  - Operations that span across the whole reference database.\n\n  - Operations that read references.\n\n  - Operations that write references.\n\nIntroduce these groups accordingly, which results in the following help\noutput:\n\n  Reference database\n      migrate               migrate the reference database to a different format\n      verify                verify the consistency of the reference database\n      optimize              optimize the reference database\n\n  Reading references\n      list                  list references\n      exists                check whether a reference exists\n\n  Writing references\n      create                create a new reference\n      delete                delete a reference\n      update                update an existing reference\n      rename                rename a reference\n\nReorder the usage strings to match the new grouping.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/git-refs.adoc |  2 +-\n builtin/refs.c              | 32 ++++++++++++++++++++++----------\n 2 files changed, 23 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 9dc08cbca9..da7260c416 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -11,6 +11,7 @@ SYNOPSIS\n [synopsis]\n git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]\n git refs verify [--strict] [--verbose]\n+git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]\n git refs list [--count=<count>] [--shell|--perl|--python|--tcl]\n \t\t   [(--sort=<key>)...] [--format=<format>]\n \t\t   [--include-root-refs] [--points-at=<object>]\n@@ -19,7 +20,6 @@ git refs list [--count=<count>] [--shell|--perl|--python|--tcl]\n \t\t   [(--exclude=<pattern>)...] [--start-after=<marker>]\n \t\t   [ --stdin | (<pattern>...)]\n git refs exists <ref>\n-git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]\n git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value>\n git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>]\n git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>]\ndiff --git a/builtin/refs.c b/builtin/refs.c\nindex 5cd21c25fe..decccc4364 100644\n--- a/builtin/refs.c\n+++ b/builtin/refs.c\n@@ -382,9 +382,9 @@ int cmd_refs(int argc,\n \tconst char * const refs_usage[] = {\n \t\tREFS_MIGRATE_USAGE,\n \t\tREFS_VERIFY_USAGE,\n+\t\tREFS_OPTIMIZE_USAGE,\n \t\t\"git refs list \" COMMON_USAGE_FOR_EACH_REF,\n \t\tREFS_EXISTS_USAGE,\n-\t\tREFS_OPTIMIZE_USAGE,\n \t\tREFS_CREATE_USAGE,\n \t\tREFS_DELETE_USAGE,\n \t\tREFS_UPDATE_USAGE,\n@@ -393,15 +393,27 @@ int cmd_refs(int argc,\n \t};\n \tparse_opt_subcommand_fn *fn = NULL;\n \tstruct option opts[] = {\n-\t\tOPT_SUBCOMMAND(\"migrate\", &fn, cmd_refs_migrate),\n-\t\tOPT_SUBCOMMAND(\"verify\", &fn, cmd_refs_verify),\n-\t\tOPT_SUBCOMMAND(\"list\", &fn, cmd_refs_list),\n-\t\tOPT_SUBCOMMAND(\"exists\", &fn, cmd_refs_exists),\n-\t\tOPT_SUBCOMMAND(\"optimize\", &fn, cmd_refs_optimize),\n-\t\tOPT_SUBCOMMAND(\"create\", &fn, cmd_refs_create),\n-\t\tOPT_SUBCOMMAND(\"delete\", &fn, cmd_refs_delete),\n-\t\tOPT_SUBCOMMAND(\"update\", &fn, cmd_refs_update),\n-\t\tOPT_SUBCOMMAND(\"rename\", &fn, cmd_refs_rename),\n+\t\tOPT_GROUP(N_(\"Reference database\")),\n+\t\tOPT_SUBCOMMAND_F(\"migrate\", &fn, cmd_refs_migrate,\n+\t\t\t\t N_(\"migrate the reference database to a different format\"), 0),\n+\t\tOPT_SUBCOMMAND_F(\"verify\", &fn, cmd_refs_verify,\n+\t\t\t\t N_(\"verify the consistency of the reference database\"), 0),\n+\t\tOPT_SUBCOMMAND_F(\"optimize\", &fn, cmd_refs_optimize,\n+\t\t\t\t N_(\"optimize the reference database\"), 0),\n+\t\tOPT_GROUP(N_(\"Reading references\")),\n+\t\tOPT_SUBCOMMAND_F(\"list\", &fn, cmd_refs_list,\n+\t\t\t\t N_(\"list references\"), 0),\n+\t\tOPT_SUBCOMMAND_F(\"exists\", &fn, cmd_refs_exists,\n+\t\t\t\t N_(\"check whether a reference exists\"), 0),\n+\t\tOPT_GROUP(N_(\"Writing references\")),\n+\t\tOPT_SUBCOMMAND_F(\"create\", &fn, cmd_refs_create,\n+\t\t\t\t N_(\"create a new reference\"), 0),\n+\t\tOPT_SUBCOMMAND_F(\"delete\", &fn, cmd_refs_delete,\n+\t\t\t\t N_(\"delete a reference\"), 0),\n+\t\tOPT_SUBCOMMAND_F(\"update\", &fn, cmd_refs_update,\n+\t\t\t\t N_(\"update an existing reference\"), 0),\n+\t\tOPT_SUBCOMMAND_F(\"rename\", &fn, cmd_refs_rename,\n+\t\t\t\t N_(\"rename a reference\"), 0),\n \t\tOPT_END(),\n \t};\n \n\n-- \n2.56.0.353.g0856645cf6.dirty\n\n"}]}