[PATCH 00/11] Fix inconsistent ref storage format terminology
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Sep 4, 2026, 10:36 UTC
- Message-ID
- <20260904-b4-pks-unify-ref-storage-format-v1-0-08144e5004ff@pks.im>
Hi,
back when we gained support for reftables we of course introduced the ability to control the reference storage format that is used by newly created repositories. This infrastructure has grown over time, and unfortunately without a lot of consistency:
- The command line parameter to specify the ref storage format is
called "--ref-format=", while the corresponding repository extension
is called "refStorage". - In most cases we refer to the "ref storage format" in our docs, so
calling it "--ref-format=" is inconsistent with them. - It is possible to override the ref storage format via an environment
variable that is called "GIT_REFERENCE_BACKEND", which is not even
remotely consistent with anything else. - There is also an "object format", but that format does not control
how we store objects but rather whether we use SHA1 or SHA256.So in summary, it's a huge mess.
This problem is about to become even worse though, as we're soon going to introduce an object storage extension. This extension is the equivalent to the ref storage extension, and of course we also want users to be able to control which object storage format new repositories are using. But we cannot properly name that parameter without creating even more inconsistencies:
- "--object-format=" would match "--ref-format=", but that parameter
name is already taken to specify the hash function. - "--object-storage=" would be a good fit, but be inconsistent with
"--ref-format=". Asking the user to execute `git init
--ref-format=reftable --object-format=sha256 --object-storage=foo`
just feels extremely awkward.So this patch series aims to clean up this huge mess that we (well, to a large extent I) have created, by bringing consistency to our command line switches, environment variables and config options to all use "ref storage" instead. And that also paves the way for the eventual "object storage" switches.
As a cherry on top, this patch series also extends the "--ref-storage=" switch to allow URIs in the form of "files://foo/bar" to bring it in line with all the other ways to specify the ref storage format that already allow for URIs.
Thanks!
Patrick
---
Patrick Steinhardt (11):
builtin/init: rename "--ref-format=" to "--ref-storage="
builtin/clone: rename "--ref-format=" to "--ref-storage="
builtin/refs: rename "--ref-format=" to "--ref-storage="
builtin/submodule: rename "--ref-format=" to "--ref-storage="
builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage"
help: rename "default-ref-format" to "default-ref-storage"
refs: expose function to parse reference URIs
setup: refactor how we configure the ref storage format
setup: rename ref storage format environment variables
setup: rename "init.defaultRefFormat" to "init.defaultRefStorage"
setup: allow "git init --ref-storage=" to specify a payloadDocumentation/BreakingChanges.adoc | 2 +- Documentation/config/feature.adoc | 2 +- Documentation/config/init.adoc | 6 +- Documentation/git-clone.adoc | 2 +- Documentation/git-init.adoc | 9 +- Documentation/git-refs.adoc | 6 +- Documentation/git-rev-parse.adoc | 2 +- Documentation/git-submodule.adoc | 8 +- Documentation/git.adoc | 8 +- Documentation/ref-storage-format.adoc | 8 +- builtin/clone.c | 18 ++-- builtin/fetch.c | 2 +- builtin/init-db.c | 19 ++-- builtin/refs.c | 11 ++- builtin/rev-parse.c | 2 +- builtin/submodule--helper.c | 24 +++-- contrib/completion/git-prompt.sh | 2 +- environment.h | 1 + git-submodule.sh | 20 ++-- help.c | 2 +- refs.c | 23 +++++ refs.h | 4 + setup.c | 162 ++++++++++++++++++--------------- setup.h | 2 +- t/perf/p1401-ref-store-tombstones.sh | 4 +- t/perf/perf-lib.sh | 4 +- t/t0001-init.sh | 126 +++++++++++++------------ t/t0610-reftable-basics.sh | 34 +++---- t/t0611-reftable-httpd.sh | 2 +- t/t1400-update-ref.sh | 2 +- t/t1419-exclude-refs.sh | 16 ++-- t/t1423-ref-backend.sh | 62 +++++++++---- t/t1460-refs-migrate.sh | 54 +++++------ t/t1500-rev-parse.sh | 8 +- t/t1900-repo-info.sh | 6 +- t/t5510-fetch.sh | 14 +-- t/t5601-clone.sh | 6 +- t/t7424-submodule-mixed-ref-formats.sh | 30 +++--- t/test-lib.sh | 8 +- 39 files changed, 407 insertions(+), 314 deletions(-)
--- base-commit: 3cb9185f65410273787f74333cc027d2ea5daada change-id: 20260904-b4-pks-unify-ref-storage-format-0c81fb038671