[PATCH v3 04/13] builtin/refs: rename "--ref-format=" to "--ref-storage-format="
From: Patrick Steinhardt <hidden>
Date: 2026-09-09 11:13:08
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
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 <redacted> --- Documentation/git-refs.adoc | 9 ++++++--- builtin/fetch.c | 2 +- builtin/refs.c | 9 +++++---- t/t1423-ref-backend.sh | 8 ++++---- t/t1460-refs-migrate.sh | 12 ++++++------ t/t7424-submodule-mixed-ref-formats.sh | 2 +- 6 files changed, 23 insertions(+), 19 deletions(-)
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 9063892651..ae722c60e6 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,11 +97,14 @@ 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[] +`--ref-format=<format>`:: +Deprecated alias of `--ref-storage-format=<format>`. + `--dry-run`:: Perform the migration, but do not modify the repository. The migrated refs will be written into a separate directory that can be inspected
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..31aafb9974 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,10 @@ 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_ALIAS_F(0, "ref-format", "ref-storage-format", PARSE_OPT_HIDDEN), OPT_BIT(0, "dry-run", &flags, N_("perform a non-destructive dry-run"), REPO_MIGRATE_REF_STORAGE_FORMAT_DRYRUN),
@@ -62,7 +63,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 5f31d233e9..e61389af05 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.1074.ge7621b4bad.dirty