From: Karthik Nayak Date: Mon, 14 Sep 2026 09:37:26 GMT Subject: Re: [PATCH v3 00/13] Fix inconsistent ref storage format terminology Message-ID: In-Reply-To: <20260909-b4-pks-unify-ref-storage-format-v3-0-ca041fb40ad8@pks.im> Patrick Steinhardt writes: > 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 format" instead. And that also paves the way for the eventual > "object storage format" switches. > > As a cherry on top, this patch series also extends the > "--ref-storage-format=" 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. > > Changes in v3: > - Add breadcrumbs for the old names to our documentation. > - Use `OPT_ALIAS()` instead of manually aliasing the options. > - Fix a comment in one of our tests that still referred to the v1 > "--ref-storage=" option. > - Print the correct environment variables in error messages. > - Also rename GIT_TEST_DEFAULT_REF_FORMAT. > - Don't adapt "ref-storage-format.adoc", as that documentation is also > shared with commands that don't support URIs yet. > - Link to v2: https://patch.msgid.link/20260907-b4-pks-unify-ref-storage-format-v2-0-6733c90ca5b0@pks.im > > Changes in v2: > - Based on Junio's feedback I've renamed all of this to instead be > called "ref storage format". > - Link to v1: https://patch.msgid.link/20260904-b4-pks-unify-ref-storage-format-v1-0-08144e5004ff@pks.im > > Thanks! > > Patrick > The new changes look good, I only had a comment regarding the use of OPT_ALIAS. But I think we can ignore that. Thanks