git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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
Previous: Junio C Hamano
Message 20 of 20 in “Fix inconsistent ref storage format terminology”
  1. 00/11 Fix inconsistent ref storage format terminologyPatrick Steinhardt, Sep 4, 2026
  2. 01/11 builtin/init: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  3. Karthik NayakSep 4, 2026
  4. Patrick SteinhardtSep 7, 2026
  5. 02/11 builtin/clone: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  6. 03/11 builtin/refs: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  7. 04/11 builtin/submodule: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  8. 05/11 builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage"Patrick Steinhardt, Sep 4, 2026
  9. 06/11 help: rename "default-ref-format" to "default-ref-storage"Patrick Steinhardt, Sep 4, 2026
  10. 07/11 refs: expose function to parse reference URIsPatrick Steinhardt, Sep 4, 2026
  11. Karthik NayakSep 4, 2026
  12. 08/11 setup: refactor how we configure the ref storage formatPatrick Steinhardt, Sep 4, 2026
  13. 09/11 setup: rename ref storage format environment variablesPatrick Steinhardt, Sep 4, 2026
  14. Karthik NayakSep 4, 2026
  15. Patrick SteinhardtSep 7, 2026
  16. 10/11 setup: rename "init.defaultRefFormat" to "init.defaultRefStorage"Patrick Steinhardt, Sep 4, 2026
  17. 11/11 setup: allow "git init --ref-storage=" to specify a payloadPatrick Steinhardt, Sep 4, 2026
  18. Karthik NayakSep 4, 2026
  19. Junio C HamanoSep 4, 2026
  20. Patrick SteinhardtSep 7, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.