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

[PATCH v2 03/11] builtin/refs: rename "--ref-format=" to "--ref-storage-format="

From
Patrick Steinhardt <ps@pks.im>
Date
Sep 7, 2026, 11:18 UTC
Message-ID
<20260907-b4-pks-unify-ref-storage-format-v2-3-6733c90ca5b0@pks.im>
In-Reply-To
<20260907-b4-pks-unify-ref-storage-format-v2-0-6733c90ca5b0@pks.im>

With the same reasoning as for git-init(1), rename "--ref-format=" to "--ref-storage-format=" and keep the old name as an alias.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-refs.adoc            |  6 +++---
 builtin/fetch.c                        |  2 +-
 builtin/refs.c                         | 11 +++++++----
 t/t1423-ref-backend.sh                 |  8 ++++----
 t/t1460-refs-migrate.sh                | 12 ++++++------
 t/t7424-submodule-mixed-ref-formats.sh |  2 +-
 6 files changed, 22 insertions(+), 19 deletions(-)
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 9063892651..09e9bde939 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -9,7 +9,7 @@ git-refs - Low-level access to refs
 SYNOPSIS
 --------
 [synopsis]
-git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
+git refs migrate --ref-storage-format=<format> [--no-reflog] [--dry-run]
 git refs verify [--strict] [--verbose]
 git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
 		   [(--sort=<key>)...] [--format=<format>]
@@ -97,8 +97,8 @@ OPTIONS
 
 The following options are specific to `git refs migrate`:
 
-`--ref-format=<format>`::
-	The ref format to migrate the ref store to. Can be one of:
+`--ref-storage-format=<format>`::
+	The ref storage format to migrate the ref store to. Can be one of:
 +
 include::ref-storage-format.adoc[]
 
diff --git a/builtin/fetch.c b/builtin/fetch.c
index ab7db2be06..687909c0c4 100644
--- a/builtin/fetch.c
+++ b/builtin/fetch.c
@@ -1848,7 +1848,7 @@ static void ref_transaction_rejection_handler(const char *refname,
 			"can either accept this as-is, in which case you won't be able to\n"
 			"store all remote references on disk. Or you can alternatively\n"
 			"migrate your repository to use the 'reftable' backend with the\n"
-			"following command:\n\n    git refs migrate --ref-format=reftable\n\n"
+			"following command:\n\n    git refs migrate --ref-storage-format=reftable\n\n"
 			"Please keep in mind that not all implementations of Git support this\n"
 			"new format yet. So if you use tools other than Git to access this\n"
 			"repository it may not be an option to migrate to reftables.\n"));
diff --git a/builtin/refs.c b/builtin/refs.c
index 5cd21c25fe..53b12accaf 100644
--- a/builtin/refs.c
+++ b/builtin/refs.c
@@ -10,7 +10,7 @@
 #include "refs/refs-internal.h"
 
 #define REFS_MIGRATE_USAGE \
-	N_("git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]")
+	N_("git refs migrate --ref-storage-format=<format> [--no-reflog] [--dry-run]")
 
 #define REFS_VERIFY_USAGE \
 	N_("git refs verify [--strict] [--verbose]")
@@ -44,9 +44,12 @@ static int cmd_refs_migrate(int argc, const char **argv, const char *prefix,
 	enum ref_storage_format format;
 	unsigned int flags = 0;
 	struct option options[] = {
-		OPT_STRING_F(0, "ref-format", &format_str, N_("format"),
-			N_("specify the reference format to convert to"),
+		OPT_STRING_F(0, "ref-storage-format", &format_str, N_("format"),
+			N_("specify the reference storage format to convert to"),
 			PARSE_OPT_NONEG),
+		OPT_STRING_F(0, "ref-format", &format_str, N_("format"),
+			N_("specify the reference storage format to convert to"),
+			PARSE_OPT_NONEG | PARSE_OPT_HIDDEN),
 		OPT_BIT(0, "dry-run", &flags,
 			N_("perform a non-destructive dry-run"),
 			REPO_MIGRATE_REF_STORAGE_FORMAT_DRYRUN),
@@ -62,7 +65,7 @@ static int cmd_refs_migrate(int argc, const char **argv, const char *prefix,
 	if (argc)
 		usage(_("too many arguments"));
 	if (!format_str)
-		usage(_("missing --ref-format=<format>"));
+		usage(_("missing --ref-storage-format=<format>"));
 
 	format = ref_storage_format_by_name(format_str);
 	if (format == REF_STORAGE_FORMAT_UNKNOWN) {
diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh
index 9ae295cf3d..ab119a6568 100755
--- a/t/t1423-ref-backend.sh
+++ b/t/t1423-ref-backend.sh
@@ -144,7 +144,7 @@ do
 				test_commit 2 &&
 				test_commit 3 &&
 
-				git refs migrate --dry-run --ref-format=$to_format >out &&
+				git refs migrate --dry-run --ref-storage-format=$to_format >out &&
 				BACKEND_PATH="$dir/$(sed "s/.* ${SQ}.git\/\(.*\)${SQ}/\1/" out)" &&
 				test_refs_backend . $from_format "$to_format://$BACKEND_PATH" "$method"
 			)
@@ -159,7 +159,7 @@ do
 				test_commit 2 &&
 				test_commit 3 &&
 
-				git refs migrate --dry-run --ref-format=$to_format >out &&
+				git refs migrate --dry-run --ref-storage-format=$to_format >out &&
 				BACKEND_PATH="$dir/$(sed "s/.* ${SQ}.git\/\(.*\)${SQ}/\1/" out)" &&
 
 				test_refs_backend . $from_format "$to_format://$BACKEND_PATH" "$method" &&
@@ -186,7 +186,7 @@ do
 				test_commit 2 &&
 				test_commit 3 &&
 
-				git refs migrate --dry-run --ref-format=$to_format >out &&
+				git refs migrate --dry-run --ref-storage-format=$to_format >out &&
 				BACKEND_PATH="$dir/$(sed "s/.* ${SQ}.git\/\(.*\)${SQ}/\1/" out)" &&
 
 				run_with_uri . "$from_format" "$to_format://$BACKEND_PATH" \
@@ -218,7 +218,7 @@ do
 			test_commit 2 &&
 			test_commit 3 &&
 
-			git refs migrate --ref-format=$to_format &&
+			git refs migrate --ref-storage-format=$to_format &&
 			git refs list >out &&
 			test_grep "refs/tags/1"	out &&
 			test_grep "refs/tags/2"	out &&
diff --git a/t/t1460-refs-migrate.sh b/t/t1460-refs-migrate.sh
index 8aded6597e..204dd79b41 100755
--- a/t/t1460-refs-migrate.sh
+++ b/t/t1460-refs-migrate.sh
@@ -42,7 +42,7 @@ test_migration () {
 		print_all_reflog_entries "$repo" >expect_logs
 	fi &&
 
-	git -C "$repo" refs migrate --ref-format="$format" "$@" &&
+	git -C "$repo" refs migrate --ref-storage-format="$format" "$@" &&
 
 	git -C "$repo" for-each-ref --include-root-refs \
 		--format='%(refname) %(objectname) %(symref)' >actual &&
@@ -77,7 +77,7 @@ test_expect_success "missing ref storage format" '
 	git init repo &&
 	test_must_fail git -C repo refs migrate 2>err &&
 	cat >expect <<-EOF &&
-	usage: missing --ref-format=<format>
+	usage: missing --ref-storage-format=<format>
 	EOF
 	test_cmp expect err
 '
@@ -86,7 +86,7 @@ test_expect_success "unknown ref storage format" '
 	test_when_finished "rm -rf repo" &&
 	git init repo &&
 	test_must_fail git -C repo refs migrate \
-		--ref-format=unknown 2>err &&
+		--ref-storage-format=unknown 2>err &&
 	cat >expect <<-EOF &&
 	error: unknown ref storage format ${SQ}unknown${SQ}
 	EOF
@@ -107,7 +107,7 @@ do
 			test_when_finished "rm -rf repo" &&
 			git init --ref-storage-format=$from_format repo &&
 			test_must_fail git -C repo refs migrate \
-				--ref-format=$from_format 2>err &&
+				--ref-storage-format=$from_format 2>err &&
 			cat >expect <<-EOF &&
 			error: repository already uses ${SQ}$from_format${SQ} format
 			EOF
@@ -119,7 +119,7 @@ do
 			git init --ref-storage-format=$from_format repo &&
 			git -C repo worktree add wt &&
 			test_must_fail git -C repo refs migrate \
-				--ref-format=$to_format 2>err &&
+				--ref-storage-format=$to_format 2>err &&
 			cat >expect <<-EOF &&
 			error: migrating repositories with worktrees is not supported yet
 			EOF
@@ -211,7 +211,7 @@ do
 			git init --ref-storage-format=$from_format repo &&
 			test_commit -C repo initial &&
 			git -C repo refs migrate --dry-run \
-				--ref-format=$to_format >output &&
+				--ref-storage-format=$to_format >output &&
 			test_grep "Finished dry-run migration of refs" output &&
 			test_path_is_dir repo/.git/ref_migration.* &&
 			echo $from_format >expect &&
diff --git a/t/t7424-submodule-mixed-ref-formats.sh b/t/t7424-submodule-mixed-ref-formats.sh
index 5eaf689d74..9081401509 100755
--- a/t/t7424-submodule-mixed-ref-formats.sh
+++ b/t/t7424-submodule-mixed-ref-formats.sh
@@ -94,7 +94,7 @@ test_expect_success 'status with mixed submodule ref storages' '
 	git init main &&
 	git -C main submodule add "file://$(pwd)/submodule" &&
 	git -C main commit -m "add submodule" &&
-	git -C main/submodule refs migrate --ref-format=$OTHER_FORMAT &&
+	git -C main/submodule refs migrate --ref-storage-format=$OTHER_FORMAT &&
 
 	# The main repository should use the default ref format now, whereas
 	# the submodule should use the other format.
-- 
2.55.0.1007.g17ff1f9808.dirty
Previous: Patrick SteinhardtNext: Kaartic Sivaraam
Message 9 of 27 in “Fix inconsistent ref storage format terminology”
  1. 00/11 Fix inconsistent ref storage format terminologyPatrick Steinhardt, Sep 7, 2026
  2. 01/11 builtin/init: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 7, 2026
  3. Kaartic SivaraamSep 8, 2026
  4. Patrick SteinhardtSep 9, 2026
  5. Kaartic SivaraamSep 9, 2026
  6. 02/11 builtin/clone: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 7, 2026
  7. Kaartic SivaraamSep 8, 2026
  8. Patrick SteinhardtSep 9, 2026
  9. 03/11 builtin/refs: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 7, 2026
  10. Kaartic SivaraamSep 8, 2026
  11. Patrick SteinhardtSep 9, 2026
  12. 04/11 builtin/submodule: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 7, 2026
  13. 05/11 builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage-format"Patrick Steinhardt, Sep 7, 2026
  14. 06/11 help: rename "default-ref-format" to "default-ref-storage-format"Patrick Steinhardt, Sep 7, 2026
  15. 07/11 refs: expose function to parse reference URIsPatrick Steinhardt, Sep 7, 2026
  16. Kaartic SivaraamSep 8, 2026
  17. Patrick SteinhardtSep 9, 2026
  18. 08/11 setup: refactor how we configure the ref storage formatPatrick Steinhardt, Sep 7, 2026
  19. Kaartic SivaraamSep 9, 2026
  20. Patrick SteinhardtSep 9, 2026
  21. 09/11 setup: rename ref storage format environment variablesPatrick Steinhardt, Sep 7, 2026
  22. Kaartic SivaraamSep 9, 2026
  23. Patrick SteinhardtSep 9, 2026
  24. 10/11 setup: rename "init.defaultRefFormat" to "init.defaultRefStorageFormat"Patrick Steinhardt, Sep 7, 2026
  25. 11/11 setup: allow "git init --ref-storage-format=" to specify a payloadPatrick Steinhardt, Sep 7, 2026
  26. Kaartic SivaraamSep 9, 2026
  27. Patrick SteinhardtSep 9, 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.