Re: [PATCH 00/11] Fix inconsistent ref storage format terminology
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Sep 7, 2026, 10:00 UTC
- Message-ID
- <ap6LPf0Ks1xTTp4z@pks.im>
- In-Reply-To
- <xmqq8q5h3plt.fsf@gitster.g>
On Fri, Sep 04, 2026 at 10:15:10AM -0700, Junio C Hamano wrote:
Show 28 quoted lines
> Patrick Steinhardt <ps@pks.im> 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. > > Unless you are unifying them all into a single ref-storage-format, I > do not see much practical difference between ref-storage and > ref-format. They are both with insufficient clarity and details.
Well, the important difference is that we don't have conflicting concerns of "--ref-format=" and "--object-format=" anymore, where the former cares about the storage format and the latter cares about how the objects themselves look.
> ref-format fails to convey "format" of what aspect of ref it is > about (among "storage", "name", and others), ref-storage fails to > convey what aspect of ref storage it is talking about (among > "format", "medium", and others).
In any case, I'm happy to call this "ref-storage-format" instead. I don't care too much about the naming, I really only want to fix the scope conflict we have with the above two flags, and be consistent. Resolving that scope conflict gives us a path forward for introducing the object storage format extension and its accompanying flags.
So with your suggestion, it would be:
- "--ref-storage-format=" and "--object-storage-format=" control the
storage format used by Git. - "--object-format=" would continue to control the hash used for
objects. This is still a tiny bit messy, as it could've been called
"--object-hash=" if you ask me. But on the other, maybe we at one
point in the future we will introduce an actual new representation
for objects? If so, it gives us a bit more flexibility.Will send a new version along these lines. Thanks!
Patrick