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

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