[PATCH v3 0/2] Add reftable by default as a breaking change

Hi,

the recent thread at [1] motivated me to hack together this tiny patch series that paves our path towards making the reftable backend the default backend. It does two things:

  - It announces the breaking change for Git 3.0.

  - It makes it the default now already when "feature.experimental" is
    enabled.

The first item is subject to ecosystem support, most notably in libraries like Gitoxide, libgit2 and JGit. The second item is intended to extend the user base to power users so that we get more test exposure out in the wild before we make it the default in Git 3.0.

Changes in v2:
  - Improve the breaking changes announcement a bit based on feedback.
  - Introduce a `REF_STORAGE_FORMAT_DEFAULT` define.
  - Print the default ref format as part of `git version --build-options`.
  - Link to v1: https://lore.kernel.org/r/20250702-pks-reftable-default-backend-v1-0-84dbaddafb50@pks.im

Changes in v3:
  - Small tweaks to the commit messages.
  - Mention better data compression as another benefit.
  - Link to v2: https://lore.kernel.org/r/20250703-pks-reftable-default-backend-v2-0-5a27e72a8c5e@pks.im

Thanks!

Patrick

[1]: <xmqqtt3vkhwk.fsf@gitster.g>

---
Patrick Steinhardt (2):
      BreakingChanges: announce switch to "reftable" format
      setup: use "reftable" format when experimental features are enabled

 Documentation/BreakingChanges.adoc | 47 ++++++++++++++++++++++++++++++++++++++
 Documentation/config/feature.adoc  |  6 +++++
 help.c                             |  2 ++
 repository.h                       |  6 +++++
 setup.c                            | 14 ++++++++++++
 t/t0001-init.sh                    | 45 ++++++++++++++++++++++++++++++++++++
 6 files changed, 120 insertions(+)

Range-diff versus v2:

1:  efbc0ba7338 ! 1:  ecf018b81ff BreakingChanges: announce switch to "reftable" format
    @@ Commit message
         significantly better in many use cases.
     
         Announce that we will switch to the "reftable" format in Git 3.0 for
    -    newly created repositories.
    +    newly created repositories and wire up the change, hidden behind the
    +    WITH_BREAKING_CHANGES preprocessor define.
     
         This switch is dependent on support in the larger Git ecosystem. Most
         importantly, libraries like JGit, libgit2 and Gitoxide should support
    @@ Documentation/BreakingChanges.adoc: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zo
     +  ** It is impossible to store two references that only differ in casing on
     +     case-insensitive filesystems with the "files" format. This issue is common
     +     on Windows and macOS platforms. As the "reftable" backend does not use
    -+     filesystem paths anymore to encode reference names this problem goes away.
    ++     filesystem paths to encode reference names this problem goes away.
     +  ** Similarly, macOS normalizes path names that contain unicode characters,
     +     which has the consequence that you cannot store two names with unicode
     +     characters that are encoded differently with the "files" backend. Again,
    @@ Documentation/BreakingChanges.adoc: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zo
     +     every reference is created as a separate file. The "reftable" backend
     +     significantly outperforms the "files" backend by multiple orders of
     +     magnitude.
    ++  ** The reftable backend uses a binary format with prefix compression for
    ++     reference names. As a result, the format uses less space compared to the
    ++     "packed-refs" file.
     ++
     +Users that get immediate benefit from the "reftable" backend could continue to
     +opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
2:  812cc75dfd8 = 2:  642f774d743 setup: use "reftable" format when experimental features are enabled

--- base-commit: 83014dc05f6fc9275c0a02886cb428805abaf9e5 change-id: 20250702-pks-reftable-default-backend-6c30f330250a