From: Patrick Steinhardt Date: Fri, 02 Oct 2026 08:09:49 GMT Subject: [PATCH v2 4/4] builtin/refs: introduce subcommand groups Message-ID: <20261002-b4-pks-parse-options-subcommand-groups-v2-4-3299bee52dea@pks.im> In-Reply-To: <20261002-b4-pks-parse-options-subcommand-groups-v2-0-3299bee52dea@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..decccc4364 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_F("migrate", &fn, cmd_refs_migrate, + N_("migrate the reference database to a different format"), 0), + OPT_SUBCOMMAND_F("verify", &fn, cmd_refs_verify, + N_("verify the consistency of the reference database"), 0), + OPT_SUBCOMMAND_F("optimize", &fn, cmd_refs_optimize, + N_("optimize the reference database"), 0), + OPT_GROUP(N_("Reading references")), + OPT_SUBCOMMAND_F("list", &fn, cmd_refs_list, + N_("list references"), 0), + OPT_SUBCOMMAND_F("exists", &fn, cmd_refs_exists, + N_("check whether a reference exists"), 0), + OPT_GROUP(N_("Writing references")), + OPT_SUBCOMMAND_F("create", &fn, cmd_refs_create, + N_("create a new reference"), 0), + OPT_SUBCOMMAND_F("delete", &fn, cmd_refs_delete, + N_("delete a reference"), 0), + OPT_SUBCOMMAND_F("update", &fn, cmd_refs_update, + N_("update an existing reference"), 0), + OPT_SUBCOMMAND_F("rename", &fn, cmd_refs_rename, + N_("rename a reference"), 0), OPT_END(), }; -- 2.56.0.353.g0856645cf6.dirty