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

From: Karthik Nayak <karthik.188@gmail.com>
Date: Dec 2, 2025, 22:21 UTC
Message-ID: <CAOLa=ZR+YaWmqUxz+OjtKP88hWj5BEKwpvY78vrgWdoJecEwkQ@mail.gmail.com>
In-Reply-To: <aS2X7pI8muco7a1Z@pks.im>

Patrick Steinhardt <ps@pks.im> writes:

Show 47 quoted lines

> 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 <aS2V4TKeS4V_oxAb@pks.im> 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.
>

I did read/respond to your reply there and I agree with your suggested approach. An additional advantage would be that this would also mean the ENV variable is more deeply integrated. So the backend override added by the ENV variable would also show up when running `git repo info`.

Show 12 quoted lines

> 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.
>

Yeah, I'm considering adding this information to the `repository` structure, so along with `ref_storage_format`, it would also contain a `ref_storage_data` which would be passed down to `get_main_ref_store()` which would in-turn call `ref_store_init()`.

In that sense, when in a worktree the $GIT_DIR is set appropriately and this should all work accordingly.

Show 5 quoted lines

> What do you think?
>
> Thanks!
>
> Patrick

Sounds great. Thanks for the input