[PATCH 03/11] builtin/refs: rename "--ref-format=" to "--ref-storage="
From: Patrick Steinhardt <hidden>
Date: 2026-09-04 10:36:22
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
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 <redacted> --- 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..823dbd72c0 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> [--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>`:: + 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..b7faee5125 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=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..deb9387375 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> [--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_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 = 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 26a3655058..20545d9db8 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=$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=$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=$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=$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 44ad24f16e..4f2ff725ce 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" "$@" && 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> 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=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=$from_format repo && test_must_fail git -C repo refs migrate \ - --ref-format=$from_format 2>err && + --ref-storage=$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=$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=$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=$from_format repo && test_commit -C repo initial && git -C repo refs migrate --dry-run \ - --ref-format=$to_format >output && + --ref-storage=$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 1adac7baed..5c26fc18be 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=$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