From: Patrick Steinhardt Date: Fri, 04 Sep 2026 10:36:01 GMT Subject: [PATCH 00/11] Fix inconsistent ref storage format terminology 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 payload Documentation/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