git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH 3/3] builtin/refs: introduce subcommand groups

From
Patrick Steinhardt <ps@pks.im>
Date
Oct 1, 2026, 10:13 UTC
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 <ps@pks.im>
---
 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
Previous: Patrick SteinhardtNext: Junio C Hamano
Message 8 of 14 in “builtin/refs: introduce subcommand groups”
  1. 0/3 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 1, 2026
  2. 1/3 parse-options: fix completion format when first option is skippedPatrick Steinhardt, Oct 1, 2026
  3. Junio C HamanoOct 1, 2026
  4. Patrick SteinhardtOct 2, 2026
  5. 2/3 parse-options: allow grouping subcommandsPatrick Steinhardt, Oct 1, 2026
  6. Junio C HamanoOct 1, 2026
  7. Patrick SteinhardtOct 2, 2026
  8. 3/3 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 1, 2026
  9. Junio C HamanoOct 1, 2026
  10. 0/4 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 2, 2026
  11. 1/4 parse-options: fix completion format when first option is skippedPatrick Steinhardt, Oct 2, 2026
  12. 2/4 parse-options: extract functions to print single optionPatrick Steinhardt, Oct 2, 2026
  13. 3/4 parse-options: allow grouping subcommandsPatrick Steinhardt, Oct 2, 2026
  14. 4/4 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 2, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.