From: Patrick Steinhardt Date: Thu, 01 Oct 2026 10:13:30 GMT Subject: [PATCH 3/3] builtin/refs: introduce subcommand groups Message-ID: <20261001-b4-pks-parse-options-subcommand-groups-v1-3-01eb2f4a4c32@pks.im> In-Reply-To: <20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im> The git-refs(1) command nowadays has a bunch of different subcommands, which makes it hard to figure out what's what at a glance. Now that the parse-options subsystem supports grouping subcommands though we can do better. The commands roughly fall into the following categories: - Operations that span across the whole reference database. - Operations that read references. - Operations that write references. Introduce these groups accordingly, which results in the following help output: Reference database migrate migrate the reference database to a different format verify verify the consistency of the reference database optimize optimize the reference database Reading references list list references exists check whether a reference exists Writing references create create a new reference delete delete a reference update update an existing reference rename rename a reference Reorder the usage strings to match the new grouping. Signed-off-by: Patrick Steinhardt --- Documentation/git-refs.adoc | 2 +- builtin/refs.c | 32 ++++++++++++++++++++++---------- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc index 9dc08cbca9..da7260c416 100644 --- a/Documentation/git-refs.adoc +++ b/Documentation/git-refs.adoc @@ -11,6 +11,7 @@ SYNOPSIS [synopsis] git refs migrate --ref-format= [--no-reflog] [--dry-run] git refs verify [--strict] [--verbose] +git refs optimize [--all] [--no-prune] [--auto] [--include ] [--exclude ] git refs list [--count=] [--shell|--perl|--python|--tcl] [(--sort=)...] [--format=] [--include-root-refs] [--points-at=] @@ -19,7 +20,6 @@ git refs list [--count=] [--shell|--perl|--python|--tcl] [(--exclude=)...] [--start-after=] [ --stdin | (...)] git refs exists -git refs optimize [--all] [--no-prune] [--auto] [--include ] [--exclude ] git refs create [--message=] [--no-deref] [--create-reflog] git refs delete [--message=] [--no-deref] [] git refs update [--message=] [--no-deref] [--create-reflog] [] diff --git a/builtin/refs.c b/builtin/refs.c index 5cd21c25fe..f46abd6268 100644 --- a/builtin/refs.c +++ b/builtin/refs.c @@ -382,9 +382,9 @@ int cmd_refs(int argc, const char * const refs_usage[] = { REFS_MIGRATE_USAGE, REFS_VERIFY_USAGE, + REFS_OPTIMIZE_USAGE, "git refs list " COMMON_USAGE_FOR_EACH_REF, REFS_EXISTS_USAGE, - REFS_OPTIMIZE_USAGE, REFS_CREATE_USAGE, REFS_DELETE_USAGE, REFS_UPDATE_USAGE, @@ -393,15 +393,27 @@ int cmd_refs(int argc, }; parse_opt_subcommand_fn *fn = NULL; struct option opts[] = { - OPT_SUBCOMMAND("migrate", &fn, cmd_refs_migrate), - OPT_SUBCOMMAND("verify", &fn, cmd_refs_verify), - OPT_SUBCOMMAND("list", &fn, cmd_refs_list), - OPT_SUBCOMMAND("exists", &fn, cmd_refs_exists), - OPT_SUBCOMMAND("optimize", &fn, cmd_refs_optimize), - OPT_SUBCOMMAND("create", &fn, cmd_refs_create), - OPT_SUBCOMMAND("delete", &fn, cmd_refs_delete), - OPT_SUBCOMMAND("update", &fn, cmd_refs_update), - OPT_SUBCOMMAND("rename", &fn, cmd_refs_rename), + OPT_GROUP(N_("Reference database")), + OPT_SUBCOMMAND_H("migrate", &fn, cmd_refs_migrate, + N_("migrate the reference database to a different format")), + OPT_SUBCOMMAND_H("verify", &fn, cmd_refs_verify, + N_("verify the consistency of the reference database")), + OPT_SUBCOMMAND_H("optimize", &fn, cmd_refs_optimize, + N_("optimize the reference database")), + OPT_GROUP(N_("Reading references")), + OPT_SUBCOMMAND_H("list", &fn, cmd_refs_list, + N_("list references")), + OPT_SUBCOMMAND_H("exists", &fn, cmd_refs_exists, + N_("check whether a reference exists")), + OPT_GROUP(N_("Writing references")), + OPT_SUBCOMMAND_H("create", &fn, cmd_refs_create, + N_("create a new reference")), + OPT_SUBCOMMAND_H("delete", &fn, cmd_refs_delete, + N_("delete a reference")), + OPT_SUBCOMMAND_H("update", &fn, cmd_refs_update, + N_("update an existing reference")), + OPT_SUBCOMMAND_H("rename", &fn, cmd_refs_rename, + N_("rename a reference")), OPT_END(), }; -- 2.56.0.353.g0856645cf6.dirty