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

[Patrick Steinhardt <ps@pks.im>]

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

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 | 44 +++++++++++++++++++++++++++++++++++++
 Documentation/config/feature.adoc  |  6 +++++
 help.c                             |  2 ++
 repository.h                       |  6 +++++
 setup.c                            | 14 ++++++++++++
 t/t0001-init.sh                    | 45 ++++++++++++++++++++++++++++++++++++++
 6 files changed, 117 insertions(+)

Range-diff versus v1:

1:  f12545f39d3 ! 1:  0b4cf2c7a25 BreakingChanges: announce switch to "reftable" format
    @@ Documentation/BreakingChanges.adoc: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zo
     +  multiple advantages over the "files" format:
     ++
     +  ** It is impossible to store two references that only differ in casing on
    -+     case-insensitive filesystems with the "files" format. This issue is
    -+     especially common on Windows, but also on older versions of macOS. As the
    -+     "reftable" backend does not use filesystem paths anymore to encode
    -+     reference names this problem goes away.
    ++     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.
     +  ** 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
     +     significantly outperforms the "files" backend by multiple orders of
     +     magnitude.
     ++
    ++Users that get immediate benefit from the "reftable" backend could continue to
    ++opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
    ++config. But defaults matter, and we think that overall users will have a better
    ++experience with less platform-specific quirks when they use the new backend by
    ++default.
    +++
     +A prerequisite for this change is that the ecosystem is ready to support the
     +"reftable" format. Most importantly, alternative implementations of Git like
     +JGit, libgit2 and Gitoxide need to support it.
    @@ Documentation/BreakingChanges.adoc: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zo
      
      * Support for grafting commits has long been superseded by git-replace(1).
     
    + ## help.c ##
    +@@ help.c: void get_version_info(struct strbuf *buf, int show_build_options)
    + 			    SHA1_UNSAFE_BACKEND);
    + #endif
    + 		strbuf_addf(buf, "SHA-256: %s\n", SHA256_BACKEND);
    ++		strbuf_addf(buf, "default-ref-format: %s\n",
    ++			    ref_storage_format_to_name(REF_STORAGE_FORMAT_DEFAULT));
    + 	}
    + }
    + 
    +
    + ## repository.h ##
    +@@ repository.h: enum ref_storage_format {
    + 	REF_STORAGE_FORMAT_REFTABLE,
    + };
    + 
    ++#ifdef WITH_BREAKING_CHANGES /* Git 3.0 */
    ++# define REF_STORAGE_FORMAT_DEFAULT REF_STORAGE_FORMAT_REFTABLE
    ++#else
    ++# define REF_STORAGE_FORMAT_DEFAULT REF_STORAGE_FORMAT_FILES
    ++#endif
    ++
    + struct repo_path_cache {
    + 	char *squash_msg;
    + 	char *merge_msg;
    +
      ## setup.c ##
     @@ setup.c: static void repository_format_configure(struct repository_format *repo_fmt,
      			repo_fmt->ref_storage_format = ref_format;
      	} else if (cfg.ref_format != REF_STORAGE_FORMAT_UNKNOWN) {
      		repo_fmt->ref_storage_format = cfg.ref_format;
     +	} else {
    -+#ifdef WITH_BREAKING_CHANGES
    -+		repo_fmt->ref_storage_format = REF_STORAGE_FORMAT_REFTABLE;
    -+#else
    -+		repo_fmt->ref_storage_format = REF_STORAGE_FORMAT_FILES;
    -+#endif
    ++		repo_fmt->ref_storage_format = REF_STORAGE_FORMAT_DEFAULT;
      	}
      	repo_set_ref_storage_format(the_repository, repo_fmt->ref_storage_format);
      }
    @@ t/t0001-init.sh: test_expect_success 'init warns about invalid init.defaultRefFo
     +		sane_unset GIT_DEFAULT_REF_FORMAT &&
     +		git init refformat
     +	) &&
    -+	if test_have_prereq WITH_BREAKING_CHANGES
    -+	then
    -+		echo reftable >expect
    -+	else
    -+		echo files >expect
    -+	fi &&
    ++	git version --build-options | sed -ne "s/^default-ref-format: //p" >expect &&
     +	git -C refformat rev-parse --show-ref-format >actual &&
     +	test_cmp expect actual
     +'
2:  1fff73157a9 = 2:  3fddba1a29a setup: use "reftable" format when experimental features are enabled

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