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

[PATCH v3 05/13] builtin/submodule: rename "--ref-format=" to "--ref-storage-format="

From
Patrick Steinhardt <ps@pks.im>
Date
Sep 9, 2026, 11:12 UTC
Message-ID
<20260909-b4-pks-unify-ref-storage-format-v3-5-ca041fb40ad8@pks.im>
In-Reply-To
<20260909-b4-pks-unify-ref-storage-format-v3-0-ca041fb40ad8@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.

Note that this commit is a bit more complex compared to the others as we also need to adapt the submodule helper for consistency. But overall, the changes are straight-forward and in the same spirit.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-submodule.adoc       | 14 ++++++++------
 builtin/clone.c                        |  2 +-
 builtin/submodule--helper.c            | 21 ++++++++++++---------
 git-submodule.sh                       | 20 ++++++++++----------
 t/t7424-submodule-mixed-ref-formats.sh |  6 +++---
 5 files changed, 34 insertions(+), 29 deletions(-)
diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
index 722d827908..e9c81a7170 100644
--- a/Documentation/git-submodule.adoc
+++ b/Documentation/git-submodule.adoc
@@ -34,7 +34,7 @@ COMMANDS
 With no arguments, shows the status of existing submodules.  Several
 subcommands are available to perform operations on the submodules.
 
-`add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]`::
+`add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--ref-storage-format <format>] [--depth <depth>] [--] <repository> [<path>]`::
 	Add the given repository as a submodule at the given path
 	to the changeset to be committed next to the current
 	project: the current project is termed the "superproject".
@@ -72,8 +72,9 @@ location, and only the superproject's URL needs to be provided.
 git-submodule will correctly locate the submodule using the relative
 URL in `.gitmodules`.
 +
-If `--ref-format <format>`  is specified, the ref storage format of newly
-cloned submodules will be set accordingly.
+If `--ref-storage-format <format>` or its deprecated alias `--ref-format
+<format>` is specified, the ref storage format of the newly cloned submodules
+will be set accordingly.
 
 `status [--cached] [--recursive] [--] [<path>...]`::
 	Show the status of the submodules. This will print the SHA-1 of the
@@ -139,7 +140,7 @@ If you really want to remove a submodule from the repository and commit
 that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal
 options.
 
-`update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<repository>] [--ref-format=<format>] [--depth=<depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter=<filter-spec>] [--] [<path>...]`::
+`update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<repository>] [--ref-storage-format=<format>] [--depth=<depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter=<filter-spec>] [--] [<path>...]`::
 +
 --
 Update the registered submodules to match what the superproject
@@ -188,8 +189,9 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 
-If `--ref-format <format>`  is specified, the ref storage format of newly
-cloned submodules will be set accordingly.
+If `--ref-storage-format <format>` or its deprecated alias `--ref-format
+<format>` is specified, the ref storage format of the newly cloned submodules
+will be set accordingly.
 
 If `--filter <filter-spec>` is specified, the given partial clone filter will be
 applied to the submodule. See linkgit:git-rev-list[1] for details on filter
diff --git a/builtin/clone.c b/builtin/clone.c
index 42cae9e0f6..dd722e4de1 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -725,7 +725,7 @@ static int checkout(int submodule_progress,
 		}
 
 		if (ref_storage_format != REF_STORAGE_FORMAT_UNKNOWN)
-			strvec_pushf(&cmd.args, "--ref-format=%s",
+			strvec_pushf(&cmd.args, "--ref-storage-format=%s",
 				     ref_storage_format_to_name(ref_storage_format));
 
 		if (filter_submodules && filter_options->choice)
diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
index e7cd3225fa..41883af2ac 100644
--- a/builtin/submodule--helper.c
+++ b/builtin/submodule--helper.c
@@ -1941,7 +1941,7 @@ static int clone_submodule(const struct module_clone_data *clone_data,
 					     item->string, NULL);
 		}
 		if (clone_data->ref_storage_format != REF_STORAGE_FORMAT_UNKNOWN)
-			strvec_pushf(&cp.args, "--ref-format=%s",
+			strvec_pushf(&cp.args, "--ref-storage-format=%s",
 				     ref_storage_format_to_name(clone_data->ref_storage_format));
 		if (clone_data->dissociate)
 			strvec_push(&cp.args, "--dissociate");
@@ -2057,8 +2057,9 @@ static int module_clone(int argc, const char **argv, const char *prefix,
 		OPT_STRING_LIST(0, "reference", &reference,
 			   N_("repo"),
 			   N_("reference repository")),
-		OPT_STRING(0, "ref-format", &ref_storage_format, N_("format"),
-			   N_("specify the reference format to use")),
+		OPT_STRING(0, "ref-storage-format", &ref_storage_format, N_("format"),
+			   N_("specify the reference storage format to use")),
+		OPT_ALIAS_F(0, "ref-format", "ref-storage-format", PARSE_OPT_HIDDEN),
 		OPT_BOOL(0, "dissociate", &dissociate,
 			   N_("use --reference only while cloning")),
 		OPT_INTEGER(0, "depth", &clone_data.depth,
@@ -2357,7 +2358,7 @@ static int prepare_to_clone_next_submodule(const struct cache_entry *ce,
 	if (suc->update_data->require_init)
 		strvec_push(&child->args, "--require-init");
 	if (suc->update_data->ref_storage_format != REF_STORAGE_FORMAT_UNKNOWN)
-		strvec_pushf(&child->args, "--ref-format=%s",
+		strvec_pushf(&child->args, "--ref-storage-format=%s",
 			     ref_storage_format_to_name(suc->update_data->ref_storage_format));
 	strvec_pushl(&child->args, "--path", sub->path, NULL);
 	strvec_pushl(&child->args, "--name", sub->name, NULL);
@@ -2801,7 +2802,7 @@ static void update_data_to_args(const struct update_data *update_data,
 			strvec_pushl(args, "--reference", item->string, NULL);
 	}
 	if (update_data->ref_storage_format != REF_STORAGE_FORMAT_UNKNOWN)
-		strvec_pushf(args, "--ref-format=%s",
+		strvec_pushf(args, "--ref-storage-format=%s",
 			     ref_storage_format_to_name(update_data->ref_storage_format));
 	if (update_data->filter_options && update_data->filter_options->choice)
 		strvec_pushf(args, "--filter=%s",
@@ -3010,8 +3011,9 @@ static int module_update(int argc, const char **argv, const char *prefix,
 			SM_UPDATE_REBASE),
 		OPT_STRING_LIST(0, "reference", &opt.references, N_("repo"),
 			   N_("reference repository")),
-		OPT_STRING(0, "ref-format", &ref_storage_format, N_("format"),
-			   N_("specify the reference format to use")),
+		OPT_STRING(0, "ref-storage-format", &ref_storage_format, N_("format"),
+			   N_("specify the reference storage format to use")),
+		OPT_ALIAS_F(0, "ref-format", "ref-storage-format", PARSE_OPT_HIDDEN),
 		OPT_BOOL(0, "dissociate", &opt.dissociate,
 			   N_("use --reference only while cloning")),
 		OPT_INTEGER(0, "depth", &opt.depth,
@@ -3659,8 +3661,9 @@ static int module_add(int argc, const char **argv, const char *prefix,
 		OPT_BOOL(0, "progress", &progress, N_("force cloning progress")),
 		OPT_STRING(0, "reference", &add_data.reference_path, N_("repository"),
 			   N_("reference repository")),
-		OPT_STRING(0, "ref-format", &ref_storage_format, N_("format"),
-			   N_("specify the reference format to use")),
+		OPT_STRING(0, "ref-storage-format", &ref_storage_format, N_("format"),
+			   N_("specify the reference storage format to use")),
+		OPT_ALIAS_F(0, "ref-format", "ref-storage-format", PARSE_OPT_HIDDEN),
 		OPT_BOOL(0, "dissociate", &dissociate, N_("borrow the objects from reference repositories")),
 		OPT_STRING(0, "name", &add_data.sm_name, N_("name"),
 			   N_("sets the submodule's name to the given string "
diff --git a/git-submodule.sh b/git-submodule.sh
index 2999b31fad..8632194138 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -95,13 +95,13 @@ cmd_add()
 		--reference=*)
 			reference="$1"
 			;;
-		--ref-format)
+		--ref-format|--ref-storage-format)
 			case "$2" in '') usage ;; esac
-			ref_format="--ref-format=$2"
+			ref_storage_format="--ref-storage-format=$2"
 			shift
 			;;
-		--ref-format=*)
-			ref_format="$1"
+		--ref-format=*|--ref-storage-format=*)
+			ref_storage_format="$1"
 			;;
 		--dissociate)
 			dissociate=$1
@@ -147,7 +147,7 @@ cmd_add()
 		$progress \
 		${branch:+"$branch"} \
 		${reference:+"$reference"} \
-		${ref_format:+"$ref_format"} \
+		${ref_storage_format:+"$ref_storage_format"} \
 		$dissociate \
 		${name:+"$name"} \
 		${depth:+"$depth"} \
@@ -302,13 +302,13 @@ cmd_update()
 		-r|--rebase)
 			rebase=$1
 			;;
-		--ref-format)
+		--ref-format|--ref-storage-format)
 			case "$2" in '') usage ;; esac
-			ref_format="--ref-format=$2"
+			ref_storage_format="--ref-storage-format=$2"
 			shift
 			;;
-		--ref-format=*)
-			ref_format="$1"
+		--ref-format=*|--ref-storage-format=*)
+			ref_storage_format="$1"
 			;;
 		--reference)
 			case "$2" in '') usage ;; esac
@@ -385,7 +385,7 @@ cmd_update()
 		$rebase \
 		$merge \
 		$checkout \
-		${ref_format:+"$ref_format"} \
+		${ref_storage_format:+"$ref_storage_format"} \
 		${reference:+"$reference"} \
 		$dissociate \
 		${depth:+"$depth"} \
diff --git a/t/t7424-submodule-mixed-ref-formats.sh b/t/t7424-submodule-mixed-ref-formats.sh
index e61389af05..2ef85289b3 100755
--- a/t/t7424-submodule-mixed-ref-formats.sh
+++ b/t/t7424-submodule-mixed-ref-formats.sh
@@ -44,7 +44,7 @@ test_expect_success 'add submodules with different ref storage format' '
 	test_commit -C submodule submodule-initial &&
 	git init upstream &&
 	test_ref_format upstream "$GIT_DEFAULT_REF_FORMAT" &&
-	git -C upstream submodule add --ref-format="$OTHER_FORMAT" "file://$(pwd)/submodule" &&
+	git -C upstream submodule add --ref-storage-format="$OTHER_FORMAT" "file://$(pwd)/submodule" &&
 	test_ref_format upstream/submodule "$OTHER_FORMAT"
 '
 
@@ -82,7 +82,7 @@ test_expect_success 'clone submodules with different ref storage format' '
 
 	git clone --no-recurse-submodules "file://$(pwd)/upstream" downstream &&
 	test_ref_format downstream "$GIT_DEFAULT_REF_FORMAT" &&
-	git -C downstream submodule update --init --ref-format=$OTHER_FORMAT &&
+	git -C downstream submodule update --init --ref-storage-format=$OTHER_FORMAT &&
 	test_ref_format downstream/submodule "$OTHER_FORMAT"
 '
 
@@ -122,7 +122,7 @@ test_expect_success 'recursive pull with mixed formats' '
 	# Clone the upstream repository such that the main repo and its
 	# submodules have different formats.
 	git clone --no-recurse-submodules "file://$(pwd)/upstream" downstream &&
-	git -C downstream submodule update --init --ref-format=$OTHER_FORMAT &&
+	git -C downstream submodule update --init --ref-storage-format=$OTHER_FORMAT &&
 	test_ref_format downstream "$GIT_DEFAULT_REF_FORMAT" &&
 	test_ref_format downstream/submodule "$OTHER_FORMAT" &&
 
-- 
2.55.0.1074.ge7621b4bad.dirty
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 9 of 20 in “Fix inconsistent ref storage format terminology”
  1. 00/13 Fix inconsistent ref storage format terminologyPatrick Steinhardt, Sep 9, 2026
  2. 01/13 parse-options: allow for hidden aliasesPatrick Steinhardt, Sep 9, 2026
  3. Karthik NayakSep 14, 2026
  4. Kaartic SivaraamSep 15, 2026
  5. Junio C HamanoSep 15, 2026
  6. 02/13 builtin/init: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  7. 03/13 builtin/clone: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  8. 04/13 builtin/refs: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  9. 05/13 builtin/submodule: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  10. 06/13 builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage-format"Patrick Steinhardt, Sep 9, 2026
  11. 07/13 help: rename "default-ref-format" to "default-ref-storage-format"Patrick Steinhardt, Sep 9, 2026
  12. 08/13 refs: expose function to parse reference URIsPatrick Steinhardt, Sep 9, 2026
  13. 09/13 setup: refactor how we configure the ref storage formatPatrick Steinhardt, Sep 9, 2026
  14. 10/13 setup: rename ref storage format environment variablesPatrick Steinhardt, Sep 9, 2026
  15. 11/13 t: rename GIT_TEST_DEFAULT_REF_FORMATPatrick Steinhardt, Sep 9, 2026
  16. 12/13 setup: rename "init.defaultRefFormat" to "init.defaultRefStorageFormat"Patrick Steinhardt, Sep 9, 2026
  17. 13/13 setup: allow "--ref-storage-format=" to specify a payloadPatrick Steinhardt, Sep 9, 2026
  18. Karthik NayakSep 14, 2026
  19. Junio C HamanoSep 14, 2026
  20. Kaartic SivaraamSep 14, 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.