{"thread":{"id":"64513","subject":"[PATCH 0/2] refs: allow setting the reference directory","startedAt":"2025-11-19T21:48:58Z","lastAt":"2026-02-25T17:42:30Z","messageCount":101,"participants":["Karthik Nayak","Eric Sunshine","Jean-Noël Avila","Justin Tobler","Toon Claes","Junio C Hamano","Patrick Steinhardt","Jeff King","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"531026","messageId":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","threadId":"64513","inReplyTo":null,"subject":"[PATCH 0/2] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-19T21:48:51Z","receivedAt":"2025-11-19T21:48:58Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"While Git allows users to select different reference backends, unlike\nwith objects, there is no flexibility in selecting the reference\ndirectory. Currently, the reference format is obtained from the config\nof the repository and the reference directory is set to the $GIT_DIR.\n\nThis patch series adds a new ENV variable 'GIT_REF_URI' which takes the\nreference backend and path in a URI form:\n\n ://\n\nFor e.g. 'reftable:///foo' or 'files://$GIT_DIR/ref_migration.0xBsa0'.\n\nOne use case for this is migration between different backends. On the\nserver side, migrating from the files backend to the newly introduced\nreftable backend can be achieved by running 'git refs migrate'. However,\nfor large repositories with millions of references, this migration can\ntake from seconds to minutes.\n\nWe could make the migration non-blocking by running the migration in the\nbackground and capturing and replaying updates to both backends. This\nwould require Git to support writing references to different reference\nbackends and paths.\n\nThe first commit adds the required changes to create a 'ref_store' for a\ngiven path. The second commit parses the URI if available when creating\nthe main ref store.\n\nThis is based on top of 9a2fb147f2 (Git 2.52, 2025-11-17).\n\nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 8 ++++\n environment.h | 1 +\n refs.c | 64 +++++++++++++++++++++++++++--\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n 5 files changed, 180 insertions(+), 3 deletions(-)\n\nKarthik Nayak (2):\n refs: support obtaining ref_store for given dir\n refs: add GIT_REF_URI to specify reference backend and directory\n\n\n\nbase-commit: 9a2fb147f2c61d0cab52c883e7e26f5b7948e3ed\nchange-id: 20251105-kn-alternate-ref-dir-3e572e8cd0ef\n\nThanks\n- Karthik\n\n"},{"id":"531027","messageId":"20251119-kn-alternate-ref-dir-v1-1-4cf4a94c8bed@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH 1/2] refs: support obtaining ref_store for given dir","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-19T21:48:52Z","receivedAt":"2025-11-19T21:48:58Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The refs subsystem uses the `get_main_ref_store()` to obtain the main\nref_store for a given repository. In the upcoming patches we also want\nto create a ref_store for any given reference directory, which may exist\nin arbitrary paths. To support such behavior, extract out the core logic\nfor creating out the ref_store from `get_main_ref_store()` into a new\nfunction `get_ref_store_for_dir()` which can provide the ref_store for a\ngiven (repository, directory, reference format) combination.\n\nSigned-off-by: Karthik Nayak \n---\n refs.c | 13 ++++++++++---\n 1 file changed, 10 insertions(+), 3 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex 965381367e..23f46867f2 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2177,6 +2177,15 @@ void ref_store_release(struct ref_store *ref_store)\n \tfree(ref_store->gitdir);\n }\n \n+static struct ref_store *get_ref_store_for_dir(struct repository *r,\n+\t\t\t\t\t char *dir,\n+\t\t\t\t\t enum ref_storage_format format)\n+{\n+\tstruct ref_store *ref_store = ref_store_init(r, format, dir,\n+\t\t\t\t\t\t REF_STORE_ALL_CAPS);\n+\treturn maybe_debug_wrap_ref_store(dir, ref_store);\n+}\n+\n struct ref_store *get_main_ref_store(struct repository *r)\n {\n \tif (r->refs_private)\n@@ -2185,9 +2194,7 @@ struct ref_store *get_main_ref_store(struct repository *r)\n \tif (!r->gitdir)\n \t\tBUG(\"attempting to get main_ref_store outside of repository\");\n \n-\tr->refs_private = ref_store_init(r, r->ref_storage_format,\n-\t\t\t\t\t r->gitdir, REF_STORE_ALL_CAPS);\n-\tr->refs_private = maybe_debug_wrap_ref_store(r->gitdir, r->refs_private);\n+\tr->refs_private = get_ref_store_for_dir(r, r->gitdir, r->ref_storage_format);\n \treturn r->refs_private;\n }\n \n\n-- \n2.51.2\n\n"},{"id":"531028","messageId":"20251119-kn-alternate-ref-dir-v1-2-4cf4a94c8bed@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-19T21:48:53Z","receivedAt":"2025-11-19T21:48:59Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Git allows setting a different object directory via\n'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\nThis asymmetry makes it difficult to test different reference backends\nor use alternative reference storage locations without modifying the\nrepository structure.\n\nAdd a new environment variable 'GIT_REF_URI' that specifies both the\nreference backend and directory path using a URI format:\n\n ://\n\nWhen set, this variable is used to obtain the main reference store for\nall Git commands. The variable is checked in `get_main_ref_store()`\nwhen lazily assigning `repo->refs_private`. We cannot initialize this\nearlier in `repo_set_gitdir()` because the repository's hash algorithm\nisn't known at that point, and the reftable backend requires this\ninformation during initialization.\n\nWhen used with worktrees, the specified directory is treated as the\nreference directory for all worktree operations.\n\nAdd a new test file 't1423-ref-backend.sh' to test this environment\nvariable.\n\nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 8 ++++\n environment.h | 1 +\n refs.c | 53 +++++++++++++++++++++++-\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n 5 files changed, 171 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..a1d1078f42 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -584,6 +584,14 @@ double-quotes and respecting backslash escapes. E.g., the value\n \trepositories will be set to this value. The default is \"files\".\n \tSee `--ref-format` in linkgit:git-init[1].\n \n+`GIT_REF_URI`::\n+ Specify which reference backend and path to be used, if not specified the\n+ backend is inferred from the configuration and $GIT_DIR is used as the\n+ path.\n++\n+Expects the format '://', where the 'backend' specifies the\n+reference backend and the 'path' specifies the directory used by the backend.\n+\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\ndiff --git a/environment.h b/environment.h\nindex 51898c99cd..9bc380bba4 100644\n--- a/environment.h\n+++ b/environment.h\n@@ -42,6 +42,7 @@\n #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n+#define GIT_REF_URI_ENVIRONMENT \"GIT_REF_URI\"\n \n /*\n * Environment variable used to propagate the --no-advice global option to the\ndiff --git a/refs.c b/refs.c\nindex 23f46867f2..0922f08c9f 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2186,15 +2186,66 @@ static struct ref_store *get_ref_store_for_dir(struct repository *r,\n \treturn maybe_debug_wrap_ref_store(dir, ref_store);\n }\n \n+static struct ref_store *get_ref_store_from_uri(struct repository *repo,\n+\t\t\t\t\t\tconst char *uri)\n+{\n+\tstruct string_list ref_backend_info = STRING_LIST_INIT_DUP;\n+\tenum ref_storage_format format;\n+\tstruct ref_store *store = NULL;\n+\tchar *format_string;\n+\tchar *dir;\n+\n+\tif (!uri || !uri[0]) {\n+\t\terror(\"reference backend uri is empty\");\n+\t\tgoto cleanup;\n+\t}\n+\n+\tif (string_list_split(&ref_backend_info, uri, \":\", 2) != 2) {\n+\t\terror(\"invalid reference backend uri format '%s'\", uri);\n+\t\tgoto cleanup;\n+\t}\n+\n+\tformat_string = ref_backend_info.items[0].string;\n+\tdir = ref_backend_info.items[1].string + 2;\n+\n+\tif (!dir || !dir[0]) {\n+\t\terror(\"invalid path in uri '%s'\", uri);\n+\t\tgoto cleanup;\n+\t}\n+\n+\tformat = ref_storage_format_by_name(format_string);\n+\tif (format == REF_STORAGE_FORMAT_UNKNOWN) {\n+\t\terror(\"unknown reference backend '%s'\", format_string);\n+\t\tgoto cleanup;\n+\t}\n+\n+\tstore = get_ref_store_for_dir(repo, dir, format);\n+\n+cleanup:\n+\tstring_list_clear(&ref_backend_info, 0);\n+\treturn store;\n+}\n+\n struct ref_store *get_main_ref_store(struct repository *r)\n {\n+\tchar *ref_uri;\n+\n \tif (r->refs_private)\n \t\treturn r->refs_private;\n \n \tif (!r->gitdir)\n \t\tBUG(\"attempting to get main_ref_store outside of repository\");\n \n-\tr->refs_private = get_ref_store_for_dir(r, r->gitdir, r->ref_storage_format);\n+\tref_uri = getenv(GIT_REF_URI_ENVIRONMENT);\n+\tif (ref_uri) {\n+\t\tr->refs_private = get_ref_store_from_uri(r, ref_uri);\n+\t\tif (!r->refs_private)\n+\t\t\tdie(\"failed to initialize ref store from URI: %s\", ref_uri);\n+\n+\t} else {\n+\t\tr->refs_private = get_ref_store_for_dir(r, r->gitdir,\n+\t\t\t\t\t\t\tr->ref_storage_format);\n+\t}\n \treturn r->refs_private;\n }\n \ndiff --git a/t/meson.build b/t/meson.build\nindex a5531df415..a66f8fafff 100644\n--- a/t/meson.build\n+++ b/t/meson.build\n@@ -208,6 +208,7 @@ integration_tests = [\n 't1420-lost-found.sh',\n 't1421-reflog-write.sh',\n 't1422-show-ref-exists.sh',\n+ 't1423-ref-backend.sh',\n 't1430-bad-ref-name.sh',\n 't1450-fsck.sh',\n 't1451-fsck-buffer.sh',\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nnew file mode 100755\nindex 0000000000..e271708e02\n--- /dev/null\n+++ b/t/t1423-ref-backend.sh\n@@ -0,0 +1,109 @@\n+#!/bin/sh\n+\n+test_description='Test different reference backend URIs'\n+\n+. ./test-lib.sh\n+\n+test_expect_success 'empty uri provided' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init --ref-format=files repo &&\n+\t(\n+\t\tcd repo &&\n+\t\tGIT_REF_URI=\"\" &&\n+\t\texport GIT_REF_URI &&\n+\t\t! git refs list 2>err &&\n+\t\ttest_grep \"reference backend uri is empty\" err\n+\t)\n+'\n+\n+test_expect_success 'invalid uri provided' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init --ref-format=files repo &&\n+\t(\n+\t\tcd repo &&\n+\t\tGIT_REF_URI=\"reftable@/home/reftable\" &&\n+\t\texport GIT_REF_URI &&\n+\t\t! git refs list 2>err &&\n+\t\ttest_grep \"invalid reference backend uri format\" err\n+\t)\n+'\n+\n+test_expect_success 'empty path in uri' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init --ref-format=files repo &&\n+\t(\n+\t\tcd repo &&\n+\t\tGIT_REF_URI=\"reftable://\" &&\n+\t\texport GIT_REF_URI &&\n+\t\t! git refs list 2>err &&\n+\t\ttest_grep \"invalid path in uri\" err\n+\t)\n+'\n+\n+test_expect_success 'unknown reference backend' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init --ref-format=files repo &&\n+\t(\n+\t\tcd repo &&\n+\t\tGIT_REF_URI=\"db://.git\" &&\n+\t\texport GIT_REF_URI &&\n+\t\t! git refs list 2>err &&\n+\t\ttest_grep \"unknown reference backend\" err\n+\t)\n+'\n+\n+ref_formats=\"files reftable\"\n+for from_format in $ref_formats\n+do\n+\tfor to_format in $ref_formats\n+\tdo\n+\t\tif test \"$from_format\" = \"$to_format\"\n+\t\tthen\n+\t\t\tcontinue\n+\t\tfi\n+\n+\t\ttest_expect_success 'read from other reference backend' '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=files repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=reftable >out &&\n+\t\t\t\tREFTABLE_PATH=$(cat out | sed \"s/.* ${SQ}\\(.*\\)${SQ}/\\1/\") &&\n+\t\t\t\tgit refs list >expect &&\n+\t\t\t\tGIT_REF_URI=\"reftable://$REFTABLE_PATH\" git refs list >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success 'write to other reference backend' '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=files repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=reftable >out &&\n+\t\t\t\tgit refs list >expect &&\n+\n+\t\t\t\tREFTABLE_PATH=$(cat out | sed \"s/.* ${SQ}\\(.*\\)${SQ}/\\1/\") &&\n+\t\t\t\tGIT_REF_URI=\"reftable://$REFTABLE_PATH\" git tag -d 1 &&\n+\n+\t\t\t\tgit refs list >actual &&\n+\t\t\t\ttest_cmp expect actual &&\n+\n+\t\t\t\tGIT_REF_URI=\"reftable://$REFTABLE_PATH\" git refs list >expect &&\n+\t\t\t\tgit refs list >out &&\n+\t\t\t\tcat out | grep -v \"refs/tags/1\" >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\tdone\n+done\n+\n+test_done\n\n-- \n2.51.2\n\n"},{"id":"531029","messageId":"CAPig+cQ1nF47Rvvm4gDks8Bzj0htzUkfR24WB8UdnJtcQTQwCA@mail.gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-2-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-11-19T22:13:19Z","receivedAt":"2025-11-19T22:13:31Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Nov 19, 2025 at 4:49 PM Karthik Nayak wrote:\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n> This asymmetry makes it difficult to test different reference backends\n> or use alternative reference storage locations without modifying the\n> repository structure.\n>\n> Add a new environment variable 'GIT_REF_URI' that specifies both the\n> reference backend and directory path using a URI format:\n> [...]\n> Signed-off-by: Karthik Nayak \n> ---\n> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n> @@ -0,0 +1,109 @@\n> +test_expect_success 'empty uri provided' '\n> + test_when_finished \"rm -rf repo\" &&\n> + git init --ref-format=files repo &&\n> + (\n> + cd repo &&\n> + GIT_REF_URI=\"\" &&\n> + export GIT_REF_URI &&\n> + ! git refs list 2>err &&\n\nShould this (and all other tests) be using `test_must_fail` rather than `!`?\n\n> + test_grep \"reference backend uri is empty\" err\n> + )\n> +'\n> +ref_formats=\"files reftable\"\n> +for from_format in $ref_formats\n> +do\n> + for to_format in $ref_formats\n> + do\n> + if test \"$from_format\" = \"$to_format\"\n> + then\n> + continue\n> + fi\n> +\n> + test_expect_success 'read from other reference backend' '\n> + test_when_finished \"rm -rf repo\" &&\n> + git init --ref-format=files repo &&\n> + (\n> + cd repo &&\n> + test_commit 1 &&\n> + test_commit 2 &&\n> + test_commit 3 &&\n> +\n> + git refs migrate --dry-run --ref-format=reftable >out &&\n> + REFTABLE_PATH=$(cat out | sed \"s/.* ${SQ}\\(.*\\)${SQ}/\\1/\") &&\n> + git refs list >expect &&\n> + GIT_REF_URI=\"reftable://$REFTABLE_PATH\" git refs list >actual &&\n> + test_cmp expect actual\n> + )\n> + '\n> +\n> + test_expect_success 'write to other reference backend' '\n> + [...]\n> + '\n> + done\n> +done\n\nSomething seems amiss here. Presumably, this nested loop wants to test\nvarious combinations but the `from_format` and `to_format` variables\nare never consulted in the tests; instead the tests just hardcode\nspecific ref-format values.\n\nAlso, if this is indeed meant to be loop-driven, then it would be\nhelpful for the test titles to include the values of `$from_format`\nand `$to_format`.\n"},{"id":"531031","messageId":"CAOLa=ZQvG+D7NwT1mW50pC6+QGc7_PSvoTA8GgK0cvDKondx8A@mail.gmail.com","threadId":"64513","inReplyTo":"CAPig+cQ1nF47Rvvm4gDks8Bzj0htzUkfR24WB8UdnJtcQTQwCA@mail.gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-19T23:01:01Z","receivedAt":"2025-11-19T23:01:04Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Eric Sunshine writes:\n\n> On Wed, Nov 19, 2025 at 4:49 PM Karthik Nayak wrote:\n>> Git allows setting a different object directory via\n>> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n>> This asymmetry makes it difficult to test different reference backends\n>> or use alternative reference storage locations without modifying the\n>> repository structure.\n>>\n>> Add a new environment variable 'GIT_REF_URI' that specifies both the\n>> reference backend and directory path using a URI format:\n>> [...]\n>> Signed-off-by: Karthik Nayak \n>> ---\n>> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n>> @@ -0,0 +1,109 @@\n>> +test_expect_success 'empty uri provided' '\n>> + test_when_finished \"rm -rf repo\" &&\n>> + git init --ref-format=files repo &&\n>> + (\n>> + cd repo &&\n>> + GIT_REF_URI=\"\" &&\n>> + export GIT_REF_URI &&\n>> + ! git refs list 2>err &&\n>\n> Should this (and all other tests) be using `test_must_fail` rather than `!`?\n>\n\nInitially I used 'BUG()' instead of 'error()', which was wrong, but\nmeant that I couldn't use `test_must_fail`. I've fixed that now, but\nthis was missed. Thanks.\n\n>> + test_grep \"reference backend uri is empty\" err\n>> + )\n>> +'\n>> +ref_formats=\"files reftable\"\n>> +for from_format in $ref_formats\n>> +do\n>> + for to_format in $ref_formats\n>> + do\n>> + if test \"$from_format\" = \"$to_format\"\n>> + then\n>> + continue\n>> + fi\n>> +\n>> + test_expect_success 'read from other reference backend' '\n>> + test_when_finished \"rm -rf repo\" &&\n>> + git init --ref-format=files repo &&\n>> + (\n>> + cd repo &&\n>> + test_commit 1 &&\n>> + test_commit 2 &&\n>> + test_commit 3 &&\n>> +\n>> + git refs migrate --dry-run --ref-format=reftable >out &&\n>> + REFTABLE_PATH=$(cat out | sed \"s/.* ${SQ}\\(.*\\)${SQ}/\\1/\") &&\n>> + git refs list >expect &&\n>> + GIT_REF_URI=\"reftable://$REFTABLE_PATH\" git refs list >actual &&\n>> + test_cmp expect actual\n>> + )\n>> + '\n>> +\n>> + test_expect_success 'write to other reference backend' '\n>> + [...]\n>> + '\n>> + done\n>> +done\n>\n> Something seems amiss here. Presumably, this nested loop wants to test\n> various combinations but the `from_format` and `to_format` variables\n> are never consulted in the tests; instead the tests just hardcode\n> specific ref-format values.\n>\n> Also, if this is indeed meant to be loop-driven, then it would be\n> helpful for the test titles to include the values of `$from_format`\n> and `$to_format`.\n\nIndeed. I was hasty, will fix :)\n"},{"id":"531054","messageId":"46f9d35e-60f2-488c-a0b4-89855f27cc66@free.fr","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-2-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-11-20T10:00:38Z","receivedAt":"2025-11-20T10:00:54Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On 19/11/2025 at 22:48, Karthik Nayak wrote:\n> ---\n> Documentation/git.adoc | 8 ++++\n> environment.h | 1 +\n> refs.c | 53 +++++++++++++++++++++++-\n> t/meson.build | 1 +\n> t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n> 5 files changed, 171 insertions(+), 1 deletion(-)\n> \n> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n> index ce099e78b8..a1d1078f42 100644\n> --- a/Documentation/git.adoc\n> +++ b/Documentation/git.adoc\n> @@ -584,6 +584,14 @@ double-quotes and respecting backslash escapes. E.g., the value\n> \trepositories will be set to this value. The default is \"files\".\n> \tSee `--ref-format` in linkgit:git-init[1].\n> \n> +`GIT_REF_URI`::\n> + Specify which reference backend and path to be used, if not specified the\n> + backend is inferred from the configuration and $GIT_DIR is used as the\n> + path.\n\nPlease use backquotes for environment variables: `$GIT_DIR`\n\n> ++\n> +Expects the format '://', where the 'backend' specifies the\n> +reference backend and the 'path' specifies the directory used by the backend.\n\nConstant strings and keywords are back-quoted too but placeholders are\nunderscored:\n\nExpects the format `://`, where the __\nspecifies the reference backend and the __ specifies the directory\nused by the backend.\n\nI'm only focusing on documentation.\n\nThanks\n"},{"id":"531071","messageId":"pyt5nc2v25oarqmuxld4nrknmsomjnyooj25ffjetcue5zq7xi@vglcil42as5a","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-1-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 1/2] refs: support obtaining ref_store for given dir","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-11-20T19:05:26Z","receivedAt":"2025-11-20T19:05:31Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 25/11/19 10:48PM, Karthik Nayak wrote:\n> The refs subsystem uses the `get_main_ref_store()` to obtain the main\n> ref_store for a given repository. In the upcoming patches we also want\n> to create a ref_store for any given reference directory, which may exist\n> in arbitrary paths. To support such behavior, extract out the core logic\n> for creating out the ref_store from `get_main_ref_store()` into a new\n> function `get_ref_store_for_dir()` which can provide the ref_store for a\n> given (repository, directory, reference format) combination.\n\nSo when we refer to the \"reference directory\" in this case, we are not\nrefering to the \"refs/\" or \"reftable/\" directories directly, but one\nlevel above that which is typically just the gitdir itself. This seems a\nbit awkward at first, but makes sense since, for the files backend,\nthere may be symbolic references such as HEAD that exist outside of\n\"refs/\" which must be considered. It might be helpful to clarify this in\nthe commit message.\n\nOtherwise this patch looks good.\n\n-Justin\n"},{"id":"531074","messageId":"3kdv5xzzoci5hmxau2qwhwtkx5rw7752vdb4a2mricrgt5vdqj@oxm7jvcr6ysy","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-2-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-11-20T19:38:37Z","receivedAt":"2025-11-20T19:38:41Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 25/11/19 10:48PM, Karthik Nayak wrote:\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n> This asymmetry makes it difficult to test different reference backends\n> or use alternative reference storage locations without modifying the\n> repository structure.\n> \n> Add a new environment variable 'GIT_REF_URI' that specifies both the\n> reference backend and directory path using a URI format:\n> \n> ://\n\nOk, we include the reference format as part of the URI here since it is\npossible that the alternative reference store could be using a different\nbackend that what the repository is currently configured to use. Makes\nsense.\n\n> When set, this variable is used to obtain the main reference store for\n> all Git commands. The variable is checked in `get_main_ref_store()`\n> when lazily assigning `repo->refs_private`. We cannot initialize this\n> earlier in `repo_set_gitdir()` because the repository's hash algorithm\n> isn't known at that point, and the reftable backend requires this\n> information during initialization.\n>\n> When used with worktrees, the specified directory is treated as the\n> reference directory for all worktree operations.\n> \n> Add a new test file 't1423-ref-backend.sh' to test this environment\n> variable.\n> \n> Signed-off-by: Karthik Nayak \n> ---\n> Documentation/git.adoc | 8 ++++\n> environment.h | 1 +\n> refs.c | 53 +++++++++++++++++++++++-\n> t/meson.build | 1 +\n> t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n> 5 files changed, 171 insertions(+), 1 deletion(-)\n> \n> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n> index ce099e78b8..a1d1078f42 100644\n> --- a/Documentation/git.adoc\n> +++ b/Documentation/git.adoc\n> @@ -584,6 +584,14 @@ double-quotes and respecting backslash escapes. E.g., the value\n> \trepositories will be set to this value. The default is \"files\".\n> \tSee `--ref-format` in linkgit:git-init[1].\n> \n> +`GIT_REF_URI`::\n> + Specify which reference backend and path to be used, if not specified the\n> + backend is inferred from the configuration and $GIT_DIR is used as the\n> + path.\n> ++\n> +Expects the format '://', where the 'backend' specifies the\n> +reference backend and the 'path' specifies the directory used by the backend.\n\nI think some users may assume that the path to the reference backend\nwould be something like \".git/refs\" similar to how\n`GIT_OBJECT_DIRECTORY` is usually \".git/objects\". It might be worth\nclarifying this in the docs here.\n\n> +\n> Git Commits\n> ~~~~~~~~~~~\n> `GIT_AUTHOR_NAME`::\n> diff --git a/environment.h b/environment.h\n> index 51898c99cd..9bc380bba4 100644\n> --- a/environment.h\n> +++ b/environment.h\n> @@ -42,6 +42,7 @@\n> #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n> #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n> #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n> +#define GIT_REF_URI_ENVIRONMENT \"GIT_REF_URI\"\n> \n> /*\n> * Environment variable used to propagate the --no-advice global option to the\n> diff --git a/refs.c b/refs.c\n> index 23f46867f2..0922f08c9f 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -2186,15 +2186,66 @@ static struct ref_store *get_ref_store_for_dir(struct repository *r,\n> \treturn maybe_debug_wrap_ref_store(dir, ref_store);\n> }\n> \n> +static struct ref_store *get_ref_store_from_uri(struct repository *repo,\n> +\t\t\t\t\t\tconst char *uri)\n> +{\n> +\tstruct string_list ref_backend_info = STRING_LIST_INIT_DUP;\n> +\tenum ref_storage_format format;\n> +\tstruct ref_store *store = NULL;\n> +\tchar *format_string;\n> +\tchar *dir;\n> +\n> +\tif (!uri || !uri[0]) {\n> +\t\terror(\"reference backend uri is empty\");\n> +\t\tgoto cleanup;\n> +\t}\n> +\n> +\tif (string_list_split(&ref_backend_info, uri, \":\", 2) != 2) {\n> +\t\terror(\"invalid reference backend uri format '%s'\", uri);\n> +\t\tgoto cleanup;\n> +\t}\n> +\n> +\tformat_string = ref_backend_info.items[0].string;\n> +\tdir = ref_backend_info.items[1].string + 2;\n> +\n> +\tif (!dir || !dir[0]) {\n> +\t\terror(\"invalid path in uri '%s'\", uri);\n> +\t\tgoto cleanup;\n> +\t}\n> +\n> +\tformat = ref_storage_format_by_name(format_string);\n> +\tif (format == REF_STORAGE_FORMAT_UNKNOWN) {\n> +\t\terror(\"unknown reference backend '%s'\", format_string);\n> +\t\tgoto cleanup;\n> +\t}\n> +\n> +\tstore = get_ref_store_for_dir(repo, dir, format);\n\nSince we don't update the reference format stored in repo, if we were to\nrun:\n\n $ GIT_REF_URI=\"reftable:// git repo info references.format\n\nit would still report what ever the repository was originally configured\nwith. Since only a single reference backend can be used at time, I\nwonder if we should go a bit further and update `r->ref_storage_format`\nto be inline with how the repository reference backend is configured via\n`GIT_REF_URI`.\n\n-Justin\n"},{"id":"531137","messageId":"CAOLa=ZTeadFsZNNxjObwrS_a4kTC3V3d6ubn=DXncEzzvWe2MQ@mail.gmail.com","threadId":"64513","inReplyTo":"pyt5nc2v25oarqmuxld4nrknmsomjnyooj25ffjetcue5zq7xi@vglcil42as5a","subject":"Re: [PATCH 1/2] refs: support obtaining ref_store for given dir","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-21T11:18:23Z","receivedAt":"2025-11-21T11:18:25Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Justin Tobler writes:\n\n> On 25/11/19 10:48PM, Karthik Nayak wrote:\n>> The refs subsystem uses the `get_main_ref_store()` to obtain the main\n>> ref_store for a given repository. In the upcoming patches we also want\n>> to create a ref_store for any given reference directory, which may exist\n>> in arbitrary paths. To support such behavior, extract out the core logic\n>> for creating out the ref_store from `get_main_ref_store()` into a new\n>> function `get_ref_store_for_dir()` which can provide the ref_store for a\n>> given (repository, directory, reference format) combination.\n>\n> So when we refer to the \"reference directory\" in this case, we are not\n> refering to the \"refs/\" or \"reftable/\" directories directly, but one\n> level above that which is typically just the gitdir itself. This seems a\n> bit awkward at first, but makes sense since, for the files backend,\n> there may be symbolic references such as HEAD that exist outside of\n> \"refs/\" which must be considered. It might be helpful to clarify this in\n> the commit message.\n>\n\nYou're right, for the files and the reftable backend, this happens to be\nthe $GIT_DIR itself, due to how closely they are integrated with Git.\nBut if you build an external reference backend, this doesn't have to be\nthe $GIT_DIR.\n\nI've modified the commit message accordingly\n\n> Otherwise this patch looks good.\n>\n> -Justin\n"},{"id":"531138","messageId":"CAOLa=ZTSqUr-2EHTYkbtukObgeHPZ5BwEc98_xx_UXJX9+Q2dQ@mail.gmail.com","threadId":"64513","inReplyTo":"46f9d35e-60f2-488c-a0b4-89855f27cc66@free.fr","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-21T11:21:02Z","receivedAt":"2025-11-21T11:21:04Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Jean-Noël Avila writes:\n\n> On 19/11/2025 at 22:48, Karthik Nayak wrote:\n>> ---\n>> Documentation/git.adoc | 8 ++++\n>> environment.h | 1 +\n>> refs.c | 53 +++++++++++++++++++++++-\n>> t/meson.build | 1 +\n>> t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n>> 5 files changed, 171 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n>> index ce099e78b8..a1d1078f42 100644\n>> --- a/Documentation/git.adoc\n>> +++ b/Documentation/git.adoc\n>> @@ -584,6 +584,14 @@ double-quotes and respecting backslash escapes. E.g., the value\n>> \trepositories will be set to this value. The default is \"files\".\n>> \tSee `--ref-format` in linkgit:git-init[1].\n>>\n>> +`GIT_REF_URI`::\n>> + Specify which reference backend and path to be used, if not specified the\n>> + backend is inferred from the configuration and $GIT_DIR is used as the\n>> + path.\n>\n> Please use backquotes for environment variables: `$GIT_DIR`\n>\n\nWill do.\n\n>> ++\n>> +Expects the format '://', where the 'backend' specifies the\n>> +reference backend and the 'path' specifies the directory used by the backend.\n>\n> Constant strings and keywords are back-quoted too but placeholders are\n> underscored:\n>\n> Expects the format `://`, where the __\n> specifies the reference backend and the __ specifies the directory\n> used by the backend.\n>\n> I'm only focusing on documentation.\n>\n> Thanks\n\nThanks for your review, will modify accordingly.\n"},{"id":"531141","messageId":"87pl9b5wos.fsf@iotcl.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-2-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2025-11-21T13:42:27Z","receivedAt":"2025-11-21T13:43:01Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Karthik Nayak writes:\n\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n> This asymmetry makes it difficult to test different reference backends\n> or use alternative reference storage locations without modifying the\n> repository structure.\n>\n> Add a new environment variable 'GIT_REF_URI' that specifies both the\n> reference backend and directory path using a URI format:\n>\n> ://\n\nI like this idea. This would allow us in the future to also do something\nlike:\n\n reftable+nfs://10.11.12.13/ref-dir\n\n> When set, this variable is used to obtain the main reference store for\n> all Git commands. The variable is checked in `get_main_ref_store()`\n> when lazily assigning `repo->refs_private`. We cannot initialize this\n> earlier in `repo_set_gitdir()` because the repository's hash algorithm\n> isn't known at that point, and the reftable backend requires this\n> information during initialization.\n>\n> When used with worktrees, the specified directory is treated as the\n> reference directory for all worktree operations.\n>\n> Add a new test file 't1423-ref-backend.sh' to test this environment\n> variable.\n>\n> Signed-off-by: Karthik Nayak \n> ---\n> Documentation/git.adoc | 8 ++++\n> environment.h | 1 +\n> refs.c | 53 +++++++++++++++++++++++-\n> t/meson.build | 1 +\n> t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n> 5 files changed, 171 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n> index ce099e78b8..a1d1078f42 100644\n> --- a/Documentation/git.adoc\n> +++ b/Documentation/git.adoc\n> @@ -584,6 +584,14 @@ double-quotes and respecting backslash escapes. E.g., the value\n> \trepositories will be set to this value. The default is \"files\".\n> \tSee `--ref-format` in linkgit:git-init[1].\n> \n> +`GIT_REF_URI`::\n> + Specify which reference backend and path to be used, if not specified the\n> + backend is inferred from the configuration and $GIT_DIR is used as the\n> + path.\n> ++\n> +Expects the format '://', where the 'backend' specifies the\n> +reference backend and the 'path' specifies the directory used by the backend.\n> +\n> Git Commits\n> ~~~~~~~~~~~\n> `GIT_AUTHOR_NAME`::\n> diff --git a/environment.h b/environment.h\n> index 51898c99cd..9bc380bba4 100644\n> --- a/environment.h\n> +++ b/environment.h\n> @@ -42,6 +42,7 @@\n> #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n> #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n> #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n> +#define GIT_REF_URI_ENVIRONMENT \"GIT_REF_URI\"\n> \n> /*\n> * Environment variable used to propagate the --no-advice global option to the\n> diff --git a/refs.c b/refs.c\n> index 23f46867f2..0922f08c9f 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -2186,15 +2186,66 @@ static struct ref_store *get_ref_store_for_dir(struct repository *r,\n> \treturn maybe_debug_wrap_ref_store(dir, ref_store);\n> }\n> \n> +static struct ref_store *get_ref_store_from_uri(struct repository *repo,\n> +\t\t\t\t\t\tconst char *uri)\n> +{\n> +\tstruct string_list ref_backend_info = STRING_LIST_INIT_DUP;\n> +\tenum ref_storage_format format;\n> +\tstruct ref_store *store = NULL;\n> +\tchar *format_string;\n> +\tchar *dir;\n> +\n> +\tif (!uri || !uri[0]) {\n> +\t\terror(\"reference backend uri is empty\");\n\nI see no localization on any of the error() or die() messages. I think\nit's worth to make them translatable.\n\n> +\t\tgoto cleanup;\n> +\t}\n> +\n> +\tif (string_list_split(&ref_backend_info, uri, \":\", 2) != 2) {\n> +\t\terror(\"invalid reference backend uri format '%s'\", uri);\n> +\t\tgoto cleanup;\n> +\t}\n> +\n> +\tformat_string = ref_backend_info.items[0].string;\n> +\tdir = ref_backend_info.items[1].string + 2;\n\nLength check before jumping to the third char would be adviced. Also I\nthink it's worth to check if the first two chars are \"//\".\n\n-- \nCheers,\nToon\n"},{"id":"531147","messageId":"xmqq34675pz1.fsf@gitster.g","threadId":"64513","inReplyTo":"87pl9b5wos.fsf@iotcl.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-11-21T16:07:30Z","receivedAt":"2025-11-21T16:07:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Toon Claes writes:\n\n>> ://\n>\n> I like this idea. This would allow us in the future to also do something\n> like:\n>\n> reftable+nfs://10.11.12.13/ref-dir\n\nI actually thought from Karthik's definition that what you are\ntrying to say is spelled more like this:\n\n reftable://nfs://10.11.12.13/ref-dir\n\nIOW, the underlying URI to \"reach the resource\" is in the \npart (i.e., \"nfs:///\"). And I found it somewhat a\nstrange syntax, because the \"to reach the resource, visit this\" URI\nmay not necessarily look like , and I also wondered if\nspelling it like : is more\nappropriate.\n"},{"id":"531171","messageId":"xmqq34651ie5.fsf@gitster.g","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 0/2] refs: allow setting the reference directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-11-23T04:29:22Z","receivedAt":"2025-11-23T04:29:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak writes:\n\n> While Git allows users to select different reference backends, unlike\n> with objects, there is no flexibility in selecting the reference\n> directory. Currently, the reference format is obtained from the config\n> of the repository and the reference directory is set to the $GIT_DIR.\n\nI actually am not sure if I like the proposed environment variable.\n\nThe proposal is based on an assumption that any reference backend\nshould be able to move their backing store anywhere, and they should\nbe able to express the location of their backing store as a single\nstring . For a new backend, \"where is your backing store\" may\nnot even be a question that does not make much sense (as \"somewhere\nin the cloud that you do not even have to know\" is certainly\npossible), and even for a new backend design that does allow such a\nquestion to have a meaningful answer, this \"you have to be able to\nuse a random place specified by this environment variable as your\nbacking storage\" is an additional requirement that its implementors\nmay not need to satisfy in order to please their user base.\n\nFor reftable and files backends, these assumptions may be true, but\nthen it is not too cumbersome if these stay to be backend specific,\nas there are only two backends.\n\nSo I dunno. In addition, if this is designed to help migration\n(which is the impression I am getting from the cover letter\ndescription), don't you need a way to specify more than one (i.e.,\nsource to migrate from and destination to migrate to)? With a\nsingle GIT_REF_URI, it would not be obvious what it refers to,\nwhether it is an additional place to write to, to read from, or\nsomething completely unrelated. For example ...\n\n> This patch series adds a new ENV variable 'GIT_REF_URI' which takes the\n> reference backend and path in a URI form:\n>\n> ://\n>\n> For e.g. 'reftable:///foo' or 'files://$GIT_DIR/ref_migration.0xBsa0'.\n>\n> One use case for this is migration between different backends. On the\n> server side, migrating from the files backend to the newly introduced\n> reftable backend can be achieved by running 'git refs migrate'. However,\n> for large repositories with millions of references, this migration can\n> take from seconds to minutes.\n>\n> We could make the migration non-blocking by running the migration in the\n> background and capturing and replaying updates to both backends. This\n> would require Git to support writing references to different reference\n> backends and paths.\n\n... I am reading that the above is saying that the system will write\nto whatever reference backend specified in the extension.refStorage,\nplus also where GIT_REF_URI points at, but if that is the way how\nthe mechanism works, the variable should be named more specific to\nwhat it does, no? It is not just a random \"REF URI\"; it is an\nadditional ref backend that the updates are dumped to. Maybe there\nwould be a different use case where you may want to read from two\nreference backends, and you'd need to specify the secondary one with\nan environment variable, but if the system behaves one specific way\nfor GIT_REF_URI (say, all updates are also copied to this additional\nref backend at the specified ref backing store), a different\nenvironment variable name needs to be chosen to serve such a\ndifferent use case, no?\n\n\n"},{"id":"531214","messageId":"CAOLa=ZS0oTvVK7bYGwOx-RhnfFw-p+ZjChJ5-3C-790qqLqX1g@mail.gmail.com","threadId":"64513","inReplyTo":"3kdv5xzzoci5hmxau2qwhwtkx5rw7752vdb4a2mricrgt5vdqj@oxm7jvcr6ysy","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-24T13:23:21Z","receivedAt":"2025-11-24T13:23:24Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Justin Tobler writes:\n\n> On 25/11/19 10:48PM, Karthik Nayak wrote:\n>> Git allows setting a different object directory via\n>> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n>> This asymmetry makes it difficult to test different reference backends\n>> or use alternative reference storage locations without modifying the\n>> repository structure.\n>>\n>> Add a new environment variable 'GIT_REF_URI' that specifies both the\n>> reference backend and directory path using a URI format:\n>>\n>> ://\n>\n> Ok, we include the reference format as part of the URI here since it is\n> possible that the alternative reference store could be using a different\n> backend that what the repository is currently configured to use. Makes\n> sense.\n>\n>> When set, this variable is used to obtain the main reference store for\n>> all Git commands. The variable is checked in `get_main_ref_store()`\n>> when lazily assigning `repo->refs_private`. We cannot initialize this\n>> earlier in `repo_set_gitdir()` because the repository's hash algorithm\n>> isn't known at that point, and the reftable backend requires this\n>> information during initialization.\n>>\n>> When used with worktrees, the specified directory is treated as the\n>> reference directory for all worktree operations.\n>>\n>> Add a new test file 't1423-ref-backend.sh' to test this environment\n>> variable.\n>>\n>> Signed-off-by: Karthik Nayak \n>> ---\n>> Documentation/git.adoc | 8 ++++\n>> environment.h | 1 +\n>> refs.c | 53 +++++++++++++++++++++++-\n>> t/meson.build | 1 +\n>> t/t1423-ref-backend.sh | 109 +++++++++++++++++++++++++++++++++++++++++++++++++\n>> 5 files changed, 171 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n>> index ce099e78b8..a1d1078f42 100644\n>> --- a/Documentation/git.adoc\n>> +++ b/Documentation/git.adoc\n>> @@ -584,6 +584,14 @@ double-quotes and respecting backslash escapes. E.g., the value\n>> \trepositories will be set to this value. The default is \"files\".\n>> \tSee `--ref-format` in linkgit:git-init[1].\n>>\n>> +`GIT_REF_URI`::\n>> + Specify which reference backend and path to be used, if not specified the\n>> + backend is inferred from the configuration and $GIT_DIR is used as the\n>> + path.\n>> ++\n>> +Expects the format '://', where the 'backend' specifies the\n>> +reference backend and the 'path' specifies the directory used by the backend.\n>\n> I think some users may assume that the path to the reference backend\n> would be something like \".git/refs\" similar to how\n> `GIT_OBJECT_DIRECTORY` is usually \".git/objects\". It might be worth\n> clarifying this in the docs here.\n>\n\nFair enough. I'll amend the commit.\n\n>> +\n>> Git Commits\n>> ~~~~~~~~~~~\n>> `GIT_AUTHOR_NAME`::\n>> diff --git a/environment.h b/environment.h\n>> index 51898c99cd..9bc380bba4 100644\n>> --- a/environment.h\n>> +++ b/environment.h\n>> @@ -42,6 +42,7 @@\n>> #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n>> #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n>> #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n>> +#define GIT_REF_URI_ENVIRONMENT \"GIT_REF_URI\"\n>>\n>> /*\n>> * Environment variable used to propagate the --no-advice global option to the\n>> diff --git a/refs.c b/refs.c\n>> index 23f46867f2..0922f08c9f 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -2186,15 +2186,66 @@ static struct ref_store *get_ref_store_for_dir(struct repository *r,\n>> \treturn maybe_debug_wrap_ref_store(dir, ref_store);\n>> }\n>>\n>> +static struct ref_store *get_ref_store_from_uri(struct repository *repo,\n>> +\t\t\t\t\t\tconst char *uri)\n>> +{\n>> +\tstruct string_list ref_backend_info = STRING_LIST_INIT_DUP;\n>> +\tenum ref_storage_format format;\n>> +\tstruct ref_store *store = NULL;\n>> +\tchar *format_string;\n>> +\tchar *dir;\n>> +\n>> +\tif (!uri || !uri[0]) {\n>> +\t\terror(\"reference backend uri is empty\");\n>> +\t\tgoto cleanup;\n>> +\t}\n>> +\n>> +\tif (string_list_split(&ref_backend_info, uri, \":\", 2) != 2) {\n>> +\t\terror(\"invalid reference backend uri format '%s'\", uri);\n>> +\t\tgoto cleanup;\n>> +\t}\n>> +\n>> +\tformat_string = ref_backend_info.items[0].string;\n>> +\tdir = ref_backend_info.items[1].string + 2;\n>> +\n>> +\tif (!dir || !dir[0]) {\n>> +\t\terror(\"invalid path in uri '%s'\", uri);\n>> +\t\tgoto cleanup;\n>> +\t}\n>> +\n>> +\tformat = ref_storage_format_by_name(format_string);\n>> +\tif (format == REF_STORAGE_FORMAT_UNKNOWN) {\n>> +\t\terror(\"unknown reference backend '%s'\", format_string);\n>> +\t\tgoto cleanup;\n>> +\t}\n>> +\n>> +\tstore = get_ref_store_for_dir(repo, dir, format);\n>\n> Since we don't update the reference format stored in repo, if we were to\n> run:\n>\n> $ GIT_REF_URI=\"reftable:// git repo info references.format\n>\n> it would still report what ever the repository was originally configured\n> with. Since only a single reference backend can be used at time, I\n> wonder if we should go a bit further and update `r->ref_storage_format`\n> to be inline with how the repository reference backend is configured via\n> `GIT_REF_URI`.\n>\n\nUpdating it here won't here won't work, this flow is lazy and only\nevaluated when you actually want to deal with references.\n\nCommands like 'git repo info reference.format' will not trigger this\nflow and will only read the config. I'm also not sure we should be\nmodifying it. Because the output of such a command is to note how the\nrepository is configured. We are not changing that configuration, but\ninstead we're simply asking the git to use a different backend for when\nthe env is provided. What do you think?\n\n> -Justin\n"},{"id":"531215","messageId":"CAOLa=ZTn5UEqifJrJcVfCt=YyVOa3CMdLRsLpG=g4x2vmDPeKQ@mail.gmail.com","threadId":"64513","inReplyTo":"xmqq34675pz1.fsf@gitster.g","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-24T13:25:55Z","receivedAt":"2025-11-24T13:25:58Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano writes:\n\n> Toon Claes writes:\n>\n>>> ://\n>>\n>> I like this idea. This would allow us in the future to also do something\n>> like:\n>>\n>> reftable+nfs://10.11.12.13/ref-dir\n>\n> I actually thought from Karthik's definition that what you are\n> trying to say is spelled more like this:\n>\n> reftable://nfs://10.11.12.13/ref-dir\n>\n\nYou're indeed correct.\n\n> IOW, the underlying URI to \"reach the resource\" is in the \n> part (i.e., \"nfs:///\"). And I found it somewhat a\n> strange syntax, because the \"to reach the resource, visit this\" URI\n> may not necessarily look like , and I also wondered if\n> spelling it like : is more\n> appropriate.\n\nThis is a much better way to state what I was going for, I was\nconsidering the entire : as the URI since currently\nwe only deal with FS paths (for files and reftable). But that could\npotentially change. As such, it makes sense to state it as\n:. Will modify accordingly.\n\nThanks.\n"},{"id":"531216","messageId":"CAOLa=ZScEu6YimZwdgGXSd0+7YGOOy_iL7M4APAMVPJkC7Pn7g@mail.gmail.com","threadId":"64513","inReplyTo":"87pl9b5wos.fsf@iotcl.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-11-24T13:26:38Z","receivedAt":"2025-11-24T13:26:40Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Toon Claes writes:\n\n[snip]\n\n>> diff --git a/refs.c b/refs.c\n>> index 23f46867f2..0922f08c9f 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -2186,15 +2186,66 @@ static struct ref_store *get_ref_store_for_dir(struct repository *r,\n>> \treturn maybe_debug_wrap_ref_store(dir, ref_store);\n>> }\n>>\n>> +static struct ref_store *get_ref_store_from_uri(struct repository *repo,\n>> +\t\t\t\t\t\tconst char *uri)\n>> +{\n>> +\tstruct string_list ref_backend_info = STRING_LIST_INIT_DUP;\n>> +\tenum ref_storage_format format;\n>> +\tstruct ref_store *store = NULL;\n>> +\tchar *format_string;\n>> +\tchar *dir;\n>> +\n>> +\tif (!uri || !uri[0]) {\n>> +\t\terror(\"reference backend uri is empty\");\n>\n> I see no localization on any of the error() or die() messages. I think\n> it's worth to make them translatable.\n>\n\nYeah, that makes sense.\n\n>> +\t\tgoto cleanup;\n>> +\t}\n>> +\n>> +\tif (string_list_split(&ref_backend_info, uri, \":\", 2) != 2) {\n>> +\t\terror(\"invalid reference backend uri format '%s'\", uri);\n>> +\t\tgoto cleanup;\n>> +\t}\n>> +\n>> +\tformat_string = ref_backend_info.items[0].string;\n>> +\tdir = ref_backend_info.items[1].string + 2;\n>\n> Length check before jumping to the third char would be adviced. Also I\n> think it's worth to check if the first two chars are \"//\".\n>\n\nThis is a good point, will add a test and fix this up.\n\n> --\n> Cheers,\n> Toon\n"},{"id":"531297","messageId":"87see1vszo.fsf@iotcl.com","threadId":"64513","inReplyTo":"CAOLa=ZTn5UEqifJrJcVfCt=YyVOa3CMdLRsLpG=g4x2vmDPeKQ@mail.gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2025-11-26T13:11:23Z","receivedAt":"2025-11-26T13:11:36Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Karthik Nayak writes:\n\n> Junio C Hamano writes:\n>\n>> Toon Claes writes:\n>>\n>>>> ://\n>>>\n>>> I like this idea. This would allow us in the future to also do something\n>>> like:\n>>>\n>>> reftable+nfs://10.11.12.13/ref-dir\n>>\n>> I actually thought from Karthik's definition that what you are\n>> trying to say is spelled more like this:\n>>\n>> reftable://nfs://10.11.12.13/ref-dir\n\nLOL, I didn't realize since 07c7782cc8 (Disown ssh+git and git+ssh,\n2016-02-15) 'ssh+git' isn't actually mentioned no more.\n\n>> IOW, the underlying URI to \"reach the resource\" is in the \n>> part (i.e., \"nfs:///\"). And I found it somewhat a\n>> strange syntax, because the \"to reach the resource, visit this\" URI\n>> may not necessarily look like , and I also wondered if\n>> spelling it like : is more\n>> appropriate.\n>\n> This is a much better way to state what I was going for, I was\n> considering the entire : as the URI since currently\n> we only deal with FS paths (for files and reftable). But that could\n> potentially change. As such, it makes sense to state it as\n> :. Will modify accordingly.\n\nI don't really care on the format, as long as we're consistent. I know\nPatrick is working on pluggable object databases and also there he's\nsuggesting to do `://` which might also lead to\ndouble `://` use. But I guess that's still subjected to change.\n\nThat said. Should we change the current proposal of\n`://` to `:file://`? Or can we\nsimply assume the latter implied from the former?\n\n\n-- \nCheers,\nToon\n"},{"id":"531508","messageId":"aS2V4TKeS4V_oxAb@pks.im","threadId":"64513","inReplyTo":"xmqq34651ie5.fsf@gitster.g","subject":"Re: [PATCH 0/2] refs: allow setting the reference directory","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-12-01T13:19:29Z","receivedAt":"2025-12-01T13:19:35Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Nov 22, 2025 at 08:29:22PM -0800, Junio C Hamano wrote:\n> Karthik Nayak writes:\n> \n> > While Git allows users to select different reference backends, unlike\n> > with objects, there is no flexibility in selecting the reference\n> > directory. Currently, the reference format is obtained from the config\n> > of the repository and the reference directory is set to the $GIT_DIR.\n> \n> I actually am not sure if I like the proposed environment variable.\n> \n> The proposal is based on an assumption that any reference backend\n> should be able to move their backing store anywhere, and they should\n> be able to express the location of their backing store as a single\n> string . For a new backend, \"where is your backing store\" may\n> not even be a question that does not make much sense (as \"somewhere\n> in the cloud that you do not even have to know\" is certainly\n> possible), and even for a new backend design that does allow such a\n> question to have a meaningful answer, this \"you have to be able to\n> use a random place specified by this environment variable as your\n> backing storage\" is an additional requirement that its implementors\n> may not need to satisfy in order to please their user base.\n> \n> For reftable and files backends, these assumptions may be true, but\n> then it is not too cumbersome if these stay to be backend specific,\n> as there are only two backends.\n\nI think it's a reasonable assumption to make that the path _can_ be\nrepresented as a single string. For now, we don't really require any\nconfiguration for the backend in the first place. So all you need to do\nis to say:\n\n [extension]\n refStorage = reftable\n\nThis implicitly identifies the location of the backend, too, as we\nderive it from the commondir/gitdir. As you say that's sufficient for\nthe \"files\" and \"reftable\" backends, but it may be insufficient for\nother backends.\n\nSuppose that we for example have a Postgres database to store data. It's\nclearly not sufficient to specify \"extension.refStorage=postgres\", as\nthat wouldn't give you enough information to also know how to connect to\nthe database.\n\nIt's a problem I have been thinking about quite a lot in the context of\npluggable object databases, as well. Ultimately, the solution I arrived\nat is to extend the extension format itself. For pluggable ODBs this\nwould look like this:\n\n [extension]\n objectStorage = postgres://127.0.0.1:5432?database=myrepo\n\nThis is similar to a normal URI with a schema: everything before the\n\"://\" identifies the format that is to be used, and everything after is\nthen passed as-is to the backend itself. I think this should give us\nenough flexibility for any future formats and it is easy enough to\nconfigure. The added benefit is that this can also work in contexts like\nthe GIT_OBJECT_DIRECTORY and GIT_ALTERNATE_OBJECT_DIRECTORIES\nenvironment variables, even though their naming is off now.\n\nFor the reference storage I think we should be moving into a similar\ndirection. Sure, for the current formats that we know its sufficient to\nonly specify their directory. But I think we should treat the directory\nas an opaque string and then let the reference backend handle it, same\nas with the proposed format for object databases:\n\n # A schema-only variable will be treated as if we specified the\n # common directory.\n [extension]\n refStorage = reftable\n\n # It's also possible to explicitly specify a different location for\n # the backend.\n [extension]\n refStorage = reftable:///foo/bar\n\n # And same as above, we can also specify non-locations.\n [extension]\n refStorage = postgres://127.0.0.1:5432?database=myrepo\n\nAs said, the important thing here is that the reference backends get the\nstring after the schema as opaque blobs that they can self-interpret.\n\n> So I dunno. In addition, if this is designed to help migration\n> (which is the impression I am getting from the cover letter\n> description), don't you need a way to specify more than one (i.e.,\n> source to migrate from and destination to migrate to)? With a\n> single GIT_REF_URI, it would not be obvious what it refers to,\n> whether it is an additional place to write to, to read from, or\n> something completely unrelated. For example ...\n\nI think we cannot easily retrofit handling of multiple refdbs into Git\nat this point in time anymore. The way to drive this would be that we\nhave two processes:\n\n - One `git refs list` process in the repository that uses the old\n format.\n\n - One `git update-ref --stdin` process in the repository that uses the\n new format specified via GIT_REF_URI.\n\nThis allows us to do an online migration of data into a separate ref\nstore.\n\n> > This patch series adds a new ENV variable 'GIT_REF_URI' which takes the\n> > reference backend and path in a URI form:\n> >\n> > ://\n> >\n> > For e.g. 'reftable:///foo' or 'files://$GIT_DIR/ref_migration.0xBsa0'.\n> >\n> > One use case for this is migration between different backends. On the\n> > server side, migrating from the files backend to the newly introduced\n> > reftable backend can be achieved by running 'git refs migrate'. However,\n> > for large repositories with millions of references, this migration can\n> > take from seconds to minutes.\n> >\n> > We could make the migration non-blocking by running the migration in the\n> > background and capturing and replaying updates to both backends. This\n> > would require Git to support writing references to different reference\n> > backends and paths.\n> \n> ... I am reading that the above is saying that the system will write\n> to whatever reference backend specified in the extension.refStorage,\n> plus also where GIT_REF_URI points at, but if that is the way how\n> the mechanism works, the variable should be named more specific to\n> what it does, no? It is not just a random \"REF URI\"; it is an\n> additional ref backend that the updates are dumped to. Maybe there\n> would be a different use case where you may want to read from two\n> reference backends, and you'd need to specify the secondary one with\n> an environment variable, but if the system behaves one specific way\n> for GIT_REF_URI (say, all updates are also copied to this additional\n> ref backend at the specified ref backing store), a different\n> environment variable name needs to be chosen to serve such a\n> different use case, no?\n\nTruth be told, I'm not realy a huge fan of the name, either. But as\nsaid, I don't think we can easily \"overlay\" multiple refdbs, as it would\nlead to various different questions due to our hierarchical layout of\nreferences.\n\nThat being said, I personally would prefer `GIT_REFERENCE_BACKEND` as\nvariable name that accepts exactly the same kind of strings as the\n`extension.refStorage` values I have proposed above.\n\nThanks!\n\nPatrick\n"},{"id":"531513","messageId":"aS2X7pI8muco7a1Z@pks.im","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-2-4cf4a94c8bed@gmail.com","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-12-01T13:28:14Z","receivedAt":"2025-12-01T13:28:21Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Nov 19, 2025 at 10:48:53PM +0100, Karthik Nayak wrote:\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n> This asymmetry makes it difficult to test different reference backends\n> or use alternative reference storage locations without modifying the\n> repository structure.\n> \n> Add a new environment variable 'GIT_REF_URI' that specifies both the\n> reference backend and directory path using a URI format:\n> \n> ://\n> \n> When set, this variable is used to obtain the main reference store for\n> all Git commands. The variable is checked in `get_main_ref_store()`\n> when lazily assigning `repo->refs_private`. We cannot initialize this\n> earlier in `repo_set_gitdir()` because the repository's hash algorithm\n> isn't known at that point, and the reftable backend requires this\n> information during initialization.\n> \n> When used with worktrees, the specified directory is treated as the\n> reference directory for all worktree operations.\n> \n> Add a new test file 't1423-ref-backend.sh' to test this environment\n> variable.\n\nBased on my reply in I wonder whether we want\nto take a bit of a different approach:\n\n - We extend the format understood by \"extensions.refStorage\" to\n understand \"schema://data\"-style strings and adapt the \"data\" part\n to be passed through to the reference backend.\n\n - We then use the same mechanism to parse both \"extensions.refStorage\"\n and the environment variable.\n\nThis would have a couple advantages:\n\n - We make the ref storage extension more flexible so that you can move\n your reference backends somewhere else entirely.\n\n - We prepare for a potential future ref format that _needs_ to receive\n data as input.\n\n - We have consistent behaviour between the environment variable and\n the extension. So basically, the environment variable starts to\n behave as an override to the extension.\n\nOne issue that we'd then have to solve is how to derive the worktree\nreferences from the backend. Arguably though, I think that the extension\nthat was specified should also be sufficient to identify the location of\nthe worktree references.\n\nWe'd have to refactor the code base a bit though to properly reflect\nthat in our tree. One way to do this is to extend `ref_store_init()` so\nthat it receives the worktree (or NULL) as input. In that case, we would\ncontinue to pass the combination of format and \"data\" to the init\nfunction, and it would then know to locate the worktree references\nitself.\n\nWhat do you think?\n\nThanks!\n\nPatrick\n"},{"id":"531545","messageId":"xmqq7bv589ks.fsf@gitster.g","threadId":"64513","inReplyTo":"aS2V4TKeS4V_oxAb@pks.im","subject":"Re: [PATCH 0/2] refs: allow setting the reference directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-02T10:25:07Z","receivedAt":"2025-12-02T10:25:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> For the reference storage I think we should be moving into a similar\n> direction. Sure, for the current formats that we know its sufficient to\n> only specify their directory. But I think we should treat the directory\n> as an opaque string and then let the reference backend handle it, same\n> as with the proposed format for object databases:\n>\n> # A schema-only variable will be treated as if we specified the\n> # common directory.\n> [extension]\n> refStorage = reftable\n>\n> # It's also possible to explicitly specify a different location for\n> # the backend.\n> [extension]\n> refStorage = reftable:///foo/bar\n>\n> # And same as above, we can also specify non-locations.\n> [extension]\n> refStorage = postgres://127.0.0.1:5432?database=myrepo\n\nCute. I kinda like it ;-)\n\n\n"},{"id":"531562","messageId":"CAOLa=ZQLUjgKkoSExd=zBO8bfXR212M=_rTUaACjZUOR0e6v7A@mail.gmail.com","threadId":"64513","inReplyTo":"aS2V4TKeS4V_oxAb@pks.im","subject":"Re: [PATCH 0/2] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-12-02T15:29:11Z","receivedAt":"2025-12-02T15:29:14Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Sat, Nov 22, 2025 at 08:29:22PM -0800, Junio C Hamano wrote:\n>> Karthik Nayak writes:\n>>\n>> > While Git allows users to select different reference backends, unlike\n>> > with objects, there is no flexibility in selecting the reference\n>> > directory. Currently, the reference format is obtained from the config\n>> > of the repository and the reference directory is set to the $GIT_DIR.\n>>\n>> I actually am not sure if I like the proposed environment variable.\n>>\n>> The proposal is based on an assumption that any reference backend\n>> should be able to move their backing store anywhere, and they should\n>> be able to express the location of their backing store as a single\n>> string . For a new backend, \"where is your backing store\" may\n>> not even be a question that does not make much sense (as \"somewhere\n>> in the cloud that you do not even have to know\" is certainly\n>> possible), and even for a new backend design that does allow such a\n>> question to have a meaningful answer, this \"you have to be able to\n>> use a random place specified by this environment variable as your\n>> backing storage\" is an additional requirement that its implementors\n>> may not need to satisfy in order to please their user base.\n>>\n>> For reftable and files backends, these assumptions may be true, but\n>> then it is not too cumbersome if these stay to be backend specific,\n>> as there are only two backends.\n>\n> I think it's a reasonable assumption to make that the path _can_ be\n> represented as a single string. For now, we don't really require any\n> configuration for the backend in the first place. So all you need to do\n> is to say:\n>\n> [extension]\n> refStorage = reftable\n>\n> This implicitly identifies the location of the backend, too, as we\n> derive it from the commondir/gitdir. As you say that's sufficient for\n> the \"files\" and \"reftable\" backends, but it may be insufficient for\n> other backends.\n>\n> Suppose that we for example have a Postgres database to store data. It's\n> clearly not sufficient to specify \"extension.refStorage=postgres\", as\n> that wouldn't give you enough information to also know how to connect to\n> the database.\n>\n> It's a problem I have been thinking about quite a lot in the context of\n> pluggable object databases, as well. Ultimately, the solution I arrived\n> at is to extend the extension format itself. For pluggable ODBs this\n> would look like this:\n>\n> [extension]\n> objectStorage = postgres://127.0.0.1:5432?database=myrepo\n>\n> This is similar to a normal URI with a schema: everything before the\n> \"://\" identifies the format that is to be used, and everything after is\n> then passed as-is to the backend itself. I think this should give us\n> enough flexibility for any future formats and it is easy enough to\n> configure. The added benefit is that this can also work in contexts like\n> the GIT_OBJECT_DIRECTORY and GIT_ALTERNATE_OBJECT_DIRECTORIES\n> environment variables, even though their naming is off now.\n>\n> For the reference storage I think we should be moving into a similar\n> direction. Sure, for the current formats that we know its sufficient to\n> only specify their directory. But I think we should treat the directory\n> as an opaque string and then let the reference backend handle it, same\n> as with the proposed format for object databases:\n>\n> # A schema-only variable will be treated as if we specified the\n> # common directory.\n> [extension]\n> refStorage = reftable\n>\n> # It's also possible to explicitly specify a different location for\n> # the backend.\n> [extension]\n> refStorage = reftable:///foo/bar\n>\n> # And same as above, we can also specify non-locations.\n> [extension]\n> refStorage = postgres://127.0.0.1:5432?database=myrepo\n>\n> As said, the important thing here is that the reference backends get the\n> string after the schema as opaque blobs that they can self-interpret.\n>\n\nI think you bring in some good points here, I didn't think of\n`extension.refStorage` and I think we can extend that like you\nmentioned, while staying backwards compatible.\n\n>> So I dunno. In addition, if this is designed to help migration\n>> (which is the impression I am getting from the cover letter\n>> description), don't you need a way to specify more than one (i.e.,\n>> source to migrate from and destination to migrate to)? With a\n>> single GIT_REF_URI, it would not be obvious what it refers to,\n>> whether it is an additional place to write to, to read from, or\n>> something completely unrelated. For example ...\n>\n> I think we cannot easily retrofit handling of multiple refdbs into Git\n> at this point in time anymore. The way to drive this would be that we\n> have two processes:\n>\n> - One `git refs list` process in the repository that uses the old\n> format.\n>\n> - One `git update-ref --stdin` process in the repository that uses the\n> new format specified via GIT_REF_URI.\n>\n> This allows us to do an online migration of data into a separate ref\n> store.\n>\n\nThat's exactly the mechanism I was talking about, thanks for explaining.\n\n>> > This patch series adds a new ENV variable 'GIT_REF_URI' which takes the\n>> > reference backend and path in a URI form:\n>> >\n>> > ://\n>> >\n>> > For e.g. 'reftable:///foo' or 'files://$GIT_DIR/ref_migration.0xBsa0'.\n>> >\n>> > One use case for this is migration between different backends. On the\n>> > server side, migrating from the files backend to the newly introduced\n>> > reftable backend can be achieved by running 'git refs migrate'. However,\n>> > for large repositories with millions of references, this migration can\n>> > take from seconds to minutes.\n>> >\n>> > We could make the migration non-blocking by running the migration in the\n>> > background and capturing and replaying updates to both backends. This\n>> > would require Git to support writing references to different reference\n>> > backends and paths.\n>>\n>> ... I am reading that the above is saying that the system will write\n>> to whatever reference backend specified in the extension.refStorage,\n>> plus also where GIT_REF_URI points at, but if that is the way how\n>> the mechanism works, the variable should be named more specific to\n>> what it does, no? It is not just a random \"REF URI\"; it is an\n>> additional ref backend that the updates are dumped to. Maybe there\n>> would be a different use case where you may want to read from two\n>> reference backends, and you'd need to specify the secondary one with\n>> an environment variable, but if the system behaves one specific way\n>> for GIT_REF_URI (say, all updates are also copied to this additional\n>> ref backend at the specified ref backing store), a different\n>> environment variable name needs to be chosen to serve such a\n>> different use case, no?\n>\n> Truth be told, I'm not realy a huge fan of the name, either. But as\n> said, I don't think we can easily \"overlay\" multiple refdbs, as it would\n> lead to various different questions due to our hierarchical layout of\n> references.\n>\n> That being said, I personally would prefer `GIT_REFERENCE_BACKEND` as\n> variable name that accepts exactly the same kind of strings as the\n> `extension.refStorage` values I have proposed above.\n>\n\nFair enough. Once both the env variable and `extension.refStorage` take\nin the same input, it does make sense to rename the env variable to\n`GIT_REFERENCE_BACKEND`.\n\n> Thanks!\n>\n> Patrick\n\nThanks for your input. I'll make the necessary changes for v4 :)\n"},{"id":"531590","messageId":"CAOLa=ZR+YaWmqUxz+OjtKP88hWj5BEKwpvY78vrgWdoJecEwkQ@mail.gmail.com","threadId":"64513","inReplyTo":"aS2X7pI8muco7a1Z@pks.im","subject":"Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-12-02T22:21:53Z","receivedAt":"2025-12-02T22:21:55Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Wed, Nov 19, 2025 at 10:48:53PM +0100, Karthik Nayak wrote:\n>> Git allows setting a different object directory via\n>> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.\n>> This asymmetry makes it difficult to test different reference backends\n>> or use alternative reference storage locations without modifying the\n>> repository structure.\n>>\n>> Add a new environment variable 'GIT_REF_URI' that specifies both the\n>> reference backend and directory path using a URI format:\n>>\n>> ://\n>>\n>> When set, this variable is used to obtain the main reference store for\n>> all Git commands. The variable is checked in `get_main_ref_store()`\n>> when lazily assigning `repo->refs_private`. We cannot initialize this\n>> earlier in `repo_set_gitdir()` because the repository's hash algorithm\n>> isn't known at that point, and the reftable backend requires this\n>> information during initialization.\n>>\n>> When used with worktrees, the specified directory is treated as the\n>> reference directory for all worktree operations.\n>>\n>> Add a new test file 't1423-ref-backend.sh' to test this environment\n>> variable.\n>\n> Based on my reply in I wonder whether we want\n> to take a bit of a different approach:\n>\n> - We extend the format understood by \"extensions.refStorage\" to\n> understand \"schema://data\"-style strings and adapt the \"data\" part\n> to be passed through to the reference backend.\n>\n> - We then use the same mechanism to parse both \"extensions.refStorage\"\n> and the environment variable.\n>\n> This would have a couple advantages:\n>\n> - We make the ref storage extension more flexible so that you can move\n> your reference backends somewhere else entirely.\n>\n> - We prepare for a potential future ref format that _needs_ to receive\n> data as input.\n>\n> - We have consistent behaviour between the environment variable and\n> the extension. So basically, the environment variable starts to\n> behave as an override to the extension.\n>\n\nI did read/respond to your reply there and I agree with your suggested\napproach. An additional advantage would be that this would also mean the\nENV variable is more deeply integrated. So the backend override added by\nthe ENV variable would also show up when running `git repo info`.\n\n> One issue that we'd then have to solve is how to derive the worktree\n> references from the backend. Arguably though, I think that the extension\n> that was specified should also be sufficient to identify the location of\n> the worktree references.\n>\n> We'd have to refactor the code base a bit though to properly reflect\n> that in our tree. One way to do this is to extend `ref_store_init()` so\n> that it receives the worktree (or NULL) as input. In that case, we would\n> continue to pass the combination of format and \"data\" to the init\n> function, and it would then know to locate the worktree references\n> itself.\n>\n\nYeah, I'm considering adding this information to the `repository`\nstructure, so along with `ref_storage_format`, it would also contain a\n`ref_storage_data` which would be passed down to `get_main_ref_store()`\nwhich would in-turn call `ref_store_init()`.\n\nIn that sense, when in a worktree the $GIT_DIR is set appropriately and\nthis should all work accordingly.\n\n> What do you think?\n>\n> Thanks!\n>\n> Patrick\n\nSounds great. Thanks for the input\n"},{"id":"534965","messageId":"20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH v4 0/4] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-02T12:26:29Z","receivedAt":"2026-02-02T12:27:04Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"While Git allows users to select different reference backends, unlike\nwith objects, there is no flexibility in selecting the reference\ndirectory. Currently, the reference format is obtained from the config\nof the repository and the reference directory is set to the $GIT_DIR.\n\nThis patch extends the config 'extensions.refStorage' to take in\nmultiple forms of inputs:\n\n - A format name alone (e.g., `reftable` or `files`) which uses the\n default location (the repository's common directory).\n\n - A URI format `://` which explicitly specifies\n both the format and location (e.g., `reftable:///foo/bar`).\n\nWe also add in a new ENV variable GIT_REFERENCE_BACKEND which can be\nused to override the config.\n\nOne use case for this is migration between different backends. On the\nserver side, migrating from the files backend to the newly introduced\nreftable backend can be achieved by running 'git refs migrate'. However,\nfor large repositories with millions of references, this migration can\ntake from seconds to minutes.\n\nFor some background, at GitLab, the criteria for our migration was to\nreduce the downtime of the migrate ideally to zero. So running 'git refs\nmigrate --ref-format=reftable' by itself wouldn't work, since it scales\nwith the number of references and we have repos with millions of\nreferences, so we need to migrate without loosing any information. We\ncame up with the following plan:\n\n 1. Run git-pack-refs(1) and note timestamp of the generated packed-refs\n file.\n 2. Run git refs migrate –dry-run.\n 3. If there are no ongoing reference requests (read/write)\n a. Lock the repository by blocking incoming requests (done on a\n layer above git, in Gitaly [1]).\n b. If the timestamp of the packed-refs file has changed, unlock\n the repo and repeat from step 1.\n c. Apply all the loose refs to the dry-run reftable folder (this\n requires support in Git to write refs to arbitrary folder).\n d. Move the reftable dry-run folder into the GIT_DIR.\n e. Swap the repo config\n f. Unlock repo access\n\nUsing such a route, scales much better since we only have to worry about\nblocking the repository by O(ref written between #1 and #3a) and not\nO(refs in repo). But for doing so, we need to be able to write to a\narbitrary reference backend + path. This is to add the missing\nreferences to the dry-run reftable folder. This series, achieves that.\n\nSince there was a long gap between v3 <> v4, the version 4 onward is\nbased on top of 2258446484 (RelNotes: correct \"fast-import\" option name,\n2026-01-30).\n\n[1]: https://gitlab.com/gitlab-org/gitaly\n\n---\nChanges in v4:\n- Mostly re-wrote the code to also support worktree. Now, the existing\n backends will store worktree references in 'ref_dir/worktrees/wt_id'\n and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n- We also support relative paths in the reference directories. These\n relative paths are resolved relative to the GIT_DIR.\n- Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n\nChanges in v3:\n- Cleanup some stale code which wasn't removed.\n- Localize strings which will be output to the user.\n- Remove additional defensive checks which are not needed.\n- Link to v2: https://patch.msgid.link/20251126-kn-alternate-ref-dir-v2-0-8b9f6f18f635@gmail.com\n\nChanges in v2:\n- Added more clarification and proper intent in the cover message.\n- Changed the format from '://' to\n `://` as it much clearer.\n- Added logic to check for the '//' in the provided URI and a test for\n the same.\n- In the tests:\n - Use test_must_fail() instead of ! git\n - Fix looped tests not using the variables correctly and ensure that\n the test description is correct.\n- Link to v1: https://patch.msgid.link/20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com\n\n---\n Documentation/config/extensions.adoc | 16 ++-\n Documentation/git.adoc | 5 +\n builtin/clone.c | 10 +-\n builtin/worktree.c | 35 +++++++\n environment.h | 1 +\n refs.c | 61 +++++++++++-\n refs.h | 13 +++\n refs/files-backend.c | 18 +++-\n refs/packed-backend.c | 1 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 15 +++\n refs/reftable-backend.c | 38 +++----\n repository.c | 9 +-\n repository.h | 5 +-\n setup.c | 59 ++++++++++-\n setup.h | 2 +\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 187 +++++++++++++++++++++++++++++++++++\n 18 files changed, 433 insertions(+), 44 deletions(-)\n\nKarthik Nayak (4):\n refs: allow reference location in refstorage config\n refs: extract out `refs_create_refdir_stubs()`\n refs: parse and use the reference storage payload\n refs: add GIT_REFERENCE_BACKEND to specify reference backend\n\nRange-diff versus v3:\n\n1: a91a4d5ba3 < -: ---------- refs: support obtaining ref_store for given dir\n2: a9f126d724 < -: ---------- refs: add GIT_REF_URI to specify reference backend and directory\n-: ---------- > 1: c8ddb8ec8d refs: allow reference location in refstorage config\n-: ---------- > 2: 02acdc16b4 refs: extract out `refs_create_refdir_stubs()`\n-: ---------- > 3: 1b0e17e705 refs: parse and use the reference storage payload\n-: ---------- > 4: 8ca379edd6 refs: add GIT_REFERENCE_BACKEND to specify reference backend\n\n\nbase-commit: 22584464849815268419fd9d2eba307362360db1\nchange-id: 20251105-kn-alternate-ref-dir-3e572e8cd0ef\n\nThanks\n- Karthik\n\n"},{"id":"534966","messageId":"20260202-kn-alternate-ref-dir-v4-1-3b30430411e3@gmail.com","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com","subject":"[PATCH v4 1/4] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-02T12:26:30Z","receivedAt":"2026-02-02T12:27:05Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'extensions.refStorage' config is used to specify the reference\nbackend for a given repository. Both the 'files' and 'reftable' backends\nutilize the $GIT_DIR as the reference folder by default in\n`get_main_ref_store()`.\n\nSince the reference backends are pluggable, this means that they should\nwork with out-of-tree reference directories too. Extend the 'refStorage'\nconfig to also support taking an URI input, where users can specify the\nreference backend and the location.\n\nAdd the required changes to obtain and propagate this value to the\nindividual backends. A follow up commit will add the required changes on\nthe backends to parse this value.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 3 ++-\n repository.c | 9 +++++++--\n repository.h | 5 ++++-\n setup.c | 39 ++++++++++++++++++++++++++++++++++-----\n setup.h | 2 ++\n 5 files changed, 49 insertions(+), 9 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex b40cee5968..28412576b3 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1442,7 +1442,8 @@ int cmd_clone(int argc,\n \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n \trepo_set_hash_algo(the_repository, hash_algo);\n-\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n+\tcreate_reference_database(the_repository->ref_storage_format,\n+\t\t\t\t the_repository->ref_storage_payload, NULL, 1);\n \n \t/*\n \t * Before fetching from the remote, download and install bundle\ndiff --git a/repository.c b/repository.c\nindex c7e75215ac..9815f081ef 100644\n--- a/repository.c\n+++ b/repository.c\n@@ -193,9 +193,12 @@ void repo_set_compat_hash_algo(struct repository *repo, int algo)\n }\n \n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format)\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload)\n {\n \trepo->ref_storage_format = format;\n+\tfree(repo->ref_storage_payload);\n+\trepo->ref_storage_payload = xstrdup_or_null(payload);\n }\n \n /*\n@@ -277,7 +280,8 @@ int repo_init(struct repository *repo,\n \n \trepo_set_hash_algo(repo, format.hash_algo);\n \trepo_set_compat_hash_algo(repo, format.compat_hash_algo);\n-\trepo_set_ref_storage_format(repo, format.ref_storage_format);\n+\trepo_set_ref_storage_format(repo, format.ref_storage_format,\n+\t\t\t\t format.ref_storage_payload);\n \trepo->repository_format_worktree_config = format.worktree_config;\n \trepo->repository_format_relative_worktrees = format.relative_worktrees;\n \trepo->repository_format_precious_objects = format.precious_objects;\n@@ -369,6 +373,7 @@ void repo_clear(struct repository *repo)\n \tFREE_AND_NULL(repo->index_file);\n \tFREE_AND_NULL(repo->worktree);\n \tFREE_AND_NULL(repo->submodule_prefix);\n+\tFREE_AND_NULL(repo->ref_storage_payload);\n \n \todb_free(repo->objects);\n \trepo->objects = NULL;\ndiff --git a/repository.h b/repository.h\nindex 6063c4b846..c648dab196 100644\n--- a/repository.h\n+++ b/repository.h\n@@ -150,6 +150,8 @@ struct repository {\n \n \t/* Repository's reference storage format, as serialized on disk. */\n \tenum ref_storage_format ref_storage_format;\n+\t/* Reference storage information as needed for the backend. */\n+\tchar *ref_storage_payload;\n \n \t/* A unique-id for tracing purposes. */\n \tint trace2_repo_id;\n@@ -204,7 +206,8 @@ void repo_set_worktree(struct repository *repo, const char *path);\n void repo_set_hash_algo(struct repository *repo, int algo);\n void repo_set_compat_hash_algo(struct repository *repo, int compat_algo);\n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format);\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload);\n void initialize_repository(struct repository *repo);\n RESULT_MUST_BE_USED\n int repo_init(struct repository *r, const char *gitdir, const char *worktree);\ndiff --git a/setup.c b/setup.c\nindex b723f8b339..44e393c251 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -632,6 +632,21 @@ static enum extension_result handle_extension_v0(const char *var,\n \t\treturn EXTENSION_UNKNOWN;\n }\n \n+static void parse_reference_uri(const char *value, char **format,\n+\t\t\t\tchar **payload)\n+{\n+\tchar *schema_end;\n+\n+\tschema_end = strstr(value, \"://\");\n+\tif (!schema_end) {\n+\t\t*format = xstrdup(value);\n+\t\t*payload = NULL;\n+\t} else {\n+\t\t*format = xstrndup(value, schema_end - value);\n+\t\t*payload = xstrdup_or_null(schema_end + 3);\n+\t}\n+}\n+\n /*\n * Record any new extensions in this function.\n */\n@@ -674,10 +689,17 @@ static enum extension_result handle_extension(const char *var,\n \t\treturn EXTENSION_OK;\n \t} else if (!strcmp(ext, \"refstorage\")) {\n \t\tunsigned int format;\n+\t\tchar *format_str;\n \n \t\tif (!value)\n \t\t\treturn config_error_nonbool(var);\n-\t\tformat = ref_storage_format_by_name(value);\n+\n+\t\tparse_reference_uri(value, &format_str,\n+\t\t\t\t &data->ref_storage_payload);\n+\n+\t\tformat = ref_storage_format_by_name(format_str);\n+\t\tfree(format_str);\n+\n \t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n \t\t\treturn error(_(\"invalid value for '%s': '%s'\"),\n \t\t\t\t \"extensions.refstorage\", value);\n@@ -850,6 +872,7 @@ void clear_repository_format(struct repository_format *format)\n \tstring_list_clear(&format->v1_only_extensions, 0);\n \tfree(format->work_tree);\n \tfree(format->partial_clone);\n+\tfree(format->ref_storage_payload);\n \tinit_repository_format(format);\n }\n \n@@ -1942,7 +1965,8 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\t\trepo_set_compat_hash_algo(the_repository,\n \t\t\t\t\t\t repo_fmt.compat_hash_algo);\n \t\t\trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t\t\t repo_fmt.ref_storage_format);\n+\t\t\t\t\t\t repo_fmt.ref_storage_format,\n+\t\t\t\t\t\t repo_fmt.ref_storage_payload);\n \t\t\tthe_repository->repository_format_worktree_config =\n \t\t\t\trepo_fmt.worktree_config;\n \t\t\tthe_repository->repository_format_relative_worktrees =\n@@ -2042,7 +2066,8 @@ void check_repository_format(struct repository_format *fmt)\n \trepo_set_hash_algo(the_repository, fmt->hash_algo);\n \trepo_set_compat_hash_algo(the_repository, fmt->compat_hash_algo);\n \trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t fmt->ref_storage_format);\n+\t\t\t\t fmt->ref_storage_format,\n+\t\t\t\t fmt->ref_storage_payload);\n \tthe_repository->repository_format_worktree_config =\n \t\tfmt->worktree_config;\n \tthe_repository->repository_format_relative_worktrees =\n@@ -2360,13 +2385,15 @@ static int is_reinit(void)\n }\n \n void create_reference_database(enum ref_storage_format ref_storage_format,\n+\t\t\t const char *ref_storage_payload,\n \t\t\t const char *initial_branch, int quiet)\n {\n \tstruct strbuf err = STRBUF_INIT;\n \tchar *to_free = NULL;\n \tint reinit = is_reinit();\n \n-\trepo_set_ref_storage_format(the_repository, ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, ref_storage_format,\n+\t\t\t\t ref_storage_payload);\n \tif (ref_store_create_on_disk(get_main_ref_store(the_repository), 0, &err))\n \t\tdie(\"failed to set up refs db: %s\", err.buf);\n \n@@ -2645,7 +2672,8 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n-\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n+\t\t\t\t repo_fmt->ref_storage_payload);\n }\n \n int init_db(const char *git_dir, const char *real_git_dir,\n@@ -2702,6 +2730,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n \n \tif (!(flags & INIT_DB_SKIP_REFDB))\n \t\tcreate_reference_database(repo_fmt.ref_storage_format,\n+\t\t\t\t\t repo_fmt.ref_storage_payload,\n \t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n \tcreate_object_directory();\n \ndiff --git a/setup.h b/setup.h\nindex d55dcc6608..4d25a353ac 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -171,6 +171,7 @@ struct repository_format {\n \tint hash_algo;\n \tint compat_hash_algo;\n \tenum ref_storage_format ref_storage_format;\n+\tchar *ref_storage_payload;\n \tint sparse_index;\n \tchar *work_tree;\n \tstruct string_list unknown_extensions;\n@@ -241,6 +242,7 @@ void initialize_repository_version(int hash_algo,\n \t\t\t\t enum ref_storage_format ref_storage_format,\n \t\t\t\t int reinit);\n void create_reference_database(enum ref_storage_format ref_storage_format,\n+\t\t\t const char *ref_storage_payload,\n \t\t\t const char *initial_branch, int quiet);\n \n /*\n\n-- \n2.52.0\n\n"},{"id":"534967","messageId":"20260202-kn-alternate-ref-dir-v4-2-3b30430411e3@gmail.com","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com","subject":"[PATCH v4 2/4] refs: extract out `refs_create_refdir_stubs()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-02T12:26:31Z","receivedAt":"2026-02-02T12:27:05Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"For Git to recognize a directory as a Git directory, it requires the\ndirectory to contain:\n\n 1. 'HEAD' file\n 2. object/ directory\n 3. 'refs/' directory\n\nHere, #1 and #3 are part of the reference storage mechanism,\nspecifically the files backend. Since then, newer backends such as the\nreftable backend have moved to using their own path ('reftable/') for\nstoring references. But to ensure git still recognizes the directory as\na Git directory, we create stubs.\n\nThere are two locations we create stubs:\n\n- In 'refs/reftable-backend.c' when creating the reftable backend.\n- In 'clone.c' before spawning transport helpers.\n\nIn a following commit, we'll add another instance. So instead of\nrepeating the code, let's extract out this code to\n`refs_create_refdir_stubs()` and use it.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 7 +------\n refs.c | 24 ++++++++++++++++++++++++\n refs.h | 13 +++++++++++++\n refs/reftable-backend.c | 14 ++------------\n 4 files changed, 40 insertions(+), 18 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex 28412576b3..11854894d3 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1225,12 +1225,7 @@ int cmd_clone(int argc,\n \tinitialize_repository_version(GIT_HASH_UNKNOWN,\n \t\t\t\t the_repository->ref_storage_format, 1);\n \n-\tstrbuf_addf(&buf, \"%s/HEAD\", git_dir);\n-\twrite_file(buf.buf, \"ref: refs/heads/.invalid\");\n-\n-\tstrbuf_reset(&buf);\n-\tstrbuf_addf(&buf, \"%s/refs\", git_dir);\n-\tsafe_create_dir(the_repository, buf.buf, 1);\n+\trefs_create_refdir_stubs(the_repository, git_dir, NULL);\n \n \t/*\n \t * additional config can be injected with -c, make sure it's included\ndiff --git a/refs.c b/refs.c\nindex 627b7f8698..32b4edaf2d 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -3402,3 +3402,27 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n \t\treturn \"unknown failure\";\n \t}\n }\n+\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_msg)\n+{\n+\tstruct strbuf path = STRBUF_INIT;\n+\n+\n+\tstrbuf_addf(&path, \"%s/HEAD\", refdir);\n+\twrite_file(path.buf, \"ref: refs/heads/.invalid\");\n+\tadjust_shared_perm(repo, path.buf);\n+\n+\tstrbuf_reset(&path);\n+\tstrbuf_addf(&path, \"%s/refs\", refdir);\n+\tsafe_create_dir(repo, path.buf, 1);\n+\n+\tif (refs_heads_msg) {\n+\t\tstrbuf_reset(&path);\n+\t\tstrbuf_addf(&path, \"%s/refs/heads\", refdir);\n+\t\twrite_file(path.buf, \"%s\", refs_heads_msg);\n+\t\tadjust_shared_perm(repo, path.buf);\n+\t}\n+\n+\tstrbuf_release(&path);\n+}\ndiff --git a/refs.h b/refs.h\nindex f0abfa1d93..9d8890fdff 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -1427,4 +1427,17 @@ void ref_iterator_free(struct ref_iterator *ref_iterator);\n int do_for_each_ref_iterator(struct ref_iterator *iter,\n \t\t\t each_ref_fn fn, void *cb_data);\n \n+/*\n+ * Git only recognizes a directory as a repository if it contains:\n+ * - HEAD file\n+ * - refs/ folder\n+ * While it is necessary within the files backend, newer backends may not\n+ * follow the same structure. To go around this, we create stubs as necessary.\n+ *\n+ * If provided with a 'refs_heads_msg', we create the 'refs/heads/head' file\n+ * with the provided message.\n+ */\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_msg);\n+\n #endif /* REFS_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex fe74af73af..d8651fe779 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,18 +491,8 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"ref: refs/heads/.invalid\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tsafe_create_dir(the_repository, sb.buf, 1);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"this repository uses the reftable format\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n+\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n+\t\t\t\t \"this repository uses the reftable format\");\n \n \tstrbuf_release(&sb);\n \treturn 0;\n\n-- \n2.52.0\n\n"},{"id":"534968","messageId":"20260202-kn-alternate-ref-dir-v4-3-3b30430411e3@gmail.com","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com","subject":"[PATCH v4 3/4] refs: parse and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-02T12:26:32Z","receivedAt":"2026-02-02T12:27:07Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The previous commit extended the 'extensions.refStorage' config to add\nsupport for a reference storage payload. The payload provides backend\nspecific information on where to store references for a given directory.\n\nPropagate this information to individual backends when initializing them\nvia the 'init()' function. Both the files and reftable backends will\nparse the information to be filesystem paths to store references.\n\nTo enable this, provide a 'refs_compute_filesystem_location()' function\nwhich will parse the current 'gitdir' and the 'payload' to provide the\nfinal reference directory and common reference directory (if working in\na linked worktree).\n\nFinally, for linked worktrees, traditionally references were stored in\nthe '$GIT_DIR/worktrees/' path. But when using an alternate\nreference storage path, it doesn't make sense to store main worktree\nreferences in the new path, and linked worktree references in the\n$GIT_DIR path. So, let's store linked worktree references in\n'$ALTERNATE_REFERENCE_DIR/worktrees/\nSigned-off-by: Karthik Nayak \n---\n Documentation/config/extensions.adoc | 16 +++-\n builtin/worktree.c | 35 ++++++++\n refs.c | 37 +++++++-\n refs/files-backend.c | 18 ++--\n refs/packed-backend.c | 1 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 15 ++++\n refs/reftable-backend.c | 24 +++---\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n 10 files changed, 290 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 532456644b..df86da6aa7 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n `core.repositoryFormatVersion` setting.\n \n refStorage:::\n-\tSpecify the ref storage format to use. The acceptable values are:\n+\tSpecify the ref storage format and location to use. The value can be\n+\teither a format name or a URI:\n +\n --\n+* A format name alone (e.g., `reftable` or `files`) uses the default\n+ location (the repository's common directory).\n+\n+* A URI format `://` explicitly specifies both the\n+ format and payload (e.g., `reftable:///foo/bar`).\n+\n+Supported format names are:\n++\n include::../ref-storage-format.adoc[]\n++\n+The payload is passed directly to the reference backend. For the files and\n+reftable backends, this must be a filesystem path. Relative paths are resolved\n+relative to the $GIT_DIR. Future backends may support other payload schemes,\n+e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n Note that this setting should only be set by linkgit:git-init[1] or\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..800a376ac5 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -425,6 +425,40 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n \treturn run_command(&cp);\n }\n \n+/*\n+ * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n+ * But when using alternate reference directories, we want to store the worktree\n+ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n+ *\n+ * Create the necessary folder structure to facilitate the same. But to ensure\n+ * that the former path is still considered a Git directory, add stubs (similar\n+ * to how we do in the reftable backend).\n+ */\n+static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\tchar *path;\n+\n+\tpath = wt->repo->ref_storage_payload;\n+\tif (!path)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(path))\n+\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n+\n+\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_addf(&sb, \"/%s\", wt->id);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_reset(&sb);\n+\n+\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n+\t\t path, wt->id);\n+\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n+\n+\tstrbuf_release(&sb);\n+}\n+\n static int add_worktree(const char *path, const char *refname,\n \t\t\tconst struct add_opts *opts)\n {\n@@ -518,6 +552,7 @@ static int add_worktree(const char *path, const char *refname,\n \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n \t\tgoto done;\n \t}\n+\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n \twt_refs = get_worktree_ref_store(wt);\n \n \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\ndiff --git a/refs.c b/refs.c\nindex 32b4edaf2d..c1d69082a9 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -5,6 +5,7 @@\n #define USE_THE_REPOSITORY_VARIABLE\n \n #include \"git-compat-util.h\"\n+#include \"abspath.h\"\n #include \"advice.h\"\n #include \"config.h\"\n #include \"environment.h\"\n@@ -2224,7 +2225,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, gitdir, flags);\n+\t/*\n+\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n+\t * allow the backend to handle how it wants to deal with worktrees.\n+\t */\n+\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n \treturn refs;\n }\n \n@@ -3426,3 +3431,33 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n \n \tstrbuf_release(&path);\n }\n+\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\n+\tstrbuf_addstr(refdir, gitdir);\n+\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n+\n+\tif (!payload)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(payload)) {\n+\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n+\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n+\t} else {\n+\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n+\t}\n+\n+\tstrbuf_reset(refdir);\n+\tstrbuf_addbuf(refdir, ref_common_dir);\n+\n+\tif (*is_worktree) {\n+\t\tchar *wt_id = strrchr(gitdir, '/') + 1;\n+\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id);\n+\t}\n+\n+\tstrbuf_release(&sb);\n+}\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex 240d3c3b26..160ecb53b7 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n * set of caches.\n */\n static struct ref_store *files_ref_store_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags)\n {\n \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n \tstruct ref_store *ref_store = (struct ref_store *)refs;\n-\tstruct strbuf sb = STRBUF_INIT;\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n+\tbool is_worktree;\n+\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n \n-\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n+\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n \trefs->store_flags = flags;\n-\tget_common_dir_noenv(&sb, gitdir);\n-\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n+\trefs->gitcommondir = xstrdup(ref_common_dir.buf);\n \trefs->packed_ref_store =\n-\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n+\t\tpacked_ref_store_init(repo, payload, ref_common_dir.buf, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n@@ -126,6 +131,9 @@ static struct ref_store *files_ref_store_init(struct repository *repo,\n \tchdir_notify_reparent(\"files-backend $GIT_COMMONDIR\",\n \t\t\t &refs->gitcommondir);\n \n+\tstrbuf_release(&ref_common_dir);\n+\tstrbuf_release(&refdir);\n+\n \treturn ref_store;\n }\n \ndiff --git a/refs/packed-backend.c b/refs/packed-backend.c\nindex 4ea0c12299..028fbc0585 100644\n--- a/refs/packed-backend.c\n+++ b/refs/packed-backend.c\n@@ -212,6 +212,7 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n }\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload UNUSED,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags)\n {\ndiff --git a/refs/packed-backend.h b/refs/packed-backend.h\nindex 9481d5e7c2..2c2377a356 100644\n--- a/refs/packed-backend.h\n+++ b/refs/packed-backend.h\n@@ -14,6 +14,7 @@ struct ref_transaction;\n */\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags);\n \ndiff --git a/refs/refs-internal.h b/refs/refs-internal.h\nindex c7d2a6e50b..bd09b1280c 100644\n--- a/refs/refs-internal.h\n+++ b/refs/refs-internal.h\n@@ -389,6 +389,7 @@ struct ref_store;\n * the ref_store and to record the ref_store for later lookup.\n */\n typedef struct ref_store *ref_store_init_fn(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags);\n /*\n@@ -666,4 +667,18 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n \t\t\t\t\t unsigned int initial_transaction,\n \t\t\t\t\t struct strbuf *err);\n \n+/*\n+ * Given a gitdir and the reference storage payload provided, retrieve the\n+ * 'refdir' and 'ref_common_dir'. The former is where references should be\n+ * stored for the current worktree, the latter is the common reference\n+ * directory if working with a linked worktree. If working with the main\n+ * worktree, both values will be the same.\n+ *\n+ * This is used by backends such as {files, reftable} which store references in\n+ * dedicated filesystem paths.\n+ */\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir);\n+\n #endif /* REFS_REFS_INTERNAL_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex d8651fe779..964b0b50fc 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -372,18 +372,24 @@ static int reftable_be_fsync(int fd)\n }\n \n static struct ref_store *reftable_be_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int store_flags)\n {\n \tstruct reftable_ref_store *refs = xcalloc(1, sizeof(*refs));\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n \tstruct strbuf path = STRBUF_INIT;\n-\tint is_worktree;\n+\tbool is_worktree;\n \tmode_t mask;\n \n \tmask = umask(0);\n \tumask(mask);\n \n-\tbase_ref_store_init(&refs->base, repo, gitdir, &refs_be_reftable);\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n+\n+\tbase_ref_store_init(&refs->base, repo, refdir.buf, &refs_be_reftable);\n \tstrmap_init(&refs->worktree_backends);\n \trefs->store_flags = store_flags;\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n@@ -419,14 +425,11 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t/*\n \t * Set up the main reftable stack that is hosted in GIT_COMMON_DIR.\n \t * This stack contains both the shared and the main worktree refs.\n-\t *\n-\t * Note that we don't try to resolve the path in case we have a\n-\t * worktree because `get_common_dir_noenv()` already does it for us.\n \t */\n-\tis_worktree = get_common_dir_noenv(&path, gitdir);\n+\tstrbuf_addbuf(&path, &ref_common_dir);\n \tif (!is_worktree) {\n \t\tstrbuf_reset(&path);\n-\t\tstrbuf_realpath(&path, gitdir, 0);\n+\t\tstrbuf_realpath(&path, ref_common_dir.buf, 0);\n \t}\n \tstrbuf_addstr(&path, \"/reftable\");\n \trefs->err = reftable_backend_init(&refs->main_backend, path.buf,\n@@ -443,10 +446,9 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t * do it efficiently.\n \t */\n \tif (is_worktree) {\n-\t\tstrbuf_reset(&path);\n-\t\tstrbuf_addf(&path, \"%s/reftable\", gitdir);\n+\t\tstrbuf_addstr(&refdir, \"/reftable\");\n \n-\t\trefs->err = reftable_backend_init(&refs->worktree_backend, path.buf,\n+\t\trefs->err = reftable_backend_init(&refs->worktree_backend, refdir.buf,\n \t\t\t\t\t\t &refs->write_options);\n \t\tif (refs->err)\n \t\t\tgoto done;\n@@ -456,6 +458,8 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \n done:\n \tassert(refs->err != REFTABLE_API_ERROR);\n+\tstrbuf_release(&ref_common_dir);\n+\tstrbuf_release(&refdir);\n \tstrbuf_release(&path);\n \treturn &refs->base;\n }\ndiff --git a/t/meson.build b/t/meson.build\nindex 459c52a489..11fc5a49ee 100644\n--- a/t/meson.build\n+++ b/t/meson.build\n@@ -210,6 +210,7 @@ integration_tests = [\n 't1420-lost-found.sh',\n 't1421-reflog-write.sh',\n 't1422-show-ref-exists.sh',\n+ 't1423-ref-backend.sh',\n 't1430-bad-ref-name.sh',\n 't1450-fsck.sh',\n 't1451-fsck-buffer.sh',\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nnew file mode 100755\nindex 0000000000..9c777b79f3\n--- /dev/null\n+++ b/t/t1423-ref-backend.sh\n@@ -0,0 +1,159 @@\n+#!/bin/sh\n+\n+test_description='Test reference backend URIs'\n+\n+. ./test-lib.sh\n+\n+# Run a git command with the provided reference storage. Reset the backend\n+# post running the command.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# is the git subcommand to be run in the repository.\n+run_with_uri() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\tcmd=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1\n+\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\tgit -C \"$repo\" $cmd &&\n+\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+}\n+\n+# Test a repository with a given reference storage by running and comparing\n+# 'git refs list' before and after setting the new reference backend. If\n+# err_msg is set, expect the command to fail and grep for the provided err_msg.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n+test_refs_backend() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\terr_msg=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test -n \"$err_msg\";\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\ttest_grep \"$err_msg\" err\n+\telse\n+\t\tgit -C \"$repo\" refs list >expect &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\ttest_cmp expect actual\n+\tfi\n+}\n+\n+test_expect_success 'URI is invalid' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'URI ends with colon' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable:\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'unknown reference backend' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"db://.git\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+ref_formats=\"files reftable\"\n+for from_format in $ref_formats\n+do\n+\n+for to_format in $ref_formats\n+do\n+\tif test \"$from_format\" = \"$to_format\"\n+\tthen\n+\t\tcontinue\n+\tfi\n+\n+\n+\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n+\tdo\n+\n+\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit refs list >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\tgit refs list >actual &&\n+\t\t\t\ttest_cmp expect actual &&\n+\n+\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\tgit config set core.repositoryformatversion 1 &&\n+\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit worktree add ../wt 2\n+\t\t\t) &&\n+\n+\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n+\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n+\t\t\t! test_cmp expect actual &&\n+\n+\t\t\tgit -C wt rev-parse 2 >expect &&\n+\t\t\tgit -C wt rev-parse HEAD >actual &&\n+\t\t\ttest_cmp expect actual\n+\t\t'\n+\tdone # closes dir\n+done # closes to_format\n+done # closes from_format\n+\n+test_done\n\n-- \n2.52.0\n\n"},{"id":"534969","messageId":"20260202-kn-alternate-ref-dir-v4-4-3b30430411e3@gmail.com","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com","subject":"[PATCH v4 4/4] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-02T12:26:33Z","receivedAt":"2026-02-02T12:27:07Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Git allows setting a different object directory via\n'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\nthe previous commit we extended the 'extensions.refStorage' config to\nalso support an URI input for reference backend with location.\n\nLet's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\ntakes in the same input as the config variable. Having an environment\nvariable allows us to modify the reference backend and location on the\nfly for individual git commands.\n\nHelped-by: Jean-Noël Avila \nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 5 +++\n environment.h | 1 +\n setup.c | 20 +++++++++++\n t/t1423-ref-backend.sh | 96 ++++++++++++++++++++++++++++++++------------------\n 4 files changed, 88 insertions(+), 34 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..ed3191e8f6 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n \trepositories will be set to this value. The default is \"files\".\n \tSee `--ref-format` in linkgit:git-init[1].\n \n+`GIT_REFERENCE_BACKEND`::\n+ Specify which reference backend to be used along with its URI.\n+ See `extensions.refStorage` option in linkgit:git-config[1] for more\n+ description. Overrides the config variable when used.\n+\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\ndiff --git a/environment.h b/environment.h\nindex 27f657af04..540e0a7f6d 100644\n--- a/environment.h\n+++ b/environment.h\n@@ -42,6 +42,7 @@\n #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n+#define GIT_REFERENCE_BACKEND_ENVIRONMENT \"GIT_REFERENCE_BACKEND\"\n \n /*\n * Environment variable used to propagate the --no-advice global option to the\ndiff --git a/setup.c b/setup.c\nindex 44e393c251..b4a7b82cca 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -1838,6 +1838,7 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \tstatic struct strbuf cwd = STRBUF_INIT;\n \tstruct strbuf dir = STRBUF_INIT, gitdir = STRBUF_INIT, report = STRBUF_INIT;\n \tconst char *prefix = NULL;\n+\tconst char *ref_backend_uri;\n \tstruct repository_format repo_fmt = REPOSITORY_FORMAT_INIT;\n \n \t/*\n@@ -1995,6 +1996,25 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\tsetenv(GIT_PREFIX_ENVIRONMENT, \"\", 1);\n \t}\n \n+\t/*\n+\t * The env variable should override the repository config\n+\t * for 'extensions.refStorage'.\n+\t */\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *location;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &location);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\t\trepo_set_ref_storage_format(the_repository, format, location);\n+\n+\t\tfree(backend);\n+\t\tfree(location);\n+\t}\n+\n \tsetup_original_cwd();\n \n \tstrbuf_release(&dir);\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nindex 9c777b79f3..10a9bb1a9b 100755\n--- a/t/t1423-ref-backend.sh\n+++ b/t/t1423-ref-backend.sh\n@@ -11,16 +11,25 @@ test_description='Test reference backend URIs'\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n # is the git subcommand to be run in the repository.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n run_with_uri() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n \tcmd=$4 &&\n+\tvia=$5 &&\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1\n-\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\tgit -C \"$repo\" $cmd &&\n-\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test \"$via\" = \"env\"\n+\tthen\n+\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" git -C \"$repo\" $cmd\n+\telif test \"$via\" = \"config\"\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\tgit -C \"$repo\" $cmd &&\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tfi\n }\n \n # Test a repository with a given reference storage by running and comparing\n@@ -30,44 +39,57 @@ run_with_uri() {\n # is the relative path to the repo to run the command in.\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n # (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n test_refs_backend() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n-\terr_msg=$4 &&\n+\tvia=$4 &&\n+\terr_msg=$5 &&\n+\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n \tif test -n \"$err_msg\";\n \tthen\n-\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n-\t\ttest_grep \"$err_msg\" err\n+\t\tif test \"$via\" = \"env\"\n+\t\tthen\n+\t\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" test_must_fail git -C \"$repo\" refs list 2>err\n+\t\telif test \"$via\" = \"config\"\n+\t\tthen\n+\t\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\t\ttest_grep \"$err_msg\" err\n+\t\tfi\n \telse\n \t\tgit -C \"$repo\" refs list >expect &&\n-\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" \"$via\">actual &&\n \t\ttest_cmp expect actual\n \tfi\n }\n \n-test_expect_success 'URI is invalid' '\n+methods=\"config\"\n+for method in $methods\n+do\n+\n+test_expect_success \"$method: URI is invalid\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'URI ends with colon' '\n+test_expect_success \"$method: URI ends with colon\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable:\" \\\n+\ttest_refs_backend repo files \"reftable:\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'unknown reference backend' '\n+test_expect_success \"$method: unknown reference backend\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"db://.git\" \\\n+\ttest_refs_backend repo files \"db://.git\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n@@ -86,7 +108,7 @@ do\n \tfor dir in \"$(pwd)/repo/.git\" \"./\"\n \tdo\n \n-\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: $read from $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -101,7 +123,7 @@ do\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: $write to $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -113,20 +135,22 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\" &&\n \n \t\t\t\tgit refs list >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"tag -d 1\" \"$method\" &&\n \t\t\t\tgit refs list >actual &&\n \t\t\t\ttest_cmp expect actual &&\n \n \t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"refs list\" \"$method\" >actual &&\n \t\t\t\ttest_cmp expect actual\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: with worktree and $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo wt\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -138,22 +162,26 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\tgit config set core.repositoryformatversion 1 &&\n-\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n \n-\t\t\t\tgit worktree add ../wt 2\n-\t\t\t) &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n+\t\t\t\t! test_cmp expect actual &&\n \n-\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n-\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n-\t\t\t! test_cmp expect actual &&\n-\n-\t\t\tgit -C wt rev-parse 2 >expect &&\n-\t\t\tgit -C wt rev-parse HEAD >actual &&\n-\t\t\ttest_cmp expect actual\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n \t\t'\n \tdone # closes dir\n done # closes to_format\n-done # closes from_format\n+done # closes to_format\n+\n+done # closes method\n \n test_done\n\n-- \n2.52.0\n\n"},{"id":"535341","messageId":"aYX7sYaTp6cArMxA@pks.im","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-1-3b30430411e3@gmail.com","subject":"Re: [PATCH v4 1/4] refs: allow reference location in refstorage config","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-06T14:33:21Z","receivedAt":"2026-02-06T14:33:34Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 02, 2026 at 01:26:30PM +0100, Karthik Nayak wrote:\n> The 'extensions.refStorage' config is used to specify the reference\n> backend for a given repository. Both the 'files' and 'reftable' backends\n> utilize the $GIT_DIR as the reference folder by default in\n> `get_main_ref_store()`.\n> \n> Since the reference backends are pluggable, this means that they should\n\ns/should/could/ I guess. It's not like they are broken currently, we\nrather want more.\n\n> diff --git a/repository.h b/repository.h\n> index 6063c4b846..c648dab196 100644\n> --- a/repository.h\n> +++ b/repository.h\n> @@ -150,6 +150,8 @@ struct repository {\n> \n> \t/* Repository's reference storage format, as serialized on disk. */\n> \tenum ref_storage_format ref_storage_format;\n> +\t/* Reference storage information as needed for the backend. */\n\nNit: it would be nice to document whether this only contains the\nadditional data after the schema, or whether it's the whole\n\"files:///dir\" string.\n\nAnother nit: ideally, the step to pass through the payload to the\nbackends came before this patch so that we could already make them fail\nin case they are passed a value they don't understand. Otherwise, a user\ncould now pass \"reftable://foobar\", and the \"foobar\" part would be\nsilently ignored without any kind of warning or error.\n\nOther than that this patch looks good to me.\n\nPatrick\n"},{"id":"535342","messageId":"aYX7vfG8XQ0p6h1F@pks.im","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-2-3b30430411e3@gmail.com","subject":"Re: [PATCH v4 2/4] refs: extract out `refs_create_refdir_stubs()`","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-06T14:33:33Z","receivedAt":"2026-02-06T14:33:38Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 02, 2026 at 01:26:31PM +0100, Karthik Nayak wrote:\n> For Git to recognize a directory as a Git directory, it requires the\n> directory to contain:\n> \n> 1. 'HEAD' file\n> 2. object/ directory\n\ns|object/|objects/|\n\n> 3. 'refs/' directory\n> \n> Here, #1 and #3 are part of the reference storage mechanism,\n> specifically the files backend. Since then, newer backends such as the\n> reftable backend have moved to using their own path ('reftable/') for\n> storing references. But to ensure git still recognizes the directory as\n\ns/git/Git/\n\n> a Git directory, we create stubs.\n> \n> There are two locations we create stubs:\n\ns/we/where &/\n\n> diff --git a/refs.c b/refs.c\n> index 627b7f8698..32b4edaf2d 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -3402,3 +3402,27 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n> \t\treturn \"unknown failure\";\n> \t}\n> }\n> +\n> +void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n> +\t\t\t const char *refs_heads_msg)\n\nIt's not really a message, but much rather its content, right?\n\nPatrick\n"},{"id":"535343","messageId":"aYX7w5flfNe_bUFD@pks.im","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-3-3b30430411e3@gmail.com","subject":"Re: [PATCH v4 3/4] refs: parse and use the reference storage payload","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-06T14:33:39Z","receivedAt":"2026-02-06T14:33:44Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 02, 2026 at 01:26:32PM +0100, Karthik Nayak wrote:\n> The previous commit extended the 'extensions.refStorage' config to add\n> support for a reference storage payload. The payload provides backend\n> specific information on where to store references for a given directory.\n> \n> Propagate this information to individual backends when initializing them\n> via the 'init()' function. Both the files and reftable backends will\n> parse the information to be filesystem paths to store references.\n> \n> To enable this, provide a 'refs_compute_filesystem_location()' function\n> which will parse the current 'gitdir' and the 'payload' to provide the\n> final reference directory and common reference directory (if working in\n> a linked worktree).\n> \n> Finally, for linked worktrees, traditionally references were stored in\n> the '$GIT_DIR/worktrees/' path. But when using an alternate\n> reference storage path, it doesn't make sense to store main worktree\n> references in the new path, and linked worktree references in the\n> $GIT_DIR path. So, let's store linked worktree references in\n> '$ALTERNATE_REFERENCE_DIR/worktrees//\n\n> diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\n> index 532456644b..df86da6aa7 100644\n> --- a/Documentation/config/extensions.adoc\n> +++ b/Documentation/config/extensions.adoc\n> @@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n> `core.repositoryFormatVersion` setting.\n> \n> refStorage:::\n> -\tSpecify the ref storage format to use. The acceptable values are:\n> +\tSpecify the ref storage format and location to use. The value can be\n> +\teither a format name or a URI:\n> +\n> --\n> +* A format name alone (e.g., `reftable` or `files`) uses the default\n> + location (the repository's common directory).\n> +\n> +* A URI format `://` explicitly specifies both the\n\nI think I mentioned this before, but shouldn't we say payload instead of\nlocation here? It may not be a location for all backends.\n\n> diff --git a/builtin/worktree.c b/builtin/worktree.c\n> index fbdaf2eb2e..800a376ac5 100644\n> --- a/builtin/worktree.c\n> +++ b/builtin/worktree.c\n> @@ -425,6 +425,40 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n> \treturn run_command(&cp);\n> }\n> \n> +/*\n> + * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n> + * But when using alternate reference directories, we want to store the worktree\n> + * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n> + *\n> + * Create the necessary folder structure to facilitate the same. But to ensure\n> + * that the former path is still considered a Git directory, add stubs (similar\n> + * to how we do in the reftable backend).\n> + */\n\nI think the last part in the braces isn't necessary to say anymore given\nthat we simply shell out to a function now.\n\n> diff --git a/refs.c b/refs.c\n> index 32b4edaf2d..c1d69082a9 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -2224,7 +2225,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n> \tif (!be)\n> \t\tBUG(\"reference backend is unknown\");\n> \n> -\trefs = be->init(repo, gitdir, flags);\n> +\t/*\n> +\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n> +\t * allow the backend to handle how it wants to deal with worktrees.\n> +\t */\n\nIt would be nice if the commit message mentioned why this isn't done now\nalready.\n\n> diff --git a/refs/files-backend.c b/refs/files-backend.c\n> index 240d3c3b26..160ecb53b7 100644\n> --- a/refs/files-backend.c\n> +++ b/refs/files-backend.c\n> @@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n> * set of caches.\n> */\n> static struct ref_store *files_ref_store_init(struct repository *repo,\n> +\t\t\t\t\t const char *payload,\n> \t\t\t\t\t const char *gitdir,\n> \t\t\t\t\t unsigned int flags)\n> {\n> \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n> \tstruct ref_store *ref_store = (struct ref_store *)refs;\n> -\tstruct strbuf sb = STRBUF_INIT;\n> +\tstruct strbuf ref_common_dir = STRBUF_INIT;\n> +\tstruct strbuf refdir = STRBUF_INIT;\n> +\tbool is_worktree;\n> +\n> +\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n> +\t\t\t\t\t &ref_common_dir);\n> \n> -\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n> +\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n> \trefs->store_flags = flags;\n> -\tget_common_dir_noenv(&sb, gitdir);\n> -\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n> +\trefs->gitcommondir = xstrdup(ref_common_dir.buf);\n\nWe can use `strbuf_detach()` instead to save an allocation and then use\n`refs->gitcommondir` below.\n\n> \trefs->packed_ref_store =\n> -\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n> +\t\tpacked_ref_store_init(repo, payload, ref_common_dir.buf, flags);\n> \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n> \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n\nPatrick\n"},{"id":"535344","messageId":"aYX7yZofAhc3xYkm@pks.im","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-4-3b30430411e3@gmail.com","subject":"Re: [PATCH v4 4/4] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-06T14:33:45Z","receivedAt":"2026-02-06T14:33:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 02, 2026 at 01:26:33PM +0100, Karthik Nayak wrote:\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\n> the previous commit we extended the 'extensions.refStorage' config to\n> also support an URI input for reference backend with location.\n> \n> Let's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\n> takes in the same input as the config variable. Having an environment\n> variable allows us to modify the reference backend and location on the\n> fly for individual git commands.\n\ns/git/Git/\n\n> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n> index ce099e78b8..ed3191e8f6 100644\n> --- a/Documentation/git.adoc\n> +++ b/Documentation/git.adoc\n> @@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n> \trepositories will be set to this value. The default is \"files\".\n> \tSee `--ref-format` in linkgit:git-init[1].\n> \n> +`GIT_REFERENCE_BACKEND`::\n> + Specify which reference backend to be used along with its URI.\n> + See `extensions.refStorage` option in linkgit:git-config[1] for more\n> + description. Overrides the config variable when used.\n\n\"for more description\" reads a bit weird. How about \"for more details\"\ninstead?\n\nPatrick\n"},{"id":"535345","messageId":"aYX7z_nUc4xJC8Qs@pks.im","threadId":"64513","inReplyTo":"20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com","subject":"Re: [PATCH v4 0/4] refs: allow setting the reference directory","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-06T14:33:51Z","receivedAt":"2026-02-06T14:33:56Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 02, 2026 at 01:26:29PM +0100, Karthik Nayak wrote:\n> Changes in v4:\n> - Mostly re-wrote the code to also support worktree. Now, the existing\n> backends will store worktree references in 'ref_dir/worktrees/wt_id'\n> and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n> - We also support relative paths in the reference directories. These\n> relative paths are resolved relative to the GIT_DIR.\n> - Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n\nI've got some of comments, but almost all of them are just nits. I quite\nlike the way this is shaping up.\n\nThanks!\n\nPatrick\n"},{"id":"535373","messageId":"xmqqldh5g3rz.fsf@gitster.g","threadId":"64513","inReplyTo":"aYX7z_nUc4xJC8Qs@pks.im","subject":"Re: [PATCH v4 0/4] refs: allow setting the reference directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-06T17:50:24Z","receivedAt":"2026-02-06T17:50:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 02, 2026 at 01:26:29PM +0100, Karthik Nayak wrote:\n>> Changes in v4:\n>> - Mostly re-wrote the code to also support worktree. Now, the existing\n>> backends will store worktree references in 'ref_dir/worktrees/wt_id'\n>> and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n>> - We also support relative paths in the reference directories. These\n>> relative paths are resolved relative to the GIT_DIR.\n>> - Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n>\n> I've got some of comments, but almost all of them are just nits. I quite\n> like the way this is shaping up.\n>\n> Thanks!\n>\n> Patrick\n\nLooking good. Thanks, both.\n"},{"id":"535518","messageId":"CAOLa=ZTji2h22bCUvMBB0mrGY12EGxJmJVQ02cDgTXmARpy0Lg@mail.gmail.com","threadId":"64513","inReplyTo":"aYX7vfG8XQ0p6h1F@pks.im","subject":"Re: [PATCH v4 2/4] refs: extract out `refs_create_refdir_stubs()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T11:21:39Z","receivedAt":"2026-02-09T11:21:41Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 02, 2026 at 01:26:31PM +0100, Karthik Nayak wrote:\n>> For Git to recognize a directory as a Git directory, it requires the\n>> directory to contain:\n>>\n>> 1. 'HEAD' file\n>> 2. object/ directory\n>\n> s|object/|objects/|\n>\n>> 3. 'refs/' directory\n>>\n>> Here, #1 and #3 are part of the reference storage mechanism,\n>> specifically the files backend. Since then, newer backends such as the\n>> reftable backend have moved to using their own path ('reftable/') for\n>> storing references. But to ensure git still recognizes the directory as\n>\n> s/git/Git/\n>\n>> a Git directory, we create stubs.\n>>\n>> There are two locations we create stubs:\n>\n> s/we/where &/\n>\n>> diff --git a/refs.c b/refs.c\n>> index 627b7f8698..32b4edaf2d 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -3402,3 +3402,27 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n>> \t\treturn \"unknown failure\";\n>> \t}\n>> }\n>> +\n>> +void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n>> +\t\t\t const char *refs_heads_msg)\n>\n> It's not really a message, but much rather its content, right?\n>\n> Patrick\n\nIndeed, will also patch up the typos. Thanks,\n\nKarthik\n"},{"id":"535520","messageId":"CAOLa=ZSpGXd0W9-1S5r5iDrifu4eeh=YTOf+OB27TH73cZ8iog@mail.gmail.com","threadId":"64513","inReplyTo":"aYX7sYaTp6cArMxA@pks.im","subject":"Re: [PATCH v4 1/4] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T12:25:04Z","receivedAt":"2026-02-09T12:25:06Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 02, 2026 at 01:26:30PM +0100, Karthik Nayak wrote:\n>> The 'extensions.refStorage' config is used to specify the reference\n>> backend for a given repository. Both the 'files' and 'reftable' backends\n>> utilize the $GIT_DIR as the reference folder by default in\n>> `get_main_ref_store()`.\n>>\n>> Since the reference backends are pluggable, this means that they should\n>\n> s/should/could/ I guess. It's not like they are broken currently, we\n> rather want more.\n>\n\nYeah, that's fair.\n\n>> diff --git a/repository.h b/repository.h\n>> index 6063c4b846..c648dab196 100644\n>> --- a/repository.h\n>> +++ b/repository.h\n>> @@ -150,6 +150,8 @@ struct repository {\n>>\n>> \t/* Repository's reference storage format, as serialized on disk. */\n>> \tenum ref_storage_format ref_storage_format;\n>> +\t/* Reference storage information as needed for the backend. */\n>\n> Nit: it would be nice to document whether this only contains the\n> additional data after the schema, or whether it's the whole\n> \"files:///dir\" string.\n>\n\nWill add some more information here.\n\n> Another nit: ideally, the step to pass through the payload to the\n> backends came before this patch so that we could already make them fail\n> in case they are passed a value they don't understand. Otherwise, a user\n> could now pass \"reftable://foobar\", and the \"foobar\" part would be\n> silently ignored without any kind of warning or error.\n>\n> Other than that this patch looks good to me.\n>\n> Patrick\n\nThat's a good point, I hadn't considered, this should be simple enough\nto do, so let me put that together.\n\nKarthik\n"},{"id":"535528","messageId":"CAOLa=ZQ20=FpdXfh6y_+NLNDgf73b51MC0mOAZX-Yd_SaPF9QA@mail.gmail.com","threadId":"64513","inReplyTo":"aYX7w5flfNe_bUFD@pks.im","subject":"Re: [PATCH v4 3/4] refs: parse and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T12:52:03Z","receivedAt":"2026-02-09T12:52:05Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 02, 2026 at 01:26:32PM +0100, Karthik Nayak wrote:\n>> The previous commit extended the 'extensions.refStorage' config to add\n>> support for a reference storage payload. The payload provides backend\n>> specific information on where to store references for a given directory.\n>>\n>> Propagate this information to individual backends when initializing them\n>> via the 'init()' function. Both the files and reftable backends will\n>> parse the information to be filesystem paths to store references.\n>>\n>> To enable this, provide a 'refs_compute_filesystem_location()' function\n>> which will parse the current 'gitdir' and the 'payload' to provide the\n>> final reference directory and common reference directory (if working in\n>> a linked worktree).\n>>\n>> Finally, for linked worktrees, traditionally references were stored in\n>> the '$GIT_DIR/worktrees/' path. But when using an alternate\n>> reference storage path, it doesn't make sense to store main worktree\n>> references in the new path, and linked worktree references in the\n>> $GIT_DIR path. So, let's store linked worktree references in\n>> '$ALTERNATE_REFERENCE_DIR/worktrees/\n> s/wt_id/&>/\n>\n\nThanks!\n\n>> diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\n>> index 532456644b..df86da6aa7 100644\n>> --- a/Documentation/config/extensions.adoc\n>> +++ b/Documentation/config/extensions.adoc\n>> @@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n>> `core.repositoryFormatVersion` setting.\n>>\n>> refStorage:::\n>> -\tSpecify the ref storage format to use. The acceptable values are:\n>> +\tSpecify the ref storage format and location to use. The value can be\n>> +\teither a format name or a URI:\n>> +\n>> --\n>> +* A format name alone (e.g., `reftable` or `files`) uses the default\n>> + location (the repository's common directory).\n>> +\n>> +* A URI format `://` explicitly specifies both the\n>\n> I think I mentioned this before, but shouldn't we say payload instead of\n> location here? It may not be a location for all backends.\n>\n\nYeah, you did. I missed this entirely somehow. Will re-do this.\n\n>> diff --git a/builtin/worktree.c b/builtin/worktree.c\n>> index fbdaf2eb2e..800a376ac5 100644\n>> --- a/builtin/worktree.c\n>> +++ b/builtin/worktree.c\n>> @@ -425,6 +425,40 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n>> \treturn run_command(&cp);\n>> }\n>>\n>> +/*\n>> + * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n>> + * But when using alternate reference directories, we want to store the worktree\n>> + * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n>> + *\n>> + * Create the necessary folder structure to facilitate the same. But to ensure\n>> + * that the former path is still considered a Git directory, add stubs (similar\n>> + * to how we do in the reftable backend).\n>> + */\n>\n> I think the last part in the braces isn't necessary to say anymore given\n> that we simply shell out to a function now.\n>\n\nYeah, will remove.\n\n>> diff --git a/refs.c b/refs.c\n>> index 32b4edaf2d..c1d69082a9 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -2224,7 +2225,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n>> \tif (!be)\n>> \t\tBUG(\"reference backend is unknown\");\n>>\n>> -\trefs = be->init(repo, gitdir, flags);\n>> +\t/*\n>> +\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n>> +\t * allow the backend to handle how it wants to deal with worktrees.\n>> +\t */\n>\n> It would be nice if the commit message mentioned why this isn't done now\n> already.\n\nWill do!\n\n>> diff --git a/refs/files-backend.c b/refs/files-backend.c\n>> index 240d3c3b26..160ecb53b7 100644\n>> --- a/refs/files-backend.c\n>> +++ b/refs/files-backend.c\n>> @@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n>> * set of caches.\n>> */\n>> static struct ref_store *files_ref_store_init(struct repository *repo,\n>> +\t\t\t\t\t const char *payload,\n>> \t\t\t\t\t const char *gitdir,\n>> \t\t\t\t\t unsigned int flags)\n>> {\n>> \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n>> \tstruct ref_store *ref_store = (struct ref_store *)refs;\n>> -\tstruct strbuf sb = STRBUF_INIT;\n>> +\tstruct strbuf ref_common_dir = STRBUF_INIT;\n>> +\tstruct strbuf refdir = STRBUF_INIT;\n>> +\tbool is_worktree;\n>> +\n>> +\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n>> +\t\t\t\t\t &ref_common_dir);\n>>\n>> -\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n>> +\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n>> \trefs->store_flags = flags;\n>> -\tget_common_dir_noenv(&sb, gitdir);\n>> -\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n>> +\trefs->gitcommondir = xstrdup(ref_common_dir.buf);\n>\n> We can use `strbuf_detach()` instead to save an allocation and then use\n> `refs->gitcommondir` below.\n>\n\nThat's a good suggestion.\n\n>> \trefs->packed_ref_store =\n>> -\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n>> +\t\tpacked_ref_store_init(repo, payload, ref_common_dir.buf, flags);\n>> \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n>> \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n>\n> Patrick\n\nThanks!\n"},{"id":"535529","messageId":"CAOLa=ZQxU4Lkd=px_KmpKgBn1A2O7bjKVRu=QFDCYT-Ntbd=Dg@mail.gmail.com","threadId":"64513","inReplyTo":"aYX7yZofAhc3xYkm@pks.im","subject":"Re: [PATCH v4 4/4] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T12:53:06Z","receivedAt":"2026-02-09T12:53:09Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 02, 2026 at 01:26:33PM +0100, Karthik Nayak wrote:\n>> Git allows setting a different object directory via\n>> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\n>> the previous commit we extended the 'extensions.refStorage' config to\n>> also support an URI input for reference backend with location.\n>>\n>> Let's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\n>> takes in the same input as the config variable. Having an environment\n>> variable allows us to modify the reference backend and location on the\n>> fly for individual git commands.\n>\n> s/git/Git/\n>\n>> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n>> index ce099e78b8..ed3191e8f6 100644\n>> --- a/Documentation/git.adoc\n>> +++ b/Documentation/git.adoc\n>> @@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n>> \trepositories will be set to this value. The default is \"files\".\n>> \tSee `--ref-format` in linkgit:git-init[1].\n>>\n>> +`GIT_REFERENCE_BACKEND`::\n>> + Specify which reference backend to be used along with its URI.\n>> + See `extensions.refStorage` option in linkgit:git-config[1] for more\n>> + description. Overrides the config variable when used.\n>\n> \"for more description\" reads a bit weird. How about \"for more details\"\n> instead?\n>\n> Patrick\n\nWill make both changes here.\n"},{"id":"535530","messageId":"CAOLa=ZQVi+zFT7ru0tuEm3a-8wr0cAfB_L1F_wEv1+HCkgDxmg@mail.gmail.com","threadId":"64513","inReplyTo":"aYX7z_nUc4xJC8Qs@pks.im","subject":"Re: [PATCH v4 0/4] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T12:53:24Z","receivedAt":"2026-02-09T12:53:25Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 02, 2026 at 01:26:29PM +0100, Karthik Nayak wrote:\n>> Changes in v4:\n>> - Mostly re-wrote the code to also support worktree. Now, the existing\n>> backends will store worktree references in 'ref_dir/worktrees/wt_id'\n>> and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n>> - We also support relative paths in the reference directories. These\n>> relative paths are resolved relative to the GIT_DIR.\n>> - Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n>\n> I've got some of comments, but almost all of them are just nits. I quite\n> like the way this is shaping up.\n>\n> Thanks!\n>\n> Patrick\n\nThanks for the review. Appreciate it.\n"},{"id":"535550","messageId":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH v5 0/4] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T15:58:17Z","receivedAt":"2026-02-09T15:58:25Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"While Git allows users to select different reference backends, unlike\nwith objects, there is no flexibility in selecting the reference\ndirectory. Currently, the reference format is obtained from the config\nof the repository and the reference directory is set to the $GIT_DIR.\n\nThis patch extends the config 'extensions.refStorage' to take in\nmultiple forms of inputs:\n\n - A format name alone (e.g., `reftable` or `files`).\n\n - A URI format `://` explicitly specifies both the\n format and payload (e.g., `reftable:///foo/bar`).\n\nWe also add in a new ENV variable GIT_REFERENCE_BACKEND which can be\nused to override the config.\n\nOne use case for this is migration between different backends. On the\nserver side, migrating from the files backend to the newly introduced\nreftable backend can be achieved by running 'git refs migrate'. However,\nfor large repositories with millions of references, this migration can\ntake from seconds to minutes.\n\nFor some background, at GitLab, the criteria for our migration was to\nreduce the downtime of the migrate ideally to zero. So running 'git refs\nmigrate --ref-format=reftable' by itself wouldn't work, since it scales\nwith the number of references and we have repos with millions of\nreferences, so we need to migrate without loosing any information. We\ncame up with the following plan:\n\n 1. Run git-pack-refs(1) and note timestamp of the generated packed-refs\n file.\n 2. Run git refs migrate –dry-run.\n 3. If there are no ongoing reference requests (read/write)\n a. Lock the repository by blocking incoming requests (done on a\n layer above git, in Gitaly [1]).\n b. If the timestamp of the packed-refs file has changed, unlock\n the repo and repeat from step 1.\n c. Apply all the loose refs to the dry-run reftable folder (this\n requires support in Git to write refs to arbitrary folder).\n d. Move the reftable dry-run folder into the GIT_DIR.\n e. Swap the repo config\n f. Unlock repo access\n\nUsing such a route, scales much better since we only have to worry about\nblocking the repository by O(ref written between #1 and #3a) and not\nO(refs in repo). But for doing so, we need to be able to write to a\narbitrary reference backend + path. This is to add the missing\nreferences to the dry-run reftable folder. This series, achieves that.\n\nSince there was a long gap between v3 <> v4, the version 4 onward is\nbased on top of 2258446484 (RelNotes: correct \"fast-import\" option name,\n2026-01-30).\n\n[1]: https://gitlab.com/gitlab-org/gitaly\n\n---\nChanges in v5:\n- Moved around the commits, to ensure that the code to handle the config\n in the backend is first. Previously, we added the config first, which\n meant the commit allowed users to provide a URI but it was simply\n ignore.\n- Fix typos and grammar and rename variables.\n- Clean up the description and documentation to actually specify\n protocol over location.\n- Avoid an extra memory allocation by detaching the strbuf value.\n- Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n\nChanges in v4:\n- Mostly re-wrote the code to also support worktree. Now, the existing\n backends will store worktree references in 'ref_dir/worktrees/wt_id'\n and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n- We also support relative paths in the reference directories. These\n relative paths are resolved relative to the GIT_DIR.\n- Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n\nChanges in v3:\n- Cleanup some stale code which wasn't removed.\n- Localize strings which will be output to the user.\n- Remove additional defensive checks which are not needed.\n- Link to v2: https://patch.msgid.link/20251126-kn-alternate-ref-dir-v2-0-8b9f6f18f635@gmail.com\n\nChanges in v2:\n- Added more clarification and proper intent in the cover message.\n- Changed the format from '://' to\n `://` as it much clearer.\n- Added logic to check for the '//' in the provided URI and a test for\n the same.\n- In the tests:\n - Use test_must_fail() instead of ! git\n - Fix looped tests not using the variables correctly and ensure that\n the test description is correct.\n- Link to v1: https://patch.msgid.link/20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com\n\n---\n Documentation/config/extensions.adoc | 16 ++-\n Documentation/git.adoc | 5 +\n builtin/clone.c | 10 +-\n builtin/worktree.c | 34 +++++++\n environment.h | 1 +\n refs.c | 60 ++++++++++-\n refs.h | 13 +++\n refs/files-backend.c | 17 +++-\n refs/packed-backend.c | 1 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 15 +++\n refs/reftable-backend.c | 38 +++----\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 59 ++++++++++-\n setup.h | 2 +\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 187 +++++++++++++++++++++++++++++++++++\n 18 files changed, 433 insertions(+), 44 deletions(-)\n\nKarthik Nayak (4):\n refs: extract out `refs_create_refdir_stubs()`\n refs: forward and use the reference storage payload\n refs: allow reference location in refstorage config\n refs: add GIT_REFERENCE_BACKEND to specify reference backend\n\nRange-diff versus v4:\n\n2: 57943ad6f9 ! 1: 6ed61ba98b refs: extract out `refs_create_refdir_stubs()`\n @@ Commit message\n directory to contain:\n \n 1. 'HEAD' file\n - 2. object/ directory\n + 2. 'objects/' directory\n 3. 'refs/' directory\n \n Here, #1 and #3 are part of the reference storage mechanism,\n specifically the files backend. Since then, newer backends such as the\n reftable backend have moved to using their own path ('reftable/') for\n - storing references. But to ensure git still recognizes the directory as\n + storing references. But to ensure Git still recognizes the directory as\n a Git directory, we create stubs.\n \n - There are two locations we create stubs:\n + There are two locations where we create stubs:\n \n - In 'refs/reftable-backend.c' when creating the reftable backend.\n - In 'clone.c' before spawning transport helpers.\n @@ refs.c: const char *ref_transaction_error_msg(enum ref_transaction_error err)\n }\n +\n +void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n -+\t\t\t const char *refs_heads_msg)\n ++\t\t\t const char *refs_heads_content)\n +{\n +\tstruct strbuf path = STRBUF_INIT;\n +\n -+\n +\tstrbuf_addf(&path, \"%s/HEAD\", refdir);\n +\twrite_file(path.buf, \"ref: refs/heads/.invalid\");\n +\tadjust_shared_perm(repo, path.buf);\n @@ refs.c: const char *ref_transaction_error_msg(enum ref_transaction_error err)\n +\tstrbuf_addf(&path, \"%s/refs\", refdir);\n +\tsafe_create_dir(repo, path.buf, 1);\n +\n -+\tif (refs_heads_msg) {\n ++\tif (refs_heads_content) {\n +\t\tstrbuf_reset(&path);\n +\t\tstrbuf_addf(&path, \"%s/refs/heads\", refdir);\n -+\t\twrite_file(path.buf, \"%s\", refs_heads_msg);\n ++\t\twrite_file(path.buf, \"%s\", refs_heads_content);\n +\t\tadjust_shared_perm(repo, path.buf);\n +\t}\n +\n3: 330a9bd253 ! 2: a907b190d1 refs: parse and use the reference storage payload\n @@ Metadata\n Author: Karthik Nayak \n \n ## Commit message ##\n - refs: parse and use the reference storage payload\n + refs: forward and use the reference storage payload\n \n - The previous commit extended the 'extensions.refStorage' config to add\n - support for a reference storage payload. The payload provides backend\n - specific information on where to store references for a given directory.\n + An upcoming commit will add support for providing an URI via the\n + 'extensions.refStorage' config. The URI will contain the reference\n + backend and a corresponding payload. The payload can be then used for\n + providing an alternate locations for the reference backend.\n \n - Propagate this information to individual backends when initializing them\n - via the 'init()' function. Both the files and reftable backends will\n - parse the information to be filesystem paths to store references.\n + To prepare for this, modify the existing backends to accept such an\n + argument when initializing via the 'init()' function. Both the files\n + and reftable backends will parse the information to be filesystem paths\n + to store references.\n \n To enable this, provide a 'refs_compute_filesystem_location()' function\n which will parse the current 'gitdir' and the 'payload' to provide the\n final reference directory and common reference directory (if working in\n a linked worktree).\n \n - Finally, for linked worktrees, traditionally references were stored in\n - the '$GIT_DIR/worktrees/' path. But when using an alternate\n - reference storage path, it doesn't make sense to store main worktree\n - references in the new path, and linked worktree references in the\n - $GIT_DIR path. So, let's store linked worktree references in\n - '$ALTERNATE_REFERENCE_DIR/worktrees/\n Signed-off-by: Karthik Nayak \n \n - ## Documentation/config/extensions.adoc ##\n -@@ Documentation/config/extensions.adoc: For historical reasons, this extension is respected regardless of the\n - `core.repositoryFormatVersion` setting.\n - \n - refStorage:::\n --\tSpecify the ref storage format to use. The acceptable values are:\n -+\tSpecify the ref storage format and location to use. The value can be\n -+\teither a format name or a URI:\n - +\n - --\n -+* A format name alone (e.g., `reftable` or `files`) uses the default\n -+ location (the repository's common directory).\n -+\n -+* A URI format `://` explicitly specifies both the\n -+ format and payload (e.g., `reftable:///foo/bar`).\n -+\n -+Supported format names are:\n -++\n - include::../ref-storage-format.adoc[]\n -++\n -+The payload is passed directly to the reference backend. For the files and\n -+reftable backends, this must be a filesystem path. Relative paths are resolved\n -+relative to the $GIT_DIR. Future backends may support other payload schemes,\n -+e.g., postgres://127.0.0.1:5432?database=myrepo.\n - --\n - +\n - Note that this setting should only be set by linkgit:git-init[1] or\n -\n - ## builtin/worktree.c ##\n -@@ builtin/worktree.c: static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n - \treturn run_command(&cp);\n - }\n - \n -+/*\n -+ * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n -+ * But when using alternate reference directories, we want to store the worktree\n -+ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n -+ *\n -+ * Create the necessary folder structure to facilitate the same. But to ensure\n -+ * that the former path is still considered a Git directory, add stubs (similar\n -+ * to how we do in the reftable backend).\n -+ */\n -+static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n -+{\n -+\tstruct strbuf sb = STRBUF_INIT;\n -+\tchar *path;\n -+\n -+\tpath = wt->repo->ref_storage_payload;\n -+\tif (!path)\n -+\t\treturn;\n -+\n -+\tif (!is_absolute_path(path))\n -+\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n -+\n -+\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n -+\tsafe_create_dir(wt->repo, sb.buf, 1);\n -+\tstrbuf_addf(&sb, \"/%s\", wt->id);\n -+\tsafe_create_dir(wt->repo, sb.buf, 1);\n -+\tstrbuf_reset(&sb);\n -+\n -+\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n -+\t\t path, wt->id);\n -+\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n -+\n -+\tstrbuf_release(&sb);\n -+}\n -+\n - static int add_worktree(const char *path, const char *refname,\n - \t\t\tconst struct add_opts *opts)\n - {\n -@@ builtin/worktree.c: static int add_worktree(const char *path, const char *refname,\n - \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n - \t\tgoto done;\n - \t}\n -+\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n - \twt_refs = get_worktree_ref_store(wt);\n - \n - \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\n -\n ## refs.c ##\n @@\n #define USE_THE_REPOSITORY_VARIABLE\n @@ refs.c: static struct ref_store *ref_store_init(struct repository *repo,\n \t\tBUG(\"reference backend is unknown\");\n \n -\trefs = be->init(repo, gitdir, flags);\n -+\t/*\n -+\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n -+\t * allow the backend to handle how it wants to deal with worktrees.\n -+\t */\n -+\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n ++\trefs = be->init(repo, NULL, gitdir, flags);\n \treturn refs;\n }\n \n @@ refs/files-backend.c: static void clear_loose_ref_cache(struct files_ref_store *\n \trefs->store_flags = flags;\n -\tget_common_dir_noenv(&sb, gitdir);\n -\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n -+\trefs->gitcommondir = xstrdup(ref_common_dir.buf);\n ++\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n \trefs->packed_ref_store =\n -\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n -+\t\tpacked_ref_store_init(repo, payload, ref_common_dir.buf, flags);\n ++\t\tpacked_ref_store_init(repo, payload, refs->gitcommondir, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n @@ refs/files-backend.c: static struct ref_store *files_ref_store_init(struct repos\n \tchdir_notify_reparent(\"files-backend $GIT_COMMONDIR\",\n \t\t\t &refs->gitcommondir);\n \n -+\tstrbuf_release(&ref_common_dir);\n +\tstrbuf_release(&refdir);\n +\n \treturn ref_store;\n @@ refs/reftable-backend.c: static struct ref_store *reftable_be_init(struct reposi\n \tstrbuf_release(&path);\n \treturn &refs->base;\n }\n -\n - ## t/meson.build ##\n -@@ t/meson.build: integration_tests = [\n - 't1420-lost-found.sh',\n - 't1421-reflog-write.sh',\n - 't1422-show-ref-exists.sh',\n -+ 't1423-ref-backend.sh',\n - 't1430-bad-ref-name.sh',\n - 't1450-fsck.sh',\n - 't1451-fsck-buffer.sh',\n -\n - ## t/t1423-ref-backend.sh (new) ##\n -@@\n -+#!/bin/sh\n -+\n -+test_description='Test reference backend URIs'\n -+\n -+. ./test-lib.sh\n -+\n -+# Run a git command with the provided reference storage. Reset the backend\n -+# post running the command.\n -+# Usage: run_with_uri \n -+# is the relative path to the repo to run the command in.\n -+# is the original ref storage of the repo.\n -+# is the new URI to be set for the ref storage.\n -+# is the git subcommand to be run in the repository.\n -+run_with_uri() {\n -+\trepo=$1 &&\n -+\tbackend=$2 &&\n -+\turi=$3 &&\n -+\tcmd=$4 &&\n -+\n -+\tgit -C \"$repo\" config set core.repositoryformatversion 1\n -+\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n -+\tgit -C \"$repo\" $cmd &&\n -+\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n -+}\n -+\n -+# Test a repository with a given reference storage by running and comparing\n -+# 'git refs list' before and after setting the new reference backend. If\n -+# err_msg is set, expect the command to fail and grep for the provided err_msg.\n -+# Usage: run_with_uri \n -+# is the relative path to the repo to run the command in.\n -+# is the original ref storage of the repo.\n -+# is the new URI to be set for the ref storage.\n -+# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n -+test_refs_backend() {\n -+\trepo=$1 &&\n -+\tbackend=$2 &&\n -+\turi=$3 &&\n -+\terr_msg=$4 &&\n -+\n -+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n -+\tif test -n \"$err_msg\";\n -+\tthen\n -+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n -+\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n -+\t\ttest_grep \"$err_msg\" err\n -+\telse\n -+\t\tgit -C \"$repo\" refs list >expect &&\n -+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n -+\t\ttest_cmp expect actual\n -+\tfi\n -+}\n -+\n -+test_expect_success 'URI is invalid' '\n -+\ttest_when_finished \"rm -rf repo\" &&\n -+\tgit init repo &&\n -+\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n -+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n -+'\n -+\n -+test_expect_success 'URI ends with colon' '\n -+\ttest_when_finished \"rm -rf repo\" &&\n -+\tgit init repo &&\n -+\ttest_refs_backend repo files \"reftable:\" \\\n -+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n -+'\n -+\n -+test_expect_success 'unknown reference backend' '\n -+\ttest_when_finished \"rm -rf repo\" &&\n -+\tgit init repo &&\n -+\ttest_refs_backend repo files \"db://.git\" \\\n -+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n -+'\n -+\n -+ref_formats=\"files reftable\"\n -+for from_format in $ref_formats\n -+do\n -+\n -+for to_format in $ref_formats\n -+do\n -+\tif test \"$from_format\" = \"$to_format\"\n -+\tthen\n -+\t\tcontinue\n -+\tfi\n -+\n -+\n -+\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n -+\tdo\n -+\n -+\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n -+\t\t\ttest_when_finished \"rm -rf repo\" &&\n -+\t\t\tgit init --ref-format=$from_format repo &&\n -+\t\t\t(\n -+\t\t\t\tcd repo &&\n -+\t\t\t\ttest_commit 1 &&\n -+\t\t\t\ttest_commit 2 &&\n -+\t\t\t\ttest_commit 3 &&\n -+\n -+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n -+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n -+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n -+\t\t\t)\n -+\t\t'\n -+\n -+\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n -+\t\t\ttest_when_finished \"rm -rf repo\" &&\n -+\t\t\tgit init --ref-format=$from_format repo &&\n -+\t\t\t(\n -+\t\t\t\tcd repo &&\n -+\t\t\t\ttest_commit 1 &&\n -+\t\t\t\ttest_commit 2 &&\n -+\t\t\t\ttest_commit 3 &&\n -+\n -+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n -+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n -+\n -+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n -+\n -+\t\t\t\tgit refs list >expect &&\n -+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n -+\t\t\t\tgit refs list >actual &&\n -+\t\t\t\ttest_cmp expect actual &&\n -+\n -+\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n -+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n -+\t\t\t\ttest_cmp expect actual\n -+\t\t\t)\n -+\t\t'\n -+\n -+\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n -+\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n -+\t\t\tgit init --ref-format=$from_format repo &&\n -+\t\t\t(\n -+\t\t\t\tcd repo &&\n -+\t\t\t\ttest_commit 1 &&\n -+\t\t\t\ttest_commit 2 &&\n -+\t\t\t\ttest_commit 3 &&\n -+\n -+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n -+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n -+\n -+\t\t\t\tgit config set core.repositoryformatversion 1 &&\n -+\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n -+\n -+\t\t\t\tgit worktree add ../wt 2\n -+\t\t\t) &&\n -+\n -+\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n -+\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n -+\t\t\t! test_cmp expect actual &&\n -+\n -+\t\t\tgit -C wt rev-parse 2 >expect &&\n -+\t\t\tgit -C wt rev-parse HEAD >actual &&\n -+\t\t\ttest_cmp expect actual\n -+\t\t'\n -+\tdone # closes dir\n -+done # closes to_format\n -+done # closes from_format\n -+\n -+test_done\n1: 77ec79dfc7 ! 3: 630aef7910 refs: allow reference location in refstorage config\n @@ Commit message\n utilize the $GIT_DIR as the reference folder by default in\n `get_main_ref_store()`.\n \n - Since the reference backends are pluggable, this means that they should\n + Since the reference backends are pluggable, this means that they could\n work with out-of-tree reference directories too. Extend the 'refStorage'\n config to also support taking an URI input, where users can specify the\n reference backend and the location.\n \n Add the required changes to obtain and propagate this value to the\n - individual backends. A follow up commit will add the required changes on\n - the backends to parse this value.\n + individual backends also add the necessary documentation and tests.\n +\n + Traditionally, for linked worktrees, references were stored in the\n + '$GIT_DIR/worktrees/' path. But when using an alternate reference\n + storage path, it doesn't make sense to store the main worktree\n + references in the new path, and the linked worktree references in the\n + $GIT_DIR. So, let's store linked worktree references in\n + '$ALTERNATE_REFERENCE_DIR/worktrees/'. To do this, create the\n + necessary files and folders while also adding stubs in the $GIT_DIR path\n + to ensure that it is still considered a Git directory.\n +\n + Ideally, we would want to pass in a `struct worktree *` to individual\n + backends, instead of passing the `gitdir`. This allows them to handle\n + worktree specific logic. Currently, that is not possible since the\n + worktree code is:\n +\n + - Tied to using the global `the_repository` variable.\n +\n + - Is not setup before the reference database during initialization of\n + the repository.\n +\n + Add a TODO in 'refs.c' to ensure we can eventually make that change.\n \n Helped-by: Patrick Steinhardt \n Signed-off-by: Karthik Nayak \n \n + ## Documentation/config/extensions.adoc ##\n +@@ Documentation/config/extensions.adoc: For historical reasons, this extension is respected regardless of the\n + `core.repositoryFormatVersion` setting.\n + \n + refStorage:::\n +-\tSpecify the ref storage format to use. The acceptable values are:\n ++\tSpecify the ref storage format and a corresponding payload. The value\n ++\tcan be either a format name or a URI:\n + +\n + --\n ++* A format name alone (e.g., `reftable` or `files`).\n ++\n ++* A URI format `://` explicitly specifies both the\n ++ format and payload (e.g., `reftable:///foo/bar`).\n ++\n ++Supported format names are:\n +++\n + include::../ref-storage-format.adoc[]\n +++\n ++The payload is passed directly to the reference backend. For the files and\n ++reftable backends, this must be a filesystem path where the references will\n ++be stored. Defaulting to the commondir when no payload is provided. Relative\n ++paths are resolved relative to the $GIT_DIR. Future backends may support\n ++other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n + --\n + +\n + Note that this setting should only be set by linkgit:git-init[1] or\n +\n ## builtin/clone.c ##\n @@ builtin/clone.c: int cmd_clone(int argc,\n \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n @@ builtin/clone.c: int cmd_clone(int argc,\n \t/*\n \t * Before fetching from the remote, download and install bundle\n \n + ## builtin/worktree.c ##\n +@@ builtin/worktree.c: static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n + \treturn run_command(&cp);\n + }\n + \n ++/*\n ++ * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n ++ * But when using alternate reference directories, we want to store the worktree\n ++ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n ++ *\n ++ * Create the necessary folder structure to facilitate the same. But to ensure\n ++ * that the former path is still considered a Git directory, add stubs.\n ++ */\n ++static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n ++{\n ++\tstruct strbuf sb = STRBUF_INIT;\n ++\tchar *path;\n ++\n ++\tpath = wt->repo->ref_storage_payload;\n ++\tif (!path)\n ++\t\treturn;\n ++\n ++\tif (!is_absolute_path(path))\n ++\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n ++\n ++\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n ++\tsafe_create_dir(wt->repo, sb.buf, 1);\n ++\tstrbuf_addf(&sb, \"/%s\", wt->id);\n ++\tsafe_create_dir(wt->repo, sb.buf, 1);\n ++\tstrbuf_reset(&sb);\n ++\n ++\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n ++\t\t path, wt->id);\n ++\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n ++\n ++\tstrbuf_release(&sb);\n ++}\n ++\n + static int add_worktree(const char *path, const char *refname,\n + \t\t\tconst struct add_opts *opts)\n + {\n +@@ builtin/worktree.c: static int add_worktree(const char *path, const char *refname,\n + \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n + \t\tgoto done;\n + \t}\n ++\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n + \twt_refs = get_worktree_ref_store(wt);\n + \n + \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\n +\n + ## refs.c ##\n +@@ refs.c: static struct ref_store *ref_store_init(struct repository *repo,\n + \tif (!be)\n + \t\tBUG(\"reference backend is unknown\");\n + \n +-\trefs = be->init(repo, NULL, gitdir, flags);\n ++\t/*\n ++\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n ++\t * allow the backend to handle how it wants to deal with worktrees.\n ++\t */\n ++\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n + \treturn refs;\n + }\n + \n +\n ## repository.c ##\n @@ repository.c: void repo_set_compat_hash_algo(struct repository *repo, int algo)\n }\n @@ repository.h: struct repository {\n \n \t/* Repository's reference storage format, as serialized on disk. */\n \tenum ref_storage_format ref_storage_format;\n -+\t/* Reference storage information as needed for the backend. */\n ++\t/*\n ++\t * Reference storage information as needed for the backend. This contains\n ++\t * only the payload from the reference URI without the schema.\n ++\t */\n +\tchar *ref_storage_payload;\n \n \t/* A unique-id for tracing purposes. */\n @@ setup.h: void initialize_repository_version(int hash_algo,\n \t\t\t const char *initial_branch, int quiet);\n \n /*\n +\n + ## t/meson.build ##\n +@@ t/meson.build: integration_tests = [\n + 't1420-lost-found.sh',\n + 't1421-reflog-write.sh',\n + 't1422-show-ref-exists.sh',\n ++ 't1423-ref-backend.sh',\n + 't1430-bad-ref-name.sh',\n + 't1450-fsck.sh',\n + 't1451-fsck-buffer.sh',\n +\n + ## t/t1423-ref-backend.sh (new) ##\n +@@\n ++#!/bin/sh\n ++\n ++test_description='Test reference backend URIs'\n ++\n ++. ./test-lib.sh\n ++\n ++# Run a git command with the provided reference storage. Reset the backend\n ++# post running the command.\n ++# Usage: run_with_uri \n ++# is the relative path to the repo to run the command in.\n ++# is the original ref storage of the repo.\n ++# is the new URI to be set for the ref storage.\n ++# is the git subcommand to be run in the repository.\n ++run_with_uri() {\n ++\trepo=$1 &&\n ++\tbackend=$2 &&\n ++\turi=$3 &&\n ++\tcmd=$4 &&\n ++\n ++\tgit -C \"$repo\" config set core.repositoryformatversion 1\n ++\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n ++\tgit -C \"$repo\" $cmd &&\n ++\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n ++}\n ++\n ++# Test a repository with a given reference storage by running and comparing\n ++# 'git refs list' before and after setting the new reference backend. If\n ++# err_msg is set, expect the command to fail and grep for the provided err_msg.\n ++# Usage: run_with_uri \n ++# is the relative path to the repo to run the command in.\n ++# is the original ref storage of the repo.\n ++# is the new URI to be set for the ref storage.\n ++# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n ++test_refs_backend() {\n ++\trepo=$1 &&\n ++\tbackend=$2 &&\n ++\turi=$3 &&\n ++\terr_msg=$4 &&\n ++\n ++\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n ++\tif test -n \"$err_msg\";\n ++\tthen\n ++\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n ++\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n ++\t\ttest_grep \"$err_msg\" err\n ++\telse\n ++\t\tgit -C \"$repo\" refs list >expect &&\n ++\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n ++\t\ttest_cmp expect actual\n ++\tfi\n ++}\n ++\n ++test_expect_success 'URI is invalid' '\n ++\ttest_when_finished \"rm -rf repo\" &&\n ++\tgit init repo &&\n ++\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n ++\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n ++'\n ++\n ++test_expect_success 'URI ends with colon' '\n ++\ttest_when_finished \"rm -rf repo\" &&\n ++\tgit init repo &&\n ++\ttest_refs_backend repo files \"reftable:\" \\\n ++\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n ++'\n ++\n ++test_expect_success 'unknown reference backend' '\n ++\ttest_when_finished \"rm -rf repo\" &&\n ++\tgit init repo &&\n ++\ttest_refs_backend repo files \"db://.git\" \\\n ++\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n ++'\n ++\n ++ref_formats=\"files reftable\"\n ++for from_format in $ref_formats\n ++do\n ++\n ++for to_format in $ref_formats\n ++do\n ++\tif test \"$from_format\" = \"$to_format\"\n ++\tthen\n ++\t\tcontinue\n ++\tfi\n ++\n ++\n ++\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n ++\tdo\n ++\n ++\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n ++\t\t\ttest_when_finished \"rm -rf repo\" &&\n ++\t\t\tgit init --ref-format=$from_format repo &&\n ++\t\t\t(\n ++\t\t\t\tcd repo &&\n ++\t\t\t\ttest_commit 1 &&\n ++\t\t\t\ttest_commit 2 &&\n ++\t\t\t\ttest_commit 3 &&\n ++\n ++\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n ++\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n ++\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n ++\t\t\t)\n ++\t\t'\n ++\n ++\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n ++\t\t\ttest_when_finished \"rm -rf repo\" &&\n ++\t\t\tgit init --ref-format=$from_format repo &&\n ++\t\t\t(\n ++\t\t\t\tcd repo &&\n ++\t\t\t\ttest_commit 1 &&\n ++\t\t\t\ttest_commit 2 &&\n ++\t\t\t\ttest_commit 3 &&\n ++\n ++\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n ++\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n ++\n ++\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n ++\n ++\t\t\t\tgit refs list >expect &&\n ++\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n ++\t\t\t\tgit refs list >actual &&\n ++\t\t\t\ttest_cmp expect actual &&\n ++\n ++\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n ++\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n ++\t\t\t\ttest_cmp expect actual\n ++\t\t\t)\n ++\t\t'\n ++\n ++\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n ++\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n ++\t\t\tgit init --ref-format=$from_format repo &&\n ++\t\t\t(\n ++\t\t\t\tcd repo &&\n ++\t\t\t\ttest_commit 1 &&\n ++\t\t\t\ttest_commit 2 &&\n ++\t\t\t\ttest_commit 3 &&\n ++\n ++\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n ++\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n ++\n ++\t\t\t\tgit config set core.repositoryformatversion 1 &&\n ++\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n ++\n ++\t\t\t\tgit worktree add ../wt 2\n ++\t\t\t) &&\n ++\n ++\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n ++\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n ++\t\t\t! test_cmp expect actual &&\n ++\n ++\t\t\tgit -C wt rev-parse 2 >expect &&\n ++\t\t\tgit -C wt rev-parse HEAD >actual &&\n ++\t\t\ttest_cmp expect actual\n ++\t\t'\n ++\tdone # closes dir\n ++done # closes to_format\n ++done # closes from_format\n ++\n ++test_done\n4: dbb7d9c632 ! 4: 590bb706dd refs: add GIT_REFERENCE_BACKEND to specify reference backend\n @@ Commit message\n Let's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\n takes in the same input as the config variable. Having an environment\n variable allows us to modify the reference backend and location on the\n - fly for individual git commands.\n + fly for individual Git commands.\n \n Helped-by: Jean-Noël Avila \n Signed-off-by: Karthik Nayak \n @@ Documentation/git.adoc: double-quotes and respecting backslash escapes. E.g., th\n +`GIT_REFERENCE_BACKEND`::\n + Specify which reference backend to be used along with its URI.\n + See `extensions.refStorage` option in linkgit:git-config[1] for more\n -+ description. Overrides the config variable when used.\n ++ details. Overrides the config variable when used.\n +\n Git Commits\n ~~~~~~~~~~~\n\n\nbase-commit: 22584464849815268419fd9d2eba307362360db1\nchange-id: 20251105-kn-alternate-ref-dir-3e572e8cd0ef\n\nThanks\n- Karthik\n\n"},{"id":"535551","messageId":"20260209-kn-alternate-ref-dir-v5-1-740899834ceb@gmail.com","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","subject":"[PATCH v5 1/4] refs: extract out `refs_create_refdir_stubs()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T15:58:18Z","receivedAt":"2026-02-09T15:58:25Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"For Git to recognize a directory as a Git directory, it requires the\ndirectory to contain:\n\n 1. 'HEAD' file\n 2. 'objects/' directory\n 3. 'refs/' directory\n\nHere, #1 and #3 are part of the reference storage mechanism,\nspecifically the files backend. Since then, newer backends such as the\nreftable backend have moved to using their own path ('reftable/') for\nstoring references. But to ensure Git still recognizes the directory as\na Git directory, we create stubs.\n\nThere are two locations where we create stubs:\n\n- In 'refs/reftable-backend.c' when creating the reftable backend.\n- In 'clone.c' before spawning transport helpers.\n\nIn a following commit, we'll add another instance. So instead of\nrepeating the code, let's extract out this code to\n`refs_create_refdir_stubs()` and use it.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 7 +------\n refs.c | 23 +++++++++++++++++++++++\n refs.h | 13 +++++++++++++\n refs/reftable-backend.c | 14 ++------------\n 4 files changed, 39 insertions(+), 18 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex b40cee5968..535a257b10 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1225,12 +1225,7 @@ int cmd_clone(int argc,\n \tinitialize_repository_version(GIT_HASH_UNKNOWN,\n \t\t\t\t the_repository->ref_storage_format, 1);\n \n-\tstrbuf_addf(&buf, \"%s/HEAD\", git_dir);\n-\twrite_file(buf.buf, \"ref: refs/heads/.invalid\");\n-\n-\tstrbuf_reset(&buf);\n-\tstrbuf_addf(&buf, \"%s/refs\", git_dir);\n-\tsafe_create_dir(the_repository, buf.buf, 1);\n+\trefs_create_refdir_stubs(the_repository, git_dir, NULL);\n \n \t/*\n \t * additional config can be injected with -c, make sure it's included\ndiff --git a/refs.c b/refs.c\nindex 627b7f8698..36f3441632 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -3402,3 +3402,26 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n \t\treturn \"unknown failure\";\n \t}\n }\n+\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_content)\n+{\n+\tstruct strbuf path = STRBUF_INIT;\n+\n+\tstrbuf_addf(&path, \"%s/HEAD\", refdir);\n+\twrite_file(path.buf, \"ref: refs/heads/.invalid\");\n+\tadjust_shared_perm(repo, path.buf);\n+\n+\tstrbuf_reset(&path);\n+\tstrbuf_addf(&path, \"%s/refs\", refdir);\n+\tsafe_create_dir(repo, path.buf, 1);\n+\n+\tif (refs_heads_content) {\n+\t\tstrbuf_reset(&path);\n+\t\tstrbuf_addf(&path, \"%s/refs/heads\", refdir);\n+\t\twrite_file(path.buf, \"%s\", refs_heads_content);\n+\t\tadjust_shared_perm(repo, path.buf);\n+\t}\n+\n+\tstrbuf_release(&path);\n+}\ndiff --git a/refs.h b/refs.h\nindex f0abfa1d93..9d8890fdff 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -1427,4 +1427,17 @@ void ref_iterator_free(struct ref_iterator *ref_iterator);\n int do_for_each_ref_iterator(struct ref_iterator *iter,\n \t\t\t each_ref_fn fn, void *cb_data);\n \n+/*\n+ * Git only recognizes a directory as a repository if it contains:\n+ * - HEAD file\n+ * - refs/ folder\n+ * While it is necessary within the files backend, newer backends may not\n+ * follow the same structure. To go around this, we create stubs as necessary.\n+ *\n+ * If provided with a 'refs_heads_msg', we create the 'refs/heads/head' file\n+ * with the provided message.\n+ */\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_msg);\n+\n #endif /* REFS_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex fe74af73af..d8651fe779 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,18 +491,8 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"ref: refs/heads/.invalid\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tsafe_create_dir(the_repository, sb.buf, 1);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"this repository uses the reftable format\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n+\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n+\t\t\t\t \"this repository uses the reftable format\");\n \n \tstrbuf_release(&sb);\n \treturn 0;\n\n-- \n2.52.0\n\n"},{"id":"535552","messageId":"20260209-kn-alternate-ref-dir-v5-2-740899834ceb@gmail.com","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","subject":"[PATCH v5 2/4] refs: forward and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T15:58:19Z","receivedAt":"2026-02-09T15:58:27Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"An upcoming commit will add support for providing an URI via the\n'extensions.refStorage' config. The URI will contain the reference\nbackend and a corresponding payload. The payload can be then used for\nproviding an alternate locations for the reference backend.\n\nTo prepare for this, modify the existing backends to accept such an\nargument when initializing via the 'init()' function. Both the files\nand reftable backends will parse the information to be filesystem paths\nto store references.\n\nTo enable this, provide a 'refs_compute_filesystem_location()' function\nwhich will parse the current 'gitdir' and the 'payload' to provide the\nfinal reference directory and common reference directory (if working in\na linked worktree).\n\nThe documentation and tests will be added alongside the extension of the\nconfig variable.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n refs.c | 33 ++++++++++++++++++++++++++++++++-\n refs/files-backend.c | 17 ++++++++++++-----\n refs/packed-backend.c | 1 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 15 +++++++++++++++\n refs/reftable-backend.c | 24 ++++++++++++++----------\n 6 files changed, 75 insertions(+), 16 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex 36f3441632..d9df25d7c0 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -5,6 +5,7 @@\n #define USE_THE_REPOSITORY_VARIABLE\n \n #include \"git-compat-util.h\"\n+#include \"abspath.h\"\n #include \"advice.h\"\n #include \"config.h\"\n #include \"environment.h\"\n@@ -2224,7 +2225,7 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, gitdir, flags);\n+\trefs = be->init(repo, NULL, gitdir, flags);\n \treturn refs;\n }\n \n@@ -3425,3 +3426,33 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n \n \tstrbuf_release(&path);\n }\n+\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\n+\tstrbuf_addstr(refdir, gitdir);\n+\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n+\n+\tif (!payload)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(payload)) {\n+\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n+\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n+\t} else {\n+\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n+\t}\n+\n+\tstrbuf_reset(refdir);\n+\tstrbuf_addbuf(refdir, ref_common_dir);\n+\n+\tif (*is_worktree) {\n+\t\tchar *wt_id = strrchr(gitdir, '/') + 1;\n+\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id);\n+\t}\n+\n+\tstrbuf_release(&sb);\n+}\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex 240d3c3b26..b192ce606d 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n * set of caches.\n */\n static struct ref_store *files_ref_store_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags)\n {\n \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n \tstruct ref_store *ref_store = (struct ref_store *)refs;\n-\tstruct strbuf sb = STRBUF_INIT;\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n+\tbool is_worktree;\n+\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n \n-\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n+\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n \trefs->store_flags = flags;\n-\tget_common_dir_noenv(&sb, gitdir);\n-\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n+\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n \trefs->packed_ref_store =\n-\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n+\t\tpacked_ref_store_init(repo, payload, refs->gitcommondir, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n@@ -126,6 +131,8 @@ static struct ref_store *files_ref_store_init(struct repository *repo,\n \tchdir_notify_reparent(\"files-backend $GIT_COMMONDIR\",\n \t\t\t &refs->gitcommondir);\n \n+\tstrbuf_release(&refdir);\n+\n \treturn ref_store;\n }\n \ndiff --git a/refs/packed-backend.c b/refs/packed-backend.c\nindex 4ea0c12299..028fbc0585 100644\n--- a/refs/packed-backend.c\n+++ b/refs/packed-backend.c\n@@ -212,6 +212,7 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n }\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload UNUSED,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags)\n {\ndiff --git a/refs/packed-backend.h b/refs/packed-backend.h\nindex 9481d5e7c2..2c2377a356 100644\n--- a/refs/packed-backend.h\n+++ b/refs/packed-backend.h\n@@ -14,6 +14,7 @@ struct ref_transaction;\n */\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags);\n \ndiff --git a/refs/refs-internal.h b/refs/refs-internal.h\nindex c7d2a6e50b..bd09b1280c 100644\n--- a/refs/refs-internal.h\n+++ b/refs/refs-internal.h\n@@ -389,6 +389,7 @@ struct ref_store;\n * the ref_store and to record the ref_store for later lookup.\n */\n typedef struct ref_store *ref_store_init_fn(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags);\n /*\n@@ -666,4 +667,18 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n \t\t\t\t\t unsigned int initial_transaction,\n \t\t\t\t\t struct strbuf *err);\n \n+/*\n+ * Given a gitdir and the reference storage payload provided, retrieve the\n+ * 'refdir' and 'ref_common_dir'. The former is where references should be\n+ * stored for the current worktree, the latter is the common reference\n+ * directory if working with a linked worktree. If working with the main\n+ * worktree, both values will be the same.\n+ *\n+ * This is used by backends such as {files, reftable} which store references in\n+ * dedicated filesystem paths.\n+ */\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir);\n+\n #endif /* REFS_REFS_INTERNAL_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex d8651fe779..964b0b50fc 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -372,18 +372,24 @@ static int reftable_be_fsync(int fd)\n }\n \n static struct ref_store *reftable_be_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int store_flags)\n {\n \tstruct reftable_ref_store *refs = xcalloc(1, sizeof(*refs));\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n \tstruct strbuf path = STRBUF_INIT;\n-\tint is_worktree;\n+\tbool is_worktree;\n \tmode_t mask;\n \n \tmask = umask(0);\n \tumask(mask);\n \n-\tbase_ref_store_init(&refs->base, repo, gitdir, &refs_be_reftable);\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n+\n+\tbase_ref_store_init(&refs->base, repo, refdir.buf, &refs_be_reftable);\n \tstrmap_init(&refs->worktree_backends);\n \trefs->store_flags = store_flags;\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n@@ -419,14 +425,11 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t/*\n \t * Set up the main reftable stack that is hosted in GIT_COMMON_DIR.\n \t * This stack contains both the shared and the main worktree refs.\n-\t *\n-\t * Note that we don't try to resolve the path in case we have a\n-\t * worktree because `get_common_dir_noenv()` already does it for us.\n \t */\n-\tis_worktree = get_common_dir_noenv(&path, gitdir);\n+\tstrbuf_addbuf(&path, &ref_common_dir);\n \tif (!is_worktree) {\n \t\tstrbuf_reset(&path);\n-\t\tstrbuf_realpath(&path, gitdir, 0);\n+\t\tstrbuf_realpath(&path, ref_common_dir.buf, 0);\n \t}\n \tstrbuf_addstr(&path, \"/reftable\");\n \trefs->err = reftable_backend_init(&refs->main_backend, path.buf,\n@@ -443,10 +446,9 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t * do it efficiently.\n \t */\n \tif (is_worktree) {\n-\t\tstrbuf_reset(&path);\n-\t\tstrbuf_addf(&path, \"%s/reftable\", gitdir);\n+\t\tstrbuf_addstr(&refdir, \"/reftable\");\n \n-\t\trefs->err = reftable_backend_init(&refs->worktree_backend, path.buf,\n+\t\trefs->err = reftable_backend_init(&refs->worktree_backend, refdir.buf,\n \t\t\t\t\t\t &refs->write_options);\n \t\tif (refs->err)\n \t\t\tgoto done;\n@@ -456,6 +458,8 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \n done:\n \tassert(refs->err != REFTABLE_API_ERROR);\n+\tstrbuf_release(&ref_common_dir);\n+\tstrbuf_release(&refdir);\n \tstrbuf_release(&path);\n \treturn &refs->base;\n }\n\n-- \n2.52.0\n\n"},{"id":"535553","messageId":"20260209-kn-alternate-ref-dir-v5-3-740899834ceb@gmail.com","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","subject":"[PATCH v5 3/4] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T15:58:20Z","receivedAt":"2026-02-09T15:58:28Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'extensions.refStorage' config is used to specify the reference\nbackend for a given repository. Both the 'files' and 'reftable' backends\nutilize the $GIT_DIR as the reference folder by default in\n`get_main_ref_store()`.\n\nSince the reference backends are pluggable, this means that they could\nwork with out-of-tree reference directories too. Extend the 'refStorage'\nconfig to also support taking an URI input, where users can specify the\nreference backend and the location.\n\nAdd the required changes to obtain and propagate this value to the\nindividual backends also add the necessary documentation and tests.\n\nTraditionally, for linked worktrees, references were stored in the\n'$GIT_DIR/worktrees/' path. But when using an alternate reference\nstorage path, it doesn't make sense to store the main worktree\nreferences in the new path, and the linked worktree references in the\n$GIT_DIR. So, let's store linked worktree references in\n'$ALTERNATE_REFERENCE_DIR/worktrees/'. To do this, create the\nnecessary files and folders while also adding stubs in the $GIT_DIR path\nto ensure that it is still considered a Git directory.\n\nIdeally, we would want to pass in a `struct worktree *` to individual\nbackends, instead of passing the `gitdir`. This allows them to handle\nworktree specific logic. Currently, that is not possible since the\nworktree code is:\n\n - Tied to using the global `the_repository` variable.\n\n - Is not setup before the reference database during initialization of\n the repository.\n\nAdd a TODO in 'refs.c' to ensure we can eventually make that change.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n Documentation/config/extensions.adoc | 16 +++-\n builtin/clone.c | 3 +-\n builtin/worktree.c | 34 ++++++++\n refs.c | 6 +-\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 39 +++++++--\n setup.h | 2 +\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n 10 files changed, 266 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 532456644b..3e51da36d3 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n `core.repositoryFormatVersion` setting.\n \n refStorage:::\n-\tSpecify the ref storage format to use. The acceptable values are:\n+\tSpecify the ref storage format and a corresponding payload. The value\n+\tcan be either a format name or a URI:\n +\n --\n+* A format name alone (e.g., `reftable` or `files`).\n+\n+* A URI format `://` explicitly specifies both the\n+ format and payload (e.g., `reftable:///foo/bar`).\n+\n+Supported format names are:\n++\n include::../ref-storage-format.adoc[]\n++\n+The payload is passed directly to the reference backend. For the files and\n+reftable backends, this must be a filesystem path where the references will\n+be stored. Defaulting to the commondir when no payload is provided. Relative\n+paths are resolved relative to the $GIT_DIR. Future backends may support\n+other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n Note that this setting should only be set by linkgit:git-init[1] or\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex 535a257b10..11854894d3 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1437,7 +1437,8 @@ int cmd_clone(int argc,\n \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n \trepo_set_hash_algo(the_repository, hash_algo);\n-\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n+\tcreate_reference_database(the_repository->ref_storage_format,\n+\t\t\t\t the_repository->ref_storage_payload, NULL, 1);\n \n \t/*\n \t * Before fetching from the remote, download and install bundle\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..94480be5c4 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -425,6 +425,39 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n \treturn run_command(&cp);\n }\n \n+/*\n+ * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n+ * But when using alternate reference directories, we want to store the worktree\n+ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n+ *\n+ * Create the necessary folder structure to facilitate the same. But to ensure\n+ * that the former path is still considered a Git directory, add stubs.\n+ */\n+static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\tchar *path;\n+\n+\tpath = wt->repo->ref_storage_payload;\n+\tif (!path)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(path))\n+\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n+\n+\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_addf(&sb, \"/%s\", wt->id);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_reset(&sb);\n+\n+\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n+\t\t path, wt->id);\n+\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n+\n+\tstrbuf_release(&sb);\n+}\n+\n static int add_worktree(const char *path, const char *refname,\n \t\t\tconst struct add_opts *opts)\n {\n@@ -518,6 +551,7 @@ static int add_worktree(const char *path, const char *refname,\n \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n \t\tgoto done;\n \t}\n+\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n \twt_refs = get_worktree_ref_store(wt);\n \n \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\ndiff --git a/refs.c b/refs.c\nindex d9df25d7c0..f520d64a9d 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2225,7 +2225,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, NULL, gitdir, flags);\n+\t/*\n+\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n+\t * allow the backend to handle how it wants to deal with worktrees.\n+\t */\n+\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n \treturn refs;\n }\n \ndiff --git a/repository.c b/repository.c\nindex c7e75215ac..9815f081ef 100644\n--- a/repository.c\n+++ b/repository.c\n@@ -193,9 +193,12 @@ void repo_set_compat_hash_algo(struct repository *repo, int algo)\n }\n \n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format)\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload)\n {\n \trepo->ref_storage_format = format;\n+\tfree(repo->ref_storage_payload);\n+\trepo->ref_storage_payload = xstrdup_or_null(payload);\n }\n \n /*\n@@ -277,7 +280,8 @@ int repo_init(struct repository *repo,\n \n \trepo_set_hash_algo(repo, format.hash_algo);\n \trepo_set_compat_hash_algo(repo, format.compat_hash_algo);\n-\trepo_set_ref_storage_format(repo, format.ref_storage_format);\n+\trepo_set_ref_storage_format(repo, format.ref_storage_format,\n+\t\t\t\t format.ref_storage_payload);\n \trepo->repository_format_worktree_config = format.worktree_config;\n \trepo->repository_format_relative_worktrees = format.relative_worktrees;\n \trepo->repository_format_precious_objects = format.precious_objects;\n@@ -369,6 +373,7 @@ void repo_clear(struct repository *repo)\n \tFREE_AND_NULL(repo->index_file);\n \tFREE_AND_NULL(repo->worktree);\n \tFREE_AND_NULL(repo->submodule_prefix);\n+\tFREE_AND_NULL(repo->ref_storage_payload);\n \n \todb_free(repo->objects);\n \trepo->objects = NULL;\ndiff --git a/repository.h b/repository.h\nindex 6063c4b846..95e2333bad 100644\n--- a/repository.h\n+++ b/repository.h\n@@ -150,6 +150,11 @@ struct repository {\n \n \t/* Repository's reference storage format, as serialized on disk. */\n \tenum ref_storage_format ref_storage_format;\n+\t/*\n+\t * Reference storage information as needed for the backend. This contains\n+\t * only the payload from the reference URI without the schema.\n+\t */\n+\tchar *ref_storage_payload;\n \n \t/* A unique-id for tracing purposes. */\n \tint trace2_repo_id;\n@@ -204,7 +209,8 @@ void repo_set_worktree(struct repository *repo, const char *path);\n void repo_set_hash_algo(struct repository *repo, int algo);\n void repo_set_compat_hash_algo(struct repository *repo, int compat_algo);\n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format);\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload);\n void initialize_repository(struct repository *repo);\n RESULT_MUST_BE_USED\n int repo_init(struct repository *r, const char *gitdir, const char *worktree);\ndiff --git a/setup.c b/setup.c\nindex b723f8b339..44e393c251 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -632,6 +632,21 @@ static enum extension_result handle_extension_v0(const char *var,\n \t\treturn EXTENSION_UNKNOWN;\n }\n \n+static void parse_reference_uri(const char *value, char **format,\n+\t\t\t\tchar **payload)\n+{\n+\tchar *schema_end;\n+\n+\tschema_end = strstr(value, \"://\");\n+\tif (!schema_end) {\n+\t\t*format = xstrdup(value);\n+\t\t*payload = NULL;\n+\t} else {\n+\t\t*format = xstrndup(value, schema_end - value);\n+\t\t*payload = xstrdup_or_null(schema_end + 3);\n+\t}\n+}\n+\n /*\n * Record any new extensions in this function.\n */\n@@ -674,10 +689,17 @@ static enum extension_result handle_extension(const char *var,\n \t\treturn EXTENSION_OK;\n \t} else if (!strcmp(ext, \"refstorage\")) {\n \t\tunsigned int format;\n+\t\tchar *format_str;\n \n \t\tif (!value)\n \t\t\treturn config_error_nonbool(var);\n-\t\tformat = ref_storage_format_by_name(value);\n+\n+\t\tparse_reference_uri(value, &format_str,\n+\t\t\t\t &data->ref_storage_payload);\n+\n+\t\tformat = ref_storage_format_by_name(format_str);\n+\t\tfree(format_str);\n+\n \t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n \t\t\treturn error(_(\"invalid value for '%s': '%s'\"),\n \t\t\t\t \"extensions.refstorage\", value);\n@@ -850,6 +872,7 @@ void clear_repository_format(struct repository_format *format)\n \tstring_list_clear(&format->v1_only_extensions, 0);\n \tfree(format->work_tree);\n \tfree(format->partial_clone);\n+\tfree(format->ref_storage_payload);\n \tinit_repository_format(format);\n }\n \n@@ -1942,7 +1965,8 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\t\trepo_set_compat_hash_algo(the_repository,\n \t\t\t\t\t\t repo_fmt.compat_hash_algo);\n \t\t\trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t\t\t repo_fmt.ref_storage_format);\n+\t\t\t\t\t\t repo_fmt.ref_storage_format,\n+\t\t\t\t\t\t repo_fmt.ref_storage_payload);\n \t\t\tthe_repository->repository_format_worktree_config =\n \t\t\t\trepo_fmt.worktree_config;\n \t\t\tthe_repository->repository_format_relative_worktrees =\n@@ -2042,7 +2066,8 @@ void check_repository_format(struct repository_format *fmt)\n \trepo_set_hash_algo(the_repository, fmt->hash_algo);\n \trepo_set_compat_hash_algo(the_repository, fmt->compat_hash_algo);\n \trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t fmt->ref_storage_format);\n+\t\t\t\t fmt->ref_storage_format,\n+\t\t\t\t fmt->ref_storage_payload);\n \tthe_repository->repository_format_worktree_config =\n \t\tfmt->worktree_config;\n \tthe_repository->repository_format_relative_worktrees =\n@@ -2360,13 +2385,15 @@ static int is_reinit(void)\n }\n \n void create_reference_database(enum ref_storage_format ref_storage_format,\n+\t\t\t const char *ref_storage_payload,\n \t\t\t const char *initial_branch, int quiet)\n {\n \tstruct strbuf err = STRBUF_INIT;\n \tchar *to_free = NULL;\n \tint reinit = is_reinit();\n \n-\trepo_set_ref_storage_format(the_repository, ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, ref_storage_format,\n+\t\t\t\t ref_storage_payload);\n \tif (ref_store_create_on_disk(get_main_ref_store(the_repository), 0, &err))\n \t\tdie(\"failed to set up refs db: %s\", err.buf);\n \n@@ -2645,7 +2672,8 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n-\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n+\t\t\t\t repo_fmt->ref_storage_payload);\n }\n \n int init_db(const char *git_dir, const char *real_git_dir,\n@@ -2702,6 +2730,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n \n \tif (!(flags & INIT_DB_SKIP_REFDB))\n \t\tcreate_reference_database(repo_fmt.ref_storage_format,\n+\t\t\t\t\t repo_fmt.ref_storage_payload,\n \t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n \tcreate_object_directory();\n \ndiff --git a/setup.h b/setup.h\nindex d55dcc6608..4d25a353ac 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -171,6 +171,7 @@ struct repository_format {\n \tint hash_algo;\n \tint compat_hash_algo;\n \tenum ref_storage_format ref_storage_format;\n+\tchar *ref_storage_payload;\n \tint sparse_index;\n \tchar *work_tree;\n \tstruct string_list unknown_extensions;\n@@ -241,6 +242,7 @@ void initialize_repository_version(int hash_algo,\n \t\t\t\t enum ref_storage_format ref_storage_format,\n \t\t\t\t int reinit);\n void create_reference_database(enum ref_storage_format ref_storage_format,\n+\t\t\t const char *ref_storage_payload,\n \t\t\t const char *initial_branch, int quiet);\n \n /*\ndiff --git a/t/meson.build b/t/meson.build\nindex 459c52a489..11fc5a49ee 100644\n--- a/t/meson.build\n+++ b/t/meson.build\n@@ -210,6 +210,7 @@ integration_tests = [\n 't1420-lost-found.sh',\n 't1421-reflog-write.sh',\n 't1422-show-ref-exists.sh',\n+ 't1423-ref-backend.sh',\n 't1430-bad-ref-name.sh',\n 't1450-fsck.sh',\n 't1451-fsck-buffer.sh',\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nnew file mode 100755\nindex 0000000000..9c777b79f3\n--- /dev/null\n+++ b/t/t1423-ref-backend.sh\n@@ -0,0 +1,159 @@\n+#!/bin/sh\n+\n+test_description='Test reference backend URIs'\n+\n+. ./test-lib.sh\n+\n+# Run a git command with the provided reference storage. Reset the backend\n+# post running the command.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# is the git subcommand to be run in the repository.\n+run_with_uri() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\tcmd=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1\n+\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\tgit -C \"$repo\" $cmd &&\n+\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+}\n+\n+# Test a repository with a given reference storage by running and comparing\n+# 'git refs list' before and after setting the new reference backend. If\n+# err_msg is set, expect the command to fail and grep for the provided err_msg.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n+test_refs_backend() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\terr_msg=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test -n \"$err_msg\";\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\ttest_grep \"$err_msg\" err\n+\telse\n+\t\tgit -C \"$repo\" refs list >expect &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\ttest_cmp expect actual\n+\tfi\n+}\n+\n+test_expect_success 'URI is invalid' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'URI ends with colon' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable:\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'unknown reference backend' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"db://.git\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+ref_formats=\"files reftable\"\n+for from_format in $ref_formats\n+do\n+\n+for to_format in $ref_formats\n+do\n+\tif test \"$from_format\" = \"$to_format\"\n+\tthen\n+\t\tcontinue\n+\tfi\n+\n+\n+\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n+\tdo\n+\n+\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit refs list >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\tgit refs list >actual &&\n+\t\t\t\ttest_cmp expect actual &&\n+\n+\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\tgit config set core.repositoryformatversion 1 &&\n+\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit worktree add ../wt 2\n+\t\t\t) &&\n+\n+\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n+\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n+\t\t\t! test_cmp expect actual &&\n+\n+\t\t\tgit -C wt rev-parse 2 >expect &&\n+\t\t\tgit -C wt rev-parse HEAD >actual &&\n+\t\t\ttest_cmp expect actual\n+\t\t'\n+\tdone # closes dir\n+done # closes to_format\n+done # closes from_format\n+\n+test_done\n\n-- \n2.52.0\n\n"},{"id":"535554","messageId":"20260209-kn-alternate-ref-dir-v5-4-740899834ceb@gmail.com","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","subject":"[PATCH v5 4/4] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-09T15:58:21Z","receivedAt":"2026-02-09T15:58:30Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Git allows setting a different object directory via\n'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\nthe previous commit we extended the 'extensions.refStorage' config to\nalso support an URI input for reference backend with location.\n\nLet's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\ntakes in the same input as the config variable. Having an environment\nvariable allows us to modify the reference backend and location on the\nfly for individual Git commands.\n\nHelped-by: Jean-Noël Avila \nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 5 +++\n environment.h | 1 +\n setup.c | 20 +++++++++++\n t/t1423-ref-backend.sh | 96 ++++++++++++++++++++++++++++++++------------------\n 4 files changed, 88 insertions(+), 34 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..66442735ea 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n \trepositories will be set to this value. The default is \"files\".\n \tSee `--ref-format` in linkgit:git-init[1].\n \n+`GIT_REFERENCE_BACKEND`::\n+ Specify which reference backend to be used along with its URI.\n+ See `extensions.refStorage` option in linkgit:git-config[1] for more\n+ details. Overrides the config variable when used.\n+\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\ndiff --git a/environment.h b/environment.h\nindex 27f657af04..540e0a7f6d 100644\n--- a/environment.h\n+++ b/environment.h\n@@ -42,6 +42,7 @@\n #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n+#define GIT_REFERENCE_BACKEND_ENVIRONMENT \"GIT_REFERENCE_BACKEND\"\n \n /*\n * Environment variable used to propagate the --no-advice global option to the\ndiff --git a/setup.c b/setup.c\nindex 44e393c251..b4a7b82cca 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -1838,6 +1838,7 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \tstatic struct strbuf cwd = STRBUF_INIT;\n \tstruct strbuf dir = STRBUF_INIT, gitdir = STRBUF_INIT, report = STRBUF_INIT;\n \tconst char *prefix = NULL;\n+\tconst char *ref_backend_uri;\n \tstruct repository_format repo_fmt = REPOSITORY_FORMAT_INIT;\n \n \t/*\n@@ -1995,6 +1996,25 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\tsetenv(GIT_PREFIX_ENVIRONMENT, \"\", 1);\n \t}\n \n+\t/*\n+\t * The env variable should override the repository config\n+\t * for 'extensions.refStorage'.\n+\t */\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *location;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &location);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\t\trepo_set_ref_storage_format(the_repository, format, location);\n+\n+\t\tfree(backend);\n+\t\tfree(location);\n+\t}\n+\n \tsetup_original_cwd();\n \n \tstrbuf_release(&dir);\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nindex 9c777b79f3..10a9bb1a9b 100755\n--- a/t/t1423-ref-backend.sh\n+++ b/t/t1423-ref-backend.sh\n@@ -11,16 +11,25 @@ test_description='Test reference backend URIs'\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n # is the git subcommand to be run in the repository.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n run_with_uri() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n \tcmd=$4 &&\n+\tvia=$5 &&\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1\n-\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\tgit -C \"$repo\" $cmd &&\n-\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test \"$via\" = \"env\"\n+\tthen\n+\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" git -C \"$repo\" $cmd\n+\telif test \"$via\" = \"config\"\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\tgit -C \"$repo\" $cmd &&\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tfi\n }\n \n # Test a repository with a given reference storage by running and comparing\n@@ -30,44 +39,57 @@ run_with_uri() {\n # is the relative path to the repo to run the command in.\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n # (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n test_refs_backend() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n-\terr_msg=$4 &&\n+\tvia=$4 &&\n+\terr_msg=$5 &&\n+\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n \tif test -n \"$err_msg\";\n \tthen\n-\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n-\t\ttest_grep \"$err_msg\" err\n+\t\tif test \"$via\" = \"env\"\n+\t\tthen\n+\t\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" test_must_fail git -C \"$repo\" refs list 2>err\n+\t\telif test \"$via\" = \"config\"\n+\t\tthen\n+\t\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\t\ttest_grep \"$err_msg\" err\n+\t\tfi\n \telse\n \t\tgit -C \"$repo\" refs list >expect &&\n-\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" \"$via\">actual &&\n \t\ttest_cmp expect actual\n \tfi\n }\n \n-test_expect_success 'URI is invalid' '\n+methods=\"config\"\n+for method in $methods\n+do\n+\n+test_expect_success \"$method: URI is invalid\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'URI ends with colon' '\n+test_expect_success \"$method: URI ends with colon\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable:\" \\\n+\ttest_refs_backend repo files \"reftable:\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'unknown reference backend' '\n+test_expect_success \"$method: unknown reference backend\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"db://.git\" \\\n+\ttest_refs_backend repo files \"db://.git\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n@@ -86,7 +108,7 @@ do\n \tfor dir in \"$(pwd)/repo/.git\" \"./\"\n \tdo\n \n-\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: $read from $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -101,7 +123,7 @@ do\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: $write to $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -113,20 +135,22 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\" &&\n \n \t\t\t\tgit refs list >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"tag -d 1\" \"$method\" &&\n \t\t\t\tgit refs list >actual &&\n \t\t\t\ttest_cmp expect actual &&\n \n \t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"refs list\" \"$method\" >actual &&\n \t\t\t\ttest_cmp expect actual\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: with worktree and $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo wt\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -138,22 +162,26 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\tgit config set core.repositoryformatversion 1 &&\n-\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n \n-\t\t\t\tgit worktree add ../wt 2\n-\t\t\t) &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n+\t\t\t\t! test_cmp expect actual &&\n \n-\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n-\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n-\t\t\t! test_cmp expect actual &&\n-\n-\t\t\tgit -C wt rev-parse 2 >expect &&\n-\t\t\tgit -C wt rev-parse HEAD >actual &&\n-\t\t\ttest_cmp expect actual\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n \t\t'\n \tdone # closes dir\n done # closes to_format\n-done # closes from_format\n+done # closes to_format\n+\n+done # closes method\n \n test_done\n\n-- \n2.52.0\n\n"},{"id":"535558","messageId":"aYoMdqDDbt-BArQQ@pks.im","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-2-740899834ceb@gmail.com","subject":"Re: [PATCH v5 2/4] refs: forward and use the reference storage payload","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-09T16:34:09Z","receivedAt":"2026-02-09T16:34:20Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 09, 2026 at 04:58:19PM +0100, Karthik Nayak wrote:\n> An upcoming commit will add support for providing an URI via the\n> 'extensions.refStorage' config. The URI will contain the reference\n> backend and a corresponding payload. The payload can be then used for\n> providing an alternate locations for the reference backend.\n> \n> To prepare for this, modify the existing backends to accept such an\n> argument when initializing via the 'init()' function. Both the files\n> and reftable backends will parse the information to be filesystem paths\n> to store references.\n\nMaybe add: \"to store references. Given that no callers pass any payload\nyet this is essentially a no-op change for now.\"\n\n> diff --git a/refs.c b/refs.c\n> index 36f3441632..d9df25d7c0 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -3425,3 +3426,33 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n> \n> \tstrbuf_release(&path);\n> }\n> +\n> +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n> +\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n> +\t\t\t\t struct strbuf *ref_common_dir)\n> +{\n> +\tstruct strbuf sb = STRBUF_INIT;\n> +\n> +\tstrbuf_addstr(refdir, gitdir);\n> +\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n> +\n> +\tif (!payload)\n> +\t\treturn;\n\nI think you should add a comment here that explains why it's not\nnecessary to modify the `refdir` in case `*is_worktree`. I'd arguably\neven move that code into `if (!payload)`, as we otherwise only set it to\nreset it later. So:\n\n if (!payload) {\n /*\n * We can use `gitdir` as `refdir` without appending the\n * worktree path because...\n /\n strbuf_addstr(refdir, gitdir);\n }\n\n> +\tif (!is_absolute_path(payload)) {\n> +\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n> +\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n> +\t} else {\n> +\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n> +\t}\n> +\n> +\tstrbuf_reset(refdir);\n\nAnd then you can drop this call to `strbuf_reset()`.\n\n> diff --git a/refs/files-backend.c b/refs/files-backend.c\n> index 240d3c3b26..b192ce606d 100644\n> --- a/refs/files-backend.c\n> +++ b/refs/files-backend.c\n> @@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n> * set of caches.\n> */\n> static struct ref_store *files_ref_store_init(struct repository *repo,\n> +\t\t\t\t\t const char *payload,\n> \t\t\t\t\t const char *gitdir,\n> \t\t\t\t\t unsigned int flags)\n> {\n> \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n> \tstruct ref_store *ref_store = (struct ref_store *)refs;\n> -\tstruct strbuf sb = STRBUF_INIT;\n> +\tstruct strbuf ref_common_dir = STRBUF_INIT;\n> +\tstruct strbuf refdir = STRBUF_INIT;\n> +\tbool is_worktree;\n> +\n> +\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n> +\t\t\t\t\t &ref_common_dir);\n> \n> -\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n> +\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n> \trefs->store_flags = flags;\n> -\tget_common_dir_noenv(&sb, gitdir);\n> -\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n> +\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n> \trefs->packed_ref_store =\n> -\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n> +\t\tpacked_ref_store_init(repo, payload, refs->gitcommondir, flags);\n\nIt's a bit weird that we end up passing the payload even though we\nunconditionally ignore it in `packed_ref_store_init()`. I'd argue that\nwe should either pass a `NULL` pointer as payload, or let the packed\nbackend call `refs_compute_filesystem_location()` itsefl.\n\n> diff --git a/refs/packed-backend.c b/refs/packed-backend.c\n> index 4ea0c12299..028fbc0585 100644\n> --- a/refs/packed-backend.c\n> +++ b/refs/packed-backend.c\n> @@ -212,6 +212,7 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n> }\n> \n> struct ref_store *packed_ref_store_init(struct repository *repo,\n> +\t\t\t\t\tconst char *payload UNUSED,\n> \t\t\t\t\tconst char *gitdir,\n> \t\t\t\t\tunsigned int store_flags)\n> {\n\nAnd here we should probably explain why we don't have to respect the\npayload.\n\n> diff --git a/refs/refs-internal.h b/refs/refs-internal.h\n> index c7d2a6e50b..bd09b1280c 100644\n> --- a/refs/refs-internal.h\n> +++ b/refs/refs-internal.h\n> @@ -666,4 +667,18 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n> \t\t\t\t\t unsigned int initial_transaction,\n> \t\t\t\t\t struct strbuf *err);\n> \n> +/*\n> + * Given a gitdir and the reference storage payload provided, retrieve the\n> + * 'refdir' and 'ref_common_dir'. The former is where references should be\n> + * stored for the current worktree, the latter is the common reference\n> + * directory if working with a linked worktree. If working with the main\n> + * worktree, both values will be the same.\n> + *\n> + * This is used by backends such as {files, reftable} which store references in\n> + * dedicated filesystem paths.\n> + */\n\nI guess we can say \"This is used by backends that store store files in\nthe repository directly.\"\n\nPatrick\n"},{"id":"535559","messageId":"aYoMk5HmpSyN1azt@pks.im","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-3-740899834ceb@gmail.com","subject":"Re: [PATCH v5 3/4] refs: allow reference location in refstorage config","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-09T16:34:27Z","receivedAt":"2026-02-09T16:34:32Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 09, 2026 at 04:58:20PM +0100, Karthik Nayak wrote:\n> The 'extensions.refStorage' config is used to specify the reference\n> backend for a given repository. Both the 'files' and 'reftable' backends\n> utilize the $GIT_DIR as the reference folder by default in\n> `get_main_ref_store()`.\n> \n> Since the reference backends are pluggable, this means that they could\n> work with out-of-tree reference directories too. Extend the 'refStorage'\n> config to also support taking an URI input, where users can specify the\n> reference backend and the location.\n> \n> Add the required changes to obtain and propagate this value to the\n> individual backends also add the necessary documentation and tests.\n\nThis reads as if this should have been two sentences.\n\n> diff --git a/builtin/worktree.c b/builtin/worktree.c\n> index fbdaf2eb2e..94480be5c4 100644\n> --- a/builtin/worktree.c\n> +++ b/builtin/worktree.c\n> @@ -425,6 +425,39 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n> \treturn run_command(&cp);\n> }\n> \n> +/*\n> + * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n\ns/worktress/worktrees/\n\n> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n> new file mode 100755\n> index 0000000000..9c777b79f3\n> --- /dev/null\n> +++ b/t/t1423-ref-backend.sh\n> @@ -0,0 +1,159 @@\n> +#!/bin/sh\n> +\n> +test_description='Test reference backend URIs'\n> +\n> +. ./test-lib.sh\n> +\n> +# Run a git command with the provided reference storage. Reset the backend\n> +# post running the command.\n> +# Usage: run_with_uri \n> +# is the relative path to the repo to run the command in.\n> +# is the original ref storage of the repo.\n> +# is the new URI to be set for the ref storage.\n> +# is the git subcommand to be run in the repository.\n> +run_with_uri() {\n> +\trepo=$1 &&\n> +\tbackend=$2 &&\n> +\turi=$3 &&\n> +\tcmd=$4 &&\n> +\n> +\tgit -C \"$repo\" config set core.repositoryformatversion 1\n> +\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n> +\tgit -C \"$repo\" $cmd &&\n> +\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n> +}\n> +\n> +# Test a repository with a given reference storage by running and comparing\n> +# 'git refs list' before and after setting the new reference backend. If\n> +# err_msg is set, expect the command to fail and grep for the provided err_msg.\n> +# Usage: run_with_uri \n> +# is the relative path to the repo to run the command in.\n> +# is the original ref storage of the repo.\n> +# is the new URI to be set for the ref storage.\n> +# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n> +test_refs_backend() {\n> +\trepo=$1 &&\n> +\tbackend=$2 &&\n> +\turi=$3 &&\n> +\terr_msg=$4 &&\n> +\n> +\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n> +\tif test -n \"$err_msg\";\n> +\tthen\n> +\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n> +\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n> +\t\ttest_grep \"$err_msg\" err\n> +\telse\n> +\t\tgit -C \"$repo\" refs list >expect &&\n> +\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n> +\t\ttest_cmp expect actual\n> +\tfi\n> +}\n> +\n> +test_expect_success 'URI is invalid' '\n> +\ttest_when_finished \"rm -rf repo\" &&\n> +\tgit init repo &&\n> +\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n> +\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n> +'\n> +\n> +test_expect_success 'URI ends with colon' '\n> +\ttest_when_finished \"rm -rf repo\" &&\n> +\tgit init repo &&\n> +\ttest_refs_backend repo files \"reftable:\" \\\n> +\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n> +'\n> +\n> +test_expect_success 'unknown reference backend' '\n> +\ttest_when_finished \"rm -rf repo\" &&\n> +\tgit init repo &&\n> +\ttest_refs_backend repo files \"db://.git\" \\\n> +\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n> +'\n> +\n> +ref_formats=\"files reftable\"\n> +for from_format in $ref_formats\n> +do\n> +\n> +for to_format in $ref_formats\n> +do\n> +\tif test \"$from_format\" = \"$to_format\"\n> +\tthen\n> +\t\tcontinue\n> +\tfi\n> +\n> +\n> +\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n\nAs \"./\" is a relative directory I expect it to be resolved relative to\n\"$GIT_DIR\", right? Also, I don't see any tests that create the ref\ndirectory outside of the repository. Should we maybe add one?\n\n> +\tdo\n> +\n> +\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n> +\t\t\ttest_when_finished \"rm -rf repo\" &&\n> +\t\t\tgit init --ref-format=$from_format repo &&\n> +\t\t\t(\n> +\t\t\t\tcd repo &&\n> +\t\t\t\ttest_commit 1 &&\n> +\t\t\t\ttest_commit 2 &&\n> +\t\t\t\ttest_commit 3 &&\n> +\n> +\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n\nOkay, we do the migration, but with \"--dry-run\". This should result in a\ntemporary staging directory, which is in fact somewhat interesting given\nthat \"to_format\" can now contain a payload. I assume it wouldn't have an\nimpact if such a payload was set here?\n\n> +\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n\nHm. I have no idea what this is doing :)\n\n> +\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n> +\t\t\t)\n> +\t\t'\n\nIn general I think it would be sensible to also have a couple tests here\nthat exercise specific formats directly. Like:\n\n - Are the files created in the right spots for the files and reftable\n backend with a specific backend?\n\n - Does `git refs migrate` know to write the files into the correct\n location in case \"--dry-run\" wasn't passed?\n\n - Does git-init(1) and git-clone(1) initialize the refstore in a\n different location as expected?\n\n - Does creating a worktree work?\n\nPatrick\n"},{"id":"535560","messageId":"aYoMmhClPzdmLjII@pks.im","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","subject":"Re: [PATCH v5 0/4] refs: allow setting the reference directory","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-09T16:34:34Z","receivedAt":"2026-02-09T16:34:40Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 09, 2026 at 04:58:17PM +0100, Karthik Nayak wrote:\n> Changes in v5:\n> - Moved around the commits, to ensure that the code to handle the config\n> in the backend is first. Previously, we added the config first, which\n> meant the commit allowed users to provide a URI but it was simply\n> ignore.\n> - Fix typos and grammar and rename variables.\n> - Clean up the description and documentation to actually specify\n> protocol over location.\n> - Avoid an extra memory allocation by detaching the strbuf value.\n> - Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n\nI've got some more smallish nits, but this version looks mostly good to\nme. The one thing that I think still needs to be extended quite a bit is\nthe tests we have. The new feature has quite a broad impact, and we\nshould at least verify that classes of commands work as expected:\n\n - Commands that create a repository should create the ref backend as\n expected.\n\n - Commands that access refs (read/write) should know to use the\n correct location.\n\n - Commands that create worktrees should know where to initialize the\n refs.\n\n - Reference migration should correctly migrate to/from an out-of-tree\n directory.\n\nThanks!\n\nPatrick\n"},{"id":"535583","messageId":"xmqqtsvp4wxv.fsf@gitster.g","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com","subject":"Re: [PATCH v5 0/4] refs: allow setting the reference directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-09T18:02:36Z","receivedAt":"2026-02-09T18:02:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak writes:\n\n> Changes in v5:\n> - Moved around the commits, to ensure that the code to handle the config\n> in the backend is first. Previously, we added the config first, which\n> meant the commit allowed users to provide a URI but it was simply\n> ignore.\n> - Fix typos and grammar and rename variables.\n> - Clean up the description and documentation to actually specify\n> protocol over location.\n\nThis one looked good.\n\n> - Avoid an extra memory allocation by detaching the strbuf value.\n\nSo did this (thanks Stolee for spotting the opportunity).\n\n> - Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n\nReplaced. Hopefully this is now ready for 'next'?\n\nThanks.\n"},{"id":"535664","messageId":"CAOLa=ZTQzckcqOcEgw+4pH+iXFTM3c7QX_tOnVSEujH1VWk4mw@mail.gmail.com","threadId":"64513","inReplyTo":"aYoMdqDDbt-BArQQ@pks.im","subject":"Re: [PATCH v5 2/4] refs: forward and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-10T10:09:16Z","receivedAt":"2026-02-10T10:09:18Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 09, 2026 at 04:58:19PM +0100, Karthik Nayak wrote:\n>> An upcoming commit will add support for providing an URI via the\n>> 'extensions.refStorage' config. The URI will contain the reference\n>> backend and a corresponding payload. The payload can be then used for\n>> providing an alternate locations for the reference backend.\n>>\n>> To prepare for this, modify the existing backends to accept such an\n>> argument when initializing via the 'init()' function. Both the files\n>> and reftable backends will parse the information to be filesystem paths\n>> to store references.\n>\n> Maybe add: \"to store references. Given that no callers pass any payload\n> yet this is essentially a no-op change for now.\"\n>\n\nWill add.\n\n>> diff --git a/refs.c b/refs.c\n>> index 36f3441632..d9df25d7c0 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -3425,3 +3426,33 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n>>\n>> \tstrbuf_release(&path);\n>> }\n>> +\n>> +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n>> +\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n>> +\t\t\t\t struct strbuf *ref_common_dir)\n>> +{\n>> +\tstruct strbuf sb = STRBUF_INIT;\n>> +\n>> +\tstrbuf_addstr(refdir, gitdir);\n>> +\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n>> +\n>> +\tif (!payload)\n>> +\t\treturn;\n>\n> I think you should add a comment here that explains why it's not\n> necessary to modify the `refdir` in case `*is_worktree`. I'd arguably\n> even move that code into `if (!payload)`, as we otherwise only set it to\n> reset it later. So:\n>\n> if (!payload) {\n> /*\n> * We can use `gitdir` as `refdir` without appending the\n> * worktree path because...\n> /\n> strbuf_addstr(refdir, gitdir);\n> }\n>\n>> +\tif (!is_absolute_path(payload)) {\n>> +\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n>> +\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n>> +\t} else {\n>> +\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n>> +\t}\n>> +\n>> +\tstrbuf_reset(refdir);\n>\n> And then you can drop this call to `strbuf_reset()`.\n>\n\nFair enough, will do this.\n\n>> diff --git a/refs/files-backend.c b/refs/files-backend.c\n>> index 240d3c3b26..b192ce606d 100644\n>> --- a/refs/files-backend.c\n>> +++ b/refs/files-backend.c\n>> @@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n>> * set of caches.\n>> */\n>> static struct ref_store *files_ref_store_init(struct repository *repo,\n>> +\t\t\t\t\t const char *payload,\n>> \t\t\t\t\t const char *gitdir,\n>> \t\t\t\t\t unsigned int flags)\n>> {\n>> \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n>> \tstruct ref_store *ref_store = (struct ref_store *)refs;\n>> -\tstruct strbuf sb = STRBUF_INIT;\n>> +\tstruct strbuf ref_common_dir = STRBUF_INIT;\n>> +\tstruct strbuf refdir = STRBUF_INIT;\n>> +\tbool is_worktree;\n>> +\n>> +\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n>> +\t\t\t\t\t &ref_common_dir);\n>>\n>> -\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n>> +\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n>> \trefs->store_flags = flags;\n>> -\tget_common_dir_noenv(&sb, gitdir);\n>> -\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n>> +\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n>> \trefs->packed_ref_store =\n>> -\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n>> +\t\tpacked_ref_store_init(repo, payload, refs->gitcommondir, flags);\n>\n> It's a bit weird that we end up passing the payload even though we\n> unconditionally ignore it in `packed_ref_store_init()`. I'd argue that\n> we should either pass a `NULL` pointer as payload, or let the packed\n> backend call `refs_compute_filesystem_location()` itsefl.\n>\n\nI'm considering passing in a NULL and relying on the 'gitdir'. Mostly\nbecause the packed-refs backend always comes linked to the files-backend\nand as such should simply rely on the 'gitdir' provided by it. Let me\nknow if you think we should go the other way.\n\n>> diff --git a/refs/packed-backend.c b/refs/packed-backend.c\n>> index 4ea0c12299..028fbc0585 100644\n>> --- a/refs/packed-backend.c\n>> +++ b/refs/packed-backend.c\n>> @@ -212,6 +212,7 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n>> }\n>>\n>> struct ref_store *packed_ref_store_init(struct repository *repo,\n>> +\t\t\t\t\tconst char *payload UNUSED,\n>> \t\t\t\t\tconst char *gitdir,\n>> \t\t\t\t\tunsigned int store_flags)\n>> {\n>\n> And here we should probably explain why we don't have to respect the\n> payload.\n>\n\nYeah, will add in a comment.\n\n>> diff --git a/refs/refs-internal.h b/refs/refs-internal.h\n>> index c7d2a6e50b..bd09b1280c 100644\n>> --- a/refs/refs-internal.h\n>> +++ b/refs/refs-internal.h\n>> @@ -666,4 +667,18 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n>> \t\t\t\t\t unsigned int initial_transaction,\n>> \t\t\t\t\t struct strbuf *err);\n>>\n>> +/*\n>> + * Given a gitdir and the reference storage payload provided, retrieve the\n>> + * 'refdir' and 'ref_common_dir'. The former is where references should be\n>> + * stored for the current worktree, the latter is the common reference\n>> + * directory if working with a linked worktree. If working with the main\n>> + * worktree, both values will be the same.\n>> + *\n>> + * This is used by backends such as {files, reftable} which store references in\n>> + * dedicated filesystem paths.\n>> + */\n>\n> I guess we can say \"This is used by backends that store store files in\n> the repository directly.\"\n>\n> Patrick\n\nMakes sense. Thanks.\n"},{"id":"535669","messageId":"CAOLa=ZRU5Bv6oAUmRkBY-sar2UskPfmJNehUjyMtKJOS4s9S9g@mail.gmail.com","threadId":"64513","inReplyTo":"aYoMk5HmpSyN1azt@pks.im","subject":"Re: [PATCH v5 3/4] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-10T13:02:10Z","receivedAt":"2026-02-10T13:02:13Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 09, 2026 at 04:58:20PM +0100, Karthik Nayak wrote:\n>> The 'extensions.refStorage' config is used to specify the reference\n>> backend for a given repository. Both the 'files' and 'reftable' backends\n>> utilize the $GIT_DIR as the reference folder by default in\n>> `get_main_ref_store()`.\n>>\n>> Since the reference backends are pluggable, this means that they could\n>> work with out-of-tree reference directories too. Extend the 'refStorage'\n>> config to also support taking an URI input, where users can specify the\n>> reference backend and the location.\n>>\n>> Add the required changes to obtain and propagate this value to the\n>> individual backends also add the necessary documentation and tests.\n>\n> This reads as if this should have been two sentences.\n\nYeah, let me split it up.\n\n>\n>> diff --git a/builtin/worktree.c b/builtin/worktree.c\n>> index fbdaf2eb2e..94480be5c4 100644\n>> --- a/builtin/worktree.c\n>> +++ b/builtin/worktree.c\n>> @@ -425,6 +425,39 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n>> \treturn run_command(&cp);\n>> }\n>>\n>> +/*\n>> + * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n>\n> s/worktress/worktrees/\n>\n\nOops.\n\n\n>> +for to_format in $ref_formats\n>> +do\n>> +\tif test \"$from_format\" = \"$to_format\"\n>> +\tthen\n>> +\t\tcontinue\n>> +\tfi\n>> +\n>> +\n>> +\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n>\n> As \"./\" is a relative directory I expect it to be resolved relative to\n> \"$GIT_DIR\", right?\n\nYup the './' is relative to the '$GIT_DIR'. It can be changed to '.', so\nI'll do that and add a comment. So we do both\n\n BACKEND_PATH='/home/karthik/code/git/build/test-output/trash\ndirectory.t1423-ref-backend/repo/.git/ref_migration.ZnKNpg'\n\nand\n\n BACKEND_PATH=./ref_migration.BFyK5k\n\n> Also, I don't see any tests that create the ref\n> directory outside of the repository. Should we maybe add one?\n\nYeah, let me add that test.\n\n>> +\tdo\n>> +\n>> +\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n>> +\t\t\ttest_when_finished \"rm -rf repo\" &&\n>> +\t\t\tgit init --ref-format=$from_format repo &&\n>> +\t\t\t(\n>> +\t\t\t\tcd repo &&\n>> +\t\t\t\ttest_commit 1 &&\n>> +\t\t\t\ttest_commit 2 &&\n>> +\t\t\t\ttest_commit 3 &&\n>> +\n>> +\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n>\n> Okay, we do the migration, but with \"--dry-run\". This should result in a\n> temporary staging directory, which is in fact somewhat interesting given\n> that \"to_format\" can now contain a payload. I assume it wouldn't have an\n> impact if such a payload was set here?\n>\n\nIt cannot, the 'git refs migrate' command parses the argument provided\nto '--ref-format' as a reference-backend.\n\n>> +\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n>\n> Hm. I have no idea what this is doing :)\n>\n\nIt extracts out the name of the dry-run folder created by 'git refs\nmigrate'. We append the $dir to it, which could be the absolute path or\nthe relative path.\n\n>> +\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n>> +\t\t\t)\n>> +\t\t'\n>\n> In general I think it would be sensible to also have a couple tests here\n> that exercise specific formats directly. Like:\n>\n> - Are the files created in the right spots for the files and reftable\n> backend with a specific backend?\n>\n> - Does `git refs migrate` know to write the files into the correct\n> location in case \"--dry-run\" wasn't passed?\n>\n\nWill add tests for the following too.\n\n> - Does git-init(1) and git-clone(1) initialize the refstore in a\n> different location as expected?\n>\n\nWell so this only works when there is a reference store already\nexisting. I thought I had explicitly called this out, but doesn't seem\nto be the case. I think it would actually make sense that it also works\nwith creation. So let me look into that.\n\n> - Does creating a worktree work?\n>\n\nThis is currently already tested.\n\n> Patrick\n"},{"id":"535670","messageId":"CAOLa=ZRPLB-jLJ=4cdtO0DuDD=+tPp7t-Kei5pMsF0en6i2jJg@mail.gmail.com","threadId":"64513","inReplyTo":"xmqqtsvp4wxv.fsf@gitster.g","subject":"Re: [PATCH v5 0/4] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-10T13:02:49Z","receivedAt":"2026-02-10T13:02:51Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano writes:\n\n> Karthik Nayak writes:\n>\n>> Changes in v5:\n>> - Moved around the commits, to ensure that the code to handle the config\n>> in the backend is first. Previously, we added the config first, which\n>> meant the commit allowed users to provide a URI but it was simply\n>> ignore.\n>> - Fix typos and grammar and rename variables.\n>> - Clean up the description and documentation to actually specify\n>> protocol over location.\n>\n> This one looked good.\n>\n>> - Avoid an extra memory allocation by detaching the strbuf value.\n>\n> So did this (thanks Stolee for spotting the opportunity).\n>\n>> - Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n>\n> Replaced. Hopefully this is now ready for 'next'?\n>\n> Thanks.\n\nHello Junio, I don't think so, I think we still need to address few\nthings as per the latest review. So let's hold off on it.\n\nKarthik\n"},{"id":"535683","messageId":"xmqqbjhw1uik.fsf@gitster.g","threadId":"64513","inReplyTo":"CAOLa=ZRPLB-jLJ=4cdtO0DuDD=+tPp7t-Kei5pMsF0en6i2jJg@mail.gmail.com","subject":"Re: [PATCH v5 0/4] refs: allow setting the reference directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-10T15:35:31Z","receivedAt":"2026-02-10T15:35:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak writes:\n\n> Junio C Hamano writes:\n>\n...\n>> Replaced. Hopefully this is now ready for 'next'?\n>>\n>> Thanks.\n>\n> Hello Junio, I don't think so, I think we still need to address few\n> things as per the latest review. So let's hold off on it.\n\nThnaks, will do.\n"},{"id":"535721","messageId":"20260210224401.GA1836788@coredump.intra.peff.net","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-3-740899834ceb@gmail.com","subject":"Re: [PATCH v5 3/4] refs: allow reference location in refstorage config","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-02-10T22:44:01Z","receivedAt":"2026-02-10T22:44:05Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Feb 09, 2026 at 04:58:20PM +0100, Karthik Nayak wrote:\n\n> +static void parse_reference_uri(const char *value, char **format,\n> +\t\t\t\tchar **payload)\n> +{\n> +\tchar *schema_end;\n> +\n> +\tschema_end = strstr(value, \"://\");\n> +\tif (!schema_end) {\n> +\t\t*format = xstrdup(value);\n> +\t\t*payload = NULL;\n> +\t} else {\n> +\t\t*format = xstrndup(value, schema_end - value);\n> +\t\t*payload = xstrdup_or_null(schema_end + 3);\n> +\t}\n> +}\n\nThe schema_end variable should be \"const\" here. Otherwise new versions\nof gcc/glibc will complain that the strstr() implicitly removes the\nconst from value (and compilation with DEVELOPER=1 fails). More details\nin this thread:\n\n https://lore.kernel.org/git/e6f7e2eddbc9aef1c21f661420a4b8cb9cd8e2c1.1770095829.git.collin.funk1@gmail.com/\n\n-Peff\n"},{"id":"535722","messageId":"20260210224654.GA1837132@coredump.intra.peff.net","threadId":"64513","inReplyTo":"20260209-kn-alternate-ref-dir-v5-2-740899834ceb@gmail.com","subject":"Re: [PATCH v5 2/4] refs: forward and use the reference storage payload","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-02-10T22:46:54Z","receivedAt":"2026-02-10T22:46:56Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Feb 09, 2026 at 04:58:19PM +0100, Karthik Nayak wrote:\n\n> +\tif (*is_worktree) {\n> +\t\tchar *wt_id = strrchr(gitdir, '/') + 1;\n> +\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id);\n> +\t}\n\nThis is another instance where the new version of glibc will complain\nabout const-ness. The wt_id variable can just be marked as const.\n\n(This and the other one I pointed out are the only two cases in your\nseries).\n\nBTW, is it possible to have a gitdir string without a slash in it? I\nguess not if it is absolute, but I didn't look at the caller to see if\nthat is always true. Anyway, I wonder if we should be checking the\nresult of strrchr() here.\n\n-Peff\n"},{"id":"535744","messageId":"CAOLa=ZS00qJuRvDA0Ud34MiUAPuSMTe7M76fSWXmHmbPtc2wsw@mail.gmail.com","threadId":"64513","inReplyTo":"20260210224401.GA1836788@coredump.intra.peff.net","subject":"Re: [PATCH v5 3/4] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-11T10:27:00Z","receivedAt":"2026-02-11T10:27:02Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Jeff King writes:\n\n> On Mon, Feb 09, 2026 at 04:58:20PM +0100, Karthik Nayak wrote:\n>\n>> +static void parse_reference_uri(const char *value, char **format,\n>> +\t\t\t\tchar **payload)\n>> +{\n>> +\tchar *schema_end;\n>> +\n>> +\tschema_end = strstr(value, \"://\");\n>> +\tif (!schema_end) {\n>> +\t\t*format = xstrdup(value);\n>> +\t\t*payload = NULL;\n>> +\t} else {\n>> +\t\t*format = xstrndup(value, schema_end - value);\n>> +\t\t*payload = xstrdup_or_null(schema_end + 3);\n>> +\t}\n>> +}\n>\n> The schema_end variable should be \"const\" here. Otherwise new versions\n> of gcc/glibc will complain that the strstr() implicitly removes the\n> const from value (and compilation with DEVELOPER=1 fails). More details\n> in this thread:\n>\n> https://lore.kernel.org/git/e6f7e2eddbc9aef1c21f661420a4b8cb9cd8e2c1.1770095829.git.collin.funk1@gmail.com/\n>\n> -Peff\n\nThanks for the hint, my Linux distribution is still on glibc 2.42 and\ndidn't see the error. Will fix it in my next version.\n"},{"id":"535936","messageId":"CAOLa=ZQdYVO8wJxs_e-6FR7x_zOJnTNTwAVm1sHv23pnDYKnug@mail.gmail.com","threadId":"64513","inReplyTo":"20260210224654.GA1837132@coredump.intra.peff.net","subject":"Re: [PATCH v5 2/4] refs: forward and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-13T14:45:20Z","receivedAt":"2026-02-13T14:45:22Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Jeff King writes:\n\n> On Mon, Feb 09, 2026 at 04:58:19PM +0100, Karthik Nayak wrote:\n>\n>> +\tif (*is_worktree) {\n>> +\t\tchar *wt_id = strrchr(gitdir, '/') + 1;\n>> +\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id);\n>> +\t}\n>\n> This is another instance where the new version of glibc will complain\n> about const-ness. The wt_id variable can just be marked as const.\n>\n\nThanks, will amend.\n\n> (This and the other one I pointed out are the only two cases in your\n> series).\n>\n> BTW, is it possible to have a gitdir string without a slash in it? I\n> guess not if it is absolute, but I didn't look at the caller to see if\n> that is always true. Anyway, I wonder if we should be checking the\n> result of strrchr() here.\n>\n> -Peff\n\nSince this is called during the ref store initialization and that value\nis generally set via:\n\n1. `repo->gitdir`: Which is resolved to an absolute path\n2. `repo->commondir`: Which is user input, can be without slash\n3. `worktree dir`: Should contain a slash\n4. `submodule dir`: Should contain a slash\n5. `refs migration dir`: Should contain a slash\n\nBut even with this, Gits understanding of linked worktrees are that they\nare in a `$gitdir/worktrees/$wt_id`. So it should be safe to do this.\nNevertheless, I'll add in a check.\n"},{"id":"536032","messageId":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH v6 0/6] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:13Z","receivedAt":"2026-02-14T22:34:30Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"While Git allows users to select different reference backends, unlike\nwith objects, there is no flexibility in selecting the reference\ndirectory. Currently, the reference format is obtained from the config\nof the repository and the reference directory is set to the $GIT_DIR.\n\nThis patch extends the config 'extensions.refStorage' to take in\nmultiple forms of inputs:\n\n - A format name alone (e.g., `reftable` or `files`).\n\n - A URI format `://` explicitly specifies both the\n format and payload (e.g., `reftable:///foo/bar`).\n\nWe also add in a new ENV variable GIT_REFERENCE_BACKEND which can be\nused to override the config.\n\nOne use case for this is migration between different backends. On the\nserver side, migrating from the files backend to the newly introduced\nreftable backend can be achieved by running 'git refs migrate'. However,\nfor large repositories with millions of references, this migration can\ntake from seconds to minutes.\n\nFor some background, at GitLab, the criteria for our migration was to\nreduce the downtime of the migrate ideally to zero. So running 'git refs\nmigrate --ref-format=reftable' by itself wouldn't work, since it scales\nwith the number of references and we have repos with millions of\nreferences, so we need to migrate without loosing any information. We\ncame up with the following plan:\n\n 1. Run git-pack-refs(1) and note timestamp of the generated packed-refs\n file.\n 2. Run git refs migrate –dry-run.\n 3. If there are no ongoing reference requests (read/write)\n a. Lock the repository by blocking incoming requests (done on a\n layer above git, in Gitaly [1]).\n b. If the timestamp of the packed-refs file has changed, unlock\n the repo and repeat from step 1.\n c. Apply all the loose refs to the dry-run reftable folder (this\n requires support in Git to write refs to arbitrary folder).\n d. Move the reftable dry-run folder into the GIT_DIR.\n e. Swap the repo config\n f. Unlock repo access\n\nUsing such a route, scales much better since we only have to worry about\nblocking the repository by O(ref written between #1 and #3a) and not\nO(refs in repo). But for doing so, we need to be able to write to a\narbitrary reference backend + path. This is to add the missing\nreferences to the dry-run reftable folder. This series, achieves that.\n\nSince there was a long gap between v3 <> v4, the version 4 onward is\nbased on top of 2258446484 (RelNotes: correct \"fast-import\" option name,\n2026-01-30).\n\n[1]: https://gitlab.com/gitlab-org/gitaly\n\n---\nChanges in v6:\n- The biggest change in this version is that we now support using the\n environment variable with 'git-clone(1)' and 'git-init(1)'. In such\n situations, the alternate reference directory is created and the\n config is added to the repository.\n- Add a new commit which moves stub creation/removal to the generic\n layer.\n- Cleanup logic flow in `refs_compute_filesystem_location()`.\n- Add more tests for usage with 'git-clone(1)', 'git-init(1)' and\n migration of repositories using alternate refs backend.\n- Fixup documentation, commit messages and typos.\n- Link to v5: https://patch.msgid.link/20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com\n\nChanges in v5:\n- Moved around the commits, to ensure that the code to handle the config\n in the backend is first. Previously, we added the config first, which\n meant the commit allowed users to provide a URI but it was simply\n ignore.\n- Fix typos and grammar and rename variables.\n- Clean up the description and documentation to actually specify\n protocol over location.\n- Avoid an extra memory allocation by detaching the strbuf value.\n- Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n\nChanges in v4:\n- Mostly re-wrote the code to also support worktree. Now, the existing\n backends will store worktree references in 'ref_dir/worktrees/wt_id'\n and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n- We also support relative paths in the reference directories. These\n relative paths are resolved relative to the GIT_DIR.\n- Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n\nChanges in v3:\n- Cleanup some stale code which wasn't removed.\n- Localize strings which will be output to the user.\n- Remove additional defensive checks which are not needed.\n- Link to v2: https://patch.msgid.link/20251126-kn-alternate-ref-dir-v2-0-8b9f6f18f635@gmail.com\n\nChanges in v2:\n- Added more clarification and proper intent in the cover message.\n- Changed the format from '://' to\n `://` as it much clearer.\n- Added logic to check for the '//' in the provided URI and a test for\n the same.\n- In the tests:\n - Use test_must_fail() instead of ! git\n - Fix looped tests not using the variables correctly and ensure that\n the test description is correct.\n- Link to v1: https://patch.msgid.link/20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com\n\n---\n Documentation/config/extensions.adoc | 16 ++-\n Documentation/git.adoc | 5 +\n builtin/clone.c | 9 +-\n builtin/worktree.c | 34 +++++\n environment.h | 1 +\n refs.c | 127 +++++++++++++++++-\n refs.h | 13 ++\n refs/files-backend.c | 23 +++-\n refs/packed-backend.c | 5 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 14 ++\n refs/reftable-backend.c | 61 ++-------\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 96 ++++++++++++--\n setup.h | 4 +-\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 250 +++++++++++++++++++++++++++++++++++\n 18 files changed, 596 insertions(+), 81 deletions(-)\n\nKarthik Nayak (6):\n setup: don't modify repo in `create_reference_database()`\n refs: extract out `refs_create_refdir_stubs()`\n refs: receive and use the reference storage payload\n refs: move out stub modification to generic layer\n refs: allow reference location in refstorage config\n refs: add GIT_REFERENCE_BACKEND to specify reference backend\n\nRange-diff versus v5:\n\n-: ---------- > 1: f8dd9a2fd6 setup: don't modify repo in `create_reference_database()`\n1: d1f777120e ! 2: 07abde22c1 refs: extract out `refs_create_refdir_stubs()`\n @@ builtin/clone.c: int cmd_clone(int argc,\n \t * additional config can be injected with -c, make sure it's included\n \n ## refs.c ##\n -@@ refs.c: const char *ref_transaction_error_msg(enum ref_transaction_error err)\n - \t\treturn \"unknown failure\";\n - \t}\n +@@ refs.c: const char *refs_resolve_ref_unsafe(struct ref_store *refs,\n + \treturn NULL;\n }\n -+\n + \n +void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n +\t\t\t const char *refs_heads_content)\n +{\n @@ refs.c: const char *ref_transaction_error_msg(enum ref_transaction_error err)\n +\n +\tstrbuf_release(&path);\n +}\n ++\n + /* backend functions */\n + int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n + {\n \n ## refs.h ##\n @@ refs.h: void ref_iterator_free(struct ref_iterator *ref_iterator);\n2: 804720d11a ! 3: aab87c8e39 refs: forward and use the reference storage payload\n @@ Metadata\n Author: Karthik Nayak \n \n ## Commit message ##\n - refs: forward and use the reference storage payload\n + refs: receive and use the reference storage payload\n \n An upcoming commit will add support for providing an URI via the\n 'extensions.refStorage' config. The URI will contain the reference\n @@ Commit message\n To prepare for this, modify the existing backends to accept such an\n argument when initializing via the 'init()' function. Both the files\n and reftable backends will parse the information to be filesystem paths\n - to store references.\n + to store references. Given that no callers pass any payload yet this is\n + essentially a no-op change for now.\n \n To enable this, provide a 'refs_compute_filesystem_location()' function\n which will parse the current 'gitdir' and the 'payload' to provide the\n @@ refs.c: static struct ref_store *ref_store_init(struct repository *repo,\n \treturn refs;\n }\n \n -@@ refs.c: void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n - \n - \tstrbuf_release(&path);\n +@@ refs.c: const char *ref_transaction_error_msg(enum ref_transaction_error err)\n + \t\treturn \"unknown failure\";\n + \t}\n }\n +\n +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n @@ refs.c: void refs_create_refdir_stubs(struct repository *repo, const char *refdi\n +{\n +\tstruct strbuf sb = STRBUF_INIT;\n +\n -+\tstrbuf_addstr(refdir, gitdir);\n +\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n +\n -+\tif (!payload)\n ++\tif (!payload) {\n ++\t\t/*\n ++\t\t * We can use the 'gitdir' as the 'refdir' without appending the\n ++\t\t * worktree path, as the 'gitdir' here is already the worktree\n ++\t\t * path and is different from 'commondir' denoted by 'ref_common_dir'.\n ++\t\t */\n ++\t\tstrbuf_addstr(refdir, gitdir);\n +\t\treturn;\n ++\t}\n +\n +\tif (!is_absolute_path(payload)) {\n +\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n @@ refs.c: void refs_create_refdir_stubs(struct repository *repo, const char *refdi\n +\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n +\t}\n +\n -+\tstrbuf_reset(refdir);\n +\tstrbuf_addbuf(refdir, ref_common_dir);\n +\n +\tif (*is_worktree) {\n -+\t\tchar *wt_id = strrchr(gitdir, '/') + 1;\n -+\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id);\n ++\t\tconst char *wt_id = strrchr(gitdir, '/');\n ++\t\tif (!wt_id)\n ++\t\t\tBUG(\"worktree path does not contain slash \");\n ++\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id + 1);\n +\t}\n +\n +\tstrbuf_release(&sb);\n @@ refs/files-backend.c: static void clear_loose_ref_cache(struct files_ref_store *\n +\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n \trefs->packed_ref_store =\n -\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n -+\t\tpacked_ref_store_init(repo, payload, refs->gitcommondir, flags);\n ++\t\tpacked_ref_store_init(repo, NULL, refs->gitcommondir, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n @@ refs/files-backend.c: static struct ref_store *files_ref_store_init(struct repos\n \n ## refs/packed-backend.c ##\n @@ refs/packed-backend.c: static size_t snapshot_hexsz(const struct snapshot *snapshot)\n + \treturn snapshot->refs->base.repo->hash_algo->hexsz;\n }\n \n ++/*\n ++ * Since packed-refs is only stored in the common dir, don't parse the\n ++ * payload and rely on the files-backend to set 'gitdir' correctly.\n ++ */\n struct ref_store *packed_ref_store_init(struct repository *repo,\n +\t\t\t\t\tconst char *payload UNUSED,\n \t\t\t\t\tconst char *gitdir,\n @@ refs/refs-internal.h: enum ref_transaction_error refs_verify_refnames_available(\n + * directory if working with a linked worktree. If working with the main\n + * worktree, both values will be the same.\n + *\n -+ * This is used by backends such as {files, reftable} which store references in\n -+ * dedicated filesystem paths.\n ++ * This is used by backends that store store files in the repository directly.\n + */\n +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n +\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n-: ---------- > 4: 9ed74524d3 refs: move out stub modification to generic layer\n3: 3a5058f39c ! 5: 331ac15000 refs: allow reference location in refstorage config\n @@ Commit message\n reference backend and the location.\n \n Add the required changes to obtain and propagate this value to the\n - individual backends also add the necessary documentation and tests.\n + individual backends. Add the necessary documentation and tests.\n \n Traditionally, for linked worktrees, references were stored in the\n '$GIT_DIR/worktrees/' path. But when using an alternate reference\n @@ Documentation/config/extensions.adoc: For historical reasons, this extension is\n +\n Note that this setting should only be set by linkgit:git-init[1] or\n \n - ## builtin/clone.c ##\n -@@ builtin/clone.c: int cmd_clone(int argc,\n - \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n - \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n - \trepo_set_hash_algo(the_repository, hash_algo);\n --\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n -+\tcreate_reference_database(the_repository->ref_storage_format,\n -+\t\t\t\t the_repository->ref_storage_payload, NULL, 1);\n - \n - \t/*\n - \t * Before fetching from the remote, download and install bundle\n -\n ## builtin/worktree.c ##\n @@ builtin/worktree.c: static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n \treturn run_command(&cp);\n }\n \n +/*\n -+ * References for worktress are generally stored in '$GIT_DIR/worktrees/'.\n ++ * References for worktrees are generally stored in '$GIT_DIR/worktrees/'.\n + * But when using alternate reference directories, we want to store the worktree\n + * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n + *\n @@ builtin/worktree.c: static int make_worktree_orphan(const char * ref, const stru\n +\tstrbuf_reset(&sb);\n +\n +\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n -+\t\t path, wt->id);\n ++\t\t path, wt->id);\n +\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n +\n +\tstrbuf_release(&sb);\n @@ setup.c: static enum extension_result handle_extension_v0(const char *var,\n +static void parse_reference_uri(const char *value, char **format,\n +\t\t\t\tchar **payload)\n +{\n -+\tchar *schema_end;\n ++\tconst char *schema_end;\n +\n +\tschema_end = strstr(value, \"://\");\n +\tif (!schema_end) {\n @@ setup.c: void check_repository_format(struct repository_format *fmt)\n \tthe_repository->repository_format_worktree_config =\n \t\tfmt->worktree_config;\n \tthe_repository->repository_format_relative_worktrees =\n -@@ setup.c: static int is_reinit(void)\n - }\n - \n - void create_reference_database(enum ref_storage_format ref_storage_format,\n -+\t\t\t const char *ref_storage_payload,\n - \t\t\t const char *initial_branch, int quiet)\n - {\n - \tstruct strbuf err = STRBUF_INIT;\n - \tchar *to_free = NULL;\n - \tint reinit = is_reinit();\n - \n --\trepo_set_ref_storage_format(the_repository, ref_storage_format);\n -+\trepo_set_ref_storage_format(the_repository, ref_storage_format,\n -+\t\t\t\t ref_storage_payload);\n - \tif (ref_store_create_on_disk(get_main_ref_store(the_repository), 0, &err))\n - \t\tdie(\"failed to set up refs db: %s\", err.buf);\n - \n @@ setup.c: static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n @@ setup.c: static void repository_format_configure(struct repository_format *repo_\n }\n \n int init_db(const char *git_dir, const char *real_git_dir,\n -@@ setup.c: int init_db(const char *git_dir, const char *real_git_dir,\n - \n - \tif (!(flags & INIT_DB_SKIP_REFDB))\n - \t\tcreate_reference_database(repo_fmt.ref_storage_format,\n -+\t\t\t\t\t repo_fmt.ref_storage_payload,\n - \t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n - \tcreate_object_directory();\n - \n \n ## setup.h ##\n @@ setup.h: struct repository_format {\n @@ setup.h: struct repository_format {\n \tint sparse_index;\n \tchar *work_tree;\n \tstruct string_list unknown_extensions;\n -@@ setup.h: void initialize_repository_version(int hash_algo,\n - \t\t\t\t enum ref_storage_format ref_storage_format,\n - \t\t\t\t int reinit);\n - void create_reference_database(enum ref_storage_format ref_storage_format,\n -+\t\t\t const char *ref_storage_payload,\n - \t\t\t const char *initial_branch, int quiet);\n - \n - /*\n \n ## t/meson.build ##\n @@ t/meson.build: integration_tests = [\n @@ t/t1423-ref-backend.sh (new)\n +\tfi\n +\n +\n -+\tfor dir in \"$(pwd)/repo/.git\" \"./\"\n ++\tfor dir in \"$(pwd)/repo/.git\" \".\"\n +\tdo\n +\n -+\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n ++\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n +\t\t\ttest_when_finished \"rm -rf repo\" &&\n +\t\t\tgit init --ref-format=$from_format repo &&\n +\t\t\t(\n @@ t/t1423-ref-backend.sh (new)\n +\t\t\t)\n +\t\t'\n +\n -+\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n ++\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n +\t\t\ttest_when_finished \"rm -rf repo\" &&\n +\t\t\tgit init --ref-format=$from_format repo &&\n +\t\t\t(\n4: 12168d2e35 ! 6: 288bc77a98 refs: add GIT_REFERENCE_BACKEND to specify reference backend\n @@ Commit message\n variable allows us to modify the reference backend and location on the\n fly for individual Git commands.\n \n + The environment variable also allows usage of alternate reference\n + directories during 'git-clone(1)' and 'git-init(1)'. Add the config to\n + the repository when created with the environment variable set.\n +\n + When initializing the repository with an alternate reference folder,\n + create the required stubs in the repositories $GIT_DIR. The inverse,\n + i.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\n + since that would render it unusable. Removal of ref store is only used\n + when migrating between ref formats and cleanup of the $GIT_DIR doesn't\n + make sense in such a situation.\n +\n Helped-by: Jean-Noël Avila \n Signed-off-by: Karthik Nayak \n \n @@ environment.h\n /*\n * Environment variable used to propagate the --no-advice global option to the\n \n + ## refs.c ##\n +@@ refs.c: int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n + {\n + \tint ret = refs->be->create_on_disk(refs, flags, err);\n + \n +-\tif (!ret &&\n +-\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n +-\t\tstruct strbuf msg = STRBUF_INIT;\n +-\n +-\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n +-\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n +-\t\tstrbuf_release(&msg);\n ++\tif (!ret) {\n ++\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n ++\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n ++\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n ++\t\t\t\t\t\t \"repository uses alternate refs storage\");\n ++\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n ++\t\t\tstruct strbuf msg = STRBUF_INIT;\n ++\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n ++\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n ++\t\t\tstrbuf_release(&msg);\n ++\t\t}\n + \t}\n + \n + \treturn ret;\n ++\n + }\n + \n + int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n +@@ refs.c: int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n + \t\tif (format == REF_STORAGE_FORMAT_FILES)\n + \t\t\treturn ret;\n + \n ++\t\t/* Alternate refs backend require stubs in the gitdir. */\n ++\t\tif (refs->repo->ref_storage_payload)\n ++\t\t\treturn ret;\n ++\n + \t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n + \t\tif (unlink(sb.buf) < 0) {\n + \t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n +\n ## setup.c ##\n @@ setup.c: const char *setup_git_directory_gently(int *nongit_ok)\n \tstatic struct strbuf cwd = STRBUF_INIT;\n @@ setup.c: const char *setup_git_directory_gently(int *nongit_ok)\n +\t */\n +\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n +\tif (ref_backend_uri) {\n -+\t\tchar *backend, *location;\n ++\t\tchar *backend, *payload;\n +\t\tenum ref_storage_format format;\n +\n -+\t\tparse_reference_uri(ref_backend_uri, &backend, &location);\n ++\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n +\t\tformat = ref_storage_format_by_name(backend);\n +\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n +\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n -+\t\trepo_set_ref_storage_format(the_repository, format, location);\n ++\t\trepo_set_ref_storage_format(the_repository, format, payload);\n +\n +\t\tfree(backend);\n -+\t\tfree(location);\n ++\t\tfree(payload);\n +\t}\n +\n \tsetup_original_cwd();\n \n \tstrbuf_release(&dir);\n +@@ setup.c: void initialize_repository_version(int hash_algo,\n + \t * the remote repository's format.\n + \t */\n + \tif (hash_algo != GIT_HASH_SHA1_LEGACY ||\n +-\t ref_storage_format != REF_STORAGE_FORMAT_FILES)\n ++\t ref_storage_format != REF_STORAGE_FORMAT_FILES ||\n ++\t the_repository->ref_storage_payload)\n + \t\ttarget_version = GIT_REPO_VERSION_READ;\n + \n + \tif (hash_algo != GIT_HASH_SHA1_LEGACY && hash_algo != GIT_HASH_UNKNOWN)\n +@@ setup.c: void initialize_repository_version(int hash_algo,\n + \telse if (reinit)\n + \t\trepo_config_set_gently(the_repository, \"extensions.objectformat\", NULL);\n + \n +-\tif (ref_storage_format != REF_STORAGE_FORMAT_FILES)\n ++\tif (the_repository->ref_storage_payload) {\n ++\t\tstruct strbuf ref_uri = STRBUF_INIT;\n ++\n ++\t\tstrbuf_addf(&ref_uri, \"%s://%s\",\n ++\t\t\t ref_storage_format_to_name(ref_storage_format),\n ++\t\t\t the_repository->ref_storage_payload);\n ++\t\trepo_config_set(the_repository, \"extensions.refstorage\", ref_uri.buf);\n ++\t\tstrbuf_release(&ref_uri);\n ++\t} else if (ref_storage_format != REF_STORAGE_FORMAT_FILES) {\n + \t\trepo_config_set(the_repository, \"extensions.refstorage\",\n + \t\t\t\tref_storage_format_to_name(ref_storage_format));\n +-\telse if (reinit)\n ++\t} else if (reinit) {\n + \t\trepo_config_set_gently(the_repository, \"extensions.refstorage\", NULL);\n ++\t}\n + \n + \tif (reinit) {\n + \t\tstruct strbuf config = STRBUF_INIT;\n +@@ setup.c: static void repository_format_configure(struct repository_format *repo_fmt,\n + \t\t.ignore_repo = 1,\n + \t\t.ignore_worktree = 1,\n + \t};\n ++\tconst char *ref_backend_uri;\n + \tconst char *env;\n + \n + \tconfig_with_options(read_default_format_config, &cfg, NULL, NULL, &opts);\n +@@ setup.c: static void repository_format_configure(struct repository_format *repo_fmt,\n + \t} else {\n + \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n + \t}\n ++\n ++\n ++\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n ++\tif (ref_backend_uri) {\n ++\t\tchar *backend, *payload;\n ++\t\tenum ref_storage_format format;\n ++\n ++\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n ++\t\tformat = ref_storage_format_by_name(backend);\n ++\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n ++\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n ++\n ++\t\trepo_fmt->ref_storage_format = format;\n ++\t\trepo_fmt->ref_storage_payload = payload;\n ++\n ++\t\tfree(backend);\n ++\t}\n ++\n + \trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n + \t\t\t\t repo_fmt->ref_storage_payload);\n + }\n \n ## t/t1423-ref-backend.sh ##\n @@ t/t1423-ref-backend.sh: test_description='Test reference backend URIs'\n @@ t/t1423-ref-backend.sh: run_with_uri() {\n }\n \n -test_expect_success 'URI is invalid' '\n -+methods=\"config\"\n ++methods=\"config env\"\n +for method in $methods\n +do\n +\n @@ t/t1423-ref-backend.sh: run_with_uri() {\n '\n \n @@ t/t1423-ref-backend.sh: do\n - \tfor dir in \"$(pwd)/repo/.git\" \"./\"\n + \tfor dir in \"$(pwd)/repo/.git\" \".\"\n \tdo\n \n --\t\ttest_expect_success \"$read from $to_format backend, $dir dir\" '\n -+\t\ttest_expect_success \"$method: $read from $to_format backend, $dir dir\" '\n +-\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n ++\t\ttest_expect_success \"$method: read from $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n @@ t/t1423-ref-backend.sh: do\n \t\t\t)\n \t\t'\n \n --\t\ttest_expect_success \"$write to $to_format backend, $dir dir\" '\n -+\t\ttest_expect_success \"$method: $write to $to_format backend, $dir dir\" '\n +-\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n ++\t\ttest_expect_success \"$method: write to $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n @@ t/t1423-ref-backend.sh: do\n \n -\t\t\t\tgit config set core.repositoryformatversion 1 &&\n -\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n +-\n +-\t\t\t\tgit worktree add ../wt 2\n +-\t\t\t) &&\n +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n +\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n \n --\t\t\t\tgit worktree add ../wt 2\n --\t\t\t) &&\n +-\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n +-\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n +-\t\t\t! test_cmp expect actual &&\n +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n +\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n +\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n +\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n +\t\t\t\t! test_cmp expect actual &&\n \n --\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n --\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n --\t\t\t! test_cmp expect actual &&\n --\n -\t\t\tgit -C wt rev-parse 2 >expect &&\n -\t\t\tgit -C wt rev-parse HEAD >actual &&\n -\t\t\ttest_cmp expect actual\n @@ t/t1423-ref-backend.sh: do\n +\t\t\t)\n \t\t'\n \tdone # closes dir\n - done # closes to_format\n --done # closes from_format\n -+done # closes to_format\n +\n -+done # closes method\n ++\ttest_expect_success \"migrating repository to $to_format with alternate refs directory\" '\n ++\t\ttest_when_finished \"rm -rf repo refdir\" &&\n ++\t\tmkdir refdir &&\n ++\t\tGIT_REFERENCE_BACKEND=\"${from_format}://$(pwd)/refdir\" git init repo &&\n ++\t\t(\n ++\t\t\tcd repo &&\n ++\n ++\t\t\ttest_commit 1 &&\n ++\t\t\ttest_commit 2 &&\n ++\t\t\ttest_commit 3 &&\n ++\n ++\t\t\tgit refs migrate --ref-format=$to_format &&\n ++\t\t\tgit refs list >out &&\n ++\t\t\ttest_grep \"refs/tags/1\"\tout &&\n ++\t\t\ttest_grep \"refs/tags/2\"\tout &&\n ++\t\t\ttest_grep \"refs/tags/3\"\tout\n ++\t\t)\n ++\t'\n ++\n + done # closes to_format\n + done # closes from_format\n \n ++done # closes method\n ++\n ++test_expect_success 'initializing repository with alt ref directory' '\n ++\ttest_when_finished \"rm -rf repo refdir\" &&\n ++\tmkdir refdir &&\n ++\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n ++\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n ++\t(\n ++\t\tcd repo &&\n ++\n ++\t\tgit config get extensions.refstorage >expect &&\n ++\t\techo $BACKEND >actual &&\n ++\t\ttest_cmp expect actual &&\n ++\n ++\t\ttest_commit 1 &&\n ++\t\ttest_commit 2 &&\n ++\t\ttest_commit 3 &&\n ++\t\tgit refs list >out &&\n ++\t\ttest_grep \"refs/tags/1\"\tout &&\n ++\t\ttest_grep \"refs/tags/2\"\tout &&\n ++\t\ttest_grep \"refs/tags/3\"\tout\n ++\t)\n ++'\n ++\n ++test_expect_success 'cloning repository with alt ref directory' '\n ++\ttest_when_finished \"rm -rf source repo refdir\" &&\n ++\tmkdir refdir &&\n ++\n ++\tgit init source &&\n ++\ttest_commit -C source 1 &&\n ++\ttest_commit -C source 2 &&\n ++\ttest_commit -C source 3 &&\n ++\n ++\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n ++\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n ++\n ++\tgit -C repo config get extensions.refstorage >expect &&\n ++\techo $BACKEND >actual &&\n ++\ttest_cmp expect actual &&\n ++\n ++\tgit -C source for-each-ref refs/tags/ >expect &&\n ++\tgit -C repo for-each-ref refs/tags/ >actual &&\n ++\ttest_cmp expect actual\n ++'\n ++\n test_done\n\n\nbase-commit: 22584464849815268419fd9d2eba307362360db1\nchange-id: 20251105-kn-alternate-ref-dir-3e572e8cd0ef\n\nThanks\n- Karthik\n\n"},{"id":"536033","messageId":"20260214-kn-alternate-ref-dir-v6-1-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","subject":"[PATCH v6 1/6] setup: don't modify repo in `create_reference_database()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:14Z","receivedAt":"2026-02-14T22:34:31Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The `create_reference_database()` function is used to create the\nreference database during initialization of a repository. The function\ncalls `repo_set_ref_storage_format()` to set the repositories reference\nformat. This is an unexpected side-effect of the function. More so\nbecause the function is only called in two locations:\n\n 1. During git-init(1) where the value is propagated from the `struct\n repository_format repo_fmt` value.\n\n 2. During git-clone(1) where the value is propagated from the\n `the_repository` value.\n\nThe former is valid, however the flow already calls\n`repo_set_ref_storage_format()`, so this effort is simply duplicated.\nThe latter sets the existing value in `the_repository` back to itself.\nWhile this is okay for now, introduction of more fields in\n`repo_set_ref_storage_format()` would cause issues, especially\ndynamically allocated strings, where we would free/allocate the same\nstring back into `the_repostiory`.\n\nTo avoid all this confusion, clean up the function to longer take in and\nset the repo's reference storage format.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 2 +-\n setup.c | 7 ++-----\n setup.h | 3 +--\n 3 files changed, 4 insertions(+), 8 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex b40cee5968..cd43bb5aa2 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1442,7 +1442,7 @@ int cmd_clone(int argc,\n \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n \trepo_set_hash_algo(the_repository, hash_algo);\n-\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n+\tcreate_reference_database(NULL, 1);\n \n \t/*\n \t * Before fetching from the remote, download and install bundle\ndiff --git a/setup.c b/setup.c\nindex b723f8b339..1fc9ae3872 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -2359,14 +2359,12 @@ static int is_reinit(void)\n \treturn ret;\n }\n \n-void create_reference_database(enum ref_storage_format ref_storage_format,\n-\t\t\t const char *initial_branch, int quiet)\n+void create_reference_database(const char *initial_branch, int quiet)\n {\n \tstruct strbuf err = STRBUF_INIT;\n \tchar *to_free = NULL;\n \tint reinit = is_reinit();\n \n-\trepo_set_ref_storage_format(the_repository, ref_storage_format);\n \tif (ref_store_create_on_disk(get_main_ref_store(the_repository), 0, &err))\n \t\tdie(\"failed to set up refs db: %s\", err.buf);\n \n@@ -2701,8 +2699,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n \t\t\t\t &repo_fmt, init_shared_repository);\n \n \tif (!(flags & INIT_DB_SKIP_REFDB))\n-\t\tcreate_reference_database(repo_fmt.ref_storage_format,\n-\t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n+\t\tcreate_reference_database(initial_branch, flags & INIT_DB_QUIET);\n \tcreate_object_directory();\n \n \tif (repo_settings_get_shared_repository(the_repository)) {\ndiff --git a/setup.h b/setup.h\nindex d55dcc6608..ddb9f6701c 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -240,8 +240,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n void initialize_repository_version(int hash_algo,\n \t\t\t\t enum ref_storage_format ref_storage_format,\n \t\t\t\t int reinit);\n-void create_reference_database(enum ref_storage_format ref_storage_format,\n-\t\t\t const char *initial_branch, int quiet);\n+void create_reference_database(const char *initial_branch, int quiet);\n \n /*\n * NOTE NOTE NOTE!!\n\n-- \n2.52.0\n\n"},{"id":"536034","messageId":"20260214-kn-alternate-ref-dir-v6-2-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","subject":"[PATCH v6 2/6] refs: extract out `refs_create_refdir_stubs()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:15Z","receivedAt":"2026-02-14T22:34:32Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"For Git to recognize a directory as a Git directory, it requires the\ndirectory to contain:\n\n 1. 'HEAD' file\n 2. 'objects/' directory\n 3. 'refs/' directory\n\nHere, #1 and #3 are part of the reference storage mechanism,\nspecifically the files backend. Since then, newer backends such as the\nreftable backend have moved to using their own path ('reftable/') for\nstoring references. But to ensure Git still recognizes the directory as\na Git directory, we create stubs.\n\nThere are two locations where we create stubs:\n\n- In 'refs/reftable-backend.c' when creating the reftable backend.\n- In 'clone.c' before spawning transport helpers.\n\nIn a following commit, we'll add another instance. So instead of\nrepeating the code, let's extract out this code to\n`refs_create_refdir_stubs()` and use it.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 7 +------\n refs.c | 23 +++++++++++++++++++++++\n refs.h | 13 +++++++++++++\n refs/reftable-backend.c | 14 ++------------\n 4 files changed, 39 insertions(+), 18 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex cd43bb5aa2..697c5bb5cb 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1225,12 +1225,7 @@ int cmd_clone(int argc,\n \tinitialize_repository_version(GIT_HASH_UNKNOWN,\n \t\t\t\t the_repository->ref_storage_format, 1);\n \n-\tstrbuf_addf(&buf, \"%s/HEAD\", git_dir);\n-\twrite_file(buf.buf, \"ref: refs/heads/.invalid\");\n-\n-\tstrbuf_reset(&buf);\n-\tstrbuf_addf(&buf, \"%s/refs\", git_dir);\n-\tsafe_create_dir(the_repository, buf.buf, 1);\n+\trefs_create_refdir_stubs(the_repository, git_dir, NULL);\n \n \t/*\n \t * additional config can be injected with -c, make sure it's included\ndiff --git a/refs.c b/refs.c\nindex 627b7f8698..77b93d655b 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2163,6 +2163,29 @@ const char *refs_resolve_ref_unsafe(struct ref_store *refs,\n \treturn NULL;\n }\n \n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_content)\n+{\n+\tstruct strbuf path = STRBUF_INIT;\n+\n+\tstrbuf_addf(&path, \"%s/HEAD\", refdir);\n+\twrite_file(path.buf, \"ref: refs/heads/.invalid\");\n+\tadjust_shared_perm(repo, path.buf);\n+\n+\tstrbuf_reset(&path);\n+\tstrbuf_addf(&path, \"%s/refs\", refdir);\n+\tsafe_create_dir(repo, path.buf, 1);\n+\n+\tif (refs_heads_content) {\n+\t\tstrbuf_reset(&path);\n+\t\tstrbuf_addf(&path, \"%s/refs/heads\", refdir);\n+\t\twrite_file(path.buf, \"%s\", refs_heads_content);\n+\t\tadjust_shared_perm(repo, path.buf);\n+\t}\n+\n+\tstrbuf_release(&path);\n+}\n+\n /* backend functions */\n int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n {\ndiff --git a/refs.h b/refs.h\nindex f0abfa1d93..9d8890fdff 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -1427,4 +1427,17 @@ void ref_iterator_free(struct ref_iterator *ref_iterator);\n int do_for_each_ref_iterator(struct ref_iterator *iter,\n \t\t\t each_ref_fn fn, void *cb_data);\n \n+/*\n+ * Git only recognizes a directory as a repository if it contains:\n+ * - HEAD file\n+ * - refs/ folder\n+ * While it is necessary within the files backend, newer backends may not\n+ * follow the same structure. To go around this, we create stubs as necessary.\n+ *\n+ * If provided with a 'refs_heads_msg', we create the 'refs/heads/head' file\n+ * with the provided message.\n+ */\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_msg);\n+\n #endif /* REFS_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex fe74af73af..d8651fe779 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,18 +491,8 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"ref: refs/heads/.invalid\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tsafe_create_dir(the_repository, sb.buf, 1);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"this repository uses the reftable format\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n+\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n+\t\t\t\t \"this repository uses the reftable format\");\n \n \tstrbuf_release(&sb);\n \treturn 0;\n\n-- \n2.52.0\n\n"},{"id":"536035","messageId":"20260214-kn-alternate-ref-dir-v6-3-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","subject":"[PATCH v6 3/6] refs: receive and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:16Z","receivedAt":"2026-02-14T22:34:33Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"An upcoming commit will add support for providing an URI via the\n'extensions.refStorage' config. The URI will contain the reference\nbackend and a corresponding payload. The payload can be then used for\nproviding an alternate locations for the reference backend.\n\nTo prepare for this, modify the existing backends to accept such an\nargument when initializing via the 'init()' function. Both the files\nand reftable backends will parse the information to be filesystem paths\nto store references. Given that no callers pass any payload yet this is\nessentially a no-op change for now.\n\nTo enable this, provide a 'refs_compute_filesystem_location()' function\nwhich will parse the current 'gitdir' and the 'payload' to provide the\nfinal reference directory and common reference directory (if working in\na linked worktree).\n\nThe documentation and tests will be added alongside the extension of the\nconfig variable.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n refs.c | 40 +++++++++++++++++++++++++++++++++++++++-\n refs/files-backend.c | 17 ++++++++++++-----\n refs/packed-backend.c | 5 +++++\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 14 ++++++++++++++\n refs/reftable-backend.c | 24 ++++++++++++++----------\n 6 files changed, 85 insertions(+), 16 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex 77b93d655b..11d028232b 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -5,6 +5,7 @@\n #define USE_THE_REPOSITORY_VARIABLE\n \n #include \"git-compat-util.h\"\n+#include \"abspath.h\"\n #include \"advice.h\"\n #include \"config.h\"\n #include \"environment.h\"\n@@ -2247,7 +2248,7 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, gitdir, flags);\n+\trefs = be->init(repo, NULL, gitdir, flags);\n \treturn refs;\n }\n \n@@ -3425,3 +3426,40 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n \t\treturn \"unknown failure\";\n \t}\n }\n+\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\n+\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n+\n+\tif (!payload) {\n+\t\t/*\n+\t\t * We can use the 'gitdir' as the 'refdir' without appending the\n+\t\t * worktree path, as the 'gitdir' here is already the worktree\n+\t\t * path and is different from 'commondir' denoted by 'ref_common_dir'.\n+\t\t */\n+\t\tstrbuf_addstr(refdir, gitdir);\n+\t\treturn;\n+\t}\n+\n+\tif (!is_absolute_path(payload)) {\n+\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n+\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n+\t} else {\n+\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n+\t}\n+\n+\tstrbuf_addbuf(refdir, ref_common_dir);\n+\n+\tif (*is_worktree) {\n+\t\tconst char *wt_id = strrchr(gitdir, '/');\n+\t\tif (!wt_id)\n+\t\t\tBUG(\"worktree path does not contain slash \");\n+\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id + 1);\n+\t}\n+\n+\tstrbuf_release(&sb);\n+}\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex 240d3c3b26..b40d6feb1f 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n * set of caches.\n */\n static struct ref_store *files_ref_store_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags)\n {\n \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n \tstruct ref_store *ref_store = (struct ref_store *)refs;\n-\tstruct strbuf sb = STRBUF_INIT;\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n+\tbool is_worktree;\n+\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n \n-\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n+\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n \trefs->store_flags = flags;\n-\tget_common_dir_noenv(&sb, gitdir);\n-\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n+\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n \trefs->packed_ref_store =\n-\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n+\t\tpacked_ref_store_init(repo, NULL, refs->gitcommondir, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n@@ -126,6 +131,8 @@ static struct ref_store *files_ref_store_init(struct repository *repo,\n \tchdir_notify_reparent(\"files-backend $GIT_COMMONDIR\",\n \t\t\t &refs->gitcommondir);\n \n+\tstrbuf_release(&refdir);\n+\n \treturn ref_store;\n }\n \ndiff --git a/refs/packed-backend.c b/refs/packed-backend.c\nindex 4ea0c12299..e7bb9f10f9 100644\n--- a/refs/packed-backend.c\n+++ b/refs/packed-backend.c\n@@ -211,7 +211,12 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n \treturn snapshot->refs->base.repo->hash_algo->hexsz;\n }\n \n+/*\n+ * Since packed-refs is only stored in the common dir, don't parse the\n+ * payload and rely on the files-backend to set 'gitdir' correctly.\n+ */\n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload UNUSED,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags)\n {\ndiff --git a/refs/packed-backend.h b/refs/packed-backend.h\nindex 9481d5e7c2..2c2377a356 100644\n--- a/refs/packed-backend.h\n+++ b/refs/packed-backend.h\n@@ -14,6 +14,7 @@ struct ref_transaction;\n */\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags);\n \ndiff --git a/refs/refs-internal.h b/refs/refs-internal.h\nindex c7d2a6e50b..9a635f4e6c 100644\n--- a/refs/refs-internal.h\n+++ b/refs/refs-internal.h\n@@ -389,6 +389,7 @@ struct ref_store;\n * the ref_store and to record the ref_store for later lookup.\n */\n typedef struct ref_store *ref_store_init_fn(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags);\n /*\n@@ -666,4 +667,17 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n \t\t\t\t\t unsigned int initial_transaction,\n \t\t\t\t\t struct strbuf *err);\n \n+/*\n+ * Given a gitdir and the reference storage payload provided, retrieve the\n+ * 'refdir' and 'ref_common_dir'. The former is where references should be\n+ * stored for the current worktree, the latter is the common reference\n+ * directory if working with a linked worktree. If working with the main\n+ * worktree, both values will be the same.\n+ *\n+ * This is used by backends that store store files in the repository directly.\n+ */\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir);\n+\n #endif /* REFS_REFS_INTERNAL_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex d8651fe779..964b0b50fc 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -372,18 +372,24 @@ static int reftable_be_fsync(int fd)\n }\n \n static struct ref_store *reftable_be_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int store_flags)\n {\n \tstruct reftable_ref_store *refs = xcalloc(1, sizeof(*refs));\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n \tstruct strbuf path = STRBUF_INIT;\n-\tint is_worktree;\n+\tbool is_worktree;\n \tmode_t mask;\n \n \tmask = umask(0);\n \tumask(mask);\n \n-\tbase_ref_store_init(&refs->base, repo, gitdir, &refs_be_reftable);\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n+\n+\tbase_ref_store_init(&refs->base, repo, refdir.buf, &refs_be_reftable);\n \tstrmap_init(&refs->worktree_backends);\n \trefs->store_flags = store_flags;\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n@@ -419,14 +425,11 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t/*\n \t * Set up the main reftable stack that is hosted in GIT_COMMON_DIR.\n \t * This stack contains both the shared and the main worktree refs.\n-\t *\n-\t * Note that we don't try to resolve the path in case we have a\n-\t * worktree because `get_common_dir_noenv()` already does it for us.\n \t */\n-\tis_worktree = get_common_dir_noenv(&path, gitdir);\n+\tstrbuf_addbuf(&path, &ref_common_dir);\n \tif (!is_worktree) {\n \t\tstrbuf_reset(&path);\n-\t\tstrbuf_realpath(&path, gitdir, 0);\n+\t\tstrbuf_realpath(&path, ref_common_dir.buf, 0);\n \t}\n \tstrbuf_addstr(&path, \"/reftable\");\n \trefs->err = reftable_backend_init(&refs->main_backend, path.buf,\n@@ -443,10 +446,9 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t * do it efficiently.\n \t */\n \tif (is_worktree) {\n-\t\tstrbuf_reset(&path);\n-\t\tstrbuf_addf(&path, \"%s/reftable\", gitdir);\n+\t\tstrbuf_addstr(&refdir, \"/reftable\");\n \n-\t\trefs->err = reftable_backend_init(&refs->worktree_backend, path.buf,\n+\t\trefs->err = reftable_backend_init(&refs->worktree_backend, refdir.buf,\n \t\t\t\t\t\t &refs->write_options);\n \t\tif (refs->err)\n \t\t\tgoto done;\n@@ -456,6 +458,8 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \n done:\n \tassert(refs->err != REFTABLE_API_ERROR);\n+\tstrbuf_release(&ref_common_dir);\n+\tstrbuf_release(&refdir);\n \tstrbuf_release(&path);\n \treturn &refs->base;\n }\n\n-- \n2.52.0\n\n"},{"id":"536036","messageId":"20260214-kn-alternate-ref-dir-v6-4-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","subject":"[PATCH v6 4/6] refs: move out stub modification to generic layer","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:17Z","receivedAt":"2026-02-14T22:34:34Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"When creating the reftable reference backend on disk, we create stubs to\nensure that the directory can be recognized as a Git repository. This is\ndone by calling `refs_create_refdir_stubs()`. Move this to the generic\nlayer as this is needed for all backends excluding from the files\nbackends. In an upcoming commit, we'll also need to extend this logic to\ncreate stubs when using alternate reference directories.\n\nSimilarly, move the logic for deletion of stubs to the generic layer.\nThe files backend recursively calls the remove function of the\n'packed-backend', here skip calling the generic function since that\nwould try to delete stubs.\n\nSigned-off-by: Karthik Nayak \n---\n refs.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++--\n refs/files-backend.c | 6 +++++-\n refs/reftable-backend.c | 27 --------------------------\n 3 files changed, 54 insertions(+), 30 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex 11d028232b..a24602c9bf 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2190,12 +2190,59 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n /* backend functions */\n int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n {\n-\treturn refs->be->create_on_disk(refs, flags, err);\n+\tint ret = refs->be->create_on_disk(refs, flags, err);\n+\n+\tif (!ret &&\n+\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\tstruct strbuf msg = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n+\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n+\t\tstrbuf_release(&msg);\n+\t}\n+\n+\treturn ret;\n }\n \n int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n {\n-\treturn refs->be->remove_on_disk(refs, err);\n+\tint ret = refs->be->remove_on_disk(refs, err);\n+\n+\tif (!ret) {\n+\t\tenum ref_storage_format format = ref_storage_format_by_name(refs->be->name);\n+\t\tstruct strbuf sb = STRBUF_INIT;\n+\n+\t\t/* Backends apart from the files backend create stubs. */\n+\t\tif (format == REF_STORAGE_FORMAT_FILES)\n+\t\t\treturn ret;\n+\n+\t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n+\t\tif (unlink(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\t\tstrbuf_reset(&sb);\n+\n+\t\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->gitdir);\n+\t\tif (unlink(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete stub heads: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\t\tstrbuf_reset(&sb);\n+\n+\t\tstrbuf_addf(&sb, \"%s/refs\", refs->gitdir);\n+\t\tif (rmdir(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete refs directory: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\n+\t\tstrbuf_release(&sb);\n+\t}\n+\n+\treturn ret;\n }\n \n int repo_resolve_gitlink_ref(struct repository *r,\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex b40d6feb1f..9cde3ba724 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -3707,7 +3707,11 @@ static int files_ref_store_remove_on_disk(struct ref_store *ref_store,\n \tif (for_each_root_ref(refs, remove_one_root_ref, &data) < 0)\n \t\tret = -1;\n \n-\tif (ref_store_remove_on_disk(refs->packed_ref_store, err) < 0)\n+\t/*\n+\t * Directly access the cleanup functions for packed-refs as the generic function\n+\t * would try to clear stubs which isn't required for the files backend.\n+\t */\n+\tif (refs->packed_ref_store->be->remove_on_disk(refs->packed_ref_store, err) < 0)\n \t\tret = -1;\n \n \tstrbuf_release(&sb);\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex 964b0b50fc..0e220d6bb5 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -495,9 +495,6 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n-\t\t\t\t \"this repository uses the reftable format\");\n-\n \tstrbuf_release(&sb);\n \treturn 0;\n }\n@@ -523,30 +520,6 @@ static int reftable_be_remove_on_disk(struct ref_store *ref_store,\n \t\t\t strerror(errno));\n \t\tret = -1;\n \t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\tif (unlink(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\tif (unlink(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete stub heads: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tif (rmdir(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete refs directory: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n \n \tstrbuf_release(&sb);\n \treturn ret;\n\n-- \n2.52.0\n\n"},{"id":"536038","messageId":"20260214-kn-alternate-ref-dir-v6-5-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","subject":"[PATCH v6 5/6] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:18Z","receivedAt":"2026-02-14T22:34:35Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'extensions.refStorage' config is used to specify the reference\nbackend for a given repository. Both the 'files' and 'reftable' backends\nutilize the $GIT_DIR as the reference folder by default in\n`get_main_ref_store()`.\n\nSince the reference backends are pluggable, this means that they could\nwork with out-of-tree reference directories too. Extend the 'refStorage'\nconfig to also support taking an URI input, where users can specify the\nreference backend and the location.\n\nAdd the required changes to obtain and propagate this value to the\nindividual backends. Add the necessary documentation and tests.\n\nTraditionally, for linked worktrees, references were stored in the\n'$GIT_DIR/worktrees/' path. But when using an alternate reference\nstorage path, it doesn't make sense to store the main worktree\nreferences in the new path, and the linked worktree references in the\n$GIT_DIR. So, let's store linked worktree references in\n'$ALTERNATE_REFERENCE_DIR/worktrees/'. To do this, create the\nnecessary files and folders while also adding stubs in the $GIT_DIR path\nto ensure that it is still considered a Git directory.\n\nIdeally, we would want to pass in a `struct worktree *` to individual\nbackends, instead of passing the `gitdir`. This allows them to handle\nworktree specific logic. Currently, that is not possible since the\nworktree code is:\n\n - Tied to using the global `the_repository` variable.\n\n - Is not setup before the reference database during initialization of\n the repository.\n\nAdd a TODO in 'refs.c' to ensure we can eventually make that change.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n Documentation/config/extensions.adoc | 16 +++-\n builtin/worktree.c | 34 ++++++++\n refs.c | 6 +-\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 34 +++++++-\n setup.h | 1 +\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n 9 files changed, 259 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 532456644b..3e51da36d3 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n `core.repositoryFormatVersion` setting.\n \n refStorage:::\n-\tSpecify the ref storage format to use. The acceptable values are:\n+\tSpecify the ref storage format and a corresponding payload. The value\n+\tcan be either a format name or a URI:\n +\n --\n+* A format name alone (e.g., `reftable` or `files`).\n+\n+* A URI format `://` explicitly specifies both the\n+ format and payload (e.g., `reftable:///foo/bar`).\n+\n+Supported format names are:\n++\n include::../ref-storage-format.adoc[]\n++\n+The payload is passed directly to the reference backend. For the files and\n+reftable backends, this must be a filesystem path where the references will\n+be stored. Defaulting to the commondir when no payload is provided. Relative\n+paths are resolved relative to the $GIT_DIR. Future backends may support\n+other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n Note that this setting should only be set by linkgit:git-init[1] or\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..293e808379 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -425,6 +425,39 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n \treturn run_command(&cp);\n }\n \n+/*\n+ * References for worktrees are generally stored in '$GIT_DIR/worktrees/'.\n+ * But when using alternate reference directories, we want to store the worktree\n+ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n+ *\n+ * Create the necessary folder structure to facilitate the same. But to ensure\n+ * that the former path is still considered a Git directory, add stubs.\n+ */\n+static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\tchar *path;\n+\n+\tpath = wt->repo->ref_storage_payload;\n+\tif (!path)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(path))\n+\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n+\n+\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_addf(&sb, \"/%s\", wt->id);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_reset(&sb);\n+\n+\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n+\t\t path, wt->id);\n+\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n+\n+\tstrbuf_release(&sb);\n+}\n+\n static int add_worktree(const char *path, const char *refname,\n \t\t\tconst struct add_opts *opts)\n {\n@@ -518,6 +551,7 @@ static int add_worktree(const char *path, const char *refname,\n \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n \t\tgoto done;\n \t}\n+\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n \twt_refs = get_worktree_ref_store(wt);\n \n \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\ndiff --git a/refs.c b/refs.c\nindex a24602c9bf..87ef54abd4 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2295,7 +2295,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, NULL, gitdir, flags);\n+\t/*\n+\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n+\t * allow the backend to handle how it wants to deal with worktrees.\n+\t */\n+\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n \treturn refs;\n }\n \ndiff --git a/repository.c b/repository.c\nindex c7e75215ac..9815f081ef 100644\n--- a/repository.c\n+++ b/repository.c\n@@ -193,9 +193,12 @@ void repo_set_compat_hash_algo(struct repository *repo, int algo)\n }\n \n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format)\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload)\n {\n \trepo->ref_storage_format = format;\n+\tfree(repo->ref_storage_payload);\n+\trepo->ref_storage_payload = xstrdup_or_null(payload);\n }\n \n /*\n@@ -277,7 +280,8 @@ int repo_init(struct repository *repo,\n \n \trepo_set_hash_algo(repo, format.hash_algo);\n \trepo_set_compat_hash_algo(repo, format.compat_hash_algo);\n-\trepo_set_ref_storage_format(repo, format.ref_storage_format);\n+\trepo_set_ref_storage_format(repo, format.ref_storage_format,\n+\t\t\t\t format.ref_storage_payload);\n \trepo->repository_format_worktree_config = format.worktree_config;\n \trepo->repository_format_relative_worktrees = format.relative_worktrees;\n \trepo->repository_format_precious_objects = format.precious_objects;\n@@ -369,6 +373,7 @@ void repo_clear(struct repository *repo)\n \tFREE_AND_NULL(repo->index_file);\n \tFREE_AND_NULL(repo->worktree);\n \tFREE_AND_NULL(repo->submodule_prefix);\n+\tFREE_AND_NULL(repo->ref_storage_payload);\n \n \todb_free(repo->objects);\n \trepo->objects = NULL;\ndiff --git a/repository.h b/repository.h\nindex 6063c4b846..95e2333bad 100644\n--- a/repository.h\n+++ b/repository.h\n@@ -150,6 +150,11 @@ struct repository {\n \n \t/* Repository's reference storage format, as serialized on disk. */\n \tenum ref_storage_format ref_storage_format;\n+\t/*\n+\t * Reference storage information as needed for the backend. This contains\n+\t * only the payload from the reference URI without the schema.\n+\t */\n+\tchar *ref_storage_payload;\n \n \t/* A unique-id for tracing purposes. */\n \tint trace2_repo_id;\n@@ -204,7 +209,8 @@ void repo_set_worktree(struct repository *repo, const char *path);\n void repo_set_hash_algo(struct repository *repo, int algo);\n void repo_set_compat_hash_algo(struct repository *repo, int compat_algo);\n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format);\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload);\n void initialize_repository(struct repository *repo);\n RESULT_MUST_BE_USED\n int repo_init(struct repository *r, const char *gitdir, const char *worktree);\ndiff --git a/setup.c b/setup.c\nindex 1fc9ae3872..d407f3347b 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -632,6 +632,21 @@ static enum extension_result handle_extension_v0(const char *var,\n \t\treturn EXTENSION_UNKNOWN;\n }\n \n+static void parse_reference_uri(const char *value, char **format,\n+\t\t\t\tchar **payload)\n+{\n+\tconst char *schema_end;\n+\n+\tschema_end = strstr(value, \"://\");\n+\tif (!schema_end) {\n+\t\t*format = xstrdup(value);\n+\t\t*payload = NULL;\n+\t} else {\n+\t\t*format = xstrndup(value, schema_end - value);\n+\t\t*payload = xstrdup_or_null(schema_end + 3);\n+\t}\n+}\n+\n /*\n * Record any new extensions in this function.\n */\n@@ -674,10 +689,17 @@ static enum extension_result handle_extension(const char *var,\n \t\treturn EXTENSION_OK;\n \t} else if (!strcmp(ext, \"refstorage\")) {\n \t\tunsigned int format;\n+\t\tchar *format_str;\n \n \t\tif (!value)\n \t\t\treturn config_error_nonbool(var);\n-\t\tformat = ref_storage_format_by_name(value);\n+\n+\t\tparse_reference_uri(value, &format_str,\n+\t\t\t\t &data->ref_storage_payload);\n+\n+\t\tformat = ref_storage_format_by_name(format_str);\n+\t\tfree(format_str);\n+\n \t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n \t\t\treturn error(_(\"invalid value for '%s': '%s'\"),\n \t\t\t\t \"extensions.refstorage\", value);\n@@ -850,6 +872,7 @@ void clear_repository_format(struct repository_format *format)\n \tstring_list_clear(&format->v1_only_extensions, 0);\n \tfree(format->work_tree);\n \tfree(format->partial_clone);\n+\tfree(format->ref_storage_payload);\n \tinit_repository_format(format);\n }\n \n@@ -1942,7 +1965,8 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\t\trepo_set_compat_hash_algo(the_repository,\n \t\t\t\t\t\t repo_fmt.compat_hash_algo);\n \t\t\trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t\t\t repo_fmt.ref_storage_format);\n+\t\t\t\t\t\t repo_fmt.ref_storage_format,\n+\t\t\t\t\t\t repo_fmt.ref_storage_payload);\n \t\t\tthe_repository->repository_format_worktree_config =\n \t\t\t\trepo_fmt.worktree_config;\n \t\t\tthe_repository->repository_format_relative_worktrees =\n@@ -2042,7 +2066,8 @@ void check_repository_format(struct repository_format *fmt)\n \trepo_set_hash_algo(the_repository, fmt->hash_algo);\n \trepo_set_compat_hash_algo(the_repository, fmt->compat_hash_algo);\n \trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t fmt->ref_storage_format);\n+\t\t\t\t fmt->ref_storage_format,\n+\t\t\t\t fmt->ref_storage_payload);\n \tthe_repository->repository_format_worktree_config =\n \t\tfmt->worktree_config;\n \tthe_repository->repository_format_relative_worktrees =\n@@ -2643,7 +2668,8 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n-\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n+\t\t\t\t repo_fmt->ref_storage_payload);\n }\n \n int init_db(const char *git_dir, const char *real_git_dir,\ndiff --git a/setup.h b/setup.h\nindex ddb9f6701c..093af39e84 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -171,6 +171,7 @@ struct repository_format {\n \tint hash_algo;\n \tint compat_hash_algo;\n \tenum ref_storage_format ref_storage_format;\n+\tchar *ref_storage_payload;\n \tint sparse_index;\n \tchar *work_tree;\n \tstruct string_list unknown_extensions;\ndiff --git a/t/meson.build b/t/meson.build\nindex 459c52a489..11fc5a49ee 100644\n--- a/t/meson.build\n+++ b/t/meson.build\n@@ -210,6 +210,7 @@ integration_tests = [\n 't1420-lost-found.sh',\n 't1421-reflog-write.sh',\n 't1422-show-ref-exists.sh',\n+ 't1423-ref-backend.sh',\n 't1430-bad-ref-name.sh',\n 't1450-fsck.sh',\n 't1451-fsck-buffer.sh',\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nnew file mode 100755\nindex 0000000000..9912433b8c\n--- /dev/null\n+++ b/t/t1423-ref-backend.sh\n@@ -0,0 +1,159 @@\n+#!/bin/sh\n+\n+test_description='Test reference backend URIs'\n+\n+. ./test-lib.sh\n+\n+# Run a git command with the provided reference storage. Reset the backend\n+# post running the command.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# is the git subcommand to be run in the repository.\n+run_with_uri() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\tcmd=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1\n+\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\tgit -C \"$repo\" $cmd &&\n+\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+}\n+\n+# Test a repository with a given reference storage by running and comparing\n+# 'git refs list' before and after setting the new reference backend. If\n+# err_msg is set, expect the command to fail and grep for the provided err_msg.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n+test_refs_backend() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\terr_msg=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test -n \"$err_msg\";\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\ttest_grep \"$err_msg\" err\n+\telse\n+\t\tgit -C \"$repo\" refs list >expect &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\ttest_cmp expect actual\n+\tfi\n+}\n+\n+test_expect_success 'URI is invalid' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'URI ends with colon' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable:\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'unknown reference backend' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"db://.git\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+ref_formats=\"files reftable\"\n+for from_format in $ref_formats\n+do\n+\n+for to_format in $ref_formats\n+do\n+\tif test \"$from_format\" = \"$to_format\"\n+\tthen\n+\t\tcontinue\n+\tfi\n+\n+\n+\tfor dir in \"$(pwd)/repo/.git\" \".\"\n+\tdo\n+\n+\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit refs list >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\tgit refs list >actual &&\n+\t\t\t\ttest_cmp expect actual &&\n+\n+\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\tgit config set core.repositoryformatversion 1 &&\n+\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit worktree add ../wt 2\n+\t\t\t) &&\n+\n+\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n+\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n+\t\t\t! test_cmp expect actual &&\n+\n+\t\t\tgit -C wt rev-parse 2 >expect &&\n+\t\t\tgit -C wt rev-parse HEAD >actual &&\n+\t\t\ttest_cmp expect actual\n+\t\t'\n+\tdone # closes dir\n+done # closes to_format\n+done # closes from_format\n+\n+test_done\n\n-- \n2.52.0\n\n"},{"id":"536037","messageId":"20260214-kn-alternate-ref-dir-v6-6-86a82c77cf59@gmail.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com","subject":"[PATCH v6 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-14T22:34:19Z","receivedAt":"2026-02-14T22:34:36Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Git allows setting a different object directory via\n'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\nthe previous commit we extended the 'extensions.refStorage' config to\nalso support an URI input for reference backend with location.\n\nLet's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\ntakes in the same input as the config variable. Having an environment\nvariable allows us to modify the reference backend and location on the\nfly for individual Git commands.\n\nThe environment variable also allows usage of alternate reference\ndirectories during 'git-clone(1)' and 'git-init(1)'. Add the config to\nthe repository when created with the environment variable set.\n\nWhen initializing the repository with an alternate reference folder,\ncreate the required stubs in the repositories $GIT_DIR. The inverse,\ni.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\nsince that would render it unusable. Removal of ref store is only used\nwhen migrating between ref formats and cleanup of the $GIT_DIR doesn't\nmake sense in such a situation.\n\nHelped-by: Jean-Noël Avila \nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 5 ++\n environment.h | 1 +\n refs.c | 23 +++++---\n setup.c | 55 ++++++++++++++++-\n t/t1423-ref-backend.sh | 157 ++++++++++++++++++++++++++++++++++++++-----------\n 5 files changed, 198 insertions(+), 43 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..66442735ea 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n \trepositories will be set to this value. The default is \"files\".\n \tSee `--ref-format` in linkgit:git-init[1].\n \n+`GIT_REFERENCE_BACKEND`::\n+ Specify which reference backend to be used along with its URI.\n+ See `extensions.refStorage` option in linkgit:git-config[1] for more\n+ details. Overrides the config variable when used.\n+\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\ndiff --git a/environment.h b/environment.h\nindex 27f657af04..540e0a7f6d 100644\n--- a/environment.h\n+++ b/environment.h\n@@ -42,6 +42,7 @@\n #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n+#define GIT_REFERENCE_BACKEND_ENVIRONMENT \"GIT_REFERENCE_BACKEND\"\n \n /*\n * Environment variable used to propagate the --no-advice global option to the\ndiff --git a/refs.c b/refs.c\nindex 87ef54abd4..6b3883a325 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2192,16 +2192,21 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n {\n \tint ret = refs->be->create_on_disk(refs, flags, err);\n \n-\tif (!ret &&\n-\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n-\t\tstruct strbuf msg = STRBUF_INIT;\n-\n-\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n-\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n-\t\tstrbuf_release(&msg);\n+\tif (!ret) {\n+\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n+\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n+\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n+\t\t\t\t\t\t \"repository uses alternate refs storage\");\n+\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\t\tstruct strbuf msg = STRBUF_INIT;\n+\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n+\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n+\t\t\tstrbuf_release(&msg);\n+\t\t}\n \t}\n \n \treturn ret;\n+\n }\n \n int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n@@ -2216,6 +2221,10 @@ int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n \t\tif (format == REF_STORAGE_FORMAT_FILES)\n \t\t\treturn ret;\n \n+\t\t/* Alternate refs backend require stubs in the gitdir. */\n+\t\tif (refs->repo->ref_storage_payload)\n+\t\t\treturn ret;\n+\n \t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n \t\tif (unlink(sb.buf) < 0) {\n \t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\ndiff --git a/setup.c b/setup.c\nindex d407f3347b..90cb9be578 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -1838,6 +1838,7 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \tstatic struct strbuf cwd = STRBUF_INIT;\n \tstruct strbuf dir = STRBUF_INIT, gitdir = STRBUF_INIT, report = STRBUF_INIT;\n \tconst char *prefix = NULL;\n+\tconst char *ref_backend_uri;\n \tstruct repository_format repo_fmt = REPOSITORY_FORMAT_INIT;\n \n \t/*\n@@ -1995,6 +1996,25 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\tsetenv(GIT_PREFIX_ENVIRONMENT, \"\", 1);\n \t}\n \n+\t/*\n+\t * The env variable should override the repository config\n+\t * for 'extensions.refStorage'.\n+\t */\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *payload;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\t\trepo_set_ref_storage_format(the_repository, format, payload);\n+\n+\t\tfree(backend);\n+\t\tfree(payload);\n+\t}\n+\n \tsetup_original_cwd();\n \n \tstrbuf_release(&dir);\n@@ -2337,7 +2357,8 @@ void initialize_repository_version(int hash_algo,\n \t * the remote repository's format.\n \t */\n \tif (hash_algo != GIT_HASH_SHA1_LEGACY ||\n-\t ref_storage_format != REF_STORAGE_FORMAT_FILES)\n+\t ref_storage_format != REF_STORAGE_FORMAT_FILES ||\n+\t the_repository->ref_storage_payload)\n \t\ttarget_version = GIT_REPO_VERSION_READ;\n \n \tif (hash_algo != GIT_HASH_SHA1_LEGACY && hash_algo != GIT_HASH_UNKNOWN)\n@@ -2346,11 +2367,20 @@ void initialize_repository_version(int hash_algo,\n \telse if (reinit)\n \t\trepo_config_set_gently(the_repository, \"extensions.objectformat\", NULL);\n \n-\tif (ref_storage_format != REF_STORAGE_FORMAT_FILES)\n+\tif (the_repository->ref_storage_payload) {\n+\t\tstruct strbuf ref_uri = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&ref_uri, \"%s://%s\",\n+\t\t\t ref_storage_format_to_name(ref_storage_format),\n+\t\t\t the_repository->ref_storage_payload);\n+\t\trepo_config_set(the_repository, \"extensions.refstorage\", ref_uri.buf);\n+\t\tstrbuf_release(&ref_uri);\n+\t} else if (ref_storage_format != REF_STORAGE_FORMAT_FILES) {\n \t\trepo_config_set(the_repository, \"extensions.refstorage\",\n \t\t\t\tref_storage_format_to_name(ref_storage_format));\n-\telse if (reinit)\n+\t} else if (reinit) {\n \t\trepo_config_set_gently(the_repository, \"extensions.refstorage\", NULL);\n+\t}\n \n \tif (reinit) {\n \t\tstruct strbuf config = STRBUF_INIT;\n@@ -2623,6 +2653,7 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t\t.ignore_repo = 1,\n \t\t.ignore_worktree = 1,\n \t};\n+\tconst char *ref_backend_uri;\n \tconst char *env;\n \n \tconfig_with_options(read_default_format_config, &cfg, NULL, NULL, &opts);\n@@ -2668,6 +2699,24 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n+\n+\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *payload;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\n+\t\trepo_fmt->ref_storage_format = format;\n+\t\trepo_fmt->ref_storage_payload = payload;\n+\n+\t\tfree(backend);\n+\t}\n+\n \trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n \t\t\t\t repo_fmt->ref_storage_payload);\n }\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nindex 9912433b8c..b743c03a59 100755\n--- a/t/t1423-ref-backend.sh\n+++ b/t/t1423-ref-backend.sh\n@@ -11,16 +11,25 @@ test_description='Test reference backend URIs'\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n # is the git subcommand to be run in the repository.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n run_with_uri() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n \tcmd=$4 &&\n+\tvia=$5 &&\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1\n-\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\tgit -C \"$repo\" $cmd &&\n-\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test \"$via\" = \"env\"\n+\tthen\n+\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" git -C \"$repo\" $cmd\n+\telif test \"$via\" = \"config\"\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\tgit -C \"$repo\" $cmd &&\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tfi\n }\n \n # Test a repository with a given reference storage by running and comparing\n@@ -30,44 +39,57 @@ run_with_uri() {\n # is the relative path to the repo to run the command in.\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n # (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n test_refs_backend() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n-\terr_msg=$4 &&\n+\tvia=$4 &&\n+\terr_msg=$5 &&\n+\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n \tif test -n \"$err_msg\";\n \tthen\n-\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n-\t\ttest_grep \"$err_msg\" err\n+\t\tif test \"$via\" = \"env\"\n+\t\tthen\n+\t\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" test_must_fail git -C \"$repo\" refs list 2>err\n+\t\telif test \"$via\" = \"config\"\n+\t\tthen\n+\t\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\t\ttest_grep \"$err_msg\" err\n+\t\tfi\n \telse\n \t\tgit -C \"$repo\" refs list >expect &&\n-\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" \"$via\">actual &&\n \t\ttest_cmp expect actual\n \tfi\n }\n \n-test_expect_success 'URI is invalid' '\n+methods=\"config env\"\n+for method in $methods\n+do\n+\n+test_expect_success \"$method: URI is invalid\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'URI ends with colon' '\n+test_expect_success \"$method: URI ends with colon\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable:\" \\\n+\ttest_refs_backend repo files \"reftable:\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'unknown reference backend' '\n+test_expect_success \"$method: unknown reference backend\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"db://.git\" \\\n+\ttest_refs_backend repo files \"db://.git\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n@@ -86,7 +108,7 @@ do\n \tfor dir in \"$(pwd)/repo/.git\" \".\"\n \tdo\n \n-\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: read from $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -101,7 +123,7 @@ do\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: write to $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -113,20 +135,22 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\" &&\n \n \t\t\t\tgit refs list >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"tag -d 1\" \"$method\" &&\n \t\t\t\tgit refs list >actual &&\n \t\t\t\ttest_cmp expect actual &&\n \n \t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"refs list\" \"$method\" >actual &&\n \t\t\t\ttest_cmp expect actual\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: with worktree and $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo wt\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -138,22 +162,89 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\tgit config set core.repositoryformatversion 1 &&\n-\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n-\n-\t\t\t\tgit worktree add ../wt 2\n-\t\t\t) &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n \n-\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n-\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n-\t\t\t! test_cmp expect actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n+\t\t\t\t! test_cmp expect actual &&\n \n-\t\t\tgit -C wt rev-parse 2 >expect &&\n-\t\t\tgit -C wt rev-parse HEAD >actual &&\n-\t\t\ttest_cmp expect actual\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n \t\t'\n \tdone # closes dir\n+\n+\ttest_expect_success \"migrating repository to $to_format with alternate refs directory\" '\n+\t\ttest_when_finished \"rm -rf repo refdir\" &&\n+\t\tmkdir refdir &&\n+\t\tGIT_REFERENCE_BACKEND=\"${from_format}://$(pwd)/refdir\" git init repo &&\n+\t\t(\n+\t\t\tcd repo &&\n+\n+\t\t\ttest_commit 1 &&\n+\t\t\ttest_commit 2 &&\n+\t\t\ttest_commit 3 &&\n+\n+\t\t\tgit refs migrate --ref-format=$to_format &&\n+\t\t\tgit refs list >out &&\n+\t\t\ttest_grep \"refs/tags/1\"\tout &&\n+\t\t\ttest_grep \"refs/tags/2\"\tout &&\n+\t\t\ttest_grep \"refs/tags/3\"\tout\n+\t\t)\n+\t'\n+\n done # closes to_format\n done # closes from_format\n \n+done # closes method\n+\n+test_expect_success 'initializing repository with alt ref directory' '\n+\ttest_when_finished \"rm -rf repo refdir\" &&\n+\tmkdir refdir &&\n+\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n+\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n+\t(\n+\t\tcd repo &&\n+\n+\t\tgit config get extensions.refstorage >expect &&\n+\t\techo $BACKEND >actual &&\n+\t\ttest_cmp expect actual &&\n+\n+\t\ttest_commit 1 &&\n+\t\ttest_commit 2 &&\n+\t\ttest_commit 3 &&\n+\t\tgit refs list >out &&\n+\t\ttest_grep \"refs/tags/1\"\tout &&\n+\t\ttest_grep \"refs/tags/2\"\tout &&\n+\t\ttest_grep \"refs/tags/3\"\tout\n+\t)\n+'\n+\n+test_expect_success 'cloning repository with alt ref directory' '\n+\ttest_when_finished \"rm -rf source repo refdir\" &&\n+\tmkdir refdir &&\n+\n+\tgit init source &&\n+\ttest_commit -C source 1 &&\n+\ttest_commit -C source 2 &&\n+\ttest_commit -C source 3 &&\n+\n+\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n+\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n+\n+\tgit -C repo config get extensions.refstorage >expect &&\n+\techo $BACKEND >actual &&\n+\ttest_cmp expect actual &&\n+\n+\tgit -C source for-each-ref refs/tags/ >expect &&\n+\tgit -C repo for-each-ref refs/tags/ >actual &&\n+\ttest_cmp expect actual\n+'\n+\n test_done\n\n-- \n2.52.0\n\n"},{"id":"536050","messageId":"20260215091204.GA696020@coredump.intra.peff.net","threadId":"64513","inReplyTo":"CAOLa=ZQdYVO8wJxs_e-6FR7x_zOJnTNTwAVm1sHv23pnDYKnug@mail.gmail.com","subject":"Re: [PATCH v5 2/4] refs: forward and use the reference storage payload","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-02-15T09:12:04Z","receivedAt":"2026-02-15T09:12:06Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Feb 13, 2026 at 06:45:20AM -0800, Karthik Nayak wrote:\n\n> > BTW, is it possible to have a gitdir string without a slash in it? I\n> > guess not if it is absolute, but I didn't look at the caller to see if\n> > that is always true. Anyway, I wonder if we should be checking the\n> > result of strrchr() here.\n> \n> Since this is called during the ref store initialization and that value\n> is generally set via:\n> \n> 1. `repo->gitdir`: Which is resolved to an absolute path\n> 2. `repo->commondir`: Which is user input, can be without slash\n> 3. `worktree dir`: Should contain a slash\n> 4. `submodule dir`: Should contain a slash\n> 5. `refs migration dir`: Should contain a slash\n> \n> But even with this, Gits understanding of linked worktrees are that they\n> are in a `$gitdir/worktrees/$wt_id`. So it should be safe to do this.\n> Nevertheless, I'll add in a check.\n\nThanks. I figured it was something like that. Even a comment or a BUG()\nwould be more than enough, I'd think.\n\n-Peff\n"},{"id":"536145","messageId":"aZQXmvZbVT1eRtSH@pks.im","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-1-86a82c77cf59@gmail.com","subject":"Re: [PATCH v6 1/6] setup: don't modify repo in `create_reference_database()`","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-17T07:24:10Z","receivedAt":"2026-02-17T07:24:18Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Feb 14, 2026 at 11:34:14PM +0100, Karthik Nayak wrote:\n> The `create_reference_database()` function is used to create the\n> reference database during initialization of a repository. The function\n> calls `repo_set_ref_storage_format()` to set the repositories reference\n> format. This is an unexpected side-effect of the function. More so\n> because the function is only called in two locations:\n> \n> 1. During git-init(1) where the value is propagated from the `struct\n> repository_format repo_fmt` value.\n> \n> 2. During git-clone(1) where the value is propagated from the\n> `the_repository` value.\n> \n> The former is valid, however the flow already calls\n> `repo_set_ref_storage_format()`, so this effort is simply duplicated.\n> The latter sets the existing value in `the_repository` back to itself.\n> While this is okay for now, introduction of more fields in\n> `repo_set_ref_storage_format()` would cause issues, especially\n> dynamically allocated strings, where we would free/allocate the same\n> string back into `the_repostiory`.\n> \n> To avoid all this confusion, clean up the function to longer take in and\n\ns/longer/no &/, I assume?\n\n> diff --git a/builtin/clone.c b/builtin/clone.c\n> index b40cee5968..cd43bb5aa2 100644\n> --- a/builtin/clone.c\n> +++ b/builtin/clone.c\n> @@ -1442,7 +1442,7 @@ int cmd_clone(int argc,\n> \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n> \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n> \trepo_set_hash_algo(the_repository, hash_algo);\n> -\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n> +\tcreate_reference_database(NULL, 1);\n> \n> \t/*\n> \t * Before fetching from the remote, download and install bundle\n\nThis is case (2), where we set the ref storage format to itself.\n\n> diff --git a/setup.c b/setup.c\n> index b723f8b339..1fc9ae3872 100644\n> --- a/setup.c\n> +++ b/setup.c\n> @@ -2701,8 +2699,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n> \t\t\t\t &repo_fmt, init_shared_repository);\n> \n> \tif (!(flags & INIT_DB_SKIP_REFDB))\n> -\t\tcreate_reference_database(repo_fmt.ref_storage_format,\n> -\t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n> +\t\tcreate_reference_database(initial_branch, flags & INIT_DB_QUIET);\n> \tcreate_object_directory();\n> \n> \tif (repo_settings_get_shared_repository(the_repository)) {\n\nAnd this is the second case. We call `repository_format_configure()` a\nfew lines above, and that function calls `repo_set_ref_storage_format()`\nitself.\n\nLooks good to me, and a nice simplification. Thanks!\n\nPatrick\n"},{"id":"536146","messageId":"aZQXnwc_90cwPaZ6@pks.im","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-3-86a82c77cf59@gmail.com","subject":"Re: [PATCH v6 3/6] refs: receive and use the reference storage payload","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-17T07:24:15Z","receivedAt":"2026-02-17T07:24:20Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Feb 14, 2026 at 11:34:16PM +0100, Karthik Nayak wrote:\n> diff --git a/refs.c b/refs.c\n> index 77b93d655b..11d028232b 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -3425,3 +3426,40 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n> \t\treturn \"unknown failure\";\n> \t}\n> }\n> +\n> +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n> +\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n> +\t\t\t\t struct strbuf *ref_common_dir)\n> +{\n> +\tstruct strbuf sb = STRBUF_INIT;\n> +\n> +\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n> +\n> +\tif (!payload) {\n> +\t\t/*\n> +\t\t * We can use the 'gitdir' as the 'refdir' without appending the\n> +\t\t * worktree path, as the 'gitdir' here is already the worktree\n> +\t\t * path and is different from 'commondir' denoted by 'ref_common_dir'.\n> +\t\t */\n> +\t\tstrbuf_addstr(refdir, gitdir);\n> +\t\treturn;\n> +\t}\n> +\n> +\tif (!is_absolute_path(payload)) {\n> +\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n> +\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n> +\t} else {\n> +\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n> +\t}\n> +\n> +\tstrbuf_addbuf(refdir, ref_common_dir);\n> +\n> +\tif (*is_worktree) {\n> +\t\tconst char *wt_id = strrchr(gitdir, '/');\n> +\t\tif (!wt_id)\n> +\t\t\tBUG(\"worktree path does not contain slash \");\n\nThere's a trailing space in the error message here.\n\nPatrick\n"},{"id":"536147","messageId":"aZQXpb7RMW83eGxe@pks.im","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-4-86a82c77cf59@gmail.com","subject":"Re: [PATCH v6 4/6] refs: move out stub modification to generic layer","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-17T07:24:21Z","receivedAt":"2026-02-17T07:24:26Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Feb 14, 2026 at 11:34:17PM +0100, Karthik Nayak wrote:\n> When creating the reftable reference backend on disk, we create stubs to\n> ensure that the directory can be recognized as a Git repository. This is\n> done by calling `refs_create_refdir_stubs()`. Move this to the generic\n> layer as this is needed for all backends excluding from the files\n> backends. In an upcoming commit, we'll also need to extend this logic to\n> create stubs when using alternate reference directories.\n> \n> Similarly, move the logic for deletion of stubs to the generic layer.\n> The files backend recursively calls the remove function of the\n> 'packed-backend', here skip calling the generic function since that\n> would try to delete stubs.\n\nTiniest nit: it might make sense to reorder patches a bit so that the\ncreation of `refs_create_refdir_stubs()` and this patch here sit next to\neach other.\n\nWhat's missing a bit in the commit message is the motivation. What does\nthis step enable us to do that we couldn't do before?\n\n> diff --git a/refs.c b/refs.c\n> index 11d028232b..a24602c9bf 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -2190,12 +2190,59 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n> /* backend functions */\n> int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n> {\n> -\treturn refs->be->create_on_disk(refs, flags, err);\n> +\tint ret = refs->be->create_on_disk(refs, flags, err);\n> +\n> +\tif (!ret &&\n> +\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n> +\t\tstruct strbuf msg = STRBUF_INIT;\n> +\n> +\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n> +\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n> +\t\tstrbuf_release(&msg);\n> +\t}\n> +\n> +\treturn ret;\n> }\n\nThis makes me wonder: if we called `refs_create_refdir_stubs()` before\nwe call `->create_on_disk()`, could we even do it for the \"files\"\nbackend? Just a thought though.\n\n> int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n> {\n> -\treturn refs->be->remove_on_disk(refs, err);\n> +\tint ret = refs->be->remove_on_disk(refs, err);\n> +\n> +\tif (!ret) {\n> +\t\tenum ref_storage_format format = ref_storage_format_by_name(refs->be->name);\n> +\t\tstruct strbuf sb = STRBUF_INIT;\n> +\n> +\t\t/* Backends apart from the files backend create stubs. */\n> +\t\tif (format == REF_STORAGE_FORMAT_FILES)\n> +\t\t\treturn ret;\n\nFor symmetry it would be nice to not have an early return here, but also\nformat the condition for this block in the same way as we have it for\n`ref_store_create_on_disk()`.\n\nPatrick\n"},{"id":"536148","messageId":"aZQXrRuX3nsnuyEw@pks.im","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-6-86a82c77cf59@gmail.com","subject":"Re: [PATCH v6 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-17T07:24:29Z","receivedAt":"2026-02-17T07:24:34Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Feb 14, 2026 at 11:34:19PM +0100, Karthik Nayak wrote:\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\n> the previous commit we extended the 'extensions.refStorage' config to\n> also support an URI input for reference backend with location.\n> \n> Let's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\n> takes in the same input as the config variable. Having an environment\n> variable allows us to modify the reference backend and location on the\n> fly for individual Git commands.\n> \n> The environment variable also allows usage of alternate reference\n> directories during 'git-clone(1)' and 'git-init(1)'. Add the config to\n> the repository when created with the environment variable set.\n> \n> When initializing the repository with an alternate reference folder,\n> create the required stubs in the repositories $GIT_DIR. The inverse,\n> i.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\n> since that would render it unusable. Removal of ref store is only used\n> when migrating between ref formats and cleanup of the $GIT_DIR doesn't\n> make sense in such a situation.\n\nNice.\n\n> diff --git a/refs.c b/refs.c\n> index 87ef54abd4..6b3883a325 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -2192,16 +2192,21 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n> {\n> \tint ret = refs->be->create_on_disk(refs, flags, err);\n> \n> -\tif (!ret &&\n> -\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n> -\t\tstruct strbuf msg = STRBUF_INIT;\n> -\n> -\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n> -\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n> -\t\tstrbuf_release(&msg);\n> +\tif (!ret) {\n> +\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n> +\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n> +\t\t\t\t\t\t \"repository uses alternate refs storage\");\n> +\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n> +\t\t\tstruct strbuf msg = STRBUF_INIT;\n> +\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n> +\t\t\tstrbuf_release(&msg);\n> +\t\t}\n> \t}\n\nOkay, this here is the reason why you've moved the stub creation into\nthe generic parts. Makes sense.\n\n> \n> \treturn ret;\n> +\n> }\n\nThere's a stray newline here.\n\n> diff --git a/setup.c b/setup.c\n> index d407f3347b..90cb9be578 100644\n> --- a/setup.c\n> +++ b/setup.c\n> @@ -2337,7 +2357,8 @@ void initialize_repository_version(int hash_algo,\n> \t * the remote repository's format.\n> \t */\n> \tif (hash_algo != GIT_HASH_SHA1_LEGACY ||\n> -\t ref_storage_format != REF_STORAGE_FORMAT_FILES)\n> +\t ref_storage_format != REF_STORAGE_FORMAT_FILES ||\n> +\t the_repository->ref_storage_payload)\n> \t\ttarget_version = GIT_REPO_VERSION_READ;\n> \n> \tif (hash_algo != GIT_HASH_SHA1_LEGACY && hash_algo != GIT_HASH_UNKNOWN)\n\nRight. If we've got a payload during init we know that we must use the\nrepository extension. Makes sense.\n\n> @@ -2346,11 +2367,20 @@ void initialize_repository_version(int hash_algo,\n> \telse if (reinit)\n> \t\trepo_config_set_gently(the_repository, \"extensions.objectformat\", NULL);\n> \n> -\tif (ref_storage_format != REF_STORAGE_FORMAT_FILES)\n> +\tif (the_repository->ref_storage_payload) {\n> +\t\tstruct strbuf ref_uri = STRBUF_INIT;\n> +\n> +\t\tstrbuf_addf(&ref_uri, \"%s://%s\",\n> +\t\t\t ref_storage_format_to_name(ref_storage_format),\n> +\t\t\t the_repository->ref_storage_payload);\n> +\t\trepo_config_set(the_repository, \"extensions.refstorage\", ref_uri.buf);\n> +\t\tstrbuf_release(&ref_uri);\n> +\t} else if (ref_storage_format != REF_STORAGE_FORMAT_FILES) {\n> \t\trepo_config_set(the_repository, \"extensions.refstorage\",\n> \t\t\t\tref_storage_format_to_name(ref_storage_format));\n> -\telse if (reinit)\n> +\t} else if (reinit) {\n> \t\trepo_config_set_gently(the_repository, \"extensions.refstorage\", NULL);\n> +\t}\n> \n> \tif (reinit) {\n> \t\tstruct strbuf config = STRBUF_INIT;\n\nAnd here we write the payload into the configuration, if we've got one.\n\n> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n> index 9912433b8c..b743c03a59 100755\n> --- a/t/t1423-ref-backend.sh\n> +++ b/t/t1423-ref-backend.sh\n[snip]\n> +test_expect_success 'initializing repository with alt ref directory' '\n> +\ttest_when_finished \"rm -rf repo refdir\" &&\n> +\tmkdir refdir &&\n> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n> +\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n> +\t(\n> +\t\tcd repo &&\n> +\n> +\t\tgit config get extensions.refstorage >expect &&\n> +\t\techo $BACKEND >actual &&\n> +\t\ttest_cmp expect actual &&\n> +\n> +\t\ttest_commit 1 &&\n> +\t\ttest_commit 2 &&\n> +\t\ttest_commit 3 &&\n> +\t\tgit refs list >out &&\n> +\t\ttest_grep \"refs/tags/1\"\tout &&\n> +\t\ttest_grep \"refs/tags/2\"\tout &&\n> +\t\ttest_grep \"refs/tags/3\"\tout\n> +\t)\n> +'\n\nShould we also verify that the refdir contains the data and that the\nrepository only contains stubs?\n\n> +test_expect_success 'cloning repository with alt ref directory' '\n> +\ttest_when_finished \"rm -rf source repo refdir\" &&\n> +\tmkdir refdir &&\n> +\n> +\tgit init source &&\n> +\ttest_commit -C source 1 &&\n> +\ttest_commit -C source 2 &&\n> +\ttest_commit -C source 3 &&\n> +\n> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n> +\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n> +\n> +\tgit -C repo config get extensions.refstorage >expect &&\n> +\techo $BACKEND >actual &&\n> +\ttest_cmp expect actual &&\n> +\n> +\tgit -C source for-each-ref refs/tags/ >expect &&\n> +\tgit -C repo for-each-ref refs/tags/ >actual &&\n> +\ttest_cmp expect actual\n> +'\n> +\n\nSame question here.\n\nThanks!\n\nPatrick\n"},{"id":"536159","messageId":"CAOLa=ZSo-2uG5dctTJAww9Qg+1a85+PJ_Fx7_AggbjLsTxD6Lw@mail.gmail.com","threadId":"64513","inReplyTo":"aZQXmvZbVT1eRtSH@pks.im","subject":"Re: [PATCH v6 1/6] setup: don't modify repo in `create_reference_database()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-17T09:15:40Z","receivedAt":"2026-02-17T09:15:41Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Sat, Feb 14, 2026 at 11:34:14PM +0100, Karthik Nayak wrote:\n>> The `create_reference_database()` function is used to create the\n>> reference database during initialization of a repository. The function\n>> calls `repo_set_ref_storage_format()` to set the repositories reference\n>> format. This is an unexpected side-effect of the function. More so\n>> because the function is only called in two locations:\n>>\n>> 1. During git-init(1) where the value is propagated from the `struct\n>> repository_format repo_fmt` value.\n>>\n>> 2. During git-clone(1) where the value is propagated from the\n>> `the_repository` value.\n>>\n>> The former is valid, however the flow already calls\n>> `repo_set_ref_storage_format()`, so this effort is simply duplicated.\n>> The latter sets the existing value in `the_repository` back to itself.\n>> While this is okay for now, introduction of more fields in\n>> `repo_set_ref_storage_format()` would cause issues, especially\n>> dynamically allocated strings, where we would free/allocate the same\n>> string back into `the_repostiory`.\n>>\n>> To avoid all this confusion, clean up the function to longer take in and\n>\n> s/longer/no &/, I assume?\n>\n\nYup.\n\n>> diff --git a/builtin/clone.c b/builtin/clone.c\n>> index b40cee5968..cd43bb5aa2 100644\n>> --- a/builtin/clone.c\n>> +++ b/builtin/clone.c\n>> @@ -1442,7 +1442,7 @@ int cmd_clone(int argc,\n>> \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n>> \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n>> \trepo_set_hash_algo(the_repository, hash_algo);\n>> -\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n>> +\tcreate_reference_database(NULL, 1);\n>>\n>> \t/*\n>> \t * Before fetching from the remote, download and install bundle\n>\n> This is case (2), where we set the ref storage format to itself.\n>\n>> diff --git a/setup.c b/setup.c\n>> index b723f8b339..1fc9ae3872 100644\n>> --- a/setup.c\n>> +++ b/setup.c\n>> @@ -2701,8 +2699,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n>> \t\t\t\t &repo_fmt, init_shared_repository);\n>>\n>> \tif (!(flags & INIT_DB_SKIP_REFDB))\n>> -\t\tcreate_reference_database(repo_fmt.ref_storage_format,\n>> -\t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n>> +\t\tcreate_reference_database(initial_branch, flags & INIT_DB_QUIET);\n>> \tcreate_object_directory();\n>>\n>> \tif (repo_settings_get_shared_repository(the_repository)) {\n>\n> And this is the second case. We call `repository_format_configure()` a\n> few lines above, and that function calls `repo_set_ref_storage_format()`\n> itself.\n>\n> Looks good to me, and a nice simplification. Thanks!\n>\n> Patrick\n\nThanks!\n"},{"id":"536160","messageId":"CAOLa=ZRxFBy3cbTxbnAVWM7cbAt1duVKkXN4wmi+r+XLaOfU6Q@mail.gmail.com","threadId":"64513","inReplyTo":"aZQXnwc_90cwPaZ6@pks.im","subject":"Re: [PATCH v6 3/6] refs: receive and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-17T09:16:21Z","receivedAt":"2026-02-17T09:16:23Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Sat, Feb 14, 2026 at 11:34:16PM +0100, Karthik Nayak wrote:\n>> diff --git a/refs.c b/refs.c\n>> index 77b93d655b..11d028232b 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -3425,3 +3426,40 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n>> \t\treturn \"unknown failure\";\n>> \t}\n>> }\n>> +\n>> +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n>> +\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n>> +\t\t\t\t struct strbuf *ref_common_dir)\n>> +{\n>> +\tstruct strbuf sb = STRBUF_INIT;\n>> +\n>> +\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n>> +\n>> +\tif (!payload) {\n>> +\t\t/*\n>> +\t\t * We can use the 'gitdir' as the 'refdir' without appending the\n>> +\t\t * worktree path, as the 'gitdir' here is already the worktree\n>> +\t\t * path and is different from 'commondir' denoted by 'ref_common_dir'.\n>> +\t\t */\n>> +\t\tstrbuf_addstr(refdir, gitdir);\n>> +\t\treturn;\n>> +\t}\n>> +\n>> +\tif (!is_absolute_path(payload)) {\n>> +\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n>> +\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n>> +\t} else {\n>> +\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n>> +\t}\n>> +\n>> +\tstrbuf_addbuf(refdir, ref_common_dir);\n>> +\n>> +\tif (*is_worktree) {\n>> +\t\tconst char *wt_id = strrchr(gitdir, '/');\n>> +\t\tif (!wt_id)\n>> +\t\t\tBUG(\"worktree path does not contain slash \");\n>\n> There's a trailing space in the error message here.\n>\n> Patrick\n\nOops, will fix.\n"},{"id":"536163","messageId":"CAOLa=ZQwrOGpZfVtfTfPFhnkJ_qnEhv8mxO3Ot7nQXusbkJkYw@mail.gmail.com","threadId":"64513","inReplyTo":"aZQXpb7RMW83eGxe@pks.im","subject":"Re: [PATCH v6 4/6] refs: move out stub modification to generic layer","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-17T09:29:31Z","receivedAt":"2026-02-17T09:29:33Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Sat, Feb 14, 2026 at 11:34:17PM +0100, Karthik Nayak wrote:\n>> When creating the reftable reference backend on disk, we create stubs to\n>> ensure that the directory can be recognized as a Git repository. This is\n>> done by calling `refs_create_refdir_stubs()`. Move this to the generic\n>> layer as this is needed for all backends excluding from the files\n>> backends. In an upcoming commit, we'll also need to extend this logic to\n>> create stubs when using alternate reference directories.\n>>\n>> Similarly, move the logic for deletion of stubs to the generic layer.\n>> The files backend recursively calls the remove function of the\n>> 'packed-backend', here skip calling the generic function since that\n>> would try to delete stubs.\n>\n> Tiniest nit: it might make sense to reorder patches a bit so that the\n> creation of `refs_create_refdir_stubs()` and this patch here sit next to\n> each other.\n>\n\nI think that would be nice, let me do that.\n\n> What's missing a bit in the commit message is the motivation. What does\n> this step enable us to do that we couldn't do before?\n>\n\nI did add a line\n\n In an upcoming commit, we'll also need to extend this logic to create\n stubs when using alternate reference directories.\n\nI'll expand a little on that.\n\n>> diff --git a/refs.c b/refs.c\n>> index 11d028232b..a24602c9bf 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -2190,12 +2190,59 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n>> /* backend functions */\n>> int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n>> {\n>> -\treturn refs->be->create_on_disk(refs, flags, err);\n>> +\tint ret = refs->be->create_on_disk(refs, flags, err);\n>> +\n>> +\tif (!ret &&\n>> +\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>> +\t\tstruct strbuf msg = STRBUF_INIT;\n>> +\n>> +\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>> +\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>> +\t\tstrbuf_release(&msg);\n>> +\t}\n>> +\n>> +\treturn ret;\n>> }\n>\n> This makes me wonder: if we called `refs_create_refdir_stubs()` before\n> we call `->create_on_disk()`, could we even do it for the \"files\"\n> backend? Just a thought though.\n>\n\nWell, there is some nuance there\n\n1. 'refs/heads', 'refs/tags' is not created for linked worktrees.\n2. 'HEAD' is only created lazily, not in `create_on_disk()`.\n\nAlso the intent is totally different, the stubs are for backward\ncompatibility. So I think its better to let that logic stay within the\nfiles-backend.\n\n>> int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n>> {\n>> -\treturn refs->be->remove_on_disk(refs, err);\n>> +\tint ret = refs->be->remove_on_disk(refs, err);\n>> +\n>> +\tif (!ret) {\n>> +\t\tenum ref_storage_format format = ref_storage_format_by_name(refs->be->name);\n>> +\t\tstruct strbuf sb = STRBUF_INIT;\n>> +\n>> +\t\t/* Backends apart from the files backend create stubs. */\n>> +\t\tif (format == REF_STORAGE_FORMAT_FILES)\n>> +\t\t\treturn ret;\n>\n> For symmetry it would be nice to not have an early return here, but also\n> format the condition for this block in the same way as we have it for\n> `ref_store_create_on_disk()`.\n>\n> Patrick\n\nYeah sure, we can do that here, in the last commit, we'll have to modify\nthat anyway back to something like this. But it definitely would be\neasier to review this commit. Will add.\n"},{"id":"536164","messageId":"CAOLa=ZQFOLh6ixB4=ukPS44uE9k3-1Zw1U2bCYf+TsKyHEqLiA@mail.gmail.com","threadId":"64513","inReplyTo":"aZQXrRuX3nsnuyEw@pks.im","subject":"Re: [PATCH v6 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-17T09:32:56Z","receivedAt":"2026-02-17T09:32:58Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n>> diff --git a/refs.c b/refs.c\n>> index 87ef54abd4..6b3883a325 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -2192,16 +2192,21 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n>> {\n>> \tint ret = refs->be->create_on_disk(refs, flags, err);\n>>\n>> -\tif (!ret &&\n>> -\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>> -\t\tstruct strbuf msg = STRBUF_INIT;\n>> -\n>> -\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>> -\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>> -\t\tstrbuf_release(&msg);\n>> +\tif (!ret) {\n>> +\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n>> +\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n>> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n>> +\t\t\t\t\t\t \"repository uses alternate refs storage\");\n>> +\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>> +\t\t\tstruct strbuf msg = STRBUF_INIT;\n>> +\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>> +\t\t\tstrbuf_release(&msg);\n>> +\t\t}\n>> \t}\n>\n> Okay, this here is the reason why you've moved the stub creation into\n> the generic parts. Makes sense.\n>\n>>\n>> \treturn ret;\n>> +\n>> }\n>\n> There's a stray newline here.\n>\n\nWill fix.\n\n[snip]\n\n>> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n>> index 9912433b8c..b743c03a59 100755\n>> --- a/t/t1423-ref-backend.sh\n>> +++ b/t/t1423-ref-backend.sh\n> [snip]\n>> +test_expect_success 'initializing repository with alt ref directory' '\n>> +\ttest_when_finished \"rm -rf repo refdir\" &&\n>> +\tmkdir refdir &&\n>> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n>> +\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n>> +\t(\n>> +\t\tcd repo &&\n>> +\n>> +\t\tgit config get extensions.refstorage >expect &&\n>> +\t\techo $BACKEND >actual &&\n>> +\t\ttest_cmp expect actual &&\n>> +\n>> +\t\ttest_commit 1 &&\n>> +\t\ttest_commit 2 &&\n>> +\t\ttest_commit 3 &&\n>> +\t\tgit refs list >out &&\n>> +\t\ttest_grep \"refs/tags/1\"\tout &&\n>> +\t\ttest_grep \"refs/tags/2\"\tout &&\n>> +\t\ttest_grep \"refs/tags/3\"\tout\n>> +\t)\n>> +'\n>\n> Should we also verify that the refdir contains the data and that the\n> repository only contains stubs?\n>\n>> +test_expect_success 'cloning repository with alt ref directory' '\n>> +\ttest_when_finished \"rm -rf source repo refdir\" &&\n>> +\tmkdir refdir &&\n>> +\n>> +\tgit init source &&\n>> +\ttest_commit -C source 1 &&\n>> +\ttest_commit -C source 2 &&\n>> +\ttest_commit -C source 3 &&\n>> +\n>> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n>> +\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n>> +\n>> +\tgit -C repo config get extensions.refstorage >expect &&\n>> +\techo $BACKEND >actual &&\n>> +\ttest_cmp expect actual &&\n>> +\n>> +\tgit -C source for-each-ref refs/tags/ >expect &&\n>> +\tgit -C repo for-each-ref refs/tags/ >actual &&\n>> +\ttest_cmp expect actual\n>> +'\n>> +\n>\n> Same question here.\n>\n> Thanks!\n>\n> Patrick\n\nWe can verify that the repository only contains stubs, but to verify\nthat the refdir contains the data, we'd have to add backend specific\nlogic, I'm not sure that is the way to go.\n"},{"id":"536167","messageId":"aZQ_0CaQG4Hhceby@pks.im","threadId":"64513","inReplyTo":"CAOLa=ZQFOLh6ixB4=ukPS44uE9k3-1Zw1U2bCYf+TsKyHEqLiA@mail.gmail.com","subject":"Re: [PATCH v6 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-17T10:15:44Z","receivedAt":"2026-02-17T10:15:52Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Feb 17, 2026 at 03:32:56AM -0600, Karthik Nayak wrote:\n> Patrick Steinhardt writes:\n> >> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n> >> index 9912433b8c..b743c03a59 100755\n> >> --- a/t/t1423-ref-backend.sh\n> >> +++ b/t/t1423-ref-backend.sh\n> > [snip]\n> >> +test_expect_success 'initializing repository with alt ref directory' '\n> >> +\ttest_when_finished \"rm -rf repo refdir\" &&\n> >> +\tmkdir refdir &&\n> >> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n> >> +\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n> >> +\t(\n> >> +\t\tcd repo &&\n> >> +\n> >> +\t\tgit config get extensions.refstorage >expect &&\n> >> +\t\techo $BACKEND >actual &&\n> >> +\t\ttest_cmp expect actual &&\n> >> +\n> >> +\t\ttest_commit 1 &&\n> >> +\t\ttest_commit 2 &&\n> >> +\t\ttest_commit 3 &&\n> >> +\t\tgit refs list >out &&\n> >> +\t\ttest_grep \"refs/tags/1\"\tout &&\n> >> +\t\ttest_grep \"refs/tags/2\"\tout &&\n> >> +\t\ttest_grep \"refs/tags/3\"\tout\n> >> +\t)\n> >> +'\n> >\n> > Should we also verify that the refdir contains the data and that the\n> > repository only contains stubs?\n> >\n> >> +test_expect_success 'cloning repository with alt ref directory' '\n> >> +\ttest_when_finished \"rm -rf source repo refdir\" &&\n> >> +\tmkdir refdir &&\n> >> +\n> >> +\tgit init source &&\n> >> +\ttest_commit -C source 1 &&\n> >> +\ttest_commit -C source 2 &&\n> >> +\ttest_commit -C source 3 &&\n> >> +\n> >> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n> >> +\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n> >> +\n> >> +\tgit -C repo config get extensions.refstorage >expect &&\n> >> +\techo $BACKEND >actual &&\n> >> +\ttest_cmp expect actual &&\n> >> +\n> >> +\tgit -C source for-each-ref refs/tags/ >expect &&\n> >> +\tgit -C repo for-each-ref refs/tags/ >actual &&\n> >> +\ttest_cmp expect actual\n> >> +'\n> >> +\n> >\n> > Same question here.\n> >\n> > Thanks!\n> >\n> > Patrick\n> \n> We can verify that the repository only contains stubs, but to verify\n> that the refdir contains the data, we'd have to add backend specific\n> logic, I'm not sure that is the way to go.\n\nI mean all of this very much is backend-specific, but I think that it's\nsensible to at least verify some of the basics here. Otherwise it might\nsilently do the wrong thing, and we'd never notice because we haven't\nbeen testing for it.\n\nPatrick\n"},{"id":"536292","messageId":"87o6lmceup.fsf@iotcl.com","threadId":"64513","inReplyTo":"CAOLa=ZQwrOGpZfVtfTfPFhnkJ_qnEhv8mxO3Ot7nQXusbkJkYw@mail.gmail.com","subject":"Re: [PATCH v6 4/6] refs: move out stub modification to generic layer","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-02-18T14:21:02Z","receivedAt":"2026-02-18T14:21:18Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Karthik Nayak writes:\n\n> Patrick Steinhardt writes:\n>\n>> On Sat, Feb 14, 2026 at 11:34:17PM +0100, Karthik Nayak wrote:\n>>> When creating the reftable reference backend on disk, we create stubs to\n>>> ensure that the directory can be recognized as a Git repository. This is\n>>> done by calling `refs_create_refdir_stubs()`. Move this to the generic\n>>> layer as this is needed for all backends excluding from the files\n>>> backends. In an upcoming commit, we'll also need to extend this logic to\n>>> create stubs when using alternate reference directories.\n>>>\n>>> Similarly, move the logic for deletion of stubs to the generic layer.\n>>> The files backend recursively calls the remove function of the\n>>> 'packed-backend', here skip calling the generic function since that\n>>> would try to delete stubs.\n>>\n>> Tiniest nit: it might make sense to reorder patches a bit so that the\n>> creation of `refs_create_refdir_stubs()` and this patch here sit next to\n>> each other.\n>>\n>\n> I think that would be nice, let me do that.\n\nThanks, I was thinking the same, but I wasn't going to comment on that.\nHappy to see you've agreed on this already.\n\n>> What's missing a bit in the commit message is the motivation. What does\n>> this step enable us to do that we couldn't do before?\n>>\n>\n> I did add a line\n>\n> In an upcoming commit, we'll also need to extend this logic to create\n> stubs when using alternate reference directories.\n>\n> I'll expand a little on that.\n\n<3\n\n>>> diff --git a/refs.c b/refs.c\n>>> index 11d028232b..a24602c9bf 100644\n>>> --- a/refs.c\n>>> +++ b/refs.c\n>>> @@ -2190,12 +2190,59 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n>>> /* backend functions */\n>>> int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n>>> {\n>>> -\treturn refs->be->create_on_disk(refs, flags, err);\n>>> +\tint ret = refs->be->create_on_disk(refs, flags, err);\n>>> +\n>>> +\tif (!ret &&\n>>> +\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>>> +\t\tstruct strbuf msg = STRBUF_INIT;\n>>> +\n>>> +\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>>> +\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>>> +\t\tstrbuf_release(&msg);\n>>> +\t}\n>>> +\n>>> +\treturn ret;\n>>> }\n>>\n>> This makes me wonder: if we called `refs_create_refdir_stubs()` before\n>> we call `->create_on_disk()`, could we even do it for the \"files\"\n>> backend? Just a thought though.\n>>\n>\n> Well, there is some nuance there\n>\n> 1. 'refs/heads', 'refs/tags' is not created for linked worktrees.\n\nI'm a little bit confused what you mean here? Would it be a problem if\nit *is* created?\n\n> 2. 'HEAD' is only created lazily, not in `create_on_disk()`.\n\nOkay, seems like a valid argument to me. You don't want to have\n`refs/HEAD` created with `ref: refs/heads/.invalid`?\n\n> Also the intent is totally different, the stubs are for backward\n> compatibility. So I think its better to let that logic stay within the\n> files-backend.\n\nThat's mainly because you named the function like this, but it doesn't\nhave to be named like that.\n\n>> For symmetry it would be nice to not have an early return here, but also\n>> format the condition for this block in the same way as we have it for\n>> `ref_store_create_on_disk()`.\n>>\n>> Patrick\n>\n> Yeah sure, we can do that here, in the last commit, we'll have to modify\n> that anyway back to something like this. But it definitely would be\n> easier to review this commit. Will add.\n\n:+1:\n\n-- \nCheers,\nToon\n"},{"id":"536300","messageId":"87jywacbrj.fsf@iotcl.com","threadId":"64513","inReplyTo":"20260214-kn-alternate-ref-dir-v6-6-86a82c77cf59@gmail.com","subject":"Re: [PATCH v6 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-02-18T15:27:44Z","receivedAt":"2026-02-18T15:27:58Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Karthik Nayak writes:\n\n> Git allows setting a different object directory via\n> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\n> the previous commit we extended the 'extensions.refStorage' config to\n> also support an URI input for reference backend with location.\n>\n> Let's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\n> takes in the same input as the config variable. Having an environment\n> variable allows us to modify the reference backend and location on the\n> fly for individual Git commands.\n>\n> The environment variable also allows usage of alternate reference\n> directories during 'git-clone(1)' and 'git-init(1)'. Add the config to\n> the repository when created with the environment variable set.\n>\n> When initializing the repository with an alternate reference folder,\n> create the required stubs in the repositories $GIT_DIR. The inverse,\n> i.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\n> since that would render it unusable. Removal of ref store is only used\n> when migrating between ref formats and cleanup of the $GIT_DIR doesn't\n> make sense in such a situation.\n>\n> Helped-by: Jean-Noël Avila \n> Signed-off-by: Karthik Nayak \n> ---\n> Documentation/git.adoc | 5 ++\n> environment.h | 1 +\n> refs.c | 23 +++++---\n> setup.c | 55 ++++++++++++++++-\n> t/t1423-ref-backend.sh | 157 ++++++++++++++++++++++++++++++++++++++-----------\n> 5 files changed, 198 insertions(+), 43 deletions(-)\n>\n> [snip]\n>\n> diff --git a/refs.c b/refs.c\n> index 87ef54abd4..6b3883a325 100644\n> --- a/refs.c\n> +++ b/refs.c\n> @@ -2192,16 +2192,21 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n> {\n> \tint ret = refs->be->create_on_disk(refs, flags, err);\n> \n> -\tif (!ret &&\n> -\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n> -\t\tstruct strbuf msg = STRBUF_INIT;\n> -\n> -\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n> -\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n> -\t\tstrbuf_release(&msg);\n> +\tif (!ret) {\n> +\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n> +\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n> +\t\t\t\t\t\t \"repository uses alternate refs storage\");\n> +\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n> +\t\t\tstruct strbuf msg = STRBUF_INIT;\n> +\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n> +\t\t\tstrbuf_release(&msg);\n> +\t\t}\n> \t}\n> \n> \treturn ret;\n> +\n> }\n> \n> int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n> @@ -2216,6 +2221,10 @@ int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n> \t\tif (format == REF_STORAGE_FORMAT_FILES)\n> \t\t\treturn ret;\n> \n> +\t\t/* Alternate refs backend require stubs in the gitdir. */\n\nI find this comment rather confusing, you say \"require stubs\" and you do\nan early return. I had to read it more than once to understand. What do\nyou think about:\n\n +\t\t/* No stubs required in the alternate refs backend,\n +\t\t * stubs only should be created in the gitdir. */\n\n> +\t\tif (refs->repo->ref_storage_payload)\n> +\t\t\treturn ret;\n> +\n\n-- \nCheers,\nToon\n"},{"id":"536382","messageId":"CAOLa=ZQqbppCi12jUdCBQAggAEPZvLz3oB0Wp6+VMv4Tb4znbw@mail.gmail.com","threadId":"64513","inReplyTo":"87o6lmceup.fsf@iotcl.com","subject":"Re: [PATCH v6 4/6] refs: move out stub modification to generic layer","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-19T09:31:21Z","receivedAt":"2026-02-19T09:31:24Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Toon Claes writes:\n\n> Karthik Nayak writes:\n>\n>> Patrick Steinhardt writes:\n>>\n>>> On Sat, Feb 14, 2026 at 11:34:17PM +0100, Karthik Nayak wrote:\n>>>> When creating the reftable reference backend on disk, we create stubs to\n>>>> ensure that the directory can be recognized as a Git repository. This is\n>>>> done by calling `refs_create_refdir_stubs()`. Move this to the generic\n>>>> layer as this is needed for all backends excluding from the files\n>>>> backends. In an upcoming commit, we'll also need to extend this logic to\n>>>> create stubs when using alternate reference directories.\n>>>>\n>>>> Similarly, move the logic for deletion of stubs to the generic layer.\n>>>> The files backend recursively calls the remove function of the\n>>>> 'packed-backend', here skip calling the generic function since that\n>>>> would try to delete stubs.\n>>>\n>>> Tiniest nit: it might make sense to reorder patches a bit so that the\n>>> creation of `refs_create_refdir_stubs()` and this patch here sit next to\n>>> each other.\n>>>\n>>\n>> I think that would be nice, let me do that.\n>\n> Thanks, I was thinking the same, but I wasn't going to comment on that.\n> Happy to see you've agreed on this already.\n>\n>>> What's missing a bit in the commit message is the motivation. What does\n>>> this step enable us to do that we couldn't do before?\n>>>\n>>\n>> I did add a line\n>>\n>> In an upcoming commit, we'll also need to extend this logic to create\n>> stubs when using alternate reference directories.\n>>\n>> I'll expand a little on that.\n>\n> <3\n>\n>>>> diff --git a/refs.c b/refs.c\n>>>> index 11d028232b..a24602c9bf 100644\n>>>> --- a/refs.c\n>>>> +++ b/refs.c\n>>>> @@ -2190,12 +2190,59 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n>>>> /* backend functions */\n>>>> int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n>>>> {\n>>>> -\treturn refs->be->create_on_disk(refs, flags, err);\n>>>> +\tint ret = refs->be->create_on_disk(refs, flags, err);\n>>>> +\n>>>> +\tif (!ret &&\n>>>> +\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>>>> +\t\tstruct strbuf msg = STRBUF_INIT;\n>>>> +\n>>>> +\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>>>> +\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>>>> +\t\tstrbuf_release(&msg);\n>>>> +\t}\n>>>> +\n>>>> +\treturn ret;\n>>>> }\n>>>\n>>> This makes me wonder: if we called `refs_create_refdir_stubs()` before\n>>> we call `->create_on_disk()`, could we even do it for the \"files\"\n>>> backend? Just a thought though.\n>>>\n>>\n>> Well, there is some nuance there\n>>\n>> 1. 'refs/heads', 'refs/tags' is not created for linked worktrees.\n>\n> I'm a little bit confused what you mean here? Would it be a problem if\n> it *is* created?\n>\n\nShouldn't be a problem, but I'd rather not create something which isn't\nneeded.\n\n>> 2. 'HEAD' is only created lazily, not in `create_on_disk()`.\n>\n> Okay, seems like a valid argument to me. You don't want to have\n> `refs/HEAD` created with `ref: refs/heads/.invalid`?\n>\n\nWe could override it when the actual HEAD ref is created.\n\n>> Also the intent is totally different, the stubs are for backward\n>> compatibility. So I think its better to let that logic stay within the\n>> files-backend.\n>\n> That's mainly because you named the function like this, but it doesn't\n> have to be named like that.\n>\n\nNot really... The difference being that the files backend creates these\nfiles/folders among others since it needs it for its operation.\n\nThe other backends create the bare minimum files and folder stubs\nbecause we need to stay backward compatible and ensure the Git folder is\nstill treated.\n\nI didn't want to mix up that because we could decide to change things in\nthe files backend, but we can't change how the stubs are created. But I\ndo agree that we could potentially combine this and allow the files\nbackend to override it. I don't think I want to get into that in this\npatch series.\n\n>>> For symmetry it would be nice to not have an early return here, but also\n>>> format the condition for this block in the same way as we have it for\n>>> `ref_store_create_on_disk()`.\n>>>\n>>> Patrick\n>>\n>> Yeah sure, we can do that here, in the last commit, we'll have to modify\n>> that anyway back to something like this. But it definitely would be\n>> easier to review this commit. Will add.\n>\n> :+1:\n>\n> --\n> Cheers,\n> Toon\n"},{"id":"536383","messageId":"CAOLa=ZTs-pxqagQxMBB8xajhfEnvhn8i2uOm2EPD187TopCCxA@mail.gmail.com","threadId":"64513","inReplyTo":"87jywacbrj.fsf@iotcl.com","subject":"Re: [PATCH v6 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-19T09:35:25Z","receivedAt":"2026-02-19T09:35:27Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Toon Claes writes:\n\n> Karthik Nayak writes:\n>\n>> Git allows setting a different object directory via\n>> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\n>> the previous commit we extended the 'extensions.refStorage' config to\n>> also support an URI input for reference backend with location.\n>>\n>> Let's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\n>> takes in the same input as the config variable. Having an environment\n>> variable allows us to modify the reference backend and location on the\n>> fly for individual Git commands.\n>>\n>> The environment variable also allows usage of alternate reference\n>> directories during 'git-clone(1)' and 'git-init(1)'. Add the config to\n>> the repository when created with the environment variable set.\n>>\n>> When initializing the repository with an alternate reference folder,\n>> create the required stubs in the repositories $GIT_DIR. The inverse,\n>> i.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\n>> since that would render it unusable. Removal of ref store is only used\n>> when migrating between ref formats and cleanup of the $GIT_DIR doesn't\n>> make sense in such a situation.\n>>\n>> Helped-by: Jean-Noël Avila \n>> Signed-off-by: Karthik Nayak \n>> ---\n>> Documentation/git.adoc | 5 ++\n>> environment.h | 1 +\n>> refs.c | 23 +++++---\n>> setup.c | 55 ++++++++++++++++-\n>> t/t1423-ref-backend.sh | 157 ++++++++++++++++++++++++++++++++++++++-----------\n>> 5 files changed, 198 insertions(+), 43 deletions(-)\n>>\n>> [snip]\n>>\n>> diff --git a/refs.c b/refs.c\n>> index 87ef54abd4..6b3883a325 100644\n>> --- a/refs.c\n>> +++ b/refs.c\n>> @@ -2192,16 +2192,21 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n>> {\n>> \tint ret = refs->be->create_on_disk(refs, flags, err);\n>>\n>> -\tif (!ret &&\n>> -\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>> -\t\tstruct strbuf msg = STRBUF_INIT;\n>> -\n>> -\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>> -\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>> -\t\tstrbuf_release(&msg);\n>> +\tif (!ret) {\n>> +\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n>> +\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n>> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n>> +\t\t\t\t\t\t \"repository uses alternate refs storage\");\n>> +\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n>> +\t\t\tstruct strbuf msg = STRBUF_INIT;\n>> +\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n>> +\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n>> +\t\t\tstrbuf_release(&msg);\n>> +\t\t}\n>> \t}\n>>\n>> \treturn ret;\n>> +\n>> }\n>>\n>> int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n>> @@ -2216,6 +2221,10 @@ int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n>> \t\tif (format == REF_STORAGE_FORMAT_FILES)\n>> \t\t\treturn ret;\n>>\n>> +\t\t/* Alternate refs backend require stubs in the gitdir. */\n>\n> I find this comment rather confusing, you say \"require stubs\" and you do\n> an early return. I had to read it more than once to understand. What do\n> you think about:\n>\n> +\t\t/* No stubs required in the alternate refs backend,\n> +\t\t * stubs only should be created in the gitdir. */\n>\n\nBut that's exactly what it is, this is the `remove_on_disk()` function,\nand for general cases it makes sense to remove the stubs, but when using\nalternate refs directories, the stubs shouldn't be removed, cause doing\nso will mean the directory is no longer recognized as a gitdir.\n\n>> +\t\tif (refs->repo->ref_storage_payload)\n>> +\t\t\treturn ret;\n>> +\n>\n> --\n> Cheers,\n> Toon\n"},{"id":"536697","messageId":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH v8 0/6] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:35Z","receivedAt":"2026-02-23T08:01:46Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"While Git allows users to select different reference backends, unlike\nwith objects, there is no flexibility in selecting the reference\ndirectory. Currently, the reference format is obtained from the config\nof the repository and the reference directory is set to the $GIT_DIR.\n\nThis patch extends the config 'extensions.refStorage' to take in\nmultiple forms of inputs:\n\n - A format name alone (e.g., `reftable` or `files`).\n\n - A URI format `://` explicitly specifies both the\n format and payload (e.g., `reftable:///foo/bar`).\n\nWe also add in a new ENV variable GIT_REFERENCE_BACKEND which can be\nused to override the config.\n\nOne use case for this is migration between different backends. On the\nserver side, migrating from the files backend to the newly introduced\nreftable backend can be achieved by running 'git refs migrate'. However,\nfor large repositories with millions of references, this migration can\ntake from seconds to minutes.\n\nFor some background, at GitLab, the criteria for our migration was to\nreduce the downtime of the migrate ideally to zero. So running 'git refs\nmigrate --ref-format=reftable' by itself wouldn't work, since it scales\nwith the number of references and we have repos with millions of\nreferences, so we need to migrate without loosing any information. We\ncame up with the following plan:\n\n 1. Run git-pack-refs(1) and note timestamp of the generated packed-refs\n file.\n 2. Run git refs migrate –dry-run.\n 3. If there are no ongoing reference requests (read/write)\n a. Lock the repository by blocking incoming requests (done on a\n layer above git, in Gitaly [1]).\n b. If the timestamp of the packed-refs file has changed, unlock\n the repo and repeat from step 1.\n c. Apply all the loose refs to the dry-run reftable folder (this\n requires support in Git to write refs to arbitrary folder).\n d. Move the reftable dry-run folder into the GIT_DIR.\n e. Swap the repo config\n f. Unlock repo access\n\nUsing such a route, scales much better since we only have to worry about\nblocking the repository by O(ref written between #1 and #3a) and not\nO(refs in repo). But for doing so, we need to be able to write to a\narbitrary reference backend + path. This is to add the missing\nreferences to the dry-run reftable folder. This series, achieves that.\n\nSince there was a long gap between v3 <> v4, the version 4 onward is\nbased on top of 2258446484 (RelNotes: correct \"fast-import\" option name,\n2026-01-30).\n\n[1]: https://gitlab.com/gitlab-org/gitaly\n\n---\nChanges in v8:\n- Fix a typo/grammar in commit 4.\n- In the final commits tests, avoid creating a file for text\n comparison.\n- Link to v7: https://patch.msgid.link/20260219-kn-alternate-ref-dir-v7-0-16f27860dbdf@gmail.com\n\nChanges in v7:\n- Add more details in the commit messages.\n- Cleanup some whitespace.\n- Reorder the commits to be group related changes together.\n- Add checks for stubs in the tests when creating new repos.\n- Link to v6: https://patch.msgid.link/20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com\n\nChanges in v6:\n- The biggest change in this version is that we now support using the\n environment variable with 'git-clone(1)' and 'git-init(1)'. In such\n situations, the alternate reference directory is created and the\n config is added to the repository.\n- Add a new commit which moves stub creation/removal to the generic\n layer.\n- Cleanup logic flow in `refs_compute_filesystem_location()`.\n- Add more tests for usage with 'git-clone(1)', 'git-init(1)' and\n migration of repositories using alternate refs backend.\n- Fixup documentation, commit messages and typos.\n- Link to v5: https://patch.msgid.link/20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com\n\nChanges in v5:\n- Moved around the commits, to ensure that the code to handle the config\n in the backend is first. Previously, we added the config first, which\n meant the commit allowed users to provide a URI but it was simply\n ignore.\n- Fix typos and grammar and rename variables.\n- Clean up the description and documentation to actually specify\n protocol over location.\n- Avoid an extra memory allocation by detaching the strbuf value.\n- Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n\nChanges in v4:\n- Mostly re-wrote the code to also support worktree. Now, the existing\n backends will store worktree references in 'ref_dir/worktrees/wt_id'\n and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n- We also support relative paths in the reference directories. These\n relative paths are resolved relative to the GIT_DIR.\n- Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n\nChanges in v3:\n- Cleanup some stale code which wasn't removed.\n- Localize strings which will be output to the user.\n- Remove additional defensive checks which are not needed.\n- Link to v2: https://patch.msgid.link/20251126-kn-alternate-ref-dir-v2-0-8b9f6f18f635@gmail.com\n\nChanges in v2:\n- Added more clarification and proper intent in the cover message.\n- Changed the format from '://' to\n `://` as it much clearer.\n- Added logic to check for the '//' in the provided URI and a test for\n the same.\n- In the tests:\n - Use test_must_fail() instead of ! git\n - Fix looped tests not using the variables correctly and ensure that\n the test description is correct.\n- Link to v1: https://patch.msgid.link/20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com\n\n---\n Documentation/config/extensions.adoc | 16 +-\n Documentation/git.adoc | 5 +\n builtin/clone.c | 9 +-\n builtin/worktree.c | 34 +++++\n environment.h | 1 +\n refs.c | 126 +++++++++++++++-\n refs.h | 13 ++\n refs/files-backend.c | 23 ++-\n refs/packed-backend.c | 5 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 14 ++\n refs/reftable-backend.c | 61 ++------\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 96 ++++++++++--\n setup.h | 4 +-\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 280 +++++++++++++++++++++++++++++++++++\n 18 files changed, 625 insertions(+), 81 deletions(-)\n\nKarthik Nayak (6):\n setup: don't modify repo in `create_reference_database()`\n refs: extract out `refs_create_refdir_stubs()`\n refs: move out stub modification to generic layer\n refs: receive and use the reference storage payload\n refs: allow reference location in refstorage config\n refs: add GIT_REFERENCE_BACKEND to specify reference backend\n\nRange-diff versus v7:\n\n1: 0f9fad1145 = 1: 8cc4b88f60 setup: don't modify repo in `create_reference_database()`\n2: cfe28f7464 = 2: 382b7b1964 refs: extract out `refs_create_refdir_stubs()`\n3: 7a08fde968 = 3: ef00e85466 refs: move out stub modification to generic layer\n4: b6988bf969 ! 4: 3e7d7042ef refs: receive and use the reference storage payload\n @@ refs/refs-internal.h: enum ref_transaction_error refs_verify_refnames_available(\n + * directory if working with a linked worktree. If working with the main\n + * worktree, both values will be the same.\n + *\n -+ * This is used by backends that store store files in the repository directly.\n ++ * This is used by backends that store references in the repository directly.\n + */\n +void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n +\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n5: 4769fae36f = 5: 5b69104cd9 refs: allow reference location in refstorage config\n6: 6bc3f09144 ! 6: 6a007df2ad refs: add GIT_REFERENCE_BACKEND to specify reference backend\n @@ t/t1423-ref-backend.sh: run_with_uri() {\n +\trefdir=$2 &&\n +\n +\t# verify that the stubs were added to the $GITDIR.\n -+\tcat $gitdir/refs/heads >actual &&\n +\techo \"repository uses alternate refs storage\" >expect &&\n -+\ttest_cmp expect actual &&\n -+\tcat $gitdir/HEAD >actual &&\n ++\ttest_cmp expect $gitdir/refs/heads &&\n +\techo \"ref: refs/heads/.invalid\" >expect &&\n -+\ttest_cmp expect actual\n ++\ttest_cmp expect $gitdir/HEAD\n +\n +\t# verify that backend specific files exist.\n +\tcase \"$GIT_DEFAULT_REF_FORMAT\" in\n\n\nbase-commit: 22584464849815268419fd9d2eba307362360db1\nchange-id: 20251105-kn-alternate-ref-dir-3e572e8cd0ef\n\nThanks\n- Karthik\n\n"},{"id":"536698","messageId":"20260223-kn-alternate-ref-dir-v8-1-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"[PATCH v8 1/6] setup: don't modify repo in `create_reference_database()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:36Z","receivedAt":"2026-02-23T08:01:47Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The `create_reference_database()` function is used to create the\nreference database during initialization of a repository. The function\ncalls `repo_set_ref_storage_format()` to set the repositories reference\nformat. This is an unexpected side-effect of the function. More so\nbecause the function is only called in two locations:\n\n 1. During git-init(1) where the value is propagated from the `struct\n repository_format repo_fmt` value.\n\n 2. During git-clone(1) where the value is propagated from the\n `the_repository` value.\n\nThe former is valid, however the flow already calls\n`repo_set_ref_storage_format()`, so this effort is simply duplicated.\nThe latter sets the existing value in `the_repository` back to itself.\nWhile this is okay for now, introduction of more fields in\n`repo_set_ref_storage_format()` would cause issues, especially\ndynamically allocated strings, where we would free/allocate the same\nstring back into `the_repostiory`.\n\nTo avoid all this confusion, clean up the function to no longer take in\nand set the repo's reference storage format.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 2 +-\n setup.c | 7 ++-----\n setup.h | 3 +--\n 3 files changed, 4 insertions(+), 8 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex b40cee5968..cd43bb5aa2 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1442,7 +1442,7 @@ int cmd_clone(int argc,\n \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n \trepo_set_hash_algo(the_repository, hash_algo);\n-\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n+\tcreate_reference_database(NULL, 1);\n \n \t/*\n \t * Before fetching from the remote, download and install bundle\ndiff --git a/setup.c b/setup.c\nindex b723f8b339..1fc9ae3872 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -2359,14 +2359,12 @@ static int is_reinit(void)\n \treturn ret;\n }\n \n-void create_reference_database(enum ref_storage_format ref_storage_format,\n-\t\t\t const char *initial_branch, int quiet)\n+void create_reference_database(const char *initial_branch, int quiet)\n {\n \tstruct strbuf err = STRBUF_INIT;\n \tchar *to_free = NULL;\n \tint reinit = is_reinit();\n \n-\trepo_set_ref_storage_format(the_repository, ref_storage_format);\n \tif (ref_store_create_on_disk(get_main_ref_store(the_repository), 0, &err))\n \t\tdie(\"failed to set up refs db: %s\", err.buf);\n \n@@ -2701,8 +2699,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n \t\t\t\t &repo_fmt, init_shared_repository);\n \n \tif (!(flags & INIT_DB_SKIP_REFDB))\n-\t\tcreate_reference_database(repo_fmt.ref_storage_format,\n-\t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n+\t\tcreate_reference_database(initial_branch, flags & INIT_DB_QUIET);\n \tcreate_object_directory();\n \n \tif (repo_settings_get_shared_repository(the_repository)) {\ndiff --git a/setup.h b/setup.h\nindex d55dcc6608..ddb9f6701c 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -240,8 +240,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n void initialize_repository_version(int hash_algo,\n \t\t\t\t enum ref_storage_format ref_storage_format,\n \t\t\t\t int reinit);\n-void create_reference_database(enum ref_storage_format ref_storage_format,\n-\t\t\t const char *initial_branch, int quiet);\n+void create_reference_database(const char *initial_branch, int quiet);\n \n /*\n * NOTE NOTE NOTE!!\n\n-- \n2.53.GIT\n\n"},{"id":"536699","messageId":"20260223-kn-alternate-ref-dir-v8-2-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"[PATCH v8 2/6] refs: extract out `refs_create_refdir_stubs()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:37Z","receivedAt":"2026-02-23T08:01:48Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"For Git to recognize a directory as a Git directory, it requires the\ndirectory to contain:\n\n 1. 'HEAD' file\n 2. 'objects/' directory\n 3. 'refs/' directory\n\nHere, #1 and #3 are part of the reference storage mechanism,\nspecifically the files backend. Since then, newer backends such as the\nreftable backend have moved to using their own path ('reftable/') for\nstoring references. But to ensure Git still recognizes the directory as\na Git directory, we create stubs.\n\nThere are two locations where we create stubs:\n\n- In 'refs/reftable-backend.c' when creating the reftable backend.\n- In 'clone.c' before spawning transport helpers.\n\nIn a following commit, we'll add another instance. So instead of\nrepeating the code, let's extract out this code to\n`refs_create_refdir_stubs()` and use it.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 7 +------\n refs.c | 23 +++++++++++++++++++++++\n refs.h | 13 +++++++++++++\n refs/reftable-backend.c | 14 ++------------\n 4 files changed, 39 insertions(+), 18 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex cd43bb5aa2..697c5bb5cb 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1225,12 +1225,7 @@ int cmd_clone(int argc,\n \tinitialize_repository_version(GIT_HASH_UNKNOWN,\n \t\t\t\t the_repository->ref_storage_format, 1);\n \n-\tstrbuf_addf(&buf, \"%s/HEAD\", git_dir);\n-\twrite_file(buf.buf, \"ref: refs/heads/.invalid\");\n-\n-\tstrbuf_reset(&buf);\n-\tstrbuf_addf(&buf, \"%s/refs\", git_dir);\n-\tsafe_create_dir(the_repository, buf.buf, 1);\n+\trefs_create_refdir_stubs(the_repository, git_dir, NULL);\n \n \t/*\n \t * additional config can be injected with -c, make sure it's included\ndiff --git a/refs.c b/refs.c\nindex 627b7f8698..77b93d655b 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2163,6 +2163,29 @@ const char *refs_resolve_ref_unsafe(struct ref_store *refs,\n \treturn NULL;\n }\n \n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_content)\n+{\n+\tstruct strbuf path = STRBUF_INIT;\n+\n+\tstrbuf_addf(&path, \"%s/HEAD\", refdir);\n+\twrite_file(path.buf, \"ref: refs/heads/.invalid\");\n+\tadjust_shared_perm(repo, path.buf);\n+\n+\tstrbuf_reset(&path);\n+\tstrbuf_addf(&path, \"%s/refs\", refdir);\n+\tsafe_create_dir(repo, path.buf, 1);\n+\n+\tif (refs_heads_content) {\n+\t\tstrbuf_reset(&path);\n+\t\tstrbuf_addf(&path, \"%s/refs/heads\", refdir);\n+\t\twrite_file(path.buf, \"%s\", refs_heads_content);\n+\t\tadjust_shared_perm(repo, path.buf);\n+\t}\n+\n+\tstrbuf_release(&path);\n+}\n+\n /* backend functions */\n int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n {\ndiff --git a/refs.h b/refs.h\nindex f0abfa1d93..9d8890fdff 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -1427,4 +1427,17 @@ void ref_iterator_free(struct ref_iterator *ref_iterator);\n int do_for_each_ref_iterator(struct ref_iterator *iter,\n \t\t\t each_ref_fn fn, void *cb_data);\n \n+/*\n+ * Git only recognizes a directory as a repository if it contains:\n+ * - HEAD file\n+ * - refs/ folder\n+ * While it is necessary within the files backend, newer backends may not\n+ * follow the same structure. To go around this, we create stubs as necessary.\n+ *\n+ * If provided with a 'refs_heads_msg', we create the 'refs/heads/head' file\n+ * with the provided message.\n+ */\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_msg);\n+\n #endif /* REFS_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex fe74af73af..d8651fe779 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,18 +491,8 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"ref: refs/heads/.invalid\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tsafe_create_dir(the_repository, sb.buf, 1);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"this repository uses the reftable format\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n+\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n+\t\t\t\t \"this repository uses the reftable format\");\n \n \tstrbuf_release(&sb);\n \treturn 0;\n\n-- \n2.53.GIT\n\n"},{"id":"536700","messageId":"20260223-kn-alternate-ref-dir-v8-3-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"[PATCH v8 3/6] refs: move out stub modification to generic layer","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:38Z","receivedAt":"2026-02-23T08:01:49Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"When creating the reftable reference backend on disk, we create stubs to\nensure that the directory can be recognized as a Git repository. This is\ndone by calling `refs_create_refdir_stubs()`. Move this to the generic\nlayer as this is needed for all backends excluding from the files\nbackends. In an upcoming commit where we introduce alternate reference\nbackend locations, we'll have to also create stubs in the $GIT_DIR\nirrespective of the backend being used. This commit builds the base to\nadd that logic.\n\nSimilarly, move the logic for deletion of stubs to the generic layer.\nThe files backend recursively calls the remove function of the\n'packed-backend', here skip calling the generic function since that\nwould try to delete stubs.\n\nSigned-off-by: Karthik Nayak \n---\n refs.c | 47 +++++++++++++++++++++++++++++++++++++++++++++--\n refs/files-backend.c | 6 +++++-\n refs/reftable-backend.c | 27 ---------------------------\n 3 files changed, 50 insertions(+), 30 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex 77b93d655b..c83af63dc5 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2189,12 +2189,55 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n /* backend functions */\n int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n {\n-\treturn refs->be->create_on_disk(refs, flags, err);\n+\tint ret = refs->be->create_on_disk(refs, flags, err);\n+\n+\tif (!ret &&\n+\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\tstruct strbuf msg = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n+\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n+\t\tstrbuf_release(&msg);\n+\t}\n+\n+\treturn ret;\n }\n \n int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n {\n-\treturn refs->be->remove_on_disk(refs, err);\n+\tint ret = refs->be->remove_on_disk(refs, err);\n+\n+\tif (!ret &&\n+\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\tstruct strbuf sb = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n+\t\tif (unlink(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\t\tstrbuf_reset(&sb);\n+\n+\t\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->gitdir);\n+\t\tif (unlink(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete stub heads: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\t\tstrbuf_reset(&sb);\n+\n+\t\tstrbuf_addf(&sb, \"%s/refs\", refs->gitdir);\n+\t\tif (rmdir(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete refs directory: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\n+\t\tstrbuf_release(&sb);\n+\t}\n+\n+\treturn ret;\n }\n \n int repo_resolve_gitlink_ref(struct repository *r,\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex 240d3c3b26..d3f6423261 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -3700,7 +3700,11 @@ static int files_ref_store_remove_on_disk(struct ref_store *ref_store,\n \tif (for_each_root_ref(refs, remove_one_root_ref, &data) < 0)\n \t\tret = -1;\n \n-\tif (ref_store_remove_on_disk(refs->packed_ref_store, err) < 0)\n+\t/*\n+\t * Directly access the cleanup functions for packed-refs as the generic function\n+\t * would try to clear stubs which isn't required for the files backend.\n+\t */\n+\tif (refs->packed_ref_store->be->remove_on_disk(refs->packed_ref_store, err) < 0)\n \t\tret = -1;\n \n \tstrbuf_release(&sb);\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex d8651fe779..6ce7f9bb8e 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,9 +491,6 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n-\t\t\t\t \"this repository uses the reftable format\");\n-\n \tstrbuf_release(&sb);\n \treturn 0;\n }\n@@ -519,30 +516,6 @@ static int reftable_be_remove_on_disk(struct ref_store *ref_store,\n \t\t\t strerror(errno));\n \t\tret = -1;\n \t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\tif (unlink(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\tif (unlink(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete stub heads: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tif (rmdir(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete refs directory: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n \n \tstrbuf_release(&sb);\n \treturn ret;\n\n-- \n2.53.GIT\n\n"},{"id":"536701","messageId":"20260223-kn-alternate-ref-dir-v8-4-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"[PATCH v8 4/6] refs: receive and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:39Z","receivedAt":"2026-02-23T08:01:50Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"An upcoming commit will add support for providing an URI via the\n'extensions.refStorage' config. The URI will contain the reference\nbackend and a corresponding payload. The payload can be then used for\nproviding an alternate locations for the reference backend.\n\nTo prepare for this, modify the existing backends to accept such an\nargument when initializing via the 'init()' function. Both the files\nand reftable backends will parse the information to be filesystem paths\nto store references. Given that no callers pass any payload yet this is\nessentially a no-op change for now.\n\nTo enable this, provide a 'refs_compute_filesystem_location()' function\nwhich will parse the current 'gitdir' and the 'payload' to provide the\nfinal reference directory and common reference directory (if working in\na linked worktree).\n\nThe documentation and tests will be added alongside the extension of the\nconfig variable.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n refs.c | 40 +++++++++++++++++++++++++++++++++++++++-\n refs/files-backend.c | 17 ++++++++++++-----\n refs/packed-backend.c | 5 +++++\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 14 ++++++++++++++\n refs/reftable-backend.c | 24 ++++++++++++++----------\n 6 files changed, 85 insertions(+), 16 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex c83af63dc5..ba2573eb7a 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -5,6 +5,7 @@\n #define USE_THE_REPOSITORY_VARIABLE\n \n #include \"git-compat-util.h\"\n+#include \"abspath.h\"\n #include \"advice.h\"\n #include \"config.h\"\n #include \"environment.h\"\n@@ -2290,7 +2291,7 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, gitdir, flags);\n+\trefs = be->init(repo, NULL, gitdir, flags);\n \treturn refs;\n }\n \n@@ -3468,3 +3469,40 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n \t\treturn \"unknown failure\";\n \t}\n }\n+\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\n+\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n+\n+\tif (!payload) {\n+\t\t/*\n+\t\t * We can use the 'gitdir' as the 'refdir' without appending the\n+\t\t * worktree path, as the 'gitdir' here is already the worktree\n+\t\t * path and is different from 'commondir' denoted by 'ref_common_dir'.\n+\t\t */\n+\t\tstrbuf_addstr(refdir, gitdir);\n+\t\treturn;\n+\t}\n+\n+\tif (!is_absolute_path(payload)) {\n+\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n+\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n+\t} else {\n+\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n+\t}\n+\n+\tstrbuf_addbuf(refdir, ref_common_dir);\n+\n+\tif (*is_worktree) {\n+\t\tconst char *wt_id = strrchr(gitdir, '/');\n+\t\tif (!wt_id)\n+\t\t\tBUG(\"worktree path does not contain slash\");\n+\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id + 1);\n+\t}\n+\n+\tstrbuf_release(&sb);\n+}\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex d3f6423261..9cde3ba724 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n * set of caches.\n */\n static struct ref_store *files_ref_store_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags)\n {\n \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n \tstruct ref_store *ref_store = (struct ref_store *)refs;\n-\tstruct strbuf sb = STRBUF_INIT;\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n+\tbool is_worktree;\n+\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n \n-\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n+\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n \trefs->store_flags = flags;\n-\tget_common_dir_noenv(&sb, gitdir);\n-\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n+\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n \trefs->packed_ref_store =\n-\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n+\t\tpacked_ref_store_init(repo, NULL, refs->gitcommondir, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n@@ -126,6 +131,8 @@ static struct ref_store *files_ref_store_init(struct repository *repo,\n \tchdir_notify_reparent(\"files-backend $GIT_COMMONDIR\",\n \t\t\t &refs->gitcommondir);\n \n+\tstrbuf_release(&refdir);\n+\n \treturn ref_store;\n }\n \ndiff --git a/refs/packed-backend.c b/refs/packed-backend.c\nindex 4ea0c12299..e7bb9f10f9 100644\n--- a/refs/packed-backend.c\n+++ b/refs/packed-backend.c\n@@ -211,7 +211,12 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n \treturn snapshot->refs->base.repo->hash_algo->hexsz;\n }\n \n+/*\n+ * Since packed-refs is only stored in the common dir, don't parse the\n+ * payload and rely on the files-backend to set 'gitdir' correctly.\n+ */\n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload UNUSED,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags)\n {\ndiff --git a/refs/packed-backend.h b/refs/packed-backend.h\nindex 9481d5e7c2..2c2377a356 100644\n--- a/refs/packed-backend.h\n+++ b/refs/packed-backend.h\n@@ -14,6 +14,7 @@ struct ref_transaction;\n */\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags);\n \ndiff --git a/refs/refs-internal.h b/refs/refs-internal.h\nindex c7d2a6e50b..4fb8fdb872 100644\n--- a/refs/refs-internal.h\n+++ b/refs/refs-internal.h\n@@ -389,6 +389,7 @@ struct ref_store;\n * the ref_store and to record the ref_store for later lookup.\n */\n typedef struct ref_store *ref_store_init_fn(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags);\n /*\n@@ -666,4 +667,17 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n \t\t\t\t\t unsigned int initial_transaction,\n \t\t\t\t\t struct strbuf *err);\n \n+/*\n+ * Given a gitdir and the reference storage payload provided, retrieve the\n+ * 'refdir' and 'ref_common_dir'. The former is where references should be\n+ * stored for the current worktree, the latter is the common reference\n+ * directory if working with a linked worktree. If working with the main\n+ * worktree, both values will be the same.\n+ *\n+ * This is used by backends that store references in the repository directly.\n+ */\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir);\n+\n #endif /* REFS_REFS_INTERNAL_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex 6ce7f9bb8e..0e220d6bb5 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -372,18 +372,24 @@ static int reftable_be_fsync(int fd)\n }\n \n static struct ref_store *reftable_be_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int store_flags)\n {\n \tstruct reftable_ref_store *refs = xcalloc(1, sizeof(*refs));\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n \tstruct strbuf path = STRBUF_INIT;\n-\tint is_worktree;\n+\tbool is_worktree;\n \tmode_t mask;\n \n \tmask = umask(0);\n \tumask(mask);\n \n-\tbase_ref_store_init(&refs->base, repo, gitdir, &refs_be_reftable);\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n+\n+\tbase_ref_store_init(&refs->base, repo, refdir.buf, &refs_be_reftable);\n \tstrmap_init(&refs->worktree_backends);\n \trefs->store_flags = store_flags;\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n@@ -419,14 +425,11 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t/*\n \t * Set up the main reftable stack that is hosted in GIT_COMMON_DIR.\n \t * This stack contains both the shared and the main worktree refs.\n-\t *\n-\t * Note that we don't try to resolve the path in case we have a\n-\t * worktree because `get_common_dir_noenv()` already does it for us.\n \t */\n-\tis_worktree = get_common_dir_noenv(&path, gitdir);\n+\tstrbuf_addbuf(&path, &ref_common_dir);\n \tif (!is_worktree) {\n \t\tstrbuf_reset(&path);\n-\t\tstrbuf_realpath(&path, gitdir, 0);\n+\t\tstrbuf_realpath(&path, ref_common_dir.buf, 0);\n \t}\n \tstrbuf_addstr(&path, \"/reftable\");\n \trefs->err = reftable_backend_init(&refs->main_backend, path.buf,\n@@ -443,10 +446,9 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t * do it efficiently.\n \t */\n \tif (is_worktree) {\n-\t\tstrbuf_reset(&path);\n-\t\tstrbuf_addf(&path, \"%s/reftable\", gitdir);\n+\t\tstrbuf_addstr(&refdir, \"/reftable\");\n \n-\t\trefs->err = reftable_backend_init(&refs->worktree_backend, path.buf,\n+\t\trefs->err = reftable_backend_init(&refs->worktree_backend, refdir.buf,\n \t\t\t\t\t\t &refs->write_options);\n \t\tif (refs->err)\n \t\t\tgoto done;\n@@ -456,6 +458,8 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \n done:\n \tassert(refs->err != REFTABLE_API_ERROR);\n+\tstrbuf_release(&ref_common_dir);\n+\tstrbuf_release(&refdir);\n \tstrbuf_release(&path);\n \treturn &refs->base;\n }\n\n-- \n2.53.GIT\n\n"},{"id":"536702","messageId":"20260223-kn-alternate-ref-dir-v8-5-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"[PATCH v8 5/6] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:40Z","receivedAt":"2026-02-23T08:01:51Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'extensions.refStorage' config is used to specify the reference\nbackend for a given repository. Both the 'files' and 'reftable' backends\nutilize the $GIT_DIR as the reference folder by default in\n`get_main_ref_store()`.\n\nSince the reference backends are pluggable, this means that they could\nwork with out-of-tree reference directories too. Extend the 'refStorage'\nconfig to also support taking an URI input, where users can specify the\nreference backend and the location.\n\nAdd the required changes to obtain and propagate this value to the\nindividual backends. Add the necessary documentation and tests.\n\nTraditionally, for linked worktrees, references were stored in the\n'$GIT_DIR/worktrees/' path. But when using an alternate reference\nstorage path, it doesn't make sense to store the main worktree\nreferences in the new path, and the linked worktree references in the\n$GIT_DIR. So, let's store linked worktree references in\n'$ALTERNATE_REFERENCE_DIR/worktrees/'. To do this, create the\nnecessary files and folders while also adding stubs in the $GIT_DIR path\nto ensure that it is still considered a Git directory.\n\nIdeally, we would want to pass in a `struct worktree *` to individual\nbackends, instead of passing the `gitdir`. This allows them to handle\nworktree specific logic. Currently, that is not possible since the\nworktree code is:\n\n - Tied to using the global `the_repository` variable.\n\n - Is not setup before the reference database during initialization of\n the repository.\n\nAdd a TODO in 'refs.c' to ensure we can eventually make that change.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n Documentation/config/extensions.adoc | 16 +++-\n builtin/worktree.c | 34 ++++++++\n refs.c | 6 +-\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 34 +++++++-\n setup.h | 1 +\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n 9 files changed, 259 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 532456644b..3e51da36d3 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n `core.repositoryFormatVersion` setting.\n \n refStorage:::\n-\tSpecify the ref storage format to use. The acceptable values are:\n+\tSpecify the ref storage format and a corresponding payload. The value\n+\tcan be either a format name or a URI:\n +\n --\n+* A format name alone (e.g., `reftable` or `files`).\n+\n+* A URI format `://` explicitly specifies both the\n+ format and payload (e.g., `reftable:///foo/bar`).\n+\n+Supported format names are:\n++\n include::../ref-storage-format.adoc[]\n++\n+The payload is passed directly to the reference backend. For the files and\n+reftable backends, this must be a filesystem path where the references will\n+be stored. Defaulting to the commondir when no payload is provided. Relative\n+paths are resolved relative to the $GIT_DIR. Future backends may support\n+other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n Note that this setting should only be set by linkgit:git-init[1] or\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..293e808379 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -425,6 +425,39 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n \treturn run_command(&cp);\n }\n \n+/*\n+ * References for worktrees are generally stored in '$GIT_DIR/worktrees/'.\n+ * But when using alternate reference directories, we want to store the worktree\n+ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n+ *\n+ * Create the necessary folder structure to facilitate the same. But to ensure\n+ * that the former path is still considered a Git directory, add stubs.\n+ */\n+static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\tchar *path;\n+\n+\tpath = wt->repo->ref_storage_payload;\n+\tif (!path)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(path))\n+\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n+\n+\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_addf(&sb, \"/%s\", wt->id);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_reset(&sb);\n+\n+\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n+\t\t path, wt->id);\n+\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n+\n+\tstrbuf_release(&sb);\n+}\n+\n static int add_worktree(const char *path, const char *refname,\n \t\t\tconst struct add_opts *opts)\n {\n@@ -518,6 +551,7 @@ static int add_worktree(const char *path, const char *refname,\n \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n \t\tgoto done;\n \t}\n+\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n \twt_refs = get_worktree_ref_store(wt);\n \n \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\ndiff --git a/refs.c b/refs.c\nindex ba2573eb7a..ef1902e85c 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2291,7 +2291,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, NULL, gitdir, flags);\n+\t/*\n+\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n+\t * allow the backend to handle how it wants to deal with worktrees.\n+\t */\n+\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n \treturn refs;\n }\n \ndiff --git a/repository.c b/repository.c\nindex c7e75215ac..9815f081ef 100644\n--- a/repository.c\n+++ b/repository.c\n@@ -193,9 +193,12 @@ void repo_set_compat_hash_algo(struct repository *repo, int algo)\n }\n \n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format)\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload)\n {\n \trepo->ref_storage_format = format;\n+\tfree(repo->ref_storage_payload);\n+\trepo->ref_storage_payload = xstrdup_or_null(payload);\n }\n \n /*\n@@ -277,7 +280,8 @@ int repo_init(struct repository *repo,\n \n \trepo_set_hash_algo(repo, format.hash_algo);\n \trepo_set_compat_hash_algo(repo, format.compat_hash_algo);\n-\trepo_set_ref_storage_format(repo, format.ref_storage_format);\n+\trepo_set_ref_storage_format(repo, format.ref_storage_format,\n+\t\t\t\t format.ref_storage_payload);\n \trepo->repository_format_worktree_config = format.worktree_config;\n \trepo->repository_format_relative_worktrees = format.relative_worktrees;\n \trepo->repository_format_precious_objects = format.precious_objects;\n@@ -369,6 +373,7 @@ void repo_clear(struct repository *repo)\n \tFREE_AND_NULL(repo->index_file);\n \tFREE_AND_NULL(repo->worktree);\n \tFREE_AND_NULL(repo->submodule_prefix);\n+\tFREE_AND_NULL(repo->ref_storage_payload);\n \n \todb_free(repo->objects);\n \trepo->objects = NULL;\ndiff --git a/repository.h b/repository.h\nindex 6063c4b846..95e2333bad 100644\n--- a/repository.h\n+++ b/repository.h\n@@ -150,6 +150,11 @@ struct repository {\n \n \t/* Repository's reference storage format, as serialized on disk. */\n \tenum ref_storage_format ref_storage_format;\n+\t/*\n+\t * Reference storage information as needed for the backend. This contains\n+\t * only the payload from the reference URI without the schema.\n+\t */\n+\tchar *ref_storage_payload;\n \n \t/* A unique-id for tracing purposes. */\n \tint trace2_repo_id;\n@@ -204,7 +209,8 @@ void repo_set_worktree(struct repository *repo, const char *path);\n void repo_set_hash_algo(struct repository *repo, int algo);\n void repo_set_compat_hash_algo(struct repository *repo, int compat_algo);\n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format);\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload);\n void initialize_repository(struct repository *repo);\n RESULT_MUST_BE_USED\n int repo_init(struct repository *r, const char *gitdir, const char *worktree);\ndiff --git a/setup.c b/setup.c\nindex 1fc9ae3872..d407f3347b 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -632,6 +632,21 @@ static enum extension_result handle_extension_v0(const char *var,\n \t\treturn EXTENSION_UNKNOWN;\n }\n \n+static void parse_reference_uri(const char *value, char **format,\n+\t\t\t\tchar **payload)\n+{\n+\tconst char *schema_end;\n+\n+\tschema_end = strstr(value, \"://\");\n+\tif (!schema_end) {\n+\t\t*format = xstrdup(value);\n+\t\t*payload = NULL;\n+\t} else {\n+\t\t*format = xstrndup(value, schema_end - value);\n+\t\t*payload = xstrdup_or_null(schema_end + 3);\n+\t}\n+}\n+\n /*\n * Record any new extensions in this function.\n */\n@@ -674,10 +689,17 @@ static enum extension_result handle_extension(const char *var,\n \t\treturn EXTENSION_OK;\n \t} else if (!strcmp(ext, \"refstorage\")) {\n \t\tunsigned int format;\n+\t\tchar *format_str;\n \n \t\tif (!value)\n \t\t\treturn config_error_nonbool(var);\n-\t\tformat = ref_storage_format_by_name(value);\n+\n+\t\tparse_reference_uri(value, &format_str,\n+\t\t\t\t &data->ref_storage_payload);\n+\n+\t\tformat = ref_storage_format_by_name(format_str);\n+\t\tfree(format_str);\n+\n \t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n \t\t\treturn error(_(\"invalid value for '%s': '%s'\"),\n \t\t\t\t \"extensions.refstorage\", value);\n@@ -850,6 +872,7 @@ void clear_repository_format(struct repository_format *format)\n \tstring_list_clear(&format->v1_only_extensions, 0);\n \tfree(format->work_tree);\n \tfree(format->partial_clone);\n+\tfree(format->ref_storage_payload);\n \tinit_repository_format(format);\n }\n \n@@ -1942,7 +1965,8 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\t\trepo_set_compat_hash_algo(the_repository,\n \t\t\t\t\t\t repo_fmt.compat_hash_algo);\n \t\t\trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t\t\t repo_fmt.ref_storage_format);\n+\t\t\t\t\t\t repo_fmt.ref_storage_format,\n+\t\t\t\t\t\t repo_fmt.ref_storage_payload);\n \t\t\tthe_repository->repository_format_worktree_config =\n \t\t\t\trepo_fmt.worktree_config;\n \t\t\tthe_repository->repository_format_relative_worktrees =\n@@ -2042,7 +2066,8 @@ void check_repository_format(struct repository_format *fmt)\n \trepo_set_hash_algo(the_repository, fmt->hash_algo);\n \trepo_set_compat_hash_algo(the_repository, fmt->compat_hash_algo);\n \trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t fmt->ref_storage_format);\n+\t\t\t\t fmt->ref_storage_format,\n+\t\t\t\t fmt->ref_storage_payload);\n \tthe_repository->repository_format_worktree_config =\n \t\tfmt->worktree_config;\n \tthe_repository->repository_format_relative_worktrees =\n@@ -2643,7 +2668,8 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n-\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n+\t\t\t\t repo_fmt->ref_storage_payload);\n }\n \n int init_db(const char *git_dir, const char *real_git_dir,\ndiff --git a/setup.h b/setup.h\nindex ddb9f6701c..093af39e84 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -171,6 +171,7 @@ struct repository_format {\n \tint hash_algo;\n \tint compat_hash_algo;\n \tenum ref_storage_format ref_storage_format;\n+\tchar *ref_storage_payload;\n \tint sparse_index;\n \tchar *work_tree;\n \tstruct string_list unknown_extensions;\ndiff --git a/t/meson.build b/t/meson.build\nindex 459c52a489..11fc5a49ee 100644\n--- a/t/meson.build\n+++ b/t/meson.build\n@@ -210,6 +210,7 @@ integration_tests = [\n 't1420-lost-found.sh',\n 't1421-reflog-write.sh',\n 't1422-show-ref-exists.sh',\n+ 't1423-ref-backend.sh',\n 't1430-bad-ref-name.sh',\n 't1450-fsck.sh',\n 't1451-fsck-buffer.sh',\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nnew file mode 100755\nindex 0000000000..9912433b8c\n--- /dev/null\n+++ b/t/t1423-ref-backend.sh\n@@ -0,0 +1,159 @@\n+#!/bin/sh\n+\n+test_description='Test reference backend URIs'\n+\n+. ./test-lib.sh\n+\n+# Run a git command with the provided reference storage. Reset the backend\n+# post running the command.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# is the git subcommand to be run in the repository.\n+run_with_uri() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\tcmd=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1\n+\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\tgit -C \"$repo\" $cmd &&\n+\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+}\n+\n+# Test a repository with a given reference storage by running and comparing\n+# 'git refs list' before and after setting the new reference backend. If\n+# err_msg is set, expect the command to fail and grep for the provided err_msg.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n+test_refs_backend() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\terr_msg=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test -n \"$err_msg\";\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\ttest_grep \"$err_msg\" err\n+\telse\n+\t\tgit -C \"$repo\" refs list >expect &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\ttest_cmp expect actual\n+\tfi\n+}\n+\n+test_expect_success 'URI is invalid' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'URI ends with colon' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable:\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'unknown reference backend' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"db://.git\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+ref_formats=\"files reftable\"\n+for from_format in $ref_formats\n+do\n+\n+for to_format in $ref_formats\n+do\n+\tif test \"$from_format\" = \"$to_format\"\n+\tthen\n+\t\tcontinue\n+\tfi\n+\n+\n+\tfor dir in \"$(pwd)/repo/.git\" \".\"\n+\tdo\n+\n+\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit refs list >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\tgit refs list >actual &&\n+\t\t\t\ttest_cmp expect actual &&\n+\n+\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\tgit config set core.repositoryformatversion 1 &&\n+\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit worktree add ../wt 2\n+\t\t\t) &&\n+\n+\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n+\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n+\t\t\t! test_cmp expect actual &&\n+\n+\t\t\tgit -C wt rev-parse 2 >expect &&\n+\t\t\tgit -C wt rev-parse HEAD >actual &&\n+\t\t\ttest_cmp expect actual\n+\t\t'\n+\tdone # closes dir\n+done # closes to_format\n+done # closes from_format\n+\n+test_done\n\n-- \n2.53.GIT\n\n"},{"id":"536703","messageId":"20260223-kn-alternate-ref-dir-v8-6-0509c132a203@gmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"[PATCH v8 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T08:01:41Z","receivedAt":"2026-02-23T08:01:53Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Git allows setting a different object directory via\n'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\nthe previous commit we extended the 'extensions.refStorage' config to\nalso support an URI input for reference backend with location.\n\nLet's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\ntakes in the same input as the config variable. Having an environment\nvariable allows us to modify the reference backend and location on the\nfly for individual Git commands.\n\nThe environment variable also allows usage of alternate reference\ndirectories during 'git-clone(1)' and 'git-init(1)'. Add the config to\nthe repository when created with the environment variable set.\n\nWhen initializing the repository with an alternate reference folder,\ncreate the required stubs in the repositories $GIT_DIR. The inverse,\ni.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\nsince that would render it unusable. Removal of ref store is only used\nwhen migrating between ref formats and cleanup of the $GIT_DIR doesn't\nmake sense in such a situation.\n\nHelped-by: Jean-Noël Avila \nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 5 ++\n environment.h | 1 +\n refs.c | 30 +++++---\n setup.c | 55 ++++++++++++++-\n t/t1423-ref-backend.sh | 187 ++++++++++++++++++++++++++++++++++++++++---------\n 5 files changed, 233 insertions(+), 45 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..66442735ea 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n \trepositories will be set to this value. The default is \"files\".\n \tSee `--ref-format` in linkgit:git-init[1].\n \n+`GIT_REFERENCE_BACKEND`::\n+ Specify which reference backend to be used along with its URI.\n+ See `extensions.refStorage` option in linkgit:git-config[1] for more\n+ details. Overrides the config variable when used.\n+\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\ndiff --git a/environment.h b/environment.h\nindex 27f657af04..540e0a7f6d 100644\n--- a/environment.h\n+++ b/environment.h\n@@ -42,6 +42,7 @@\n #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n+#define GIT_REFERENCE_BACKEND_ENVIRONMENT \"GIT_REFERENCE_BACKEND\"\n \n /*\n * Environment variable used to propagate the --no-advice global option to the\ndiff --git a/refs.c b/refs.c\nindex ef1902e85c..a700a66f08 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2192,13 +2192,17 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n {\n \tint ret = refs->be->create_on_disk(refs, flags, err);\n \n-\tif (!ret &&\n-\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n-\t\tstruct strbuf msg = STRBUF_INIT;\n-\n-\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n-\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n-\t\tstrbuf_release(&msg);\n+\tif (!ret) {\n+\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n+\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n+\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n+\t\t\t\t\t\t \"repository uses alternate refs storage\");\n+\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\t\tstruct strbuf msg = STRBUF_INIT;\n+\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n+\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n+\t\t\tstrbuf_release(&msg);\n+\t\t}\n \t}\n \n \treturn ret;\n@@ -2208,10 +2212,18 @@ int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n {\n \tint ret = refs->be->remove_on_disk(refs, err);\n \n-\tif (!ret &&\n-\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\tif (!ret) {\n+\t\tenum ref_storage_format format = ref_storage_format_by_name(refs->be->name);\n \t\tstruct strbuf sb = STRBUF_INIT;\n \n+\t\t/* Backends apart from the files backend create stubs. */\n+\t\tif (format == REF_STORAGE_FORMAT_FILES)\n+\t\t\treturn ret;\n+\n+\t\t/* Alternate refs backend require stubs in the gitdir. */\n+\t\tif (refs->repo->ref_storage_payload)\n+\t\t\treturn ret;\n+\n \t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n \t\tif (unlink(sb.buf) < 0) {\n \t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\ndiff --git a/setup.c b/setup.c\nindex d407f3347b..90cb9be578 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -1838,6 +1838,7 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \tstatic struct strbuf cwd = STRBUF_INIT;\n \tstruct strbuf dir = STRBUF_INIT, gitdir = STRBUF_INIT, report = STRBUF_INIT;\n \tconst char *prefix = NULL;\n+\tconst char *ref_backend_uri;\n \tstruct repository_format repo_fmt = REPOSITORY_FORMAT_INIT;\n \n \t/*\n@@ -1995,6 +1996,25 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\tsetenv(GIT_PREFIX_ENVIRONMENT, \"\", 1);\n \t}\n \n+\t/*\n+\t * The env variable should override the repository config\n+\t * for 'extensions.refStorage'.\n+\t */\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *payload;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\t\trepo_set_ref_storage_format(the_repository, format, payload);\n+\n+\t\tfree(backend);\n+\t\tfree(payload);\n+\t}\n+\n \tsetup_original_cwd();\n \n \tstrbuf_release(&dir);\n@@ -2337,7 +2357,8 @@ void initialize_repository_version(int hash_algo,\n \t * the remote repository's format.\n \t */\n \tif (hash_algo != GIT_HASH_SHA1_LEGACY ||\n-\t ref_storage_format != REF_STORAGE_FORMAT_FILES)\n+\t ref_storage_format != REF_STORAGE_FORMAT_FILES ||\n+\t the_repository->ref_storage_payload)\n \t\ttarget_version = GIT_REPO_VERSION_READ;\n \n \tif (hash_algo != GIT_HASH_SHA1_LEGACY && hash_algo != GIT_HASH_UNKNOWN)\n@@ -2346,11 +2367,20 @@ void initialize_repository_version(int hash_algo,\n \telse if (reinit)\n \t\trepo_config_set_gently(the_repository, \"extensions.objectformat\", NULL);\n \n-\tif (ref_storage_format != REF_STORAGE_FORMAT_FILES)\n+\tif (the_repository->ref_storage_payload) {\n+\t\tstruct strbuf ref_uri = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&ref_uri, \"%s://%s\",\n+\t\t\t ref_storage_format_to_name(ref_storage_format),\n+\t\t\t the_repository->ref_storage_payload);\n+\t\trepo_config_set(the_repository, \"extensions.refstorage\", ref_uri.buf);\n+\t\tstrbuf_release(&ref_uri);\n+\t} else if (ref_storage_format != REF_STORAGE_FORMAT_FILES) {\n \t\trepo_config_set(the_repository, \"extensions.refstorage\",\n \t\t\t\tref_storage_format_to_name(ref_storage_format));\n-\telse if (reinit)\n+\t} else if (reinit) {\n \t\trepo_config_set_gently(the_repository, \"extensions.refstorage\", NULL);\n+\t}\n \n \tif (reinit) {\n \t\tstruct strbuf config = STRBUF_INIT;\n@@ -2623,6 +2653,7 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t\t.ignore_repo = 1,\n \t\t.ignore_worktree = 1,\n \t};\n+\tconst char *ref_backend_uri;\n \tconst char *env;\n \n \tconfig_with_options(read_default_format_config, &cfg, NULL, NULL, &opts);\n@@ -2668,6 +2699,24 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n+\n+\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *payload;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\n+\t\trepo_fmt->ref_storage_format = format;\n+\t\trepo_fmt->ref_storage_payload = payload;\n+\n+\t\tfree(backend);\n+\t}\n+\n \trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n \t\t\t\t repo_fmt->ref_storage_payload);\n }\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nindex 9912433b8c..1a7b8eadba 100755\n--- a/t/t1423-ref-backend.sh\n+++ b/t/t1423-ref-backend.sh\n@@ -11,16 +11,25 @@ test_description='Test reference backend URIs'\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n # is the git subcommand to be run in the repository.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n run_with_uri() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n \tcmd=$4 &&\n+\tvia=$5 &&\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1\n-\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\tgit -C \"$repo\" $cmd &&\n-\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test \"$via\" = \"env\"\n+\tthen\n+\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" git -C \"$repo\" $cmd\n+\telif test \"$via\" = \"config\"\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\tgit -C \"$repo\" $cmd &&\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tfi\n }\n \n # Test a repository with a given reference storage by running and comparing\n@@ -30,44 +39,84 @@ run_with_uri() {\n # is the relative path to the repo to run the command in.\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n # (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n test_refs_backend() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n-\terr_msg=$4 &&\n+\tvia=$4 &&\n+\terr_msg=$5 &&\n+\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n \tif test -n \"$err_msg\";\n \tthen\n-\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n-\t\ttest_grep \"$err_msg\" err\n+\t\tif test \"$via\" = \"env\"\n+\t\tthen\n+\t\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" test_must_fail git -C \"$repo\" refs list 2>err\n+\t\telif test \"$via\" = \"config\"\n+\t\tthen\n+\t\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\t\ttest_grep \"$err_msg\" err\n+\t\tfi\n \telse\n \t\tgit -C \"$repo\" refs list >expect &&\n-\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" \"$via\">actual &&\n \t\ttest_cmp expect actual\n \tfi\n }\n \n-test_expect_success 'URI is invalid' '\n+# Verify that the expected files are present in the gitdir and the refsdir.\n+# Usage: verify_files_exist \n+# is the path for the gitdir.\n+# is the path for the refdir.\n+verify_files_exist() {\n+\tgitdir=$1 &&\n+\trefdir=$2 &&\n+\n+\t# verify that the stubs were added to the $GITDIR.\n+\techo \"repository uses alternate refs storage\" >expect &&\n+\ttest_cmp expect $gitdir/refs/heads &&\n+\techo \"ref: refs/heads/.invalid\" >expect &&\n+\ttest_cmp expect $gitdir/HEAD\n+\n+\t# verify that backend specific files exist.\n+\tcase \"$GIT_DEFAULT_REF_FORMAT\" in\n+\tfiles)\n+\t\ttest_path_is_dir $refdir/refs/heads &&\n+\t\ttest_path_is_file $refdir/HEAD;;\n+\treftable)\n+\t\ttest_path_is_dir $refdir/reftable &&\n+\t\ttest_path_is_file $refdir/reftable/tables.list;;\n+\t*)\n+\t\tBUG \"unhandled ref format $GIT_DEFAULT_REF_FORMAT\";;\n+\tesac\n+}\n+\n+methods=\"config env\"\n+for method in $methods\n+do\n+\n+test_expect_success \"$method: URI is invalid\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'URI ends with colon' '\n+test_expect_success \"$method: URI ends with colon\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable:\" \\\n+\ttest_refs_backend repo files \"reftable:\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'unknown reference backend' '\n+test_expect_success \"$method: unknown reference backend\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"db://.git\" \\\n+\ttest_refs_backend repo files \"db://.git\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n@@ -86,7 +135,7 @@ do\n \tfor dir in \"$(pwd)/repo/.git\" \".\"\n \tdo\n \n-\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: read from $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -101,7 +150,7 @@ do\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: write to $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -113,20 +162,22 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\" &&\n \n \t\t\t\tgit refs list >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"tag -d 1\" \"$method\" &&\n \t\t\t\tgit refs list >actual &&\n \t\t\t\ttest_cmp expect actual &&\n \n \t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"refs list\" \"$method\" >actual &&\n \t\t\t\ttest_cmp expect actual\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: with worktree and $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo wt\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -138,22 +189,92 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\tgit config set core.repositoryformatversion 1 &&\n-\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n-\n-\t\t\t\tgit worktree add ../wt 2\n-\t\t\t) &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n \n-\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n-\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n-\t\t\t! test_cmp expect actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n+\t\t\t\t! test_cmp expect actual &&\n \n-\t\t\tgit -C wt rev-parse 2 >expect &&\n-\t\t\tgit -C wt rev-parse HEAD >actual &&\n-\t\t\ttest_cmp expect actual\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n \t\t'\n \tdone # closes dir\n+\n+\ttest_expect_success \"migrating repository to $to_format with alternate refs directory\" '\n+\t\ttest_when_finished \"rm -rf repo refdir\" &&\n+\t\tmkdir refdir &&\n+\t\tGIT_REFERENCE_BACKEND=\"${from_format}://$(pwd)/refdir\" git init repo &&\n+\t\t(\n+\t\t\tcd repo &&\n+\n+\t\t\ttest_commit 1 &&\n+\t\t\ttest_commit 2 &&\n+\t\t\ttest_commit 3 &&\n+\n+\t\t\tgit refs migrate --ref-format=$to_format &&\n+\t\t\tgit refs list >out &&\n+\t\t\ttest_grep \"refs/tags/1\"\tout &&\n+\t\t\ttest_grep \"refs/tags/2\"\tout &&\n+\t\t\ttest_grep \"refs/tags/3\"\tout\n+\t\t)\n+\t'\n+\n done # closes to_format\n done # closes from_format\n \n+done # closes method\n+\n+test_expect_success 'initializing repository with alt ref directory' '\n+\ttest_when_finished \"rm -rf repo refdir\" &&\n+\tmkdir refdir &&\n+\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n+\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n+\tverify_files_exist repo/.git refdir &&\n+\t(\n+\t\tcd repo &&\n+\n+\t\tgit config get extensions.refstorage >expect &&\n+\t\techo $BACKEND >actual &&\n+\t\ttest_cmp expect actual &&\n+\n+\t\ttest_commit 1 &&\n+\t\ttest_commit 2 &&\n+\t\ttest_commit 3 &&\n+\t\tgit refs list >out &&\n+\t\ttest_grep \"refs/tags/1\"\tout &&\n+\t\ttest_grep \"refs/tags/2\"\tout &&\n+\t\ttest_grep \"refs/tags/3\"\tout\n+\t)\n+'\n+\n+test_expect_success 'cloning repository with alt ref directory' '\n+\ttest_when_finished \"rm -rf source repo refdir\" &&\n+\tmkdir refdir &&\n+\n+\tgit init source &&\n+\ttest_commit -C source 1 &&\n+\ttest_commit -C source 2 &&\n+\ttest_commit -C source 3 &&\n+\n+\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n+\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n+\n+\tgit -C repo config get extensions.refstorage >expect &&\n+\techo $BACKEND >actual &&\n+\ttest_cmp expect actual &&\n+\n+\tverify_files_exist repo/.git refdir &&\n+\n+\tgit -C source for-each-ref refs/tags/ >expect &&\n+\tgit -C repo for-each-ref refs/tags/ >actual &&\n+\ttest_cmp expect actual\n+'\n+\n test_done\n\n-- \n2.53.GIT\n\n"},{"id":"536740","messageId":"aZwx6F-ZeQ-LZv1M@pks.im","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com","subject":"Re: [PATCH v8 0/6] refs: allow setting the reference directory","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-23T10:54:32Z","receivedAt":"2026-02-23T10:54:38Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Feb 23, 2026 at 09:01:35AM +0100, Karthik Nayak wrote:\n> Changes in v8:\n> - Fix a typo/grammar in commit 4.\n> - In the final commits tests, avoid creating a file for text\n> comparison.\n> - Link to v7: https://patch.msgid.link/20260219-kn-alternate-ref-dir-v7-0-16f27860dbdf@gmail.com\n\nThanks, I'm happy now with the current version based on the range-diff.\n\nPatrick\n"},{"id":"536790","messageId":"CAOLa=ZQ2qaSbxaEfK-ngZUfM-WwPhiFF6wYRK68=0QJ9P-5BnA@mail.gmail.com","threadId":"64513","inReplyTo":"aZwx6F-ZeQ-LZv1M@pks.im","subject":"Re: [PATCH v8 0/6] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-23T13:37:57Z","receivedAt":"2026-02-23T13:37:59Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Mon, Feb 23, 2026 at 09:01:35AM +0100, Karthik Nayak wrote:\n>> Changes in v8:\n>> - Fix a typo/grammar in commit 4.\n>> - In the final commits tests, avoid creating a file for text\n>> comparison.\n>> - Link to v7: https://patch.msgid.link/20260219-kn-alternate-ref-dir-v7-0-16f27860dbdf@gmail.com\n>\n> Thanks, I'm happy now with the current version based on the range-diff.\n>\n> Patrick\n\nThanks for the reviews.\n"},{"id":"536863","messageId":"3af8a2ba-dfe4-4e43-8f86-b03a0cbc3698@app.fastmail.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-5-0509c132a203@gmail.com","subject":"Re: [PATCH v8 5/6] refs: allow reference location in refstorage config","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-02-23T17:43:29Z","receivedAt":"2026-02-23T17:46:41Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Mon, Feb 23, 2026, at 09:01, Karthik Nayak wrote:\n>[snip]\n>\n> Helped-by: Patrick Steinhardt \n> Signed-off-by: Karthik Nayak \n> ---\n> Documentation/config/extensions.adoc | 16 +++-\n> builtin/worktree.c | 34 ++++++++\n> refs.c | 6 +-\n> repository.c | 9 +-\n> repository.h | 8 +-\n> setup.c | 34 +++++++-\n> setup.h | 1 +\n> t/meson.build | 1 +\n> t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n> 9 files changed, 259 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/config/extensions.adoc\n> b/Documentation/config/extensions.adoc\n> index 532456644b..3e51da36d3 100644\n> --- a/Documentation/config/extensions.adoc\n> +++ b/Documentation/config/extensions.adoc\n> @@ -57,10 +57,24 @@ For historical reasons, this extension is respected\n> regardless of the\n> `core.repositoryFormatVersion` setting.\n>\n> refStorage:::\n> -\tSpecify the ref storage format to use. The acceptable values are:\n> +\tSpecify the ref storage format and a corresponding payload. The value\n> +\tcan be either a format name or a URI:\n> +\n> --\n> +* A format name alone (e.g., `reftable` or `files`).\n> +\n> +* A URI format `://` explicitly specifies both the\n> + format and payload (e.g., `reftable:///foo/bar`).\n> +\n> +Supported format names are:\n> ++\n> include::../ref-storage-format.adoc[]\n\nIt looks like this causes list continuation (+) and the `;;` syntax to\nappear in the HTML output of git-config(1).\n\n + files;; for loose files with packed-refs. ...\n\n + The payload is passed ...\n\nAccording to `Documentation/doc-diff master seen`.\n\nIt looks like dropping the list continuations fixes it.\n\n Supported format names are:\n\n include::../ref-storage-format.adoc[]\n\n The payload is passed directly to the reference backend. For the files and\n [...]\n\nMaybe because you are inside an open block? I don’t know.\n\n> ++\n> +The payload is passed directly to the reference backend. For the files\n>[snip]\n"},{"id":"536881","messageId":"xmqqikbnmdjf.fsf@gitster.g","threadId":"64513","inReplyTo":"CAOLa=ZQ2qaSbxaEfK-ngZUfM-WwPhiFF6wYRK68=0QJ9P-5BnA@mail.gmail.com","subject":"Re: [PATCH v8 0/6] refs: allow setting the reference directory","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-23T20:05:08Z","receivedAt":"2026-02-23T20:05:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak writes:\n\n> Patrick Steinhardt writes:\n>\n>> On Mon, Feb 23, 2026 at 09:01:35AM +0100, Karthik Nayak wrote:\n>>> Changes in v8:\n>>> - Fix a typo/grammar in commit 4.\n>>> - In the final commits tests, avoid creating a file for text\n>>> comparison.\n>>> - Link to v7: https://patch.msgid.link/20260219-kn-alternate-ref-dir-v7-0-16f27860dbdf@gmail.com\n>>\n>> Thanks, I'm happy now with the current version based on the range-diff.\n>>\n>> Patrick\n>\n> Thanks for the reviews.\n\nLet me replace what I have with this latest and mark the topic for\n'next', then.\n\nThanks, all!\n"},{"id":"536968","messageId":"CAOLa=ZTJ3-7OSbfRYbYuTaZBsPSSXrHHJ5LkCO_HSMw=y5+Gfg@mail.gmail.com","threadId":"64513","inReplyTo":"3af8a2ba-dfe4-4e43-8f86-b03a0cbc3698@app.fastmail.com","subject":"Re: [PATCH v8 5/6] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-24T13:09:52Z","receivedAt":"2026-02-24T13:09:54Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Mon, Feb 23, 2026, at 09:01, Karthik Nayak wrote:\n>>[snip]\n>>\n>> Helped-by: Patrick Steinhardt \n>> Signed-off-by: Karthik Nayak \n>> ---\n>> Documentation/config/extensions.adoc | 16 +++-\n>> builtin/worktree.c | 34 ++++++++\n>> refs.c | 6 +-\n>> repository.c | 9 +-\n>> repository.h | 8 +-\n>> setup.c | 34 +++++++-\n>> setup.h | 1 +\n>> t/meson.build | 1 +\n>> t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n>> 9 files changed, 259 insertions(+), 9 deletions(-)\n>>\n>> diff --git a/Documentation/config/extensions.adoc\n>> b/Documentation/config/extensions.adoc\n>> index 532456644b..3e51da36d3 100644\n>> --- a/Documentation/config/extensions.adoc\n>> +++ b/Documentation/config/extensions.adoc\n>> @@ -57,10 +57,24 @@ For historical reasons, this extension is respected\n>> regardless of the\n>> `core.repositoryFormatVersion` setting.\n>>\n>> refStorage:::\n>> -\tSpecify the ref storage format to use. The acceptable values are:\n>> +\tSpecify the ref storage format and a corresponding payload. The value\n>> +\tcan be either a format name or a URI:\n>> +\n>> --\n>> +* A format name alone (e.g., `reftable` or `files`).\n>> +\n>> +* A URI format `://` explicitly specifies both the\n>> + format and payload (e.g., `reftable:///foo/bar`).\n>> +\n>> +Supported format names are:\n>> ++\n>> include::../ref-storage-format.adoc[]\n>\n> It looks like this causes list continuation (+) and the `;;` syntax to\n> appear in the HTML output of git-config(1).\n>\n> + files;; for loose files with packed-refs. ...\n>\n> + The payload is passed ...\n>\n> According to `Documentation/doc-diff master seen`.\n>\n> It looks like dropping the list continuations fixes it.\n>\n> Supported format names are:\n>\n> include::../ref-storage-format.adoc[]\n>\n> The payload is passed directly to the reference backend. For the files and\n> [...]\n>\n> Maybe because you are inside an open block? I don’t know.\n>\n\nI don't know either. But this seems to fix it, let me know if it does\nfor you too.\n\n--8<--\n\ndiff --git a/Documentation/config/extensions.adoc\nb/Documentation/config/extensions.adoc\nindex 3e51da36d3..329d02b3c4 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -67,13 +67,13 @@ refStorage:::\n format and payload (e.g., `reftable:///foo/bar`).\n\n Supported format names are:\n-+\n+\n include::../ref-storage-format.adoc[]\n-+\n+\n The payload is passed directly to the reference backend. For the files and\n reftable backends, this must be a filesystem path where the references will\n be stored. Defaulting to the commondir when no payload is provided. Relative\n-paths are resolved relative to the $GIT_DIR. Future backends may support\n+paths are resolved relative to the `$GIT_DIR`. Future backends may support\n other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n\n\n>> ++\n>> +The payload is passed directly to the reference backend. For the files\n>>[snip]\n"},{"id":"536970","messageId":"78ade921-321c-493e-ae4a-dbada55b0fff@app.fastmail.com","threadId":"64513","inReplyTo":"CAOLa=ZTJ3-7OSbfRYbYuTaZBsPSSXrHHJ5LkCO_HSMw=y5+Gfg@mail.gmail.com","subject":"Re: [PATCH v8 5/6] refs: allow reference location in refstorage config","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-02-24T13:20:20Z","receivedAt":"2026-02-24T13:20:41Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Tue, Feb 24, 2026, at 14:09, Karthik Nayak wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>\n>> On Mon, Feb 23, 2026, at 09:01, Karthik Nayak wrote:\n>>[snip]\n>> It looks like dropping the list continuations fixes it.\n>>\n>> Supported format names are:\n>>\n>> include::../ref-storage-format.adoc[]\n>>\n>> The payload is passed directly to the reference backend. For the files and\n>> [...]\n>>\n>> Maybe because you are inside an open block? I don’t know.\n>>\n>\n> I don't know either. But this seems to fix it, let me know if it does\n> for you too.\n>\n> --8<--\n>\n> diff --git a/Documentation/config/extensions.adoc\n> b/Documentation/config/extensions.adoc\n> index 3e51da36d3..329d02b3c4 100644\n> --- a/Documentation/config/extensions.adoc\n> +++ b/Documentation/config/extensions.adoc\n> @@ -67,13 +67,13 @@ refStorage:::\n> format and payload (e.g., `reftable:///foo/bar`).\n>\n> Supported format names are:\n> -+\n> +\n> include::../ref-storage-format.adoc[]\n> -+\n> +\n> The payload is passed directly to the reference backend. For the files and\n> reftable backends, this must be a filesystem path where the references will\n> be stored. Defaulting to the commondir when no payload is provided. Relative\n> -paths are resolved relative to the $GIT_DIR. Future backends may support\n> +paths are resolved relative to the `$GIT_DIR`. Future backends may support\n> other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n> --\n> +\n>\n>\n>>>[snip]\n\nYeah it does. Thanks!\n"},{"id":"536978","messageId":"CAOLa=ZT6ws=CMVcrktnN2MAahosKYHHccgz-8E5+fUHbW9FNFw@mail.gmail.com","threadId":"64513","inReplyTo":"78ade921-321c-493e-ae4a-dbada55b0fff@app.fastmail.com","subject":"Re: [PATCH v8 5/6] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-24T15:05:25Z","receivedAt":"2026-02-24T15:05:27Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Tue, Feb 24, 2026, at 14:09, Karthik Nayak wrote:\n>> \"Kristoffer Haugsbakk\" writes:\n>>\n>>> On Mon, Feb 23, 2026, at 09:01, Karthik Nayak wrote:\n>>>[snip]\n>>> It looks like dropping the list continuations fixes it.\n>>>\n>>> Supported format names are:\n>>>\n>>> include::../ref-storage-format.adoc[]\n>>>\n>>> The payload is passed directly to the reference backend. For the files and\n>>> [...]\n>>>\n>>> Maybe because you are inside an open block? I don’t know.\n>>>\n>>\n>> I don't know either. But this seems to fix it, let me know if it does\n>> for you too.\n>>\n>> --8<--\n>>\n>> diff --git a/Documentation/config/extensions.adoc\n>> b/Documentation/config/extensions.adoc\n>> index 3e51da36d3..329d02b3c4 100644\n>> --- a/Documentation/config/extensions.adoc\n>> +++ b/Documentation/config/extensions.adoc\n>> @@ -67,13 +67,13 @@ refStorage:::\n>> format and payload (e.g., `reftable:///foo/bar`).\n>>\n>> Supported format names are:\n>> -+\n>> +\n>> include::../ref-storage-format.adoc[]\n>> -+\n>> +\n>> The payload is passed directly to the reference backend. For the files and\n>> reftable backends, this must be a filesystem path where the references will\n>> be stored. Defaulting to the commondir when no payload is provided. Relative\n>> -paths are resolved relative to the $GIT_DIR. Future backends may support\n>> +paths are resolved relative to the `$GIT_DIR`. Future backends may support\n>> other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n>> --\n>> +\n>>\n>>\n>>>>[snip]\n>\n> Yeah it does. Thanks!\n\nAwesome. Thanks for noticing.\n"},{"id":"537068","messageId":"874in5nr5p.fsf@iotcl.com","threadId":"64513","inReplyTo":"20260223-kn-alternate-ref-dir-v8-6-0509c132a203@gmail.com","subject":"Re: [PATCH v8 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-02-25T08:50:10Z","receivedAt":"2026-02-25T08:50:24Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"Karthik Nayak writes:\n\n> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n> index 9912433b8c..1a7b8eadba 100755\n> --- a/t/t1423-ref-backend.sh\n> +++ b/t/t1423-ref-backend.sh\n> @@ -138,22 +189,92 @@ do\n> \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n> \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n> \n> -\t\t\t\tgit config set core.repositoryformatversion 1 &&\n> -\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n> -\n> -\t\t\t\tgit worktree add ../wt 2\n> -\t\t\t) &&\n> +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n> +\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n> \n> -\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n> -\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n> -\t\t\t! test_cmp expect actual &&\n> +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n> +\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n> +\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n> +\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n> +\t\t\t\t! test_cmp expect actual &&\n> \n> -\t\t\tgit -C wt rev-parse 2 >expect &&\n> -\t\t\tgit -C wt rev-parse HEAD >actual &&\n> -\t\t\ttest_cmp expect actual\n> +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n> +\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n> +\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n> +\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n> +\t\t\t\ttest_cmp expect actual\n> +\t\t\t)\n> \t\t'\n> \tdone # closes dir\n> +\n> +\ttest_expect_success \"migrating repository to $to_format with alternate refs directory\" '\n> +\t\ttest_when_finished \"rm -rf repo refdir\" &&\n> +\t\tmkdir refdir &&\n> +\t\tGIT_REFERENCE_BACKEND=\"${from_format}://$(pwd)/refdir\" git init repo &&\n> +\t\t(\n> +\t\t\tcd repo &&\n> +\n> +\t\t\ttest_commit 1 &&\n> +\t\t\ttest_commit 2 &&\n> +\t\t\ttest_commit 3 &&\n> +\n> +\t\t\tgit refs migrate --ref-format=$to_format &&\n> +\t\t\tgit refs list >out &&\n> +\t\t\ttest_grep \"refs/tags/1\"\tout &&\n> +\t\t\ttest_grep \"refs/tags/2\"\tout &&\n> +\t\t\ttest_grep \"refs/tags/3\"\tout\n> +\t\t)\n> +\t'\n> +\n> done # closes to_format\n> done # closes from_format\n> \n> +done # closes method\n> +\n> +test_expect_success 'initializing repository with alt ref directory' '\n> +\ttest_when_finished \"rm -rf repo refdir\" &&\n> +\tmkdir refdir &&\n> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n> +\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n> +\tverify_files_exist repo/.git refdir &&\n> +\t(\n> +\t\tcd repo &&\n> +\n> +\t\tgit config get extensions.refstorage >expect &&\n> +\t\techo $BACKEND >actual &&\n\nShouldn't these two be swapped, like:\n\n\t\tgit config get extensions.refstorage >actual &&\n\t\techo $BACKEND >expect &&\n\n> +\t\ttest_cmp expect actual &&\n> +\n> +\t\ttest_commit 1 &&\n> +\t\ttest_commit 2 &&\n> +\t\ttest_commit 3 &&\n> +\t\tgit refs list >out &&\n> +\t\ttest_grep \"refs/tags/1\"\tout &&\n> +\t\ttest_grep \"refs/tags/2\"\tout &&\n> +\t\ttest_grep \"refs/tags/3\"\tout\n> +\t)\n> +'\n> +\n> +test_expect_success 'cloning repository with alt ref directory' '\n> +\ttest_when_finished \"rm -rf source repo refdir\" &&\n> +\tmkdir refdir &&\n> +\n> +\tgit init source &&\n> +\ttest_commit -C source 1 &&\n> +\ttest_commit -C source 2 &&\n> +\ttest_commit -C source 3 &&\n> +\n> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n> +\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n> +\n> +\tgit -C repo config get extensions.refstorage >expect &&\n> +\techo $BACKEND >actual &&\n> +\ttest_cmp expect actual &&\n\nSame here.\n\n> +\n> +\tverify_files_exist repo/.git refdir &&\n> +\n> +\tgit -C source for-each-ref refs/tags/ >expect &&\n> +\tgit -C repo for-each-ref refs/tags/ >actual &&\n> +\ttest_cmp expect actual\n> +'\n> +\n> test_done\n>\n> -- \n> 2.53.GIT\n>\n>\n\n-- \nCheers,\nToon\n"},{"id":"537069","messageId":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com","subject":"[PATCH v9 0/6] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:40Z","receivedAt":"2026-02-25T09:40:49Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"While Git allows users to select different reference backends, unlike\nwith objects, there is no flexibility in selecting the reference\ndirectory. Currently, the reference format is obtained from the config\nof the repository and the reference directory is set to the $GIT_DIR.\n\nThis patch extends the config 'extensions.refStorage' to take in\nmultiple forms of inputs:\n\n - A format name alone (e.g., `reftable` or `files`).\n\n - A URI format `://` explicitly specifies both the\n format and payload (e.g., `reftable:///foo/bar`).\n\nWe also add in a new ENV variable GIT_REFERENCE_BACKEND which can be\nused to override the config.\n\nOne use case for this is migration between different backends. On the\nserver side, migrating from the files backend to the newly introduced\nreftable backend can be achieved by running 'git refs migrate'. However,\nfor large repositories with millions of references, this migration can\ntake from seconds to minutes.\n\nFor some background, at GitLab, the criteria for our migration was to\nreduce the downtime of the migrate ideally to zero. So running 'git refs\nmigrate --ref-format=reftable' by itself wouldn't work, since it scales\nwith the number of references and we have repos with millions of\nreferences, so we need to migrate without loosing any information. We\ncame up with the following plan:\n\n 1. Run git-pack-refs(1) and note timestamp of the generated packed-refs\n file.\n 2. Run git refs migrate –dry-run.\n 3. If there are no ongoing reference requests (read/write)\n a. Lock the repository by blocking incoming requests (done on a\n layer above git, in Gitaly [1]).\n b. If the timestamp of the packed-refs file has changed, unlock\n the repo and repeat from step 1.\n c. Apply all the loose refs to the dry-run reftable folder (this\n requires support in Git to write refs to arbitrary folder).\n d. Move the reftable dry-run folder into the GIT_DIR.\n e. Swap the repo config\n f. Unlock repo access\n\nUsing such a route, scales much better since we only have to worry about\nblocking the repository by O(ref written between #1 and #3a) and not\nO(refs in repo). But for doing so, we need to be able to write to a\narbitrary reference backend + path. This is to add the missing\nreferences to the dry-run reftable folder. This series, achieves that.\n\nSince there was a long gap between v3 <> v4, the version 4 onward is\nbased on top of 2258446484 (RelNotes: correct \"fast-import\" option name,\n2026-01-30).\n\n[1]: https://gitlab.com/gitlab-org/gitaly\n\n---\nChanges in v9:\n- There was a issue with how the docs were parsed, causing the list to\n not be rendered correctly.\n- Some small other nits.\n- Link to v8: https://patch.msgid.link/20260223-kn-alternate-ref-dir-v8-0-0509c132a203@gmail.com\n\nChanges in v8:\n- Fix a typo/grammar in commit 4.\n- In the final commits tests, avoid creating a file for text\n comparison.\n- Link to v7: https://patch.msgid.link/20260219-kn-alternate-ref-dir-v7-0-16f27860dbdf@gmail.com\n\nChanges in v7:\n- Add more details in the commit messages.\n- Cleanup some whitespace.\n- Reorder the commits to be group related changes together.\n- Add checks for stubs in the tests when creating new repos.\n- Link to v6: https://patch.msgid.link/20260214-kn-alternate-ref-dir-v6-0-86a82c77cf59@gmail.com\n\nChanges in v6:\n- The biggest change in this version is that we now support using the\n environment variable with 'git-clone(1)' and 'git-init(1)'. In such\n situations, the alternate reference directory is created and the\n config is added to the repository.\n- Add a new commit which moves stub creation/removal to the generic\n layer.\n- Cleanup logic flow in `refs_compute_filesystem_location()`.\n- Add more tests for usage with 'git-clone(1)', 'git-init(1)' and\n migration of repositories using alternate refs backend.\n- Fixup documentation, commit messages and typos.\n- Link to v5: https://patch.msgid.link/20260209-kn-alternate-ref-dir-v5-0-740899834ceb@gmail.com\n\nChanges in v5:\n- Moved around the commits, to ensure that the code to handle the config\n in the backend is first. Previously, we added the config first, which\n meant the commit allowed users to provide a URI but it was simply\n ignore.\n- Fix typos and grammar and rename variables.\n- Clean up the description and documentation to actually specify\n protocol over location.\n- Avoid an extra memory allocation by detaching the strbuf value.\n- Link to v4: https://patch.msgid.link/20260202-kn-alternate-ref-dir-v4-0-3b30430411e3@gmail.com\n\nChanges in v4:\n- Mostly re-wrote the code to also support worktree. Now, the existing\n backends will store worktree references in 'ref_dir/worktrees/wt_id'\n and add corresponding stubs in 'git_dir/worktrees/wt_id'.\n- We also support relative paths in the reference directories. These\n relative paths are resolved relative to the GIT_DIR.\n- Link to v3: https://patch.msgid.link/20251201-kn-alternate-ref-dir-v3-0-c11b946bc2fa@gmail.com\n\nChanges in v3:\n- Cleanup some stale code which wasn't removed.\n- Localize strings which will be output to the user.\n- Remove additional defensive checks which are not needed.\n- Link to v2: https://patch.msgid.link/20251126-kn-alternate-ref-dir-v2-0-8b9f6f18f635@gmail.com\n\nChanges in v2:\n- Added more clarification and proper intent in the cover message.\n- Changed the format from '://' to\n `://` as it much clearer.\n- Added logic to check for the '//' in the provided URI and a test for\n the same.\n- In the tests:\n - Use test_must_fail() instead of ! git\n - Fix looped tests not using the variables correctly and ensure that\n the test description is correct.\n- Link to v1: https://patch.msgid.link/20251119-kn-alternate-ref-dir-v1-0-4cf4a94c8bed@gmail.com\n\n---\n Documentation/config/extensions.adoc | 16 +-\n Documentation/git.adoc | 5 +\n builtin/clone.c | 9 +-\n builtin/worktree.c | 34 +++++\n environment.h | 1 +\n refs.c | 126 +++++++++++++++-\n refs.h | 13 ++\n refs/files-backend.c | 23 ++-\n refs/packed-backend.c | 5 +\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 14 ++\n refs/reftable-backend.c | 61 ++------\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 96 ++++++++++--\n setup.h | 4 +-\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 280 +++++++++++++++++++++++++++++++++++\n 18 files changed, 625 insertions(+), 81 deletions(-)\n\nKarthik Nayak (6):\n setup: don't modify repo in `create_reference_database()`\n refs: extract out `refs_create_refdir_stubs()`\n refs: move out stub modification to generic layer\n refs: receive and use the reference storage payload\n refs: allow reference location in refstorage config\n refs: add GIT_REFERENCE_BACKEND to specify reference backend\n\nRange-diff versus v8:\n\n1: 9f1978e991 = 1: 71504213ca setup: don't modify repo in `create_reference_database()`\n2: 75013d6874 ! 2: f372287ec6 refs: extract out `refs_create_refdir_stubs()`\n @@ refs.h: void ref_iterator_free(struct ref_iterator *ref_iterator);\n + * While it is necessary within the files backend, newer backends may not\n + * follow the same structure. To go around this, we create stubs as necessary.\n + *\n -+ * If provided with a 'refs_heads_msg', we create the 'refs/heads/head' file\n ++ * If provided with a 'refs_heads_content', we create the 'refs/heads/head' file\n + * with the provided message.\n + */\n +void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n -+\t\t\t const char *refs_heads_msg);\n ++\t\t\t const char *refs_heads_content);\n +\n #endif /* REFS_H */\n \n3: 97bef9c5c0 = 3: b79ac00a3d refs: move out stub modification to generic layer\n4: ed55f79701 = 4: d0ffa07dfc refs: receive and use the reference storage payload\n5: 5902a4588c ! 5: bf17494952 refs: allow reference location in refstorage config\n @@ Documentation/config/extensions.adoc: For historical reasons, this extension is\n + format and payload (e.g., `reftable:///foo/bar`).\n +\n +Supported format names are:\n -++\n ++\n include::../ref-storage-format.adoc[]\n -++\n ++\n +The payload is passed directly to the reference backend. For the files and\n +reftable backends, this must be a filesystem path where the references will\n +be stored. Defaulting to the commondir when no payload is provided. Relative\n -+paths are resolved relative to the $GIT_DIR. Future backends may support\n ++paths are resolved relative to the `$GIT_DIR`. Future backends may support\n +other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n6: 7b0f103dbf ! 6: d1f3323df6 refs: add GIT_REFERENCE_BACKEND to specify reference backend\n @@ t/t1423-ref-backend.sh: do\n +\t(\n +\t\tcd repo &&\n +\n -+\t\tgit config get extensions.refstorage >expect &&\n -+\t\techo $BACKEND >actual &&\n ++\t\tgit config get extensions.refstorage >actual &&\n ++\t\techo $BACKEND >expect &&\n +\t\ttest_cmp expect actual &&\n +\n +\t\ttest_commit 1 &&\n @@ t/t1423-ref-backend.sh: do\n +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n +\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n +\n -+\tgit -C repo config get extensions.refstorage >expect &&\n -+\techo $BACKEND >actual &&\n ++\tgit -C repo config get extensions.refstorage >actual &&\n ++\techo $BACKEND >expect &&\n +\ttest_cmp expect actual &&\n +\n +\tverify_files_exist repo/.git refdir &&\n\n\nbase-commit: 22584464849815268419fd9d2eba307362360db1\nchange-id: 20251105-kn-alternate-ref-dir-3e572e8cd0ef\n\nThanks\n- Karthik\n\n"},{"id":"537070","messageId":"20260225-kn-alternate-ref-dir-v9-1-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","subject":"[PATCH v9 1/6] setup: don't modify repo in `create_reference_database()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:41Z","receivedAt":"2026-02-25T09:40:50Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The `create_reference_database()` function is used to create the\nreference database during initialization of a repository. The function\ncalls `repo_set_ref_storage_format()` to set the repositories reference\nformat. This is an unexpected side-effect of the function. More so\nbecause the function is only called in two locations:\n\n 1. During git-init(1) where the value is propagated from the `struct\n repository_format repo_fmt` value.\n\n 2. During git-clone(1) where the value is propagated from the\n `the_repository` value.\n\nThe former is valid, however the flow already calls\n`repo_set_ref_storage_format()`, so this effort is simply duplicated.\nThe latter sets the existing value in `the_repository` back to itself.\nWhile this is okay for now, introduction of more fields in\n`repo_set_ref_storage_format()` would cause issues, especially\ndynamically allocated strings, where we would free/allocate the same\nstring back into `the_repostiory`.\n\nTo avoid all this confusion, clean up the function to no longer take in\nand set the repo's reference storage format.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 2 +-\n setup.c | 7 ++-----\n setup.h | 3 +--\n 3 files changed, 4 insertions(+), 8 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex b40cee5968..cd43bb5aa2 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1442,7 +1442,7 @@ int cmd_clone(int argc,\n \thash_algo = hash_algo_by_ptr(transport_get_hash_algo(transport));\n \tinitialize_repository_version(hash_algo, the_repository->ref_storage_format, 1);\n \trepo_set_hash_algo(the_repository, hash_algo);\n-\tcreate_reference_database(the_repository->ref_storage_format, NULL, 1);\n+\tcreate_reference_database(NULL, 1);\n \n \t/*\n \t * Before fetching from the remote, download and install bundle\ndiff --git a/setup.c b/setup.c\nindex b723f8b339..1fc9ae3872 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -2359,14 +2359,12 @@ static int is_reinit(void)\n \treturn ret;\n }\n \n-void create_reference_database(enum ref_storage_format ref_storage_format,\n-\t\t\t const char *initial_branch, int quiet)\n+void create_reference_database(const char *initial_branch, int quiet)\n {\n \tstruct strbuf err = STRBUF_INIT;\n \tchar *to_free = NULL;\n \tint reinit = is_reinit();\n \n-\trepo_set_ref_storage_format(the_repository, ref_storage_format);\n \tif (ref_store_create_on_disk(get_main_ref_store(the_repository), 0, &err))\n \t\tdie(\"failed to set up refs db: %s\", err.buf);\n \n@@ -2701,8 +2699,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n \t\t\t\t &repo_fmt, init_shared_repository);\n \n \tif (!(flags & INIT_DB_SKIP_REFDB))\n-\t\tcreate_reference_database(repo_fmt.ref_storage_format,\n-\t\t\t\t\t initial_branch, flags & INIT_DB_QUIET);\n+\t\tcreate_reference_database(initial_branch, flags & INIT_DB_QUIET);\n \tcreate_object_directory();\n \n \tif (repo_settings_get_shared_repository(the_repository)) {\ndiff --git a/setup.h b/setup.h\nindex d55dcc6608..ddb9f6701c 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -240,8 +240,7 @@ int init_db(const char *git_dir, const char *real_git_dir,\n void initialize_repository_version(int hash_algo,\n \t\t\t\t enum ref_storage_format ref_storage_format,\n \t\t\t\t int reinit);\n-void create_reference_database(enum ref_storage_format ref_storage_format,\n-\t\t\t const char *initial_branch, int quiet);\n+void create_reference_database(const char *initial_branch, int quiet);\n \n /*\n * NOTE NOTE NOTE!!\n\n-- \n2.53.GIT\n\n"},{"id":"537071","messageId":"20260225-kn-alternate-ref-dir-v9-2-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","subject":"[PATCH v9 2/6] refs: extract out `refs_create_refdir_stubs()`","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:42Z","receivedAt":"2026-02-25T09:40:51Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"For Git to recognize a directory as a Git directory, it requires the\ndirectory to contain:\n\n 1. 'HEAD' file\n 2. 'objects/' directory\n 3. 'refs/' directory\n\nHere, #1 and #3 are part of the reference storage mechanism,\nspecifically the files backend. Since then, newer backends such as the\nreftable backend have moved to using their own path ('reftable/') for\nstoring references. But to ensure Git still recognizes the directory as\na Git directory, we create stubs.\n\nThere are two locations where we create stubs:\n\n- In 'refs/reftable-backend.c' when creating the reftable backend.\n- In 'clone.c' before spawning transport helpers.\n\nIn a following commit, we'll add another instance. So instead of\nrepeating the code, let's extract out this code to\n`refs_create_refdir_stubs()` and use it.\n\nSigned-off-by: Karthik Nayak \n---\n builtin/clone.c | 7 +------\n refs.c | 23 +++++++++++++++++++++++\n refs.h | 13 +++++++++++++\n refs/reftable-backend.c | 14 ++------------\n 4 files changed, 39 insertions(+), 18 deletions(-)\n\ndiff --git a/builtin/clone.c b/builtin/clone.c\nindex cd43bb5aa2..697c5bb5cb 100644\n--- a/builtin/clone.c\n+++ b/builtin/clone.c\n@@ -1225,12 +1225,7 @@ int cmd_clone(int argc,\n \tinitialize_repository_version(GIT_HASH_UNKNOWN,\n \t\t\t\t the_repository->ref_storage_format, 1);\n \n-\tstrbuf_addf(&buf, \"%s/HEAD\", git_dir);\n-\twrite_file(buf.buf, \"ref: refs/heads/.invalid\");\n-\n-\tstrbuf_reset(&buf);\n-\tstrbuf_addf(&buf, \"%s/refs\", git_dir);\n-\tsafe_create_dir(the_repository, buf.buf, 1);\n+\trefs_create_refdir_stubs(the_repository, git_dir, NULL);\n \n \t/*\n \t * additional config can be injected with -c, make sure it's included\ndiff --git a/refs.c b/refs.c\nindex 627b7f8698..77b93d655b 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2163,6 +2163,29 @@ const char *refs_resolve_ref_unsafe(struct ref_store *refs,\n \treturn NULL;\n }\n \n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_content)\n+{\n+\tstruct strbuf path = STRBUF_INIT;\n+\n+\tstrbuf_addf(&path, \"%s/HEAD\", refdir);\n+\twrite_file(path.buf, \"ref: refs/heads/.invalid\");\n+\tadjust_shared_perm(repo, path.buf);\n+\n+\tstrbuf_reset(&path);\n+\tstrbuf_addf(&path, \"%s/refs\", refdir);\n+\tsafe_create_dir(repo, path.buf, 1);\n+\n+\tif (refs_heads_content) {\n+\t\tstrbuf_reset(&path);\n+\t\tstrbuf_addf(&path, \"%s/refs/heads\", refdir);\n+\t\twrite_file(path.buf, \"%s\", refs_heads_content);\n+\t\tadjust_shared_perm(repo, path.buf);\n+\t}\n+\n+\tstrbuf_release(&path);\n+}\n+\n /* backend functions */\n int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n {\ndiff --git a/refs.h b/refs.h\nindex f0abfa1d93..a35fdc6642 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -1427,4 +1427,17 @@ void ref_iterator_free(struct ref_iterator *ref_iterator);\n int do_for_each_ref_iterator(struct ref_iterator *iter,\n \t\t\t each_ref_fn fn, void *cb_data);\n \n+/*\n+ * Git only recognizes a directory as a repository if it contains:\n+ * - HEAD file\n+ * - refs/ folder\n+ * While it is necessary within the files backend, newer backends may not\n+ * follow the same structure. To go around this, we create stubs as necessary.\n+ *\n+ * If provided with a 'refs_heads_content', we create the 'refs/heads/head' file\n+ * with the provided message.\n+ */\n+void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n+\t\t\t const char *refs_heads_content);\n+\n #endif /* REFS_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex fe74af73af..d8651fe779 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,18 +491,8 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"ref: refs/heads/.invalid\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tsafe_create_dir(the_repository, sb.buf, 1);\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\twrite_file(sb.buf, \"this repository uses the reftable format\");\n-\tadjust_shared_perm(the_repository, sb.buf);\n+\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n+\t\t\t\t \"this repository uses the reftable format\");\n \n \tstrbuf_release(&sb);\n \treturn 0;\n\n-- \n2.53.GIT\n\n"},{"id":"537072","messageId":"20260225-kn-alternate-ref-dir-v9-3-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","subject":"[PATCH v9 3/6] refs: move out stub modification to generic layer","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:43Z","receivedAt":"2026-02-25T09:40:52Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"When creating the reftable reference backend on disk, we create stubs to\nensure that the directory can be recognized as a Git repository. This is\ndone by calling `refs_create_refdir_stubs()`. Move this to the generic\nlayer as this is needed for all backends excluding from the files\nbackends. In an upcoming commit where we introduce alternate reference\nbackend locations, we'll have to also create stubs in the $GIT_DIR\nirrespective of the backend being used. This commit builds the base to\nadd that logic.\n\nSimilarly, move the logic for deletion of stubs to the generic layer.\nThe files backend recursively calls the remove function of the\n'packed-backend', here skip calling the generic function since that\nwould try to delete stubs.\n\nSigned-off-by: Karthik Nayak \n---\n refs.c | 47 +++++++++++++++++++++++++++++++++++++++++++++--\n refs/files-backend.c | 6 +++++-\n refs/reftable-backend.c | 27 ---------------------------\n 3 files changed, 50 insertions(+), 30 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex 77b93d655b..c83af63dc5 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2189,12 +2189,55 @@ void refs_create_refdir_stubs(struct repository *repo, const char *refdir,\n /* backend functions */\n int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err)\n {\n-\treturn refs->be->create_on_disk(refs, flags, err);\n+\tint ret = refs->be->create_on_disk(refs, flags, err);\n+\n+\tif (!ret &&\n+\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\tstruct strbuf msg = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n+\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n+\t\tstrbuf_release(&msg);\n+\t}\n+\n+\treturn ret;\n }\n \n int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n {\n-\treturn refs->be->remove_on_disk(refs, err);\n+\tint ret = refs->be->remove_on_disk(refs, err);\n+\n+\tif (!ret &&\n+\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\tstruct strbuf sb = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n+\t\tif (unlink(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\t\tstrbuf_reset(&sb);\n+\n+\t\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->gitdir);\n+\t\tif (unlink(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete stub heads: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\t\tstrbuf_reset(&sb);\n+\n+\t\tstrbuf_addf(&sb, \"%s/refs\", refs->gitdir);\n+\t\tif (rmdir(sb.buf) < 0) {\n+\t\t\tstrbuf_addf(err, \"could not delete refs directory: %s\",\n+\t\t\t\t strerror(errno));\n+\t\t\tret = -1;\n+\t\t}\n+\n+\t\tstrbuf_release(&sb);\n+\t}\n+\n+\treturn ret;\n }\n \n int repo_resolve_gitlink_ref(struct repository *r,\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex 240d3c3b26..d3f6423261 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -3700,7 +3700,11 @@ static int files_ref_store_remove_on_disk(struct ref_store *ref_store,\n \tif (for_each_root_ref(refs, remove_one_root_ref, &data) < 0)\n \t\tret = -1;\n \n-\tif (ref_store_remove_on_disk(refs->packed_ref_store, err) < 0)\n+\t/*\n+\t * Directly access the cleanup functions for packed-refs as the generic function\n+\t * would try to clear stubs which isn't required for the files backend.\n+\t */\n+\tif (refs->packed_ref_store->be->remove_on_disk(refs->packed_ref_store, err) < 0)\n \t\tret = -1;\n \n \tstrbuf_release(&sb);\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex d8651fe779..6ce7f9bb8e 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -491,9 +491,6 @@ static int reftable_be_create_on_disk(struct ref_store *ref_store,\n \tsafe_create_dir(the_repository, sb.buf, 1);\n \tstrbuf_reset(&sb);\n \n-\trefs_create_refdir_stubs(the_repository, refs->base.gitdir,\n-\t\t\t\t \"this repository uses the reftable format\");\n-\n \tstrbuf_release(&sb);\n \treturn 0;\n }\n@@ -519,30 +516,6 @@ static int reftable_be_remove_on_disk(struct ref_store *ref_store,\n \t\t\t strerror(errno));\n \t\tret = -1;\n \t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/HEAD\", refs->base.gitdir);\n-\tif (unlink(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs/heads\", refs->base.gitdir);\n-\tif (unlink(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete stub heads: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n-\tstrbuf_reset(&sb);\n-\n-\tstrbuf_addf(&sb, \"%s/refs\", refs->base.gitdir);\n-\tif (rmdir(sb.buf) < 0) {\n-\t\tstrbuf_addf(err, \"could not delete refs directory: %s\",\n-\t\t\t strerror(errno));\n-\t\tret = -1;\n-\t}\n \n \tstrbuf_release(&sb);\n \treturn ret;\n\n-- \n2.53.GIT\n\n"},{"id":"537073","messageId":"20260225-kn-alternate-ref-dir-v9-4-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","subject":"[PATCH v9 4/6] refs: receive and use the reference storage payload","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:44Z","receivedAt":"2026-02-25T09:40:54Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"An upcoming commit will add support for providing an URI via the\n'extensions.refStorage' config. The URI will contain the reference\nbackend and a corresponding payload. The payload can be then used for\nproviding an alternate locations for the reference backend.\n\nTo prepare for this, modify the existing backends to accept such an\nargument when initializing via the 'init()' function. Both the files\nand reftable backends will parse the information to be filesystem paths\nto store references. Given that no callers pass any payload yet this is\nessentially a no-op change for now.\n\nTo enable this, provide a 'refs_compute_filesystem_location()' function\nwhich will parse the current 'gitdir' and the 'payload' to provide the\nfinal reference directory and common reference directory (if working in\na linked worktree).\n\nThe documentation and tests will be added alongside the extension of the\nconfig variable.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n refs.c | 40 +++++++++++++++++++++++++++++++++++++++-\n refs/files-backend.c | 17 ++++++++++++-----\n refs/packed-backend.c | 5 +++++\n refs/packed-backend.h | 1 +\n refs/refs-internal.h | 14 ++++++++++++++\n refs/reftable-backend.c | 24 ++++++++++++++----------\n 6 files changed, 85 insertions(+), 16 deletions(-)\n\ndiff --git a/refs.c b/refs.c\nindex c83af63dc5..ba2573eb7a 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -5,6 +5,7 @@\n #define USE_THE_REPOSITORY_VARIABLE\n \n #include \"git-compat-util.h\"\n+#include \"abspath.h\"\n #include \"advice.h\"\n #include \"config.h\"\n #include \"environment.h\"\n@@ -2290,7 +2291,7 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, gitdir, flags);\n+\trefs = be->init(repo, NULL, gitdir, flags);\n \treturn refs;\n }\n \n@@ -3468,3 +3469,40 @@ const char *ref_transaction_error_msg(enum ref_transaction_error err)\n \t\treturn \"unknown failure\";\n \t}\n }\n+\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\n+\t*is_worktree = get_common_dir_noenv(ref_common_dir, gitdir);\n+\n+\tif (!payload) {\n+\t\t/*\n+\t\t * We can use the 'gitdir' as the 'refdir' without appending the\n+\t\t * worktree path, as the 'gitdir' here is already the worktree\n+\t\t * path and is different from 'commondir' denoted by 'ref_common_dir'.\n+\t\t */\n+\t\tstrbuf_addstr(refdir, gitdir);\n+\t\treturn;\n+\t}\n+\n+\tif (!is_absolute_path(payload)) {\n+\t\tstrbuf_addf(&sb, \"%s/%s\", ref_common_dir->buf, payload);\n+\t\tstrbuf_realpath(ref_common_dir, sb.buf, 1);\n+\t} else {\n+\t\tstrbuf_realpath(ref_common_dir, payload, 1);\n+\t}\n+\n+\tstrbuf_addbuf(refdir, ref_common_dir);\n+\n+\tif (*is_worktree) {\n+\t\tconst char *wt_id = strrchr(gitdir, '/');\n+\t\tif (!wt_id)\n+\t\t\tBUG(\"worktree path does not contain slash\");\n+\t\tstrbuf_addf(refdir, \"/worktrees/%s\", wt_id + 1);\n+\t}\n+\n+\tstrbuf_release(&sb);\n+}\ndiff --git a/refs/files-backend.c b/refs/files-backend.c\nindex d3f6423261..9cde3ba724 100644\n--- a/refs/files-backend.c\n+++ b/refs/files-backend.c\n@@ -106,19 +106,24 @@ static void clear_loose_ref_cache(struct files_ref_store *refs)\n * set of caches.\n */\n static struct ref_store *files_ref_store_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags)\n {\n \tstruct files_ref_store *refs = xcalloc(1, sizeof(*refs));\n \tstruct ref_store *ref_store = (struct ref_store *)refs;\n-\tstruct strbuf sb = STRBUF_INIT;\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n+\tbool is_worktree;\n+\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n \n-\tbase_ref_store_init(ref_store, repo, gitdir, &refs_be_files);\n+\tbase_ref_store_init(ref_store, repo, refdir.buf, &refs_be_files);\n \trefs->store_flags = flags;\n-\tget_common_dir_noenv(&sb, gitdir);\n-\trefs->gitcommondir = strbuf_detach(&sb, NULL);\n+\trefs->gitcommondir = strbuf_detach(&ref_common_dir, NULL);\n \trefs->packed_ref_store =\n-\t\tpacked_ref_store_init(repo, refs->gitcommondir, flags);\n+\t\tpacked_ref_store_init(repo, NULL, refs->gitcommondir, flags);\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n \trepo_config_get_bool(repo, \"core.prefersymlinkrefs\", &refs->prefer_symlink_refs);\n \n@@ -126,6 +131,8 @@ static struct ref_store *files_ref_store_init(struct repository *repo,\n \tchdir_notify_reparent(\"files-backend $GIT_COMMONDIR\",\n \t\t\t &refs->gitcommondir);\n \n+\tstrbuf_release(&refdir);\n+\n \treturn ref_store;\n }\n \ndiff --git a/refs/packed-backend.c b/refs/packed-backend.c\nindex 4ea0c12299..e7bb9f10f9 100644\n--- a/refs/packed-backend.c\n+++ b/refs/packed-backend.c\n@@ -211,7 +211,12 @@ static size_t snapshot_hexsz(const struct snapshot *snapshot)\n \treturn snapshot->refs->base.repo->hash_algo->hexsz;\n }\n \n+/*\n+ * Since packed-refs is only stored in the common dir, don't parse the\n+ * payload and rely on the files-backend to set 'gitdir' correctly.\n+ */\n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload UNUSED,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags)\n {\ndiff --git a/refs/packed-backend.h b/refs/packed-backend.h\nindex 9481d5e7c2..2c2377a356 100644\n--- a/refs/packed-backend.h\n+++ b/refs/packed-backend.h\n@@ -14,6 +14,7 @@ struct ref_transaction;\n */\n \n struct ref_store *packed_ref_store_init(struct repository *repo,\n+\t\t\t\t\tconst char *payload,\n \t\t\t\t\tconst char *gitdir,\n \t\t\t\t\tunsigned int store_flags);\n \ndiff --git a/refs/refs-internal.h b/refs/refs-internal.h\nindex c7d2a6e50b..4fb8fdb872 100644\n--- a/refs/refs-internal.h\n+++ b/refs/refs-internal.h\n@@ -389,6 +389,7 @@ struct ref_store;\n * the ref_store and to record the ref_store for later lookup.\n */\n typedef struct ref_store *ref_store_init_fn(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int flags);\n /*\n@@ -666,4 +667,17 @@ enum ref_transaction_error refs_verify_refnames_available(struct ref_store *refs\n \t\t\t\t\t unsigned int initial_transaction,\n \t\t\t\t\t struct strbuf *err);\n \n+/*\n+ * Given a gitdir and the reference storage payload provided, retrieve the\n+ * 'refdir' and 'ref_common_dir'. The former is where references should be\n+ * stored for the current worktree, the latter is the common reference\n+ * directory if working with a linked worktree. If working with the main\n+ * worktree, both values will be the same.\n+ *\n+ * This is used by backends that store references in the repository directly.\n+ */\n+void refs_compute_filesystem_location(const char *gitdir, const char *payload,\n+\t\t\t\t bool *is_worktree, struct strbuf *refdir,\n+\t\t\t\t struct strbuf *ref_common_dir);\n+\n #endif /* REFS_REFS_INTERNAL_H */\ndiff --git a/refs/reftable-backend.c b/refs/reftable-backend.c\nindex 6ce7f9bb8e..0e220d6bb5 100644\n--- a/refs/reftable-backend.c\n+++ b/refs/reftable-backend.c\n@@ -372,18 +372,24 @@ static int reftable_be_fsync(int fd)\n }\n \n static struct ref_store *reftable_be_init(struct repository *repo,\n+\t\t\t\t\t const char *payload,\n \t\t\t\t\t const char *gitdir,\n \t\t\t\t\t unsigned int store_flags)\n {\n \tstruct reftable_ref_store *refs = xcalloc(1, sizeof(*refs));\n+\tstruct strbuf ref_common_dir = STRBUF_INIT;\n+\tstruct strbuf refdir = STRBUF_INIT;\n \tstruct strbuf path = STRBUF_INIT;\n-\tint is_worktree;\n+\tbool is_worktree;\n \tmode_t mask;\n \n \tmask = umask(0);\n \tumask(mask);\n \n-\tbase_ref_store_init(&refs->base, repo, gitdir, &refs_be_reftable);\n+\trefs_compute_filesystem_location(gitdir, payload, &is_worktree, &refdir,\n+\t\t\t\t\t &ref_common_dir);\n+\n+\tbase_ref_store_init(&refs->base, repo, refdir.buf, &refs_be_reftable);\n \tstrmap_init(&refs->worktree_backends);\n \trefs->store_flags = store_flags;\n \trefs->log_all_ref_updates = repo_settings_get_log_all_ref_updates(repo);\n@@ -419,14 +425,11 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t/*\n \t * Set up the main reftable stack that is hosted in GIT_COMMON_DIR.\n \t * This stack contains both the shared and the main worktree refs.\n-\t *\n-\t * Note that we don't try to resolve the path in case we have a\n-\t * worktree because `get_common_dir_noenv()` already does it for us.\n \t */\n-\tis_worktree = get_common_dir_noenv(&path, gitdir);\n+\tstrbuf_addbuf(&path, &ref_common_dir);\n \tif (!is_worktree) {\n \t\tstrbuf_reset(&path);\n-\t\tstrbuf_realpath(&path, gitdir, 0);\n+\t\tstrbuf_realpath(&path, ref_common_dir.buf, 0);\n \t}\n \tstrbuf_addstr(&path, \"/reftable\");\n \trefs->err = reftable_backend_init(&refs->main_backend, path.buf,\n@@ -443,10 +446,9 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \t * do it efficiently.\n \t */\n \tif (is_worktree) {\n-\t\tstrbuf_reset(&path);\n-\t\tstrbuf_addf(&path, \"%s/reftable\", gitdir);\n+\t\tstrbuf_addstr(&refdir, \"/reftable\");\n \n-\t\trefs->err = reftable_backend_init(&refs->worktree_backend, path.buf,\n+\t\trefs->err = reftable_backend_init(&refs->worktree_backend, refdir.buf,\n \t\t\t\t\t\t &refs->write_options);\n \t\tif (refs->err)\n \t\t\tgoto done;\n@@ -456,6 +458,8 @@ static struct ref_store *reftable_be_init(struct repository *repo,\n \n done:\n \tassert(refs->err != REFTABLE_API_ERROR);\n+\tstrbuf_release(&ref_common_dir);\n+\tstrbuf_release(&refdir);\n \tstrbuf_release(&path);\n \treturn &refs->base;\n }\n\n-- \n2.53.GIT\n\n"},{"id":"537074","messageId":"20260225-kn-alternate-ref-dir-v9-5-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","subject":"[PATCH v9 5/6] refs: allow reference location in refstorage config","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:45Z","receivedAt":"2026-02-25T09:40:55Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"The 'extensions.refStorage' config is used to specify the reference\nbackend for a given repository. Both the 'files' and 'reftable' backends\nutilize the $GIT_DIR as the reference folder by default in\n`get_main_ref_store()`.\n\nSince the reference backends are pluggable, this means that they could\nwork with out-of-tree reference directories too. Extend the 'refStorage'\nconfig to also support taking an URI input, where users can specify the\nreference backend and the location.\n\nAdd the required changes to obtain and propagate this value to the\nindividual backends. Add the necessary documentation and tests.\n\nTraditionally, for linked worktrees, references were stored in the\n'$GIT_DIR/worktrees/' path. But when using an alternate reference\nstorage path, it doesn't make sense to store the main worktree\nreferences in the new path, and the linked worktree references in the\n$GIT_DIR. So, let's store linked worktree references in\n'$ALTERNATE_REFERENCE_DIR/worktrees/'. To do this, create the\nnecessary files and folders while also adding stubs in the $GIT_DIR path\nto ensure that it is still considered a Git directory.\n\nIdeally, we would want to pass in a `struct worktree *` to individual\nbackends, instead of passing the `gitdir`. This allows them to handle\nworktree specific logic. Currently, that is not possible since the\nworktree code is:\n\n - Tied to using the global `the_repository` variable.\n\n - Is not setup before the reference database during initialization of\n the repository.\n\nAdd a TODO in 'refs.c' to ensure we can eventually make that change.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Karthik Nayak \n---\n Documentation/config/extensions.adoc | 16 +++-\n builtin/worktree.c | 34 ++++++++\n refs.c | 6 +-\n repository.c | 9 +-\n repository.h | 8 +-\n setup.c | 34 +++++++-\n setup.h | 1 +\n t/meson.build | 1 +\n t/t1423-ref-backend.sh | 159 +++++++++++++++++++++++++++++++++++\n 9 files changed, 259 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 532456644b..329d02b3c4 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the\n `core.repositoryFormatVersion` setting.\n \n refStorage:::\n-\tSpecify the ref storage format to use. The acceptable values are:\n+\tSpecify the ref storage format and a corresponding payload. The value\n+\tcan be either a format name or a URI:\n +\n --\n+* A format name alone (e.g., `reftable` or `files`).\n+\n+* A URI format `://` explicitly specifies both the\n+ format and payload (e.g., `reftable:///foo/bar`).\n+\n+Supported format names are:\n+\n include::../ref-storage-format.adoc[]\n+\n+The payload is passed directly to the reference backend. For the files and\n+reftable backends, this must be a filesystem path where the references will\n+be stored. Defaulting to the commondir when no payload is provided. Relative\n+paths are resolved relative to the `$GIT_DIR`. Future backends may support\n+other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.\n --\n +\n Note that this setting should only be set by linkgit:git-init[1] or\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..293e808379 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -425,6 +425,39 @@ static int make_worktree_orphan(const char * ref, const struct add_opts *opts,\n \treturn run_command(&cp);\n }\n \n+/*\n+ * References for worktrees are generally stored in '$GIT_DIR/worktrees/'.\n+ * But when using alternate reference directories, we want to store the worktree\n+ * references in '$ALTERNATE_REFERENCE_DIR/worktrees/'.\n+ *\n+ * Create the necessary folder structure to facilitate the same. But to ensure\n+ * that the former path is still considered a Git directory, add stubs.\n+ */\n+static void setup_alternate_ref_dir(struct worktree *wt, const char *wt_git_path)\n+{\n+\tstruct strbuf sb = STRBUF_INIT;\n+\tchar *path;\n+\n+\tpath = wt->repo->ref_storage_payload;\n+\tif (!path)\n+\t\treturn;\n+\n+\tif (!is_absolute_path(path))\n+\t\tstrbuf_addf(&sb, \"%s/\", wt->repo->commondir);\n+\n+\tstrbuf_addf(&sb, \"%s/worktrees\", path);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_addf(&sb, \"/%s\", wt->id);\n+\tsafe_create_dir(wt->repo, sb.buf, 1);\n+\tstrbuf_reset(&sb);\n+\n+\tstrbuf_addf(&sb, \"this worktree stores references in %s/worktrees/%s\",\n+\t\t path, wt->id);\n+\trefs_create_refdir_stubs(wt->repo, wt_git_path, sb.buf);\n+\n+\tstrbuf_release(&sb);\n+}\n+\n static int add_worktree(const char *path, const char *refname,\n \t\t\tconst struct add_opts *opts)\n {\n@@ -518,6 +551,7 @@ static int add_worktree(const char *path, const char *refname,\n \t\tret = error(_(\"could not find created worktree '%s'\"), name);\n \t\tgoto done;\n \t}\n+\tsetup_alternate_ref_dir(wt, sb_repo.buf);\n \twt_refs = get_worktree_ref_store(wt);\n \n \tret = ref_store_create_on_disk(wt_refs, REF_STORE_CREATE_ON_DISK_IS_WORKTREE, &sb);\ndiff --git a/refs.c b/refs.c\nindex ba2573eb7a..ef1902e85c 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2291,7 +2291,11 @@ static struct ref_store *ref_store_init(struct repository *repo,\n \tif (!be)\n \t\tBUG(\"reference backend is unknown\");\n \n-\trefs = be->init(repo, NULL, gitdir, flags);\n+\t/*\n+\t * TODO Send in a 'struct worktree' instead of a 'gitdir', and\n+\t * allow the backend to handle how it wants to deal with worktrees.\n+\t */\n+\trefs = be->init(repo, repo->ref_storage_payload, gitdir, flags);\n \treturn refs;\n }\n \ndiff --git a/repository.c b/repository.c\nindex c7e75215ac..9815f081ef 100644\n--- a/repository.c\n+++ b/repository.c\n@@ -193,9 +193,12 @@ void repo_set_compat_hash_algo(struct repository *repo, int algo)\n }\n \n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format)\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload)\n {\n \trepo->ref_storage_format = format;\n+\tfree(repo->ref_storage_payload);\n+\trepo->ref_storage_payload = xstrdup_or_null(payload);\n }\n \n /*\n@@ -277,7 +280,8 @@ int repo_init(struct repository *repo,\n \n \trepo_set_hash_algo(repo, format.hash_algo);\n \trepo_set_compat_hash_algo(repo, format.compat_hash_algo);\n-\trepo_set_ref_storage_format(repo, format.ref_storage_format);\n+\trepo_set_ref_storage_format(repo, format.ref_storage_format,\n+\t\t\t\t format.ref_storage_payload);\n \trepo->repository_format_worktree_config = format.worktree_config;\n \trepo->repository_format_relative_worktrees = format.relative_worktrees;\n \trepo->repository_format_precious_objects = format.precious_objects;\n@@ -369,6 +373,7 @@ void repo_clear(struct repository *repo)\n \tFREE_AND_NULL(repo->index_file);\n \tFREE_AND_NULL(repo->worktree);\n \tFREE_AND_NULL(repo->submodule_prefix);\n+\tFREE_AND_NULL(repo->ref_storage_payload);\n \n \todb_free(repo->objects);\n \trepo->objects = NULL;\ndiff --git a/repository.h b/repository.h\nindex 6063c4b846..95e2333bad 100644\n--- a/repository.h\n+++ b/repository.h\n@@ -150,6 +150,11 @@ struct repository {\n \n \t/* Repository's reference storage format, as serialized on disk. */\n \tenum ref_storage_format ref_storage_format;\n+\t/*\n+\t * Reference storage information as needed for the backend. This contains\n+\t * only the payload from the reference URI without the schema.\n+\t */\n+\tchar *ref_storage_payload;\n \n \t/* A unique-id for tracing purposes. */\n \tint trace2_repo_id;\n@@ -204,7 +209,8 @@ void repo_set_worktree(struct repository *repo, const char *path);\n void repo_set_hash_algo(struct repository *repo, int algo);\n void repo_set_compat_hash_algo(struct repository *repo, int compat_algo);\n void repo_set_ref_storage_format(struct repository *repo,\n-\t\t\t\t enum ref_storage_format format);\n+\t\t\t\t enum ref_storage_format format,\n+\t\t\t\t const char *payload);\n void initialize_repository(struct repository *repo);\n RESULT_MUST_BE_USED\n int repo_init(struct repository *r, const char *gitdir, const char *worktree);\ndiff --git a/setup.c b/setup.c\nindex 1fc9ae3872..d407f3347b 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -632,6 +632,21 @@ static enum extension_result handle_extension_v0(const char *var,\n \t\treturn EXTENSION_UNKNOWN;\n }\n \n+static void parse_reference_uri(const char *value, char **format,\n+\t\t\t\tchar **payload)\n+{\n+\tconst char *schema_end;\n+\n+\tschema_end = strstr(value, \"://\");\n+\tif (!schema_end) {\n+\t\t*format = xstrdup(value);\n+\t\t*payload = NULL;\n+\t} else {\n+\t\t*format = xstrndup(value, schema_end - value);\n+\t\t*payload = xstrdup_or_null(schema_end + 3);\n+\t}\n+}\n+\n /*\n * Record any new extensions in this function.\n */\n@@ -674,10 +689,17 @@ static enum extension_result handle_extension(const char *var,\n \t\treturn EXTENSION_OK;\n \t} else if (!strcmp(ext, \"refstorage\")) {\n \t\tunsigned int format;\n+\t\tchar *format_str;\n \n \t\tif (!value)\n \t\t\treturn config_error_nonbool(var);\n-\t\tformat = ref_storage_format_by_name(value);\n+\n+\t\tparse_reference_uri(value, &format_str,\n+\t\t\t\t &data->ref_storage_payload);\n+\n+\t\tformat = ref_storage_format_by_name(format_str);\n+\t\tfree(format_str);\n+\n \t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n \t\t\treturn error(_(\"invalid value for '%s': '%s'\"),\n \t\t\t\t \"extensions.refstorage\", value);\n@@ -850,6 +872,7 @@ void clear_repository_format(struct repository_format *format)\n \tstring_list_clear(&format->v1_only_extensions, 0);\n \tfree(format->work_tree);\n \tfree(format->partial_clone);\n+\tfree(format->ref_storage_payload);\n \tinit_repository_format(format);\n }\n \n@@ -1942,7 +1965,8 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\t\trepo_set_compat_hash_algo(the_repository,\n \t\t\t\t\t\t repo_fmt.compat_hash_algo);\n \t\t\trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t\t\t repo_fmt.ref_storage_format);\n+\t\t\t\t\t\t repo_fmt.ref_storage_format,\n+\t\t\t\t\t\t repo_fmt.ref_storage_payload);\n \t\t\tthe_repository->repository_format_worktree_config =\n \t\t\t\trepo_fmt.worktree_config;\n \t\t\tthe_repository->repository_format_relative_worktrees =\n@@ -2042,7 +2066,8 @@ void check_repository_format(struct repository_format *fmt)\n \trepo_set_hash_algo(the_repository, fmt->hash_algo);\n \trepo_set_compat_hash_algo(the_repository, fmt->compat_hash_algo);\n \trepo_set_ref_storage_format(the_repository,\n-\t\t\t\t fmt->ref_storage_format);\n+\t\t\t\t fmt->ref_storage_format,\n+\t\t\t\t fmt->ref_storage_payload);\n \tthe_repository->repository_format_worktree_config =\n \t\tfmt->worktree_config;\n \tthe_repository->repository_format_relative_worktrees =\n@@ -2643,7 +2668,8 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n-\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format);\n+\trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n+\t\t\t\t repo_fmt->ref_storage_payload);\n }\n \n int init_db(const char *git_dir, const char *real_git_dir,\ndiff --git a/setup.h b/setup.h\nindex ddb9f6701c..093af39e84 100644\n--- a/setup.h\n+++ b/setup.h\n@@ -171,6 +171,7 @@ struct repository_format {\n \tint hash_algo;\n \tint compat_hash_algo;\n \tenum ref_storage_format ref_storage_format;\n+\tchar *ref_storage_payload;\n \tint sparse_index;\n \tchar *work_tree;\n \tstruct string_list unknown_extensions;\ndiff --git a/t/meson.build b/t/meson.build\nindex 459c52a489..11fc5a49ee 100644\n--- a/t/meson.build\n+++ b/t/meson.build\n@@ -210,6 +210,7 @@ integration_tests = [\n 't1420-lost-found.sh',\n 't1421-reflog-write.sh',\n 't1422-show-ref-exists.sh',\n+ 't1423-ref-backend.sh',\n 't1430-bad-ref-name.sh',\n 't1450-fsck.sh',\n 't1451-fsck-buffer.sh',\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nnew file mode 100755\nindex 0000000000..9912433b8c\n--- /dev/null\n+++ b/t/t1423-ref-backend.sh\n@@ -0,0 +1,159 @@\n+#!/bin/sh\n+\n+test_description='Test reference backend URIs'\n+\n+. ./test-lib.sh\n+\n+# Run a git command with the provided reference storage. Reset the backend\n+# post running the command.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# is the git subcommand to be run in the repository.\n+run_with_uri() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\tcmd=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1\n+\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\tgit -C \"$repo\" $cmd &&\n+\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+}\n+\n+# Test a repository with a given reference storage by running and comparing\n+# 'git refs list' before and after setting the new reference backend. If\n+# err_msg is set, expect the command to fail and grep for the provided err_msg.\n+# Usage: run_with_uri \n+# is the relative path to the repo to run the command in.\n+# is the original ref storage of the repo.\n+# is the new URI to be set for the ref storage.\n+# (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n+test_refs_backend() {\n+\trepo=$1 &&\n+\tbackend=$2 &&\n+\turi=$3 &&\n+\terr_msg=$4 &&\n+\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test -n \"$err_msg\";\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\ttest_grep \"$err_msg\" err\n+\telse\n+\t\tgit -C \"$repo\" refs list >expect &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\ttest_cmp expect actual\n+\tfi\n+}\n+\n+test_expect_success 'URI is invalid' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'URI ends with colon' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"reftable:\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+test_expect_success 'unknown reference backend' '\n+\ttest_when_finished \"rm -rf repo\" &&\n+\tgit init repo &&\n+\ttest_refs_backend repo files \"db://.git\" \\\n+\t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n+'\n+\n+ref_formats=\"files reftable\"\n+for from_format in $ref_formats\n+do\n+\n+for to_format in $ref_formats\n+do\n+\tif test \"$from_format\" = \"$to_format\"\n+\tthen\n+\t\tcontinue\n+\tfi\n+\n+\n+\tfor dir in \"$(pwd)/repo/.git\" \".\"\n+\tdo\n+\n+\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\"\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit refs list >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\tgit refs list >actual &&\n+\t\t\t\ttest_cmp expect actual &&\n+\n+\t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n+\t\t'\n+\n+\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\t\ttest_when_finished \"rm -rf repo wt\" &&\n+\t\t\tgit init --ref-format=$from_format repo &&\n+\t\t\t(\n+\t\t\t\tcd repo &&\n+\t\t\t\ttest_commit 1 &&\n+\t\t\t\ttest_commit 2 &&\n+\t\t\t\ttest_commit 3 &&\n+\n+\t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n+\t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n+\n+\t\t\t\tgit config set core.repositoryformatversion 1 &&\n+\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n+\n+\t\t\t\tgit worktree add ../wt 2\n+\t\t\t) &&\n+\n+\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n+\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n+\t\t\t! test_cmp expect actual &&\n+\n+\t\t\tgit -C wt rev-parse 2 >expect &&\n+\t\t\tgit -C wt rev-parse HEAD >actual &&\n+\t\t\ttest_cmp expect actual\n+\t\t'\n+\tdone # closes dir\n+done # closes to_format\n+done # closes from_format\n+\n+test_done\n\n-- \n2.53.GIT\n\n"},{"id":"537075","messageId":"20260225-kn-alternate-ref-dir-v9-6-3fe118e40e28@gmail.com","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-0-3fe118e40e28@gmail.com","subject":"[PATCH v9 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:40:46Z","receivedAt":"2026-02-25T09:40:57Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Git allows setting a different object directory via\n'GIT_OBJECT_DIRECTORY', but provides no equivalent for references. In\nthe previous commit we extended the 'extensions.refStorage' config to\nalso support an URI input for reference backend with location.\n\nLet's also add a new environment variable 'GIT_REFERENCE_BACKEND' that\ntakes in the same input as the config variable. Having an environment\nvariable allows us to modify the reference backend and location on the\nfly for individual Git commands.\n\nThe environment variable also allows usage of alternate reference\ndirectories during 'git-clone(1)' and 'git-init(1)'. Add the config to\nthe repository when created with the environment variable set.\n\nWhen initializing the repository with an alternate reference folder,\ncreate the required stubs in the repositories $GIT_DIR. The inverse,\ni.e. removal of the ref store doesn't clean up the stubs in the $GIT_DIR\nsince that would render it unusable. Removal of ref store is only used\nwhen migrating between ref formats and cleanup of the $GIT_DIR doesn't\nmake sense in such a situation.\n\nHelped-by: Jean-Noël Avila \nSigned-off-by: Karthik Nayak \n---\n Documentation/git.adoc | 5 ++\n environment.h | 1 +\n refs.c | 30 +++++---\n setup.c | 55 ++++++++++++++-\n t/t1423-ref-backend.sh | 187 ++++++++++++++++++++++++++++++++++++++++---------\n 5 files changed, 233 insertions(+), 45 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..66442735ea 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -584,6 +584,11 @@ double-quotes and respecting backslash escapes. E.g., the value\n \trepositories will be set to this value. The default is \"files\".\n \tSee `--ref-format` in linkgit:git-init[1].\n \n+`GIT_REFERENCE_BACKEND`::\n+ Specify which reference backend to be used along with its URI.\n+ See `extensions.refStorage` option in linkgit:git-config[1] for more\n+ details. Overrides the config variable when used.\n+\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\ndiff --git a/environment.h b/environment.h\nindex 27f657af04..540e0a7f6d 100644\n--- a/environment.h\n+++ b/environment.h\n@@ -42,6 +42,7 @@\n #define GIT_OPTIONAL_LOCKS_ENVIRONMENT \"GIT_OPTIONAL_LOCKS\"\n #define GIT_TEXT_DOMAIN_DIR_ENVIRONMENT \"GIT_TEXTDOMAINDIR\"\n #define GIT_ATTR_SOURCE_ENVIRONMENT \"GIT_ATTR_SOURCE\"\n+#define GIT_REFERENCE_BACKEND_ENVIRONMENT \"GIT_REFERENCE_BACKEND\"\n \n /*\n * Environment variable used to propagate the --no-advice global option to the\ndiff --git a/refs.c b/refs.c\nindex ef1902e85c..a700a66f08 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -2192,13 +2192,17 @@ int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *e\n {\n \tint ret = refs->be->create_on_disk(refs, flags, err);\n \n-\tif (!ret &&\n-\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n-\t\tstruct strbuf msg = STRBUF_INIT;\n-\n-\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n-\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n-\t\tstrbuf_release(&msg);\n+\tif (!ret) {\n+\t\t/* Creation of stubs for linked worktrees are handled in the worktree code. */\n+\t\tif (!(flags & REF_STORE_CREATE_ON_DISK_IS_WORKTREE) && refs->repo->ref_storage_payload) {\n+\t\t\trefs_create_refdir_stubs(refs->repo, refs->repo->gitdir,\n+\t\t\t\t\t\t \"repository uses alternate refs storage\");\n+\t\t} else if (ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\t\t\tstruct strbuf msg = STRBUF_INIT;\n+\t\t\tstrbuf_addf(&msg, \"this repository uses the %s format\", refs->be->name);\n+\t\t\trefs_create_refdir_stubs(refs->repo, refs->gitdir, msg.buf);\n+\t\t\tstrbuf_release(&msg);\n+\t\t}\n \t}\n \n \treturn ret;\n@@ -2208,10 +2212,18 @@ int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err)\n {\n \tint ret = refs->be->remove_on_disk(refs, err);\n \n-\tif (!ret &&\n-\t ref_storage_format_by_name(refs->be->name) != REF_STORAGE_FORMAT_FILES) {\n+\tif (!ret) {\n+\t\tenum ref_storage_format format = ref_storage_format_by_name(refs->be->name);\n \t\tstruct strbuf sb = STRBUF_INIT;\n \n+\t\t/* Backends apart from the files backend create stubs. */\n+\t\tif (format == REF_STORAGE_FORMAT_FILES)\n+\t\t\treturn ret;\n+\n+\t\t/* Alternate refs backend require stubs in the gitdir. */\n+\t\tif (refs->repo->ref_storage_payload)\n+\t\t\treturn ret;\n+\n \t\tstrbuf_addf(&sb, \"%s/HEAD\", refs->gitdir);\n \t\tif (unlink(sb.buf) < 0) {\n \t\t\tstrbuf_addf(err, \"could not delete stub HEAD: %s\",\ndiff --git a/setup.c b/setup.c\nindex d407f3347b..90cb9be578 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -1838,6 +1838,7 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \tstatic struct strbuf cwd = STRBUF_INIT;\n \tstruct strbuf dir = STRBUF_INIT, gitdir = STRBUF_INIT, report = STRBUF_INIT;\n \tconst char *prefix = NULL;\n+\tconst char *ref_backend_uri;\n \tstruct repository_format repo_fmt = REPOSITORY_FORMAT_INIT;\n \n \t/*\n@@ -1995,6 +1996,25 @@ const char *setup_git_directory_gently(int *nongit_ok)\n \t\tsetenv(GIT_PREFIX_ENVIRONMENT, \"\", 1);\n \t}\n \n+\t/*\n+\t * The env variable should override the repository config\n+\t * for 'extensions.refStorage'.\n+\t */\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *payload;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\t\trepo_set_ref_storage_format(the_repository, format, payload);\n+\n+\t\tfree(backend);\n+\t\tfree(payload);\n+\t}\n+\n \tsetup_original_cwd();\n \n \tstrbuf_release(&dir);\n@@ -2337,7 +2357,8 @@ void initialize_repository_version(int hash_algo,\n \t * the remote repository's format.\n \t */\n \tif (hash_algo != GIT_HASH_SHA1_LEGACY ||\n-\t ref_storage_format != REF_STORAGE_FORMAT_FILES)\n+\t ref_storage_format != REF_STORAGE_FORMAT_FILES ||\n+\t the_repository->ref_storage_payload)\n \t\ttarget_version = GIT_REPO_VERSION_READ;\n \n \tif (hash_algo != GIT_HASH_SHA1_LEGACY && hash_algo != GIT_HASH_UNKNOWN)\n@@ -2346,11 +2367,20 @@ void initialize_repository_version(int hash_algo,\n \telse if (reinit)\n \t\trepo_config_set_gently(the_repository, \"extensions.objectformat\", NULL);\n \n-\tif (ref_storage_format != REF_STORAGE_FORMAT_FILES)\n+\tif (the_repository->ref_storage_payload) {\n+\t\tstruct strbuf ref_uri = STRBUF_INIT;\n+\n+\t\tstrbuf_addf(&ref_uri, \"%s://%s\",\n+\t\t\t ref_storage_format_to_name(ref_storage_format),\n+\t\t\t the_repository->ref_storage_payload);\n+\t\trepo_config_set(the_repository, \"extensions.refstorage\", ref_uri.buf);\n+\t\tstrbuf_release(&ref_uri);\n+\t} else if (ref_storage_format != REF_STORAGE_FORMAT_FILES) {\n \t\trepo_config_set(the_repository, \"extensions.refstorage\",\n \t\t\t\tref_storage_format_to_name(ref_storage_format));\n-\telse if (reinit)\n+\t} else if (reinit) {\n \t\trepo_config_set_gently(the_repository, \"extensions.refstorage\", NULL);\n+\t}\n \n \tif (reinit) {\n \t\tstruct strbuf config = STRBUF_INIT;\n@@ -2623,6 +2653,7 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t\t.ignore_repo = 1,\n \t\t.ignore_worktree = 1,\n \t};\n+\tconst char *ref_backend_uri;\n \tconst char *env;\n \n \tconfig_with_options(read_default_format_config, &cfg, NULL, NULL, &opts);\n@@ -2668,6 +2699,24 @@ static void repository_format_configure(struct repository_format *repo_fmt,\n \t} else {\n \t\trepo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;\n \t}\n+\n+\n+\tref_backend_uri = getenv(GIT_REFERENCE_BACKEND_ENVIRONMENT);\n+\tif (ref_backend_uri) {\n+\t\tchar *backend, *payload;\n+\t\tenum ref_storage_format format;\n+\n+\t\tparse_reference_uri(ref_backend_uri, &backend, &payload);\n+\t\tformat = ref_storage_format_by_name(backend);\n+\t\tif (format == REF_STORAGE_FORMAT_UNKNOWN)\n+\t\t\tdie(_(\"unknown ref storage format: '%s'\"), backend);\n+\n+\t\trepo_fmt->ref_storage_format = format;\n+\t\trepo_fmt->ref_storage_payload = payload;\n+\n+\t\tfree(backend);\n+\t}\n+\n \trepo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format,\n \t\t\t\t repo_fmt->ref_storage_payload);\n }\ndiff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\nindex 9912433b8c..9884a07447 100755\n--- a/t/t1423-ref-backend.sh\n+++ b/t/t1423-ref-backend.sh\n@@ -11,16 +11,25 @@ test_description='Test reference backend URIs'\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n # is the git subcommand to be run in the repository.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n run_with_uri() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n \tcmd=$4 &&\n+\tvia=$5 &&\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1\n-\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\tgit -C \"$repo\" $cmd &&\n-\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n+\tif test \"$via\" = \"env\"\n+\tthen\n+\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" git -C \"$repo\" $cmd\n+\telif test \"$via\" = \"config\"\n+\tthen\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\tgit -C \"$repo\" $cmd &&\n+\t\tgit -C \"$repo\" config set extensions.refStorage \"$backend\"\n+\tfi\n }\n \n # Test a repository with a given reference storage by running and comparing\n@@ -30,44 +39,84 @@ run_with_uri() {\n # is the relative path to the repo to run the command in.\n # is the original ref storage of the repo.\n # is the new URI to be set for the ref storage.\n+# if 'config', set the backend via the 'extensions.refStorage' config.\n+# if 'env', set the backend via the 'GIT_REFERENCE_BACKEND' env.\n # (optional) if set, check if 'git-refs(1)' failed with the provided msg.\n test_refs_backend() {\n \trepo=$1 &&\n \tbackend=$2 &&\n \turi=$3 &&\n-\terr_msg=$4 &&\n+\tvia=$4 &&\n+\terr_msg=$5 &&\n+\n \n-\tgit -C \"$repo\" config set core.repositoryformatversion 1 &&\n \tif test -n \"$err_msg\";\n \tthen\n-\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n-\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n-\t\ttest_grep \"$err_msg\" err\n+\t\tif test \"$via\" = \"env\"\n+\t\tthen\n+\t\t\ttest_env GIT_REFERENCE_BACKEND=\"$uri\" test_must_fail git -C \"$repo\" refs list 2>err\n+\t\telif test \"$via\" = \"config\"\n+\t\tthen\n+\t\t\tgit -C \"$repo\" config set extensions.refStorage \"$uri\" &&\n+\t\t\ttest_must_fail git -C \"$repo\" refs list 2>err &&\n+\t\t\ttest_grep \"$err_msg\" err\n+\t\tfi\n \telse\n \t\tgit -C \"$repo\" refs list >expect &&\n-\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" >actual &&\n+\t\trun_with_uri \"$repo\" \"$backend\" \"$uri\" \"refs list\" \"$via\">actual &&\n \t\ttest_cmp expect actual\n \tfi\n }\n \n-test_expect_success 'URI is invalid' '\n+# Verify that the expected files are present in the gitdir and the refsdir.\n+# Usage: verify_files_exist \n+# is the path for the gitdir.\n+# is the path for the refdir.\n+verify_files_exist() {\n+\tgitdir=$1 &&\n+\trefdir=$2 &&\n+\n+\t# verify that the stubs were added to the $GITDIR.\n+\techo \"repository uses alternate refs storage\" >expect &&\n+\ttest_cmp expect $gitdir/refs/heads &&\n+\techo \"ref: refs/heads/.invalid\" >expect &&\n+\ttest_cmp expect $gitdir/HEAD\n+\n+\t# verify that backend specific files exist.\n+\tcase \"$GIT_DEFAULT_REF_FORMAT\" in\n+\tfiles)\n+\t\ttest_path_is_dir $refdir/refs/heads &&\n+\t\ttest_path_is_file $refdir/HEAD;;\n+\treftable)\n+\t\ttest_path_is_dir $refdir/reftable &&\n+\t\ttest_path_is_file $refdir/reftable/tables.list;;\n+\t*)\n+\t\tBUG \"unhandled ref format $GIT_DEFAULT_REF_FORMAT\";;\n+\tesac\n+}\n+\n+methods=\"config env\"\n+for method in $methods\n+do\n+\n+test_expect_success \"$method: URI is invalid\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable@/home/reftable\" \\\n+\ttest_refs_backend repo files \"reftable@/home/reftable\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'URI ends with colon' '\n+test_expect_success \"$method: URI ends with colon\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"reftable:\" \\\n+\ttest_refs_backend repo files \"reftable:\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n-test_expect_success 'unknown reference backend' '\n+test_expect_success \"$method: unknown reference backend\" '\n \ttest_when_finished \"rm -rf repo\" &&\n \tgit init repo &&\n-\ttest_refs_backend repo files \"db://.git\" \\\n+\ttest_refs_backend repo files \"db://.git\" \"$method\" \\\n \t\t\"invalid value for ${SQ}extensions.refstorage${SQ}\"\n '\n \n@@ -86,7 +135,7 @@ do\n \tfor dir in \"$(pwd)/repo/.git\" \".\"\n \tdo\n \n-\t\ttest_expect_success \"read from $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: read from $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -101,7 +150,7 @@ do\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"write to $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: write to $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -113,20 +162,22 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" &&\n+\t\t\t\ttest_refs_backend . $from_format \"$to_format://$BACKEND_PATH\" \"$method\" &&\n \n \t\t\t\tgit refs list >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"tag -d 1\" &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"tag -d 1\" \"$method\" &&\n \t\t\t\tgit refs list >actual &&\n \t\t\t\ttest_cmp expect actual &&\n \n \t\t\t\tgit refs list | grep -v \"refs/tags/1\" >expect &&\n-\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \"refs list\" >actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"refs list\" \"$method\" >actual &&\n \t\t\t\ttest_cmp expect actual\n \t\t\t)\n \t\t'\n \n-\t\ttest_expect_success \"with worktree and $to_format backend, $dir dir\" '\n+\t\ttest_expect_success \"$method: with worktree and $to_format backend, $dir dir\" '\n \t\t\ttest_when_finished \"rm -rf repo wt\" &&\n \t\t\tgit init --ref-format=$from_format repo &&\n \t\t\t(\n@@ -138,22 +189,92 @@ do\n \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n \n-\t\t\t\tgit config set core.repositoryformatversion 1 &&\n-\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n-\n-\t\t\t\tgit worktree add ../wt 2\n-\t\t\t) &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n \n-\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n-\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n-\t\t\t! test_cmp expect actual &&\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n+\t\t\t\t! test_cmp expect actual &&\n \n-\t\t\tgit -C wt rev-parse 2 >expect &&\n-\t\t\tgit -C wt rev-parse HEAD >actual &&\n-\t\t\ttest_cmp expect actual\n+\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n+\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n+\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n+\t\t\t\ttest_cmp expect actual\n+\t\t\t)\n \t\t'\n \tdone # closes dir\n+\n+\ttest_expect_success \"migrating repository to $to_format with alternate refs directory\" '\n+\t\ttest_when_finished \"rm -rf repo refdir\" &&\n+\t\tmkdir refdir &&\n+\t\tGIT_REFERENCE_BACKEND=\"${from_format}://$(pwd)/refdir\" git init repo &&\n+\t\t(\n+\t\t\tcd repo &&\n+\n+\t\t\ttest_commit 1 &&\n+\t\t\ttest_commit 2 &&\n+\t\t\ttest_commit 3 &&\n+\n+\t\t\tgit refs migrate --ref-format=$to_format &&\n+\t\t\tgit refs list >out &&\n+\t\t\ttest_grep \"refs/tags/1\"\tout &&\n+\t\t\ttest_grep \"refs/tags/2\"\tout &&\n+\t\t\ttest_grep \"refs/tags/3\"\tout\n+\t\t)\n+\t'\n+\n done # closes to_format\n done # closes from_format\n \n+done # closes method\n+\n+test_expect_success 'initializing repository with alt ref directory' '\n+\ttest_when_finished \"rm -rf repo refdir\" &&\n+\tmkdir refdir &&\n+\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n+\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n+\tverify_files_exist repo/.git refdir &&\n+\t(\n+\t\tcd repo &&\n+\n+\t\tgit config get extensions.refstorage >actual &&\n+\t\techo $BACKEND >expect &&\n+\t\ttest_cmp expect actual &&\n+\n+\t\ttest_commit 1 &&\n+\t\ttest_commit 2 &&\n+\t\ttest_commit 3 &&\n+\t\tgit refs list >out &&\n+\t\ttest_grep \"refs/tags/1\"\tout &&\n+\t\ttest_grep \"refs/tags/2\"\tout &&\n+\t\ttest_grep \"refs/tags/3\"\tout\n+\t)\n+'\n+\n+test_expect_success 'cloning repository with alt ref directory' '\n+\ttest_when_finished \"rm -rf source repo refdir\" &&\n+\tmkdir refdir &&\n+\n+\tgit init source &&\n+\ttest_commit -C source 1 &&\n+\ttest_commit -C source 2 &&\n+\ttest_commit -C source 3 &&\n+\n+\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n+\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n+\n+\tgit -C repo config get extensions.refstorage >actual &&\n+\techo $BACKEND >expect &&\n+\ttest_cmp expect actual &&\n+\n+\tverify_files_exist repo/.git refdir &&\n+\n+\tgit -C source for-each-ref refs/tags/ >expect &&\n+\tgit -C repo for-each-ref refs/tags/ >actual &&\n+\ttest_cmp expect actual\n+'\n+\n test_done\n\n-- \n2.53.GIT\n\n"},{"id":"537076","messageId":"CAOLa=ZQ54NpKGywvW2aVdZNmSFarkWyp97hmwB5Ou3K40FavNA@mail.gmail.com","threadId":"64513","inReplyTo":"874in5nr5p.fsf@iotcl.com","subject":"Re: [PATCH v8 6/6] refs: add GIT_REFERENCE_BACKEND to specify reference backend","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:41:06Z","receivedAt":"2026-02-25T09:41:08Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Toon Claes writes:\n\n> Karthik Nayak writes:\n>\n>> diff --git a/t/t1423-ref-backend.sh b/t/t1423-ref-backend.sh\n>> index 9912433b8c..1a7b8eadba 100755\n>> --- a/t/t1423-ref-backend.sh\n>> +++ b/t/t1423-ref-backend.sh\n>> @@ -138,22 +189,92 @@ do\n>> \t\t\t\tgit refs migrate --dry-run --ref-format=$to_format >out &&\n>> \t\t\t\tBACKEND_PATH=\"$dir/$(sed \"s/.* ${SQ}.git\\/\\(.*\\)${SQ}/\\1/\" out)\" &&\n>>\n>> -\t\t\t\tgit config set core.repositoryformatversion 1 &&\n>> -\t\t\t\tgit config set extensions.refStorage \"$to_format://$BACKEND_PATH\" &&\n>> -\n>> -\t\t\t\tgit worktree add ../wt 2\n>> -\t\t\t) &&\n>> +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n>> +\t\t\t\t\t\"worktree add ../wt 2\" \"$method\" &&\n>>\n>> -\t\t\tgit -C repo for-each-ref --include-root-refs >expect &&\n>> -\t\t\tgit -C wt for-each-ref --include-root-refs >expect &&\n>> -\t\t\t! test_cmp expect actual &&\n>> +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n>> +\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >actual &&\n>> +\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n>> +\t\t\t\t\t\"for-each-ref --include-root-refs\" \"$method\" >expect &&\n>> +\t\t\t\t! test_cmp expect actual &&\n>>\n>> -\t\t\tgit -C wt rev-parse 2 >expect &&\n>> -\t\t\tgit -C wt rev-parse HEAD >actual &&\n>> -\t\t\ttest_cmp expect actual\n>> +\t\t\t\trun_with_uri . \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n>> +\t\t\t\t\t\"rev-parse 2\" \"$method\" >actual &&\n>> +\t\t\t\trun_with_uri ../wt \"$from_format\" \"$to_format://$BACKEND_PATH\" \\\n>> +\t\t\t\t\t\"rev-parse HEAD\" \"$method\" >expect &&\n>> +\t\t\t\ttest_cmp expect actual\n>> +\t\t\t)\n>> \t\t'\n>> \tdone # closes dir\n>> +\n>> +\ttest_expect_success \"migrating repository to $to_format with alternate refs directory\" '\n>> +\t\ttest_when_finished \"rm -rf repo refdir\" &&\n>> +\t\tmkdir refdir &&\n>> +\t\tGIT_REFERENCE_BACKEND=\"${from_format}://$(pwd)/refdir\" git init repo &&\n>> +\t\t(\n>> +\t\t\tcd repo &&\n>> +\n>> +\t\t\ttest_commit 1 &&\n>> +\t\t\ttest_commit 2 &&\n>> +\t\t\ttest_commit 3 &&\n>> +\n>> +\t\t\tgit refs migrate --ref-format=$to_format &&\n>> +\t\t\tgit refs list >out &&\n>> +\t\t\ttest_grep \"refs/tags/1\"\tout &&\n>> +\t\t\ttest_grep \"refs/tags/2\"\tout &&\n>> +\t\t\ttest_grep \"refs/tags/3\"\tout\n>> +\t\t)\n>> +\t'\n>> +\n>> done # closes to_format\n>> done # closes from_format\n>>\n>> +done # closes method\n>> +\n>> +test_expect_success 'initializing repository with alt ref directory' '\n>> +\ttest_when_finished \"rm -rf repo refdir\" &&\n>> +\tmkdir refdir &&\n>> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n>> +\tGIT_REFERENCE_BACKEND=$BACKEND git init repo &&\n>> +\tverify_files_exist repo/.git refdir &&\n>> +\t(\n>> +\t\tcd repo &&\n>> +\n>> +\t\tgit config get extensions.refstorage >expect &&\n>> +\t\techo $BACKEND >actual &&\n>\n> Shouldn't these two be swapped, like:\n>\n> \t\tgit config get extensions.refstorage >actual &&\n> \t\techo $BACKEND >expect &&\n>\n>> +\t\ttest_cmp expect actual &&\n>> +\n>> +\t\ttest_commit 1 &&\n>> +\t\ttest_commit 2 &&\n>> +\t\ttest_commit 3 &&\n>> +\t\tgit refs list >out &&\n>> +\t\ttest_grep \"refs/tags/1\"\tout &&\n>> +\t\ttest_grep \"refs/tags/2\"\tout &&\n>> +\t\ttest_grep \"refs/tags/3\"\tout\n>> +\t)\n>> +'\n>> +\n>> +test_expect_success 'cloning repository with alt ref directory' '\n>> +\ttest_when_finished \"rm -rf source repo refdir\" &&\n>> +\tmkdir refdir &&\n>> +\n>> +\tgit init source &&\n>> +\ttest_commit -C source 1 &&\n>> +\ttest_commit -C source 2 &&\n>> +\ttest_commit -C source 3 &&\n>> +\n>> +\tBACKEND=\"$(test_detect_ref_format)://$(pwd)/refdir\" &&\n>> +\tGIT_REFERENCE_BACKEND=$BACKEND git clone source repo &&\n>> +\n>> +\tgit -C repo config get extensions.refstorage >expect &&\n>> +\techo $BACKEND >actual &&\n>> +\ttest_cmp expect actual &&\n>\n> Same here.\n>\n\nMakes sense. Will amend.\n"},{"id":"537077","messageId":"CAOLa=ZTejaVY_fvMsGdw_ZmcQijDex6=43RKHBM9HWv05u17Gg@mail.gmail.com","threadId":"64513","inReplyTo":"xmqqikbnmdjf.fsf@gitster.g","subject":"Re: [PATCH v8 0/6] refs: allow setting the reference directory","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-02-25T09:42:32Z","receivedAt":"2026-02-25T09:42:33Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano writes:\n\n> Karthik Nayak writes:\n>\n>> Patrick Steinhardt writes:\n>>\n>>> On Mon, Feb 23, 2026 at 09:01:35AM +0100, Karthik Nayak wrote:\n>>>> Changes in v8:\n>>>> - Fix a typo/grammar in commit 4.\n>>>> - In the final commits tests, avoid creating a file for text\n>>>> comparison.\n>>>> - Link to v7: https://patch.msgid.link/20260219-kn-alternate-ref-dir-v7-0-16f27860dbdf@gmail.com\n>>>\n>>> Thanks, I'm happy now with the current version based on the range-diff.\n>>>\n>>> Patrick\n>>\n>> Thanks for the reviews.\n>\n> Let me replace what I have with this latest and mark the topic for\n> 'next', then.\n>\n> Thanks, all!\n\nThere was an issue with the doc rendering and small nits that Toon\nsuggested, so I pushed a new version. Hope you can replace it with the\nlatest for 'next'.\n\nThanks and sorry for the churn.\n"},{"id":"537108","messageId":"xmqq8qcgbtz0.fsf@gitster.g","threadId":"64513","inReplyTo":"20260225-kn-alternate-ref-dir-v9-5-3fe118e40e28@gmail.com","subject":"Re: [PATCH v9 5/6] refs: allow reference location in refstorage config","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-25T17:42:27Z","receivedAt":"2026-02-25T17:42:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak writes:\n\n> +run_with_uri() {\n> +test_refs_backend() {\n\nI've been fixing these style violations (and another one in 6/6) for\nthe past few iterations, but forgot to report it.\n\nHopefully this will not be rerolled and we can merge the result in\n'next', which would mean that I'll do the local touch-up for just\nonce more.\n\nThe changes relative to the previous round all looked sensible. The\nchanges to the tests to swap expect and actual so that they correctly\nhold expected and actual contents are nice touch.\n\nThanks.\n\n"}]}