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

[PATCH] docs: correct information about reftable

From
brian m. carlson <sandals@crustytoothpaste.net>
Date
Apr 2, 2026, 22:42 UTC
Message-ID
<20260402224241.4104726-1-sandals@crustytoothpaste.net>

Our description of the reftable format is that it is experimental and subject to change, but that is no longer true. Remove this statement so as not to mislead users.

In addition, the documentation says that the files format is the default, but that is not true if breaking changes mode is on. Correct this information with a conditional.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
Someone who was asking a question on the list pointed out that the docs
still said reftable was experimental and I said I'd send a patch to fix
that, so here it is.

Moreover, I think the with-breaking-changes item is helpful for us to find all the places that we'll need to change for Git 3.0, in addition to our goal of having strictly accurate documentation.

 Documentation/ref-storage-format.adoc | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/Documentation/ref-storage-format.adoc b/Documentation/ref-storage-format.adoc
index 6a8db4712b..c5e29ec831 100644
--- a/Documentation/ref-storage-format.adoc
+++ b/Documentation/ref-storage-format.adoc
@@ -1,3 +1,8 @@
-`files`;; for loose files with packed-refs. This is the default.
-`reftable`;; for the reftable format. This format is experimental and its
-  internals are subject to change.
+`files`;; for loose files with packed-refs.
+ifndef::with-breaking-changes[]
+	This is the default.
+endif::with-breaking-changes[]
+`reftable`;; for the reftable format.
+ifdef::with-breaking-changes[]
+	This is the default.
+endif::with-breaking-changes[]
Next: Patrick Steinhardt
Message 1 of 3 in “docs: correct information about reftable”
  1. docs: correct information about reftablebrian m. carlson, Apr 2, 2026
  2. Patrick SteinhardtApr 8, 2026
  3. Junio C HamanoApr 8, 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.