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

[PATCH 02/11] builtin/clone: rename "--ref-format=" to "--ref-storage="

From
Patrick Steinhardt <ps@pks.im>
Date
Sep 4, 2026, 10:36 UTC
Message-ID
<20260904-b4-pks-unify-ref-storage-format-v1-2-08144e5004ff@pks.im>
In-Reply-To
<20260904-b4-pks-unify-ref-storage-format-v1-0-08144e5004ff@pks.im>

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

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-clone.adoc           |  2 +-
 builtin/clone.c                        | 14 ++++++++------
 t/t0610-reftable-basics.sh             |  4 ++--
 t/t1460-refs-migrate.sh                |  2 +-
 t/t5510-fetch.sh                       |  6 +++---
 t/t5601-clone.sh                       |  4 ++--
 t/t7424-submodule-mixed-ref-formats.sh |  4 ++--
 7 files changed, 19 insertions(+), 17 deletions(-)
diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc
index b6e1f8ada2..57e2bda044 100644
--- a/Documentation/git-clone.adoc
+++ b/Documentation/git-clone.adoc
@@ -348,7 +348,7 @@ or `--mirror` is given)
 	The result is Git repository can be separated from working
 	tree.
 
-`--ref-format=<ref-format>`::
+`--ref-storage=<ref-format>`::
 
 Specify the given ref storage format for the repository. The valid values are:
 +
diff --git a/builtin/clone.c b/builtin/clone.c
index 5b25cca510..63bd7b795d 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -901,7 +901,7 @@ int cmd_clone(int argc,
 	char *option_origin = NULL;
 	struct string_list option_not = STRING_LIST_INIT_NODUP;
 	const char *real_git_dir = NULL;
-	const char *ref_format = NULL;
+	const char *ref_storage = NULL;
 	const char *option_upload_pack = "git-upload-pack";
 	int option_progress = -1;
 	int option_sparse_checkout = 0;
@@ -981,8 +981,10 @@ int cmd_clone(int argc,
 			 N_("any cloned submodules will be shallow")),
 		OPT_STRING(0, "separate-git-dir", &real_git_dir, N_("gitdir"),
 			   N_("separate git dir from working tree")),
-		OPT_STRING(0, "ref-format", &ref_format, N_("format"),
-			   N_("specify the reference format to use")),
+		OPT_STRING(0, "ref-storage", &ref_storage, N_("format"),
+			   N_("specify the reference storage format to use")),
+		OPT_STRING_F(0, "ref-format", &ref_storage, N_("format"),
+			   N_("specify the reference storage format to use"), PARSE_OPT_HIDDEN),
 		OPT_STRING_LIST('c', "config", &option_config, N_("key=value"),
 				N_("set config inside the new repository")),
 		OPT_STRING_LIST(0, "server-option", &server_options,
@@ -1027,10 +1029,10 @@ int cmd_clone(int argc,
 	if (option_single_branch == -1)
 		option_single_branch = deepen ? 1 : 0;
 
-	if (ref_format) {
-		ref_storage_format = ref_storage_format_by_name(ref_format);
+	if (ref_storage) {
+		ref_storage_format = ref_storage_format_by_name(ref_storage);
 		if (ref_storage_format == REF_STORAGE_FORMAT_UNKNOWN)
-			die(_("unknown ref storage format '%s'"), ref_format);
+			die(_("unknown ref storage format '%s'"), ref_storage);
 	}
 
 	if (option_mirror) {
diff --git a/t/t0610-reftable-basics.sh b/t/t0610-reftable-basics.sh
index 4a83e1ce56..d367b4b787 100755
--- a/t/t0610-reftable-basics.sh
+++ b/t/t0610-reftable-basics.sh
@@ -165,7 +165,7 @@ test_expect_success 'clone: can clone reffiles into reftable repository' '
 	test_when_finished "rm -rf reffiles reftable" &&
 	git init --ref-storage=files reffiles &&
 	test_commit -C reffiles A &&
-	git clone --ref-format=reftable ./reffiles reftable &&
+	git clone --ref-storage=reftable ./reffiles reftable &&
 
 	git -C reffiles rev-parse HEAD >expect &&
 	git -C reftable rev-parse HEAD >actual &&
@@ -184,7 +184,7 @@ test_expect_success 'clone: can clone reftable into reffiles repository' '
 	test_when_finished "rm -rf reffiles reftable" &&
 	git init --ref-storage=reftable reftable &&
 	test_commit -C reftable A &&
-	git clone --ref-format=files ./reftable reffiles &&
+	git clone --ref-storage=files ./reftable reffiles &&
 
 	git -C reftable rev-parse HEAD >expect &&
 	git -C reffiles rev-parse HEAD >actual &&
diff --git a/t/t1460-refs-migrate.sh b/t/t1460-refs-migrate.sh
index fc04bb7c70..44ad24f16e 100755
--- a/t/t1460-refs-migrate.sh
+++ b/t/t1460-refs-migrate.sh
@@ -143,7 +143,7 @@ do
 			test_when_finished "rm -rf repo repo.git" &&
 			git init --ref-storage=$from_format repo &&
 			test_commit -C repo initial &&
-			git clone --ref-format=$from_format --mirror repo repo.git &&
+			git clone --ref-storage=$from_format --mirror repo repo.git &&
 			test_migration repo.git "$to_format"
 		'
 
diff --git a/t/t5510-fetch.sh b/t/t5510-fetch.sh
index 1b239f4f22..720157e6c5 100755
--- a/t/t5510-fetch.sh
+++ b/t/t5510-fetch.sh
@@ -46,19 +46,19 @@ test_expect_success "clone and setup child repos" '
 	) &&
 	git clone . bundle &&
 	git clone . seven &&
-	git clone --ref-format=reftable . case_sensitive &&
+	git clone --ref-storage=reftable . case_sensitive &&
 	(
 		cd case_sensitive &&
 		git branch branch1 &&
 		git branch bRanch1
 	) &&
-	git clone --ref-format=reftable . case_sensitive_fd &&
+	git clone --ref-storage=reftable . case_sensitive_fd &&
 	(
 		cd case_sensitive_fd &&
 		git branch foo/bar &&
 		git branch Foo
 	) &&
-	git clone --ref-format=reftable . case_sensitive_df &&
+	git clone --ref-storage=reftable . case_sensitive_df &&
 	(
 		cd case_sensitive_df &&
 		git branch Foo/bar &&
diff --git a/t/t5601-clone.sh b/t/t5601-clone.sh
index b6167582a1..88f359914f 100755
--- a/t/t5601-clone.sh
+++ b/t/t5601-clone.sh
@@ -166,7 +166,7 @@ test_expect_success 'clone --mirror does not repeat tags' '
 
 test_expect_success 'clone with files ref format' '
 	test_when_finished "rm -rf ref-storage" &&
-	git clone --ref-format=files --mirror src ref-storage &&
+	git clone --ref-storage=files --mirror src ref-storage &&
 	echo files >expect &&
 	git -C ref-storage rev-parse --show-ref-format >actual &&
 	test_cmp expect actual
@@ -176,7 +176,7 @@ test_expect_success 'clone with garbage ref format' '
 	cat >expect <<-EOF &&
 	fatal: unknown ref storage format ${SQ}garbage${SQ}
 	EOF
-	test_must_fail git clone --ref-format=garbage --mirror src ref-storage 2>err &&
+	test_must_fail git clone --ref-storage=garbage --mirror src ref-storage 2>err &&
 	test_cmp expect err &&
 	test_path_is_missing ref-storage
 '
diff --git a/t/t7424-submodule-mixed-ref-formats.sh b/t/t7424-submodule-mixed-ref-formats.sh
index d6ea84bb90..1adac7baed 100755
--- a/t/t7424-submodule-mixed-ref-formats.sh
+++ b/t/t7424-submodule-mixed-ref-formats.sh
@@ -63,9 +63,9 @@ test_expect_success 'recursive clone propagates ref storage format' '
 	test_ref_format upstream/submodule "$GIT_DEFAULT_REF_FORMAT" &&
 
 	# The cloned repositories should use the other ref format that we have
-	# specified via `--ref-format`. The option should propagate to cloned
+	# specified via `--ref-storage`. The option should propagate to cloned
 	# submodules.
-	git clone --ref-format=$OTHER_FORMAT --recurse-submodules \
+	git clone --ref-storage=$OTHER_FORMAT --recurse-submodules \
 		upstream downstream &&
 	test_ref_format downstream "$OTHER_FORMAT" &&
 	test_ref_format downstream/submodule "$OTHER_FORMAT"
-- 
2.55.0.1007.g17ff1f9808.dirty
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 5 of 20 in “Fix inconsistent ref storage format terminology”
  1. 00/11 Fix inconsistent ref storage format terminologyPatrick Steinhardt, Sep 4, 2026
  2. 01/11 builtin/init: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  3. Karthik NayakSep 4, 2026
  4. Patrick SteinhardtSep 7, 2026
  5. 02/11 builtin/clone: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  6. 03/11 builtin/refs: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  7. 04/11 builtin/submodule: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  8. 05/11 builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage"Patrick Steinhardt, Sep 4, 2026
  9. 06/11 help: rename "default-ref-format" to "default-ref-storage"Patrick Steinhardt, Sep 4, 2026
  10. 07/11 refs: expose function to parse reference URIsPatrick Steinhardt, Sep 4, 2026
  11. Karthik NayakSep 4, 2026
  12. 08/11 setup: refactor how we configure the ref storage formatPatrick Steinhardt, Sep 4, 2026
  13. 09/11 setup: rename ref storage format environment variablesPatrick Steinhardt, Sep 4, 2026
  14. Karthik NayakSep 4, 2026
  15. Patrick SteinhardtSep 7, 2026
  16. 10/11 setup: rename "init.defaultRefFormat" to "init.defaultRefStorage"Patrick Steinhardt, Sep 4, 2026
  17. 11/11 setup: allow "git init --ref-storage=" to specify a payloadPatrick Steinhardt, Sep 4, 2026
  18. Karthik NayakSep 4, 2026
  19. Junio C HamanoSep 4, 2026
  20. Patrick SteinhardtSep 7, 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.