Subject: Re: [PATCH 2/2] refs: add GIT_REF_URI to specify reference backend and directory

From: Patrick Steinhardt <[email-masked]>
Date: Mon, 1 Dec 2025 14:28:14 +0100

On Wed, Nov 19, 2025 at 10:48:53PM +0100, Karthik Nayak wrote:
> Git allows setting a different object directory via
> 'GIT_OBJECT_DIRECTORY', but provides no equivalent for references.
> This asymmetry makes it difficult to test different reference backends
> or use alternative reference storage locations without modifying the
> repository structure.
> 
> Add a new environment variable 'GIT_REF_URI' that specifies both the
> reference backend and directory path using a URI format:
> 
>     <ref_backend>://<path>
> 
> When set, this variable is used to obtain the main reference store for
> all Git commands. The variable is checked in `get_main_ref_store()`
> when lazily assigning `repo->refs_private`. We cannot initialize this
> earlier in `repo_set_gitdir()` because the repository's hash algorithm
> isn't known at that point, and the reftable backend requires this
> information during initialization.
> 
> When used with worktrees, the specified directory is treated as the
> reference directory for all worktree operations.
> 
> Add a new test file 't1423-ref-backend.sh' to test this environment
> variable.

Based on my reply in <[email-masked]> I wonder whether we want
to take a bit of a different approach:

  - We extend the format understood by "extensions.refStorage" to
    understand "schema://data"-style strings and adapt the "data" part
    to be passed through to the reference backend.

  - We then use the same mechanism to parse both "extensions.refStorage"
    and the environment variable.

This would have a couple advantages:

  - We make the ref storage extension more flexible so that you can move
    your reference backends somewhere else entirely.

  - We prepare for a potential future ref format that _needs_ to receive
    data as input.

  - We have consistent behaviour between the environment variable and
    the extension. So basically, the environment variable starts to
    behave as an override to the extension.

One issue that we'd then have to solve is how to derive the worktree
references from the backend. Arguably though, I think that the extension
that was specified should also be sufficient to identify the location of
the worktree references.

We'd have to refactor the code base a bit though to properly reflect
that in our tree. One way to do this is to extend `ref_store_init()` so
that it receives the worktree (or NULL) as input. In that case, we would
continue to pass the combination of format and "data" to the init
function, and it would then know to locate the worktree references
itself.

What do you think?

Thanks!

Patrick