Re: [PATCH 00/11] Fix inconsistent ref storage format terminology

[Patrick Steinhardt <ps@pks.im>]

On Fri, Sep 04, 2026 at 10:15:10AM -0700, Junio C Hamano wrote:
> 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