[PATCH 3/3] builtin/refs: introduce subcommand groups
flat view
COOLING7d
From: Patrick Steinhardt <hidden>
Date: 2026-10-01 10:13:51
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Revision v1 of 2 in this series.
Revisions (2)
- v1 current
- v2 [diff vs current]
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 <redacted>
---
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=<format> [--no-reflog] [--dry-run] git refs verify [--strict] [--verbose] +git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>] git refs list [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [--include-root-refs] [--points-at=<object>]
@@ -19,7 +20,6 @@ git refs list [--count=<count>] [--shell|--perl|--python|--tcl] [(--exclude=<pattern>)...] [--start-after=<marker>] [ --stdin | (<pattern>...)] git refs exists <ref> -git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>] git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>] git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>]
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