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

On Fri, Sep 04, 2026 at 10:15:10AM -0700, Junio C Hamano wrote:

Patrick Steinhardt [off-list ref] writes:

quoted

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