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

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

From
Patrick Steinhardt <ps@pks.im>
Date
Sep 4, 2026, 10:36 UTC
Message-ID
<20260904-b4-pks-unify-ref-storage-format-v1-0-08144e5004ff@pks.im>
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" instead. And that also paves the way for the eventual "object storage" switches.

As a cherry on top, this patch series also extends the "--ref-storage=" 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.

Thanks!
Patrick
---
Patrick Steinhardt (11):
      builtin/init: rename "--ref-format=" to "--ref-storage="
      builtin/clone: rename "--ref-format=" to "--ref-storage="
      builtin/refs: rename "--ref-format=" to "--ref-storage="
      builtin/submodule: rename "--ref-format=" to "--ref-storage="
      builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage"
      help: rename "default-ref-format" to "default-ref-storage"
      refs: expose function to parse reference URIs
      setup: refactor how we configure the ref storage format
      setup: rename ref storage format environment variables
      setup: rename "init.defaultRefFormat" to "init.defaultRefStorage"
      setup: allow "git init --ref-storage=" to specify a payload
 Documentation/BreakingChanges.adoc     |   2 +-
 Documentation/config/feature.adoc      |   2 +-
 Documentation/config/init.adoc         |   6 +-
 Documentation/git-clone.adoc           |   2 +-
 Documentation/git-init.adoc            |   9 +-
 Documentation/git-refs.adoc            |   6 +-
 Documentation/git-rev-parse.adoc       |   2 +-
 Documentation/git-submodule.adoc       |   8 +-
 Documentation/git.adoc                 |   8 +-
 Documentation/ref-storage-format.adoc  |   8 +-
 builtin/clone.c                        |  18 ++--
 builtin/fetch.c                        |   2 +-
 builtin/init-db.c                      |  19 ++--
 builtin/refs.c                         |  11 ++-
 builtin/rev-parse.c                    |   2 +-
 builtin/submodule--helper.c            |  24 +++--
 contrib/completion/git-prompt.sh       |   2 +-
 environment.h                          |   1 +
 git-submodule.sh                       |  20 ++--
 help.c                                 |   2 +-
 refs.c                                 |  23 +++++
 refs.h                                 |   4 +
 setup.c                                | 162 ++++++++++++++++++---------------
 setup.h                                |   2 +-
 t/perf/p1401-ref-store-tombstones.sh   |   4 +-
 t/perf/perf-lib.sh                     |   4 +-
 t/t0001-init.sh                        | 126 +++++++++++++------------
 t/t0610-reftable-basics.sh             |  34 +++----
 t/t0611-reftable-httpd.sh              |   2 +-
 t/t1400-update-ref.sh                  |   2 +-
 t/t1419-exclude-refs.sh                |  16 ++--
 t/t1423-ref-backend.sh                 |  62 +++++++++----
 t/t1460-refs-migrate.sh                |  54 +++++------
 t/t1500-rev-parse.sh                   |   8 +-
 t/t1900-repo-info.sh                   |   6 +-
 t/t5510-fetch.sh                       |  14 +--
 t/t5601-clone.sh                       |   6 +-
 t/t7424-submodule-mixed-ref-formats.sh |  30 +++---
 t/test-lib.sh                          |   8 +-
 39 files changed, 407 insertions(+), 314 deletions(-)

--- base-commit: 3cb9185f65410273787f74333cc027d2ea5daada change-id: 20260904-b4-pks-unify-ref-storage-format-0c81fb038671

Next: Patrick Steinhardt
Message 1 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.