threads / rfc / 66404

RFC patch, 4 partsdoc: move BreakingChanges to a manpage

Subject: [RFC PATCH 0/4] doc: move BreakingChanges to a manpage

## tl;dr

The RFC to publish planned breaking changes as gitbreaking-changes(7) never reached seen or What's Cooking and has no actionable feedback. Read the story.

replies: 34people: 4as markdown or json

kristofferhaugsbakk@fastmail.com· Sep 28, 2026, 10:41 UTC · lore
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name: kh/doc-gitbreaking-changes7

Topic summary: Move BreakingChanges document to a manpage for easier visibility.

Users are the ones who are impacted by breaking changes. Certainly much more than Git developers who are already plugged in to the development channels that discuss the trajectory of the project. Advertizing the planned breaking changes to all users will help the whole Git community prepare.

[1/4] doc: transform breaking changes doc to a manpage [2/4] doc: gitbreaking-changes: replace msg-ids with URLs [3/4] doc: gitbreaking-changes: add note about living document [4/4] doc: git: mention gitbreaking-changes(7)

 Documentation/BreakingChanges.adoc     | 360 +----------------------
 Documentation/Makefile                 |   1 +
 Documentation/git.adoc                 |   5 +-
 Documentation/gitbreaking-changes.adoc | 387 +++++++++++++++++++++++++
 Documentation/meson.build              |   1 +
 command-list.txt                       |   1 +
 6 files changed, 395 insertions(+), 360 deletions(-)
 create mode 100644 Documentation/gitbreaking-changes.adoc
base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Sep 28, 2026, 10:41 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[RFC PATCH 1/4] doc: transform breaking changes doc to a manpage

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The breaking changes document is not a regular Git documentation page. That means that you cannot navigate to the doc with git(1), i.e. with:

    git help BreakingChanges

You instead have to download the Git project source. Or go to git-scm.com.[1] Then you get this disclaimer:[2]

    This information is specific to the Git project
    Please note that this information is only relevant to you if you
    plan on contributing to the Git project itself. It is in no shape or
    form required reading for regular Git users.

But this document is relevant to *all* Git users. Everyone should have as easy access to it as the other doc and guide pages.

To that end, let’s move the text to a manpage. But keep the old page, just linking to the new one. (We wouldn’t want to break any readers.)

Just do the minimal changes for the new format. Also demote the first section to the second level, i.e. make “Introduction” the same level as “Procedure’.

† 1: https://git-scm.com/docs/BreakingChanges.html
† 2: Which I first mentioned in 098230f7 (you-still-use-that??: help the
     user help themselves, 2025-09-17), footnote #1.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/BreakingChanges.adoc     | 360 +----------------------
 Documentation/Makefile                 |   1 +
 Documentation/gitbreaking-changes.adoc | 378 +++++++++++++++++++++++++
 Documentation/meson.build              |   1 +
 4 files changed, 381 insertions(+), 359 deletions(-)
 create mode 100644 Documentation/gitbreaking-changes.adoc
Show changes to 4 files +381 −357

Documentation/BreakingChanges.adoc, Documentation/Makefile, Documentation/gitbreaking-changes.adoc, Documentation/meson.build

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index 73bb939359c..d35850a08e4 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -1,359 +1 @@
-= Upcoming breaking changes
-
-The Git project aims to ensure backwards compatibility to the best extent
-possible. Minor releases will not break backwards compatibility unless there is
-a very strong reason to do so, like for example a security vulnerability.
-
-Regardless of that, due to the age of the Git project, it is only natural to
-accumulate a backlog of backwards-incompatible changes that will eventually be
-required to keep the project aligned with a changing world. These changes fall
-into several categories:
-
-* Changes to long established defaults.
-* Concepts that have been replaced with a superior design.
-* Concepts, commands, configuration or options that have been lacking in major
-  ways and that cannot be fixed and which will thus be removed without any
-  replacement.
-
-Explicitly not included in this list are fixes to minor bugs that may cause a
-change in user-visible behavior.
-
-The Git project irregularly releases breaking versions that deliberately break
-backwards compatibility with older versions. This is done to ensure that Git
-remains relevant, safe and maintainable going forward. The release cadence of
-breaking versions is typically measured in multiple years. We had the following
-major breaking releases in the past:
-
-* Git 1.6.0, released in August 2008.
-* Git 2.0, released in May 2014.
-
-We use <major>.<minor> release numbers these days, starting from Git 2.0. For
-future releases, our plan is to increment <major> in the release number when we
-make the next breaking release. Before Git 2.0, the release numbers were
-1.<major>.<minor> with the intention to increment <major> for "usual" breaking
-releases, reserving the jump to Git 2.0 for really large backward-compatibility
-breaking changes.
-
-The intent of this document is to track upcoming deprecations for future
-breaking releases. Furthermore, this document also tracks what will _not_ be
-deprecated. This is done such that the outcome of discussions document both
-when the discussion favors deprecation, but also when it rejects a deprecation.
-
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by references to relevant mailing list threads
-where the deprecation was discussed. These references use message-IDs, which
-can visited via
-
-  https://lore.kernel.org/git/$message_id/
-
-to see the message and its surrounding discussion. Such a reference is there to
-make it easier for you to find how the project reached consensus on the
-described item back then.
-
-This is a living document as the environment surrounding the project changes
-over time. If circumstances change, an earlier decision to deprecate or change
-something may need to be revisited from time to time. So do not take items on
-this list to mean "it is settled, do not waste our time bringing it up again".
-
-== Procedure
-
-Discussing the desire to make breaking changes, declaring that breaking
-changes are made at a certain version boundary, and recording these
-decisions in this document, are necessary but not sufficient.
-Because such changes are expected to be numerous, and the design and
-implementation of them are expected to span over time, they have to
-be deployable trivially at such a version boundary, prepared over long
-time.
-
-The breaking changes MUST be guarded with the a compile-time switch,
-WITH_BREAKING_CHANGES, to help this process.  When built with it,
-the resulting Git binary together with its documentation would
-behave as if these breaking changes slated for the next big version
-boundary are already in effect.  We also have a CI job to exercise
-the work-in-progress version of Git with these breaking changes.
-
-
-== Git 3.0
-
-The following subsections document upcoming breaking changes for Git 3.0. There
-is no planned release date for this breaking version yet.
-
-Proposed changes and removals only include items which are "ready" to be done.
-In other words, this is not supposed to be a wishlist of features that should
-be changed to or replaced in case the alternative was implemented already.
-
-=== Changes
-
-* The default hash function for new repositories will be changed from "sha1"
-  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
-  recommended against in FIPS 140-2 and similar certifications. Furthermore,
-  there are practical attacks on SHA-1 that weaken its cryptographic properties:
-+
-  ** The SHAppening (2015). The first demonstration of a practical attack
-     against SHA-1 with 2^57 operations.
-  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
-  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
-     attacks with 2^68 operations.
-  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
-     operations.
-+
-While we have protections in place against known attacks, it is expected
-that more attacks against SHA-1 will be found by future research. Paired
-with the ever-growing capability of hardware, it is only a matter of time
-before SHA-1 will be considered broken completely. We want to be prepared
-and will thus change the default hash algorithm to "sha256" for newly
-initialized repositories.
-+
-An important requirement for this change is that the ecosystem is ready to
-support the "sha256" object format. This includes popular Git libraries,
-applications and forges.
-+
-There is no plan to deprecate the "sha1" object format at this point in time.
-+
-Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
-<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
-
-* The default storage format for references in newly created repositories will
-  be changed from "files" to "reftable". The "reftable" format provides
-  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 common
-     on Windows and macOS platforms. As the "reftable" backend does not use
-     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,
-     this is not an issue with the "reftable" backend.
-  ** Deleting references with the "files" backend requires Git to rewrite the
-     complete "packed-refs" file. In large repositories with many references
-     this file can easily be dozens of megabytes in size, in extreme cases it
-     may be gigabytes. The "reftable" backend uses tombstone markers for
-     deleted references and thus does not have to rewrite all of its data.
-  ** Repository housekeeping with the "files" backend typically performs
-     all-into-one repacks of references. This can be quite expensive, and
-     consequently housekeeping is a tradeoff between the number of loose
-     references that accumulate and slow down operations that read references,
-     and compressing those loose references into the "packed-refs" file. The
-     "reftable" backend uses geometric compaction after every write, which
-     amortizes costs and ensures that the backend is always in a
-     well-maintained state.
-  ** Operations that write multiple references at once are not atomic with the
-     "files" backend. Consequently, Git may see in-between states when it reads
-     references while a reference transaction is in the process of being
-     committed to disk.
-  ** Writing many references at once is slow with the "files" backend because
-     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"
-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.
-
-* In new repositories, the default branch name will be `main`. We have been
-  warning that the default name will change since 675704c74dd (init:
-  provide useful advice about init.defaultBranch, 2020-12-11).  The new name
-  matches the default branch name used in new repositories by many of the
-  big Git forges.
-
-* Git will require Rust as a mandatory part of the build process. While Git
-  already started to adopt Rust in Git 2.49, all parts written in Rust are
-  optional for the time being. This includes:
-+
-  ** The Rust wrapper around libgit.a that is part of "contrib/" and which has
-     been introduced in Git 2.49.
-  ** Subsystems that have an alternative implementation in Rust to test
-     interoperability between our C and Rust codebase.
-  ** Newly written features that are not mission critical for a fully functional
-     Git client.
-+
-These changes are meant as test balloons to allow distributors of Git to prepare
-for Rust becoming a mandatory part of the build process. There will be multiple
-milestones for the introduction of Rust:
-+
---
-1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and
-   disabled in our Makefile so that the project can sort out the initial
-   infrastructure.
-2. In Git 2.55, both build systems will default-enable support for Rust.
-   Consequently, builds will break by default if Rust is not available on the
-   build host. The use of Rust can still be explicitly disabled via build
-   flags.
-3. In Git 3.0, the build options will be removed and support for Rust is
-   mandatory.
---
-+
-You can explicitly ask both Meson and our Makefile-based system to enable Rust
-by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`,
-respectively.
-+
-The Git project will declare the last version before Git 3.0 to be a long-term
-support release. This long-term release will receive important bug fixes for at
-least four release cycles and security fixes for six release cycles. The Git
-project will hand over maintainership of the long-term release to distributors
-in case they need to extend the life of that long-term release even further.
-Details of how this long-term release will be handed over to the community will
-be discussed once the Git project decides to stop officially supporting it.
-+
-We will evaluate the impact on downstream distributions before making Rust
-mandatory in Git 3.0. If we see that the impact on downstream distributions
-would be significant, we may decide to defer this change to a subsequent minor
-release. This evaluation will also take into account our own experience with
-how painful it is to keep Rust an optional component.
-
-* The default value of `safe.bareRepository` will change from `all` to
-  `explicit`. It is all too easy for an attacker to trick a user into cloning a
-  repository that contains an embedded bare repository with malicious hooks
-  configured. If the user enters that subdirectory and runs any Git command, Git
-  discovers the bare repository and the hooks fire. The user does not even need
-  to run a Git command explicitly: many shell prompts run `git status` in the
-  background to display branch and dirty state information, and `git status` in
-  turn may invoke the fsmonitor hook if so configured, making the user
-  vulnerable the moment they `cd` into the directory. The `safe.bareRepository`
-  configuration variable was introduced in 8959555cee (setup_git_directory():
-  add an owner check for the top-level directory, 2022-03-02) with a default of
-  `all` to preserve backwards compatibility.
-+
-Changing the default to `explicit` means that Git will refuse to work with bare
-repositories that are discovered implicitly by walking up the directory tree.
-Bare repositories specified explicitly via the `--git-dir` command-line option
-or the `GIT_DIR` environment variable continue to work regardless of this
-setting. Repositories that look like a `.git` directory, a worktree, or a
-submodule directory are also unaffected.
-+
-Users who rely on implicit discovery of bare repositories can restore the
-previous behavior by setting `safe.bareRepository=all` in their global or
-system configuration.
-
-=== Removals
-
-* Support for grafting commits has long been superseded by git-replace(1).
-  Grafts are inferior to replacement refs:
-+
-  ** Grafts are a local-only mechanism and cannot be shared across
-     repositories.
-  ** Grafts can lead to hard-to-diagnose problems when transferring objects
-     between repositories.
-+
-The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
-info/grafts as outdated, 2014-03-05) and will be removed.
-+
-Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
-
-* The git-pack-redundant(1) command can be used to remove redundant pack files.
-  The subcommand is unusably slow and the reason why nobody reports it as a
-  performance bug is suspected to be the absence of users. We have nominated
-  the command for removal and have started to emit a user-visible warning in
-  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
-  2020-08-25) whenever the command is executed.
-+
-So far there was a single complaint about somebody still using the command, but
-that complaint did not cause us to reverse course. On the contrary, we have
-doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
-escalate deprecation warning to an error, 2023-03-23), the command dies unless
-the user passes the `--i-still-use-this` option.
-+
-There have not been any subsequent complaints, so this command will finally be
-removed.
-+
-Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
-    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
-    <20230323204047.GA9290@coredump.intra.peff.net>,
-
-* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
-  and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
-  the repository configuration.
-+
-The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
-short-hand notation for remote repositories., 2005-07-16) and was superseded by
-6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
-2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
-commit already mentions an upcoming deprecation of the ".git/branches/"
-directory, and starting with a1d4aa7424 (Add repository-layout document.,
-2005-09-01) we have also marked this layout as deprecated. Eventually we also
-started to migrate away from ".git/remotes/" in favor of config-based remotes,
-and we have marked the directory as legacy in 3d3d282146 (Documentation:
-Grammar correction, wording fixes and cleanup, 2011-08-23)
-+
-As our documentation mentions, these directories are unlikely to be used in
-modern repositories and most users aren't even aware of these mechanisms. They
-have been deprecated for almost 20 years and 14 years respectively, and we are
-not aware of any active users that have complained about this deprecation.
-Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
-may cause confusion as "branches" are almost exclusively used in the context of
-references.
-+
-These features will be removed.
-
-* Support for "--stdin" option in the "name-rev" command was
-  deprecated (and hidden from the documentation) in the Git 2.40
-  timeframe, in preference to its synonym "--annotate-stdin".  Git 3.0
-  removes the support for "--stdin" altogether.
-
-* The git-whatchanged(1) command has outlived its usefulness more than
-  10 years ago, and takes more keystrokes to type than its rough
-  equivalent `git log --raw`.  We have nominated the command for
-  removal, have changed the command to refuse to work unless the
-  `--i-still-use-this` option is given, and asked the users to report
-  when they do so.
-+
-The command will be removed.
-
-* Support for `core.commentString=auto` has been deprecated and will
-  be removed in Git 3.0.
-+
-cf. <xmqqa59i45wc.fsf@gitster.g>
-
-* Support for `core.preferSymlinkRefs=true` has been deprecated and will be
-  removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
-  out in favor of using plain files using the textual representation of
-  symbolic refs.
-+
-Symbolic references were initially always stored as a symbolic link. This was
-changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a
-textfile., 2005-09-25), where a new textual symref format was introduced to
-store those symbolic refs in a plain file. In 9f0bb90d16
-(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git
-project switched the default to use the textual symrefs in favor of symbolic
-links.
-+
-The migration away from symbolic links has happened almost 20 years ago by now,
-and there is no known reason why one should prefer them nowadays. Furthermore,
-symbolic links are not supported on some platforms.
-+
-Note that only the writing side for such symbolic links is deprecated. Reading
-such symbolic links is still supported for now.
-
-== Superseded features that will not be deprecated
-
-Some features have gained newer replacements that aim to improve the design in
-certain ways. The fact that there is a replacement does not automatically mean
-that the old way of doing things will eventually be removed. This section tracks
-those features with newer alternatives.
-
-* The features git-checkout(1) offers are covered by the pair of commands
-  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
-  widespread, and it is not expected that this will change anytime soon, all
-  three commands will stay.
-+
-This decision may get revisited in case we ever figure out that there are
-almost no users of any of the commands anymore.
-+
-Cf. <xmqqttjazwwa.fsf@gitster.g>,
-<xmqqleeubork.fsf@gitster.g>,
-<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+This document as been moved to linkgit:gitbreaking-changes[7].
diff --git a/Documentation/Makefile b/Documentation/Makefile
index f8dea4b3953..8b0390ac0fc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -49,6 +49,7 @@ MAN5_TXT += gitprotocol-v2.adoc
 MAN5_TXT += gitrepository-layout.adoc
 MAN5_TXT += gitweb.conf.adoc
 
+MAN7_TXT += gitbreaking-changes.adoc
 MAN7_TXT += gitcli.adoc
 MAN7_TXT += gitcore-tutorial.adoc
 MAN7_TXT += gitcredentials.adoc
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
new file mode 100644
index 00000000000..c6b974b6d8c
--- /dev/null
+++ b/Documentation/gitbreaking-changes.adoc
@@ -0,0 +1,378 @@
+gitbreaking-changes(7)
+======================
+
+NAME
+----
+gitbreaking-changes - Breaking changes for upcoming Git 3.0
+
+SYNOPSIS
+--------
+*
+
+DESCRIPTION
+-----------
+*
+
+== Introduction: Upcoming breaking changes
+
+The Git project aims to ensure backwards compatibility to the best extent
+possible. Minor releases will not break backwards compatibility unless there is
+a very strong reason to do so, like for example a security vulnerability.
+
+Regardless of that, due to the age of the Git project, it is only natural to
+accumulate a backlog of backwards-incompatible changes that will eventually be
+required to keep the project aligned with a changing world. These changes fall
+into several categories:
+
+* Changes to long established defaults.
+* Concepts that have been replaced with a superior design.
+* Concepts, commands, configuration or options that have been lacking in major
+  ways and that cannot be fixed and which will thus be removed without any
+  replacement.
+
+Explicitly not included in this list are fixes to minor bugs that may cause a
+change in user-visible behavior.
+
+The Git project irregularly releases breaking versions that deliberately break
+backwards compatibility with older versions. This is done to ensure that Git
+remains relevant, safe and maintainable going forward. The release cadence of
+breaking versions is typically measured in multiple years. We had the following
+major breaking releases in the past:
+
+* Git 1.6.0, released in August 2008.
+* Git 2.0, released in May 2014.
+
+We use <major>.<minor> release numbers these days, starting from Git 2.0. For
+future releases, our plan is to increment <major> in the release number when we
+make the next breaking release. Before Git 2.0, the release numbers were
+1.<major>.<minor> with the intention to increment <major> for "usual" breaking
+releases, reserving the jump to Git 2.0 for really large backward-compatibility
+breaking changes.
+
+The intent of this document is to track upcoming deprecations for future
+breaking releases. Furthermore, this document also tracks what will _not_ be
+deprecated. This is done such that the outcome of discussions document both
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
+where the deprecation was discussed. These references use message-IDs, which
+can visited via
+
+  https://lore.kernel.org/git/$message_id/
+
+to see the message and its surrounding discussion. Such a reference is there to
+make it easier for you to find how the project reached consensus on the
+described item back then.
+
+This is a living document as the environment surrounding the project changes
+over time. If circumstances change, an earlier decision to deprecate or change
+something may need to be revisited from time to time. So do not take items on
+this list to mean "it is settled, do not waste our time bringing it up again".
+
+== Procedure
+
+Discussing the desire to make breaking changes, declaring that breaking
+changes are made at a certain version boundary, and recording these
+decisions in this document, are necessary but not sufficient.
+Because such changes are expected to be numerous, and the design and
+implementation of them are expected to span over time, they have to
+be deployable trivially at such a version boundary, prepared over long
+time.
+
+The breaking changes MUST be guarded with the a compile-time switch,
+WITH_BREAKING_CHANGES, to help this process.  When built with it,
+the resulting Git binary together with its documentation would
+behave as if these breaking changes slated for the next big version
+boundary are already in effect.  We also have a CI job to exercise
+the work-in-progress version of Git with these breaking changes.
+
+
+== Git 3.0
+
+The following subsections document upcoming breaking changes for Git 3.0. There
+is no planned release date for this breaking version yet.
+
+Proposed changes and removals only include items which are "ready" to be done.
+In other words, this is not supposed to be a wishlist of features that should
+be changed to or replaced in case the alternative was implemented already.
+
+=== Changes
+
+* The default hash function for new repositories will be changed from "sha1"
+  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
+  recommended against in FIPS 140-2 and similar certifications. Furthermore,
+  there are practical attacks on SHA-1 that weaken its cryptographic properties:
++
+  ** The SHAppening (2015). The first demonstration of a practical attack
+     against SHA-1 with 2^57 operations.
+  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
+  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
+     attacks with 2^68 operations.
+  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
+     operations.
++
+While we have protections in place against known attacks, it is expected
+that more attacks against SHA-1 will be found by future research. Paired
+with the ever-growing capability of hardware, it is only a matter of time
+before SHA-1 will be considered broken completely. We want to be prepared
+and will thus change the default hash algorithm to "sha256" for newly
+initialized repositories.
++
+An important requirement for this change is that the ecosystem is ready to
+support the "sha256" object format. This includes popular Git libraries,
+applications and forges.
++
+There is no plan to deprecate the "sha1" object format at this point in time.
++
+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
+* The default storage format for references in newly created repositories will
+  be changed from "files" to "reftable". The "reftable" format provides
+  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 common
+     on Windows and macOS platforms. As the "reftable" backend does not use
+     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,
+     this is not an issue with the "reftable" backend.
+  ** Deleting references with the "files" backend requires Git to rewrite the
+     complete "packed-refs" file. In large repositories with many references
+     this file can easily be dozens of megabytes in size, in extreme cases it
+     may be gigabytes. The "reftable" backend uses tombstone markers for
+     deleted references and thus does not have to rewrite all of its data.
+  ** Repository housekeeping with the "files" backend typically performs
+     all-into-one repacks of references. This can be quite expensive, and
+     consequently housekeeping is a tradeoff between the number of loose
+     references that accumulate and slow down operations that read references,
+     and compressing those loose references into the "packed-refs" file. The
+     "reftable" backend uses geometric compaction after every write, which
+     amortizes costs and ensures that the backend is always in a
+     well-maintained state.
+  ** Operations that write multiple references at once are not atomic with the
+     "files" backend. Consequently, Git may see in-between states when it reads
+     references while a reference transaction is in the process of being
+     committed to disk.
+  ** Writing many references at once is slow with the "files" backend because
+     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"
+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.
+
+* In new repositories, the default branch name will be `main`. We have been
+  warning that the default name will change since 675704c74dd (init:
+  provide useful advice about init.defaultBranch, 2020-12-11).  The new name
+  matches the default branch name used in new repositories by many of the
+  big Git forges.
+
+* Git will require Rust as a mandatory part of the build process. While Git
+  already started to adopt Rust in Git 2.49, all parts written in Rust are
+  optional for the time being. This includes:
++
+  ** The Rust wrapper around libgit.a that is part of "contrib/" and which has
+     been introduced in Git 2.49.
+  ** Subsystems that have an alternative implementation in Rust to test
+     interoperability between our C and Rust codebase.
+  ** Newly written features that are not mission critical for a fully functional
+     Git client.
++
+These changes are meant as test balloons to allow distributors of Git to prepare
+for Rust becoming a mandatory part of the build process. There will be multiple
+milestones for the introduction of Rust:
++
+--
+1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and
+   disabled in our Makefile so that the project can sort out the initial
+   infrastructure.
+2. In Git 2.55, both build systems will default-enable support for Rust.
+   Consequently, builds will break by default if Rust is not available on the
+   build host. The use of Rust can still be explicitly disabled via build
+   flags.
+3. In Git 3.0, the build options will be removed and support for Rust is
+   mandatory.
+--
++
+You can explicitly ask both Meson and our Makefile-based system to enable Rust
+by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`,
+respectively.
++
+The Git project will declare the last version before Git 3.0 to be a long-term
+support release. This long-term release will receive important bug fixes for at
+least four release cycles and security fixes for six release cycles. The Git
+project will hand over maintainership of the long-term release to distributors
+in case they need to extend the life of that long-term release even further.
+Details of how this long-term release will be handed over to the community will
+be discussed once the Git project decides to stop officially supporting it.
++
+We will evaluate the impact on downstream distributions before making Rust
+mandatory in Git 3.0. If we see that the impact on downstream distributions
+would be significant, we may decide to defer this change to a subsequent minor
+release. This evaluation will also take into account our own experience with
+how painful it is to keep Rust an optional component.
+
+* The default value of `safe.bareRepository` will change from `all` to
+  `explicit`. It is all too easy for an attacker to trick a user into cloning a
+  repository that contains an embedded bare repository with malicious hooks
+  configured. If the user enters that subdirectory and runs any Git command, Git
+  discovers the bare repository and the hooks fire. The user does not even need
+  to run a Git command explicitly: many shell prompts run `git status` in the
+  background to display branch and dirty state information, and `git status` in
+  turn may invoke the fsmonitor hook if so configured, making the user
+  vulnerable the moment they `cd` into the directory. The `safe.bareRepository`
+  configuration variable was introduced in 8959555cee (setup_git_directory():
+  add an owner check for the top-level directory, 2022-03-02) with a default of
+  `all` to preserve backwards compatibility.
++
+Changing the default to `explicit` means that Git will refuse to work with bare
+repositories that are discovered implicitly by walking up the directory tree.
+Bare repositories specified explicitly via the `--git-dir` command-line option
+or the `GIT_DIR` environment variable continue to work regardless of this
+setting. Repositories that look like a `.git` directory, a worktree, or a
+submodule directory are also unaffected.
++
+Users who rely on implicit discovery of bare repositories can restore the
+previous behavior by setting `safe.bareRepository=all` in their global or
+system configuration.
+
+=== Removals
+
+* Support for grafting commits has long been superseded by git-replace(1).
+  Grafts are inferior to replacement refs:
++
+  ** Grafts are a local-only mechanism and cannot be shared across
+     repositories.
+  ** Grafts can lead to hard-to-diagnose problems when transferring objects
+     between repositories.
++
+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
+info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
+
+* The git-pack-redundant(1) command can be used to remove redundant pack files.
+  The subcommand is unusably slow and the reason why nobody reports it as a
+  performance bug is suspected to be the absence of users. We have nominated
+  the command for removal and have started to emit a user-visible warning in
+  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
+  2020-08-25) whenever the command is executed.
++
+So far there was a single complaint about somebody still using the command, but
+that complaint did not cause us to reverse course. On the contrary, we have
+doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
+escalate deprecation warning to an error, 2023-03-23), the command dies unless
+the user passes the `--i-still-use-this` option.
++
+There have not been any subsequent complaints, so this command will finally be
+removed.
++
+Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
+    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
+    <20230323204047.GA9290@coredump.intra.peff.net>,
+
+* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
+  and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
+  the repository configuration.
++
+The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
+short-hand notation for remote repositories., 2005-07-16) and was superseded by
+6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
+2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
+commit already mentions an upcoming deprecation of the ".git/branches/"
+directory, and starting with a1d4aa7424 (Add repository-layout document.,
+2005-09-01) we have also marked this layout as deprecated. Eventually we also
+started to migrate away from ".git/remotes/" in favor of config-based remotes,
+and we have marked the directory as legacy in 3d3d282146 (Documentation:
+Grammar correction, wording fixes and cleanup, 2011-08-23)
++
+As our documentation mentions, these directories are unlikely to be used in
+modern repositories and most users aren't even aware of these mechanisms. They
+have been deprecated for almost 20 years and 14 years respectively, and we are
+not aware of any active users that have complained about this deprecation.
+Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
+may cause confusion as "branches" are almost exclusively used in the context of
+references.
++
+These features will be removed.
+
+* Support for "--stdin" option in the "name-rev" command was
+  deprecated (and hidden from the documentation) in the Git 2.40
+  timeframe, in preference to its synonym "--annotate-stdin".  Git 3.0
+  removes the support for "--stdin" altogether.
+
+* The git-whatchanged(1) command has outlived its usefulness more than
+  10 years ago, and takes more keystrokes to type than its rough
+  equivalent `git log --raw`.  We have nominated the command for
+  removal, have changed the command to refuse to work unless the
+  `--i-still-use-this` option is given, and asked the users to report
+  when they do so.
++
+The command will be removed.
+
+* Support for `core.commentString=auto` has been deprecated and will
+  be removed in Git 3.0.
++
+cf. <xmqqa59i45wc.fsf@gitster.g>
+
+* Support for `core.preferSymlinkRefs=true` has been deprecated and will be
+  removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
+  out in favor of using plain files using the textual representation of
+  symbolic refs.
++
+Symbolic references were initially always stored as a symbolic link. This was
+changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a
+textfile., 2005-09-25), where a new textual symref format was introduced to
+store those symbolic refs in a plain file. In 9f0bb90d16
+(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git
+project switched the default to use the textual symrefs in favor of symbolic
+links.
++
+The migration away from symbolic links has happened almost 20 years ago by now,
+and there is no known reason why one should prefer them nowadays. Furthermore,
+symbolic links are not supported on some platforms.
++
+Note that only the writing side for such symbolic links is deprecated. Reading
+such symbolic links is still supported for now.
+
+== Superseded features that will not be deprecated
+
+Some features have gained newer replacements that aim to improve the design in
+certain ways. The fact that there is a replacement does not automatically mean
+that the old way of doing things will eventually be removed. This section tracks
+those features with newer alternatives.
+
+* The features git-checkout(1) offers are covered by the pair of commands
+  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
+  widespread, and it is not expected that this will change anytime soon, all
+  three commands will stay.
++
+This decision may get revisited in case we ever figure out that there are
+almost no users of any of the commands anymore.
++
+Cf. <xmqqttjazwwa.fsf@gitster.g>,
+<xmqqleeubork.fsf@gitster.g>,
+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/meson.build b/Documentation/meson.build
index f4854f802d4..af436b2d5e9 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -192,6 +192,7 @@ manpages = {
   'gitweb.conf.adoc' : 5,
 
   # Category 7.
+  'gitbreaking-changes.adoc' : 7,
   'gitcli.adoc' : 7,
   'gitcore-tutorial.adoc' : 7,
   'gitcredentials.adoc' : 7,
-- 
2.55.0.793.gc667de3f2c5
Patrick Steinhardt· Sep 30, 2026, 13:28 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [RFC PATCH 1/4] doc: transform breaking changes doc to a manpage

On Mon, Sep 28, 2026 at 12:41:25PM +0200, kristofferhaugsbakk@fastmail.com wrote:
Show 18 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> The breaking changes document is not a regular Git documentation page.
> That means that you cannot navigate to the doc with git(1), i.e. with:
> 
>     git help BreakingChanges
> 
> You instead have to download the Git project source. Or go to
> git-scm.com.[1] Then you get this disclaimer:[2]
> 
>     This information is specific to the Git project
> 
>     Please note that this information is only relevant to you if you
>     plan on contributing to the Git project itself. It is in no shape or
>     form required reading for regular Git users.
> 
> But this document is relevant to *all* Git users. Everyone should have
> as easy access to it as the other doc and guide pages.

Yeah, I agree with that sentiment. The one interesting question about it is of course what we'll do with the document once Git 3.0 is out. Will we retain it? Will we remove it? Will we empty it and make it focus on Git 4.0?

I guess once it's a manpage we should definitely retain its contents for a while longer. The breaking changes will be relevant to users even after they've already upgraded to Git 3.0. But if so, we should probably introduce a new section for Git 4.0, at least if we already want to start thinking about that.

  NB: even if we start thinking about it I think we should probably not
  release it anytime soon. I guess having a major release once per
  decade may be good enough.
Show 6 quoted lines
> To that end, let’s move the text to a manpage. But keep the old page,
> just linking to the new one. (We wouldn’t want to break any readers.)
> 
> Just do the minimal changes for the new format. Also demote the first
> section to the second level, i.e. make “Introduction” the same level
> as “Procedure’.

I feel like a good first step could've been to convert the BreakingChanges.adoc document in-place to use the new format. Like that, it would've become way easier to see what's actually changing. The rename could've then been a 1:1 move.

Patrick
Kristoffer Haugsbakk· Sep 30, 2026, 14:17 UTC · re: Patrick Steinhardt · lore

Re: [RFC PATCH 1/4] doc: transform breaking changes doc to a manpage

On Wed, Sep 30, 2026, at 15:28, Patrick Steinhardt wrote:
Show 22 quoted lines
> On Mon, Sep 28, 2026 at 12:41:25PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> The breaking changes document is not a regular Git documentation page.
>> That means that you cannot navigate to the doc with git(1), i.e. with:
>>
>>     git help BreakingChanges
>>
>> You instead have to download the Git project source. Or go to
>> git-scm.com.[1] Then you get this disclaimer:[2]
>>
>>     This information is specific to the Git project
>>
>>     Please note that this information is only relevant to you if you
>>     plan on contributing to the Git project itself. It is in no shape or
>>     form required reading for regular Git users.
>>
>> But this document is relevant to *all* Git users. Everyone should have
>> as easy access to it as the other doc and guide pages.
>
> Yeah, I agree with that sentiment.
I’m glad that this idea makes sense to more than one person. x)
Show 13 quoted lines
> [...] The one interesting question about it is of course what we'll do
> with the document once Git 3.0 is out. Will we retain it? Will we
> remove it? Will we empty it and make it focus on Git 4.0?
>
> I guess once it's a manpage we should definitely retain its contents for
> a while longer. The breaking changes will be relevant to users even
> after they've already upgraded to Git 3.0. But if so, we should probably
> introduce a new section for Git 4.0, at least if we already want to
> start thinking about that.
>
>   NB: even if we start thinking about it I think we should probably not
>   release it anytime soon. I guess having a major release once per
>   decade may be good enough.

I know you are wondering out loud here to the fora. But just personally, I imagine that this will happen after Git 3.0:

• A section at the end about Git 3.0 for historical interest as well as
  people on older versions who might be browsing outside of their
  installation (probably git-scm) (and who might be on pre-3.0)
• Git 4.0 discussion before that, however hypothetical or distant the
  release date
Show 12 quoted lines
>
>> To that end, let’s move the text to a manpage. But keep the old page,
>> just linking to the new one. (We wouldn’t want to break any readers.)
>>
>> Just do the minimal changes for the new format. Also demote the first
>> section to the second level, i.e. make “Introduction” the same level
>> as “Procedure’.
>
> I feel like a good first step could've been to convert the
> BreakingChanges.adoc document in-place to use the new format. Like that,
> it would've become way easier to see what's actually changing. The
> rename could've then been a 1:1 move.
Like this?
1. Convert to the manpage format without changing the filename
2. Rename the file: pure rename without any other modifications
3. Resurrect `BreakingChanges.adoc` with one line that points to the new
   document
Thanks for reviewing.
Patrick Steinhardt· Sep 30, 2026, 14:28 UTC · re: Kristoffer Haugsbakk · lore

Re: [RFC PATCH 1/4] doc: transform breaking changes doc to a manpage

On Wed, Sep 30, 2026 at 04:17:44PM +0200, Kristoffer Haugsbakk wrote:
Show 25 quoted lines
> On Wed, Sep 30, 2026, at 15:28, Patrick Steinhardt wrote:
> > On Mon, Sep 28, 2026 at 12:41:25PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> >> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> > [...] The one interesting question about it is of course what we'll do
> > with the document once Git 3.0 is out. Will we retain it? Will we
> > remove it? Will we empty it and make it focus on Git 4.0?
> >
> > I guess once it's a manpage we should definitely retain its contents for
> > a while longer. The breaking changes will be relevant to users even
> > after they've already upgraded to Git 3.0. But if so, we should probably
> > introduce a new section for Git 4.0, at least if we already want to
> > start thinking about that.
> >
> >   NB: even if we start thinking about it I think we should probably not
> >   release it anytime soon. I guess having a major release once per
> >   decade may be good enough.
> 
> I know you are wondering out loud here to the fora. But just personally,
> I imagine that this will happen after Git 3.0:
> 
> • A section at the end about Git 3.0 for historical interest as well as
>   people on older versions who might be browsing outside of their
>   installation (probably git-scm) (and who might be on pre-3.0)
> • Git 4.0 discussion before that, however hypothetical or distant the
>   release date
Yeah, that's also mostly what I arrived at, too.
Show 18 quoted lines
> >> To that end, let’s move the text to a manpage. But keep the old page,
> >> just linking to the new one. (We wouldn’t want to break any readers.)
> >>
> >> Just do the minimal changes for the new format. Also demote the first
> >> section to the second level, i.e. make “Introduction” the same level
> >> as “Procedure’.
> >
> > I feel like a good first step could've been to convert the
> > BreakingChanges.adoc document in-place to use the new format. Like that,
> > it would've become way easier to see what's actually changing. The
> > rename could've then been a 1:1 move.
> 
> Like this?
> 
> 1. Convert to the manpage format without changing the filename
> 2. Rename the file: pure rename without any other modifications
> 3. Resurrect `BreakingChanges.adoc` with one line that points to the new
>    document

I guess (2) and (3) can easily be combined. I'd hope that Git still detects this as a 1:1 rename.

Patrick
kristofferhaugsbakk@fastmail.com· Sep 28, 2026, 10:41 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This document has used msg-ids to reference emails since its inception.[1] This makes the text a bit more terse, and is perhaps also convenient for people who can use msg-ids to link to messages in their inbox. But we should consider how convenient this is for people in general, now that this is a more public-facing page (see previous commit). And I suspect that most people will be forced to paste the msg-id according to the described URL template:

    https://lore.kernel.org/git/$message_id/

Let’s instead replace all of the msg-ids with complete links. That way everyone can jump right to the discussions.

† 1: 57ec9254 (docs: introduce document to announce breaking changes, 2024-06-14)
Note that we have to URL encode two msg-ids:
     CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com
     CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com
Lore can handle them just fine, but asciidoctor(1) cannot.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/gitbreaking-changes.adoc | 33 +++++++++++++-------------
 1 file changed, 16 insertions(+), 17 deletions(-)
Show changes to Documentation/gitbreaking-changes.adoc +16 −17
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index c6b974b6d8c..9aba419efc9 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -59,15 +59,14 @@ make the described change that can be easily understood without having to read
 the mailing list discussions. If there are alternatives to the changed feature,
 those alternatives should be pointed out to our users.
 
-All items should be accompanied by references to relevant mailing list threads
-where the deprecation was discussed. These references use message-IDs, which
-can visited via
+All items should be accompanied by links to relevant mailing list threads
+where the deprecation was discussed. These links use this format:
 
   https://lore.kernel.org/git/$message_id/
 
-to see the message and its surrounding discussion. Such a reference is there to
-make it easier for you to find how the project reached consensus on the
-described item back then.
+I.e. they link to the `Message-ID` of the email on the mailing
+list. These references are there to make it easier for you to find how
+the project reached consensus on the described item back then.
 
 This is a living document as the environment surrounding the project changes
 over time. If circumstances change, an earlier decision to deprecate or change
@@ -129,9 +128,9 @@ applications and forges.
 +
 There is no plan to deprecate the "sha1" object format at this point in time.
 +
-Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
-<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
+https://lore.kernel.org/git/20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain,
+https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%2BDiUQ@mail.gmail.com/.
 
 * The default storage format for references in newly created repositories will
   be changed from "files" to "reftable". The "reftable" format provides
@@ -268,7 +267,7 @@ system configuration.
 The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
 info/grafts as outdated, 2014-03-05) and will be removed.
 +
-Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
+Cf. https://lore.kernel.org/git/20140304174806.GA11561@sigill.intra.peff.net.
 
 * The git-pack-redundant(1) command can be used to remove redundant pack files.
   The subcommand is unusably slow and the reason why nobody reports it as a
@@ -286,9 +285,9 @@ the user passes the `--i-still-use-this` option.
 There have not been any subsequent complaints, so this command will finally be
 removed.
 +
-Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
-    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
-    <20230323204047.GA9290@coredump.intra.peff.net>,
+Cf. https://lore.kernel.org/git/xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com,
+https://lore.kernel.org/git/CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ%3DKAKhtpDNTvHJFuX1NA%40mail.gmail.com,
+https://lore.kernel.org/git/20230323204047.GA9290@coredump.intra.peff.net,
 
 * Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
   and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
@@ -332,7 +331,7 @@ The command will be removed.
 * Support for `core.commentString=auto` has been deprecated and will
   be removed in Git 3.0.
 +
-cf. <xmqqa59i45wc.fsf@gitster.g>
+cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
 
 * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
   removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
@@ -369,9 +368,9 @@ those features with newer alternatives.
 This decision may get revisited in case we ever figure out that there are
 almost no users of any of the commands anymore.
 +
-Cf. <xmqqttjazwwa.fsf@gitster.g>,
-<xmqqleeubork.fsf@gitster.g>,
-<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
+https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
+https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
 
 GIT
 ---
-- 
2.55.0.793.gc667de3f2c5
Patrick Steinhardt· Sep 30, 2026, 13:28 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

On Mon, Sep 28, 2026 at 12:41:26PM +0200, kristofferhaugsbakk@fastmail.com wrote:
Show 14 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> This document has used msg-ids to reference emails since its
> inception.[1] This makes the text a bit more terse, and is perhaps
> also convenient for people who can use msg-ids to link to messages
> in their inbox. But we should consider how convenient this is for people
> in general, now that this is a more public-facing page (see previous
> commit). And I suspect that most people will be forced to paste the
> msg-id according to the described URL template:
> 
>     https://lore.kernel.org/git/$message_id/
> 
> Let’s instead replace all of the msg-ids with complete links. That way
> everyone can jump right to the discussions.

Fair. The links may of course break if at any point in time lore.kernel.org were to vanish or change its interface. But if so we can adapt accordingly, also because the message ID can still be extracted trivially.

Show 26 quoted lines
> 
> diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
> index c6b974b6d8c..9aba419efc9 100644
> --- a/Documentation/gitbreaking-changes.adoc
> +++ b/Documentation/gitbreaking-changes.adoc
> @@ -59,15 +59,14 @@ make the described change that can be easily understood without having to read
>  the mailing list discussions. If there are alternatives to the changed feature,
>  those alternatives should be pointed out to our users.
>  
> -All items should be accompanied by references to relevant mailing list threads
> -where the deprecation was discussed. These references use message-IDs, which
> -can visited via
> +All items should be accompanied by links to relevant mailing list threads
> +where the deprecation was discussed. These links use this format:
>  
>    https://lore.kernel.org/git/$message_id/
>  
> -to see the message and its surrounding discussion. Such a reference is there to
> -make it easier for you to find how the project reached consensus on the
> -described item back then.
> +I.e. they link to the `Message-ID` of the email on the mailing
> +list. These references are there to make it easier for you to find how
> +the project reached consensus on the described item back then.
>  
>  This is a living document as the environment surrounding the project changes
>  over time. If circumstances change, an earlier decision to deprecate or change

I wonder whether the information on how to add new entries should now go towards the end of this document. The target audience is expanding with your patch series, and most of those new readers will not care about how to add an entry.

Show 9 quoted lines
> @@ -332,7 +331,7 @@ The command will be removed.
>  * Support for `core.commentString=auto` has been deprecated and will
>    be removed in Git 3.0.
>  +
> -cf. <xmqqa59i45wc.fsf@gitster.g>
> +cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
>  
>  * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
>    removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
Nit: two spaces.
Patrick
Kristoffer Haugsbakk· Sep 30, 2026, 14:09 UTC · re: Patrick Steinhardt · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

On Wed, Sep 30, 2026, at 15:28, Patrick Steinhardt wrote:
Show 10 quoted lines
> On Mon, Sep 28, 2026 at 12:41:26PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>>[snip]
>> Let’s instead replace all of the msg-ids with complete links. That way
>> everyone can jump right to the discussions.
>
> Fair. The links may of course break if at any point in time
> lore.kernel.org were to vanish or change its interface. But if so we can
> adapt accordingly, also because the message ID can still be extracted
> trivially.
Yeah makes sense.
Show 32 quoted lines
>
>>
>> diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
>> index c6b974b6d8c..9aba419efc9 100644
>> --- a/Documentation/gitbreaking-changes.adoc
>> +++ b/Documentation/gitbreaking-changes.adoc
>> @@ -59,15 +59,14 @@ make the described change that can be easily understood without having to read
>>  the mailing list discussions. If there are alternatives to the changed feature,
>>  those alternatives should be pointed out to our users.
>>
>> -All items should be accompanied by references to relevant mailing list threads
>> -where the deprecation was discussed. These references use message-IDs, which
>> -can visited via
>> +All items should be accompanied by links to relevant mailing list threads
>> +where the deprecation was discussed. These links use this format:
>>
>>    https://lore.kernel.org/git/$message_id/
>>
>> -to see the message and its surrounding discussion. Such a reference is there to
>> -make it easier for you to find how the project reached consensus on the
>> -described item back then.
>> +I.e. they link to the `Message-ID` of the email on the mailing
>> +list. These references are there to make it easier for you to find how
>> +the project reached consensus on the described item back then.
>>
>>  This is a living document as the environment surrounding the project changes
>>  over time. If circumstances change, an earlier decision to deprecate or change
>
> I wonder whether the information on how to add new entries should now go
> towards the end of this document. The target audience is expanding with
> your patch series, and most of those new readers will not care about how
> to add an entry.
Yeah, I can make that change.
Show 12 quoted lines
>
>> @@ -332,7 +331,7 @@ The command will be removed.
>>  * Support for `core.commentString=auto` has been deprecated and will
>>    be removed in Git 3.0.
>>  +
>> -cf. <xmqqa59i45wc.fsf@gitster.g>
>> +cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
>>
>>  * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
>>    removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
>
> Nit: two spaces.
Thanks, I’ll fix that.
Junio C Hamano· Sep 30, 2026, 19:45 UTC · re: Patrick Steinhardt · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

Patrick Steinhardt <ps@pks.im> writes:
Show 20 quoted lines
> On Mon, Sep 28, 2026 at 12:41:26PM +0200, kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>> 
>> This document has used msg-ids to reference emails since its
>> inception.[1] This makes the text a bit more terse, and is perhaps
>> also convenient for people who can use msg-ids to link to messages
>> in their inbox. But we should consider how convenient this is for people
>> in general, now that this is a more public-facing page (see previous
>> commit). And I suspect that most people will be forced to paste the
>> msg-id according to the described URL template:
>> 
>>     https://lore.kernel.org/git/$message_id/
>> 
>> Let’s instead replace all of the msg-ids with complete links. That way
>> everyone can jump right to the discussions.
>
> Fair. The links may of course break if at any point in time
> lore.kernel.org were to vanish or change its interface. But if so we can
> adapt accordingly, also because the message ID can still be extracted
> trivially.

One caveat is that some "funny characters" in message IDs need to be URL-encoded.

A recent example I saw was <20260930061524.GNkIK%taahol@utu.fi>; https://lore.kernel.org/git/20260930061524.GNkIK%25taahol@utu.fi/ is the URL you need to visit to view the message.

Having said that, I am somewhat negative on what this particular patch does. We should instead give both, having something like

 cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/[<xmqqa59i45wc.fsf@gitster.g>^]

in the source, and render a readable link text with reachable href when shown in the browser.

Patrick Steinhardt· Oct 1, 2026, 06:27 UTC · re: Junio C Hamano · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

On Wed, Sep 30, 2026 at 12:45:06PM -0700, Junio C Hamano wrote:
Show 37 quoted lines
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > On Mon, Sep 28, 2026 at 12:41:26PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> >> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> >> 
> >> This document has used msg-ids to reference emails since its
> >> inception.[1] This makes the text a bit more terse, and is perhaps
> >> also convenient for people who can use msg-ids to link to messages
> >> in their inbox. But we should consider how convenient this is for people
> >> in general, now that this is a more public-facing page (see previous
> >> commit). And I suspect that most people will be forced to paste the
> >> msg-id according to the described URL template:
> >> 
> >>     https://lore.kernel.org/git/$message_id/
> >> 
> >> Let’s instead replace all of the msg-ids with complete links. That way
> >> everyone can jump right to the discussions.
> >
> > Fair. The links may of course break if at any point in time
> > lore.kernel.org were to vanish or change its interface. But if so we can
> > adapt accordingly, also because the message ID can still be extracted
> > trivially.
> 
> One caveat is that some "funny characters" in message IDs need to be
> URL-encoded.
> 
> A recent example I saw was <20260930061524.GNkIK%taahol@utu.fi>;
> https://lore.kernel.org/git/20260930061524.GNkIK%25taahol@utu.fi/ is
> the URL you need to visit to view the message.
> 
> Having said that, I am somewhat negative on what this particular
> patch does.  We should instead give both, having something like
> 
>  cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/[<xmqqa59i45wc.fsf@gitster.g>^]
> 
> in the source, and render a readable link text with reachable href
> when shown in the browser.
Oh, that's even better if you ask me!
Patrick
Kristoffer Haugsbakk· Oct 3, 2026, 11:52 UTC · re: Junio C Hamano · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

On Wed, Sep 30, 2026, at 21:45, Junio C Hamano wrote:
Show 25 quoted lines
> Patrick Steinhardt <ps@pks.im> writes:
>> On Mon, Sep 28, 2026 at 12:41:26PM +0200, kristofferhaugsbakk@fastmail.com wrote:
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>>[snip]
>>
>> Fair. The links may of course break if at any point in time
>> lore.kernel.org were to vanish or change its interface. But if so we can
>> adapt accordingly, also because the message ID can still be extracted
>> trivially.
>
> One caveat is that some "funny characters" in message IDs need to be
> URL-encoded.
>
> A recent example I saw was <20260930061524.GNkIK%taahol@utu.fi>;
> https://lore.kernel.org/git/20260930061524.GNkIK%25taahol@utu.fi/ is
> the URL you need to visit to view the message.
>
> Having said that, I am somewhat negative on what this particular
> patch does.  We should instead give both, having something like
>
>  cf.
> https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/[<xmqqa59i45wc.fsf@gitster.g>^]
>
> in the source, and render a readable link text with reachable href
> when shown in the browser.
With that I get a regular `href` and a `mailto` href.
    <div class="paragraph"><p>cf. <a href="https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/">&lt;<a href="mailto:xmqqa59i45wc.fsf@gitster.g">xmqqa59i45wc.fsf@gitster.g</a>&gt;^</a></p></div>
The `mailto` wins and prepares to send an email.

For HTML output at least (I haven’t tested man yet) you can use `&commat;`:

    cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/[<xmqqa59i45wc.fsf&commat;gitster.g>^]
And that works.
But with this rendered output:
    • Support for core.commentString=auto has been deprecated and will
      be removed in Git 3.0.
      cf. <xmqqa59i45wc.fsf@gitster.g>^

You have an exceptionally short (cf. UUID monstrosity) msg-id, like all your msg-ids,[1] to the point that it looks as long as an email address but more random-looking and with a weird domain name. And the exception for email addresses (looking) that are formatted as links are that they are `mailto` links. So what would the expectation be for someone who hasn’t read a preamble about what these things with @-symbols are? That they are contact addresses perhaps?

I don’t think this is an improvement. Now people unaccustomed to using msg-ids have to be cognizant of these things as links (not as weird email addresses), which is even assuming that they read the preamble. But with regular URLs you don’t even need a preamble.

As for the man format: my terminal lets me open links.

Maybe we should drop this patch if we disagree that either choice here is an improvement.

† 1: 3/11 of the existing msg-ids are from the maintainer
Kristoffer Haugsbakk· Oct 3, 2026, 14:10 UTC · re: Kristoffer Haugsbakk · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

On Sat, Oct 3, 2026, at 13:52, Kristoffer Haugsbakk wrote:
> [snip]
> And the exception
> for email addresses (looking) that are formatted as links are that they
> are `mailto` links. 
Sorry. Replace “exception” with “expectation”.
Junio C Hamano· Oct 4, 2026, 02:31 UTC · re: Kristoffer Haugsbakk · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 14 quoted lines
>> Having said that, I am somewhat negative on what this particular
>> patch does.  We should instead give both, having something like
>>
>>  cf.
>> https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/[<xmqqa59i45wc.fsf@gitster.g>^]
>>
>> in the source, and render a readable link text with reachable href
>> when shown in the browser.
>
> With that I get a regular `href` and a `mailto` href.
>
>     <div class="paragraph"><p>cf. <a href="https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/">&lt;<a href="mailto:xmqqa59i45wc.fsf@gitster.g">xmqqa59i45wc.fsf@gitster.g</a>&gt;^</a></p></div>
>
> The `mailto` wins and prepares to send an email.
Ouch.

Our primary goal is to give readers ready access to the messages we refer to. With that mailto glitch, it would be unusable, so let's scrap the idea of using the Message-ID as the link text for the link that leads to the lore archive, unless we can tell Asciidoctor to do what we want. Quite honestly, I did not know Asciidoctor was that broken.

Also, if readers do not recognize "Message-ID used as link text" as clickable links, that also defeats the purpose.

The secondary goal of my suggestion was to avoid repeating the disaster we faced after gmane stopped offering HTTP access to its archive. We ended up with a bunch of references like $gmane/217 to refer to their article numbers in our historical commit log messages, and of course, once we could no longer rely on them, we had no way of knowing what message article 217 referred to [*]. The URL to the lore archive does contain an encoded Message-ID, so the situation is much better than that of gmane from long ago. However, if you live in an environment where it is easier to feed the Message-ID directly to your e-mail program or newsreader than having to visit the web and then come back to your e-mail environment to continue your work, having a readily cut-and-pasteable Message-ID that is not encoded as part of a URL is definitely superior to having the lore URL alone.

But the important point is that this was a secondary goal. If the format using Message-IDs as link texts to go to the lore archive does not work (either because we cannot bypass the mailto behavior, or because readers would not recognize that Message-IDs are clickable links), I am perfectly fine with leaving only the HTTP link that is so obviously a URL (even though I find them rather ugly, but I am not the primary target audience).

Thanks for testing this and finding the issues before we went too far.

[References]
 * It is <Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org>, which I
   think is still one of the most important messages on the list ;-)
Kristoffer Haugsbakk· Oct 6, 2026, 16:38 UTC · re: Junio C Hamano · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

On Sun, Oct 4, 2026, at 04:31, Junio C Hamano wrote:
Show 18 quoted lines
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>>>[snip]
>>
>> With that I get a regular `href` and a `mailto` href.
>>
>>     <div class="paragraph"><p>cf. <a href="https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/">&lt;<a href="mailto:xmqqa59i45wc.fsf@gitster.g">xmqqa59i45wc.fsf@gitster.g</a>&gt;^</a></p></div>
>>
>> The `mailto` wins and prepares to send an email.
>
> Ouch.
>
> Our primary goal is to give readers ready access to the messages we
> refer to.  With that mailto glitch, it would be unusable, so let's
> scrap the idea of using the Message-ID as the link text for the link
> that leads to the lore archive, unless we can tell Asciidoctor to do
> what we want.  Quite honestly, I did not know Asciidoctor was that
> broken.
Surprised I was not.
Show 12 quoted lines
>
> Also, if readers do not recognize "Message-ID used as link text" as
> clickable links, that also defeats the purpose.
>
> The secondary goal of my suggestion was to avoid repeating the
> disaster we faced after gmane stopped offering HTTP access to its
> archive.  We ended up with a bunch of references like $gmane/217 to
> refer to their article numbers in our historical commit log
> messages, and of course, once we could no longer rely on them, we
> had no way of knowing what message article 217 referred to [*].  The
> URL to the lore archive does contain an encoded Message-ID, so the
> situation is much better than that of gmane from long ago.
Yes, I find it frustrating to read Gmane-era list messages.

But now these references are already forever in the Git history. So even if I end up obfuscating them with a URL encoding, it will be clear from the history... for those who go to the trouble of looking.

But see later in this message about how to retain the original msg-ids.
Show 7 quoted lines
> However,
> if you live in an environment where it is easier to feed the
> Message-ID directly to your e-mail program or newsreader than having
> to visit the web and then come back to your e-mail environment to
> continue your work, having a readily cut-and-pasteable Message-ID
> that is not encoded as part of a URL is definitely superior to
> having the lore URL alone.

Yeah I suspected that email-only users would have such a slick setup. Thanks for explaining.

Show 7 quoted lines
> But the important point is that this was a secondary goal.  If the
> format using Message-IDs as link texts to go to the lore archive does
> not work (either because we cannot bypass the mailto behavior, or
> because readers would not recognize that Message-IDs are clickable
> links), I am perfectly fine with leaving only the HTTP link that
> is so obviously a URL (even though I find them rather ugly, but
> I am not the primary target audience).
What if we used footnotes for all of the original msg-ids?
    <URL>[1]
    [...]
    [1]: <msg-id>

Or maybe just for the ones that need URL encoding? I personally think it would be better to use them for all if we go for this approach.

>[snip]
Junio C Hamano· Oct 6, 2026, 20:33 UTC · re: Kristoffer Haugsbakk · lore

Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 10 quoted lines
> What if we used footnotes for all of the original msg-ids?
>
>     <URL>[1]
>
>     [...]
>
>     [1]: <msg-id>
>
> Or maybe just for the ones that need URL encoding? I personally think it
> would be better to use them for all if we go for this approach.

If this is an attempt to cater to those who prefer raw message IDs over URLs that encode them, I doubt it is an improvement.

A footnote placed far down the document that merely repeats what is already in the URL is uglier than simply using the URL without such a footnote layout. The cost of avoiding this ugliness is rather small for such users. They have to extract the encoded message ID from the URL, perhaps decoding it manually, before using it. That is not too much work.

So, unless we can use a clickable link whose text can be copied to get the raw message ID (which even novice users would clearly recognize as a link rather than an e-mail address), which we already agreed is impossible, let's just provide the URL. Users can copy and paste it into their browsers, and many terminal emulators will let them click it directly, as you mentioned earlier.

Thanks.
kristofferhaugsbakk@fastmail.com· Sep 28, 2026, 10:41 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[RFC PATCH 3/4] doc: gitbreaking-changes: add note about living document

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This document has always stated that it is a “living document”, subject to change. With that in mind, we should be mindful of a potentially larger readerbase now that this is a more public-facing page. One could imagine that someone reads this document on a released version, disagrees with a point there, and posts feedback to the project—but this decision could have already been reverted in the live document.[1]

Let’s add a note (admonition) following the “live document” with such a reminder. Let’s keep it short and simple though and not go into how to fetch the source. They can figure that out themselves.

† 1: Let’s say that someone on Git for Debian Stable reads about the
     breaking changes for Git 3.0. They don’t like something about it
     so they post it to the mailing list. Then the mailing list informs
     them that Git 3.0 was released two years ago and that the current
     document is about Git 4.0.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/gitbreaking-changes.adoc | 10 ++++++++++
 1 file changed, 10 insertions(+)
Show changes to Documentation/gitbreaking-changes.adoc +10 −0
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index 9aba419efc9..410476c7993 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -73,6 +73,16 @@ over time. If circumstances change, an earlier decision to deprecate or change
 something may need to be revisited from time to time. So do not take items on
 this list to mean "it is settled, do not waste our time bringing it up again".
 
+[NOTE]
+--
+In case you are reading this document from a released version: this
+being a _living document_ means that you might want to consult what
+the current, development version of the document looks like in case
+anything here motivates you to post some feedback to the project.
+Because specific details you read here might have been changed in the
+development version.
+--
+
 == Procedure
 
 Discussing the desire to make breaking changes, declaring that breaking
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Sep 28, 2026, 10:41 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[RFC PATCH 4/4] doc: git: mention gitbreaking-changes(7)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Users are the ones who are impacted by breaking changes. Certainly much more than Git developers who are already plugged in to the development channels that discuss the trajectory of the project.

We have to that end already made the breaking changes document into a more public-facing page, namely a regular manpage. Now let’s mention on git(1) like the other user-relevant guides.

Like last time,[1] use double-spacing for sentences since that is the existing convention.

† 1: 5745353d (doc: git: link to the gitdatamodel(7) tutorial,
     2026-09-05)
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git.adoc | 5 ++++-
 command-list.txt       | 1 +
 2 files changed, 5 insertions(+), 1 deletion(-)
Show changes to 2 files +5 −1

Documentation/git.adoc, command-list.txt

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index 6f0075f9188..6a4ef2dff5c 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc
@@ -26,7 +26,9 @@ See linkgit:gittutorial[7] to get started, then see
 linkgit:giteveryday[7] for a useful minimum set of
 commands.  The link:user-manual.html[Git User's Manual] has a more
 in-depth introduction.  See linkgit:gitdatamodel[7] if you want to
-learn about the data model and important terminology.
+learn about the data model and important terminology.  See
+linkgit:gitbreaking-changes[7] for a discussion of breaking changes
+planned for Git 3.0.
 
 After you mastered the basic concepts, you can come back to this
 page to learn what commands Git offers.  You can learn more about
@@ -1204,6 +1206,7 @@ linkgit:gittutorial[7], linkgit:gittutorial-2[7],
 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
 linkgit:gitglossary[7], linkgit:gitdatamodel[7],
 linkgit:gitcore-tutorial[7], linkgit:gitcli[7],
+linkgit:gitbreaking-changes[7],
 link:user-manual.html[The Git User's Manual],
 linkgit:gitworkflows[7]
 
diff --git a/command-list.txt b/command-list.txt
index 63ae2a67c94..1b7236a62fd 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -213,6 +213,7 @@ git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
 gitattributes                           userinterfaces
+gitbreaking-changes                     guide
 gitcli                                  userinterfaces
 gitcore-tutorial                        guide
 gitcredentials                          guide
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Oct 8, 2026, 19:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 0/5] doc: move BreakingChanges to a manpage

From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name: kh/doc-gitbreaking-changes7

Topic summary: Move BreakingChanges document to a manpage for easier visibility.

Notes to the maintainer: conflicts with topics ps/ref-storage-format (in `master`) and bc/restrict-hex-to-lowercase (in `seen`). Respectively, they add these things to `BreakingChanges.adoc`:

(1)
     +
     Users that get immediate benefit from the "reftable" backend could continue to
    -opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
    +opt-in to the "reftable" format manually by setting the "init.defaultRefStorageFormat"
(2)
      matches the default branch name used in new repositories by many of the
      big Git forges.
   +* Git will accept hex object IDs only in lowercase. The fact that Git has
   +        historically allowed uppercase characters in hex object IDs has been the
   +        source of a variety of bugs and security problems in software using Git. We
   +        don't expect most users to notice any change.
(But (2) uses tabs for the three last lines)

So they would need to be moved from `BreakingChanges.adoc` to `gitbreaking-changes.adoc`.

***

Users are the ones who are impacted by breaking changes. Certainly much more than Git developers who are already plugged in to the development channels that discuss the trajectory of the project. Advertizing the planned breaking changes to all users will help the whole Git community prepare.

§ Changes in v2

Drop RFC status since Patrick seems to think that this is an okay change.[1]

Patch “mention gitbreaking-changes(7)” is dropped. This is because Julia’s parallel topic je/doc-promote-git-help removes guide-mentions on the git(1) doc.[2]

Series v1 patch “transform breaking changes doc to a manpage” has been split into two in order to make tracing the moved lines easier.[1] I did not go all the way and made another commit for a pure filemove. I think `--color-moved` should be enough here. But I can of course make another commit.

Note that this split isn’t that obvious from the range diff. It might have been etter if it compared the previous round with the first commit, but futzing with `--creation-factor` didn’t help me here.

Patch “replace msg-ids with URLs”: fixed unintended space changes. Another linking scheme was discussed but it lead to no changes.[4] But! I found out that one URL does not render properly with asciidoc(1). So I made a compromise for now. Maybe that sinks the URL aspirations here.

Patch “move new-items discussion to the end” is new and based on what I hope is my correct interpretation of Patrick’s suggestion.[3]

† 1: <ar0OicAaDipYx-xU@pks.im> † 2: <ea29fe74-7f76-440c-9597-fdbc173be90f@app.fastmail.com> † 3: <ar0OltAkeTiCx81c@pks.im> † 4: <xmqqeceaa5h9.fsf@gitster.g>

§ Link to v1
https://lore.kernel.org/git/CV_gitbrchanges7_please.d1c@m5gid.xyz/

[1/5] doc: BreakingChanges: transform to a manpage [2/5] doc: gitbreaking-changes: create from BreakingChanges [3/5] doc: gitbreaking-changes: replace msg-ids with URLs [4/5] doc: gitbreaking-changes: add note about living document [5/5] doc: gitbreaking-changes: move new-items discussion to the end

 Documentation/BreakingChanges.adoc     | 360 +----------------------
 Documentation/Makefile                 |   1 +
 Documentation/gitbreaking-changes.adoc | 389 +++++++++++++++++++++++++
 Documentation/meson.build              |   1 +
 command-list.txt                       |   1 +
 5 files changed, 393 insertions(+), 359 deletions(-)
 create mode 100644 Documentation/gitbreaking-changes.adoc
Interdiff against v1:
Show changes to 2 files +21 −24

Documentation/git.adoc, Documentation/gitbreaking-changes.adoc

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index 6a4ef2dff5c..6f0075f9188 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc
@@ -26,9 +26,7 @@ See linkgit:gittutorial[7] to get started, then see
 linkgit:giteveryday[7] for a useful minimum set of
 commands.  The link:user-manual.html[Git User's Manual] has a more
 in-depth introduction.  See linkgit:gitdatamodel[7] if you want to
-learn about the data model and important terminology.  See
-linkgit:gitbreaking-changes[7] for a discussion of breaking changes
-planned for Git 3.0.
+learn about the data model and important terminology.
 
 After you mastered the basic concepts, you can come back to this
 page to learn what commands Git offers.  You can learn more about
@@ -1206,7 +1204,6 @@ linkgit:gittutorial[7], linkgit:gittutorial-2[7],
 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
 linkgit:gitglossary[7], linkgit:gitdatamodel[7],
 linkgit:gitcore-tutorial[7], linkgit:gitcli[7],
-linkgit:gitbreaking-changes[7],
 link:user-manual.html[The Git User's Manual],
 linkgit:gitworkflows[7]
 
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index 410476c7993..e984c2c8ca5 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -54,20 +54,6 @@ breaking releases. Furthermore, this document also tracks what will _not_ be
 deprecated. This is done such that the outcome of discussions document both
 when the discussion favors deprecation, but also when it rejects a deprecation.
 
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by links to relevant mailing list threads
-where the deprecation was discussed. These links use this format:
-
-  https://lore.kernel.org/git/$message_id/
-
-I.e. they link to the `Message-ID` of the email on the mailing
-list. These references are there to make it easier for you to find how
-the project reached consensus on the described item back then.
-
 This is a living document as the environment surrounding the project changes
 over time. If circumstances change, an earlier decision to deprecate or change
 something may need to be revisited from time to time. So do not take items on
@@ -140,7 +126,7 @@ There is no plan to deprecate the "sha1" object format at this point in time.
 +
 Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
 https://lore.kernel.org/git/20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain,
-https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%2BDiUQ@mail.gmail.com/.
+https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com.
 
 * The default storage format for references in newly created repositories will
   be changed from "files" to "reftable". The "reftable" format provides
@@ -341,7 +327,7 @@ The command will be removed.
 * Support for `core.commentString=auto` has been deprecated and will
   be removed in Git 3.0.
 +
-cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
+cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
 
 * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
   removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
@@ -379,8 +365,24 @@ This decision may get revisited in case we ever figure out that there are
 almost no users of any of the commands anymore.
 +
 Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
-https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
-https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
+    https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
+    https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
+
+== Adding new items
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by links to relevant mailing list threads
+where the deprecation was discussed. These links use this format:
+
+  https://lore.kernel.org/git/$message_id/
+
+I.e. they link to the `Message-ID` of the email on the mailing
+list. These references are there to make it easier for you to find how
+the project reached consensus on the described item back then.
 
 GIT
 ---
Range-diff against v1:
-:  ----------- > 1:  2b5d0b23a5a doc: BreakingChanges: transform to a manpage
1:  4f98172c30d ! 2:  476d8849135 doc: transform breaking changes doc to a manpage
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: transform breaking changes doc to a manpage
    +    doc: gitbreaking-changes: create from BreakingChanges
     
    -    The breaking changes document is not a regular Git documentation page.
    -    That means that you cannot navigate to the doc with git(1), i.e. with:
    +    We can rename to gitbreaking-changes(7) now that we have changed to
    +    the required format in the preceding commit.
     
    -        git help BreakingChanges
    -
    -    You instead have to download the Git project source. Or go to
    -    git-scm.com.[1] Then you get this disclaimer:[2]
    -
    -        This information is specific to the Git project
    -
    -        Please note that this information is only relevant to you if you
    -        plan on contributing to the Git project itself. It is in no shape or
    -        form required reading for regular Git users.
    -
    -    But this document is relevant to *all* Git users. Everyone should have
    -    as easy access to it as the other doc and guide pages.
    -
    -    To that end, let’s move the text to a manpage. But keep the old page,
    -    just linking to the new one. (We wouldn’t want to break any readers.)
    -
    -    Just do the minimal changes for the new format. Also demote the first
    -    section to the second level, i.e. make “Introduction” the same level
    -    as “Procedure’.
    -
    -    † 1: https://git-scm.com/docs/BreakingChanges.html
    -    † 2: Which I first mentioned in 098230f7 (you-still-use-that??: help the
    -         user help themselves, 2025-09-17), footnote #1.
    +    But we also need to keep `BreakingChanges.adoc` in order to point to
    +    the new document. That way old links and whatnot are still serviceable.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/BreakingChanges.adoc ##
     @@
    --= Upcoming breaking changes
    +-gitbreaking-changes(7)
    +-======================
    +-
    +-NAME
    +-----
    +-gitbreaking-changes - Breaking changes for upcoming Git 3.0
    +-
    +-SYNOPSIS
    +---------
    +-*
    +-
    +-DESCRIPTION
    +------------
    +-*
    +-
    +-== Introduction: Upcoming breaking changes
     -
     -The Git project aims to ensure backwards compatibility to the best extent
     -possible. Minor releases will not break backwards compatibility unless there is
    @@ Documentation/BreakingChanges.adoc
     -Cf. <xmqqttjazwwa.fsf@gitster.g>,
     -<xmqqleeubork.fsf@gitster.g>,
     -<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
    +-
    +-GIT
    +----
    +-Part of the linkgit:git[1] suite
     +This document as been moved to linkgit:gitbreaking-changes[7].
     
      ## Documentation/Makefile ##
    @@ Documentation/meson.build: manpages = {
        'gitcli.adoc' : 7,
        'gitcore-tutorial.adoc' : 7,
        'gitcredentials.adoc' : 7,
    +
    + ## command-list.txt ##
    +@@ command-list.txt: git-whatchanged                         ancillaryinterrogators          complete
    + git-worktree                            mainporcelain
    + git-write-tree                          plumbingmanipulators
    + gitattributes                           userinterfaces
    ++gitbreaking-changes                     guide
    + gitcli                                  userinterfaces
    + gitcore-tutorial                        guide
    + gitcredentials                          guide
2:  a6626aafac8 ! 3:  c8983aced71 doc: gitbreaking-changes: replace msg-ids with URLs
    @@ Commit message
     
         † 1: 57ec9254 (docs: introduce document to announce breaking changes, 2024-06-14)
     
    -    Note that we have to URL encode two msg-ids:
    +    Note that we have to URL encode this msg-id:
     
              CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com
    +
    +    Lore can handle it just fine, but asciidoctor(1) cannot.
    +
    +    Worse yet, this msg-id can be handled by asciidoctor(1) but not by
    +    asciidoc:
    +
              CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com
     
    -    Lore can handle them just fine, but asciidoctor(1) cannot.
    +    URL encoding does not help. So compromise by linking to the only
    +    second-level reply:
    +
    +        CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com
    +
    +    Which properly quotes the first message. So no loss of fidelity in
    +    my opinion.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    @@ Documentation/gitbreaking-changes.adoc: applications and forges.
     -<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
     +Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
     +https://lore.kernel.org/git/20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain,
    -+https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%2BDiUQ@mail.gmail.com/.
    ++https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com.
      
      * The default storage format for references in newly created repositories will
        be changed from "files" to "reftable". The "reftable" format provides
    @@ Documentation/gitbreaking-changes.adoc: The command will be removed.
        be removed in Git 3.0.
      +
     -cf. <xmqqa59i45wc.fsf@gitster.g>
    -+cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
    ++cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
      
      * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
        removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
    @@ Documentation/gitbreaking-changes.adoc: those features with newer alternatives.
     -<xmqqleeubork.fsf@gitster.g>,
     -<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
     +Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
    -+https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
    -+https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
    ++    https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
    ++    https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
      
      GIT
      ---
3:  75397436eb9 = 4:  46f08bb65d9 doc: gitbreaking-changes: add note about living document
4:  9d14f13664f < -:  ----------- doc: git: mention gitbreaking-changes(7)
-:  ----------- > 5:  85fe7ebe89e doc: gitbreaking-changes: move new-items discussion to the end

base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Oct 8, 2026, 19:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 1/5] doc: BreakingChanges: transform to a manpage

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The breaking changes document is not a regular Git documentation page. That means that you cannot navigate to the doc with git(1), i.e. with:

    git help BreakingChanges

You instead have to download the Git project source. Or go to git-scm.com.[1] Then you get this disclaimer:[2]

    This information is specific to the Git project
    Please note that this information is only relevant to you if you
    plan on contributing to the Git project itself. It is in no shape or
    form required reading for regular Git users.

But this document is relevant to *all* Git users. Everyone should have as easy access to it as the other doc and guide pages.

To that end, let’s move the text to a new manpage gitbreaking-changes(7) in two steps:

1. Transform this document without renaming it (this step)
2. Rename it to gitbreaking-changes(7). But resurrect BreakingChanges in
   order to add a line linking to the new manpage (We wouldn’t want to
   break any readers)

Just do the minimal changes for the new format. Also demote the first section to the second level, i.e. make “Introduction” the same level as “Procedure’.

Step two is for the next commit.
† 1: https://git-scm.com/docs/BreakingChanges.html
† 2: Which I first mentioned in 098230f7 (you-still-use-that??: help the
     user help themselves, 2025-09-17), footnote #1.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/BreakingChanges.adoc | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)
Show changes to Documentation/BreakingChanges.adoc +20 −1
diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index 73bb939359c..c6b974b6d8c 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -1,4 +1,19 @@
-= Upcoming breaking changes
+gitbreaking-changes(7)
+======================
+
+NAME
+----
+gitbreaking-changes - Breaking changes for upcoming Git 3.0
+
+SYNOPSIS
+--------
+*
+
+DESCRIPTION
+-----------
+*
+
+== Introduction: Upcoming breaking changes
 
 The Git project aims to ensure backwards compatibility to the best extent
 possible. Minor releases will not break backwards compatibility unless there is
@@ -357,3 +372,7 @@ almost no users of any of the commands anymore.
 Cf. <xmqqttjazwwa.fsf@gitster.g>,
 <xmqqleeubork.fsf@gitster.g>,
 <112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+
+GIT
+---
+Part of the linkgit:git[1] suite
-- 
2.55.0.793.gc667de3f2c5
D. Ben Knoble· Oct 8, 2026, 19:46 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH v2 1/5] doc: BreakingChanges: transform to a manpage

On Thu, Oct 8, 2026 at 3:38 PM <kristofferhaugsbakk@fastmail.com> wrote:
Show 19 quoted lines
>
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> The breaking changes document is not a regular Git documentation page.
> That means that you cannot navigate to the doc with git(1), i.e. with:
>
>     git help BreakingChanges
>
> You instead have to download the Git project source. Or go to
> git-scm.com.[1] Then you get this disclaimer:[2]
>
>     This information is specific to the Git project
>
>     Please note that this information is only relevant to you if you
>     plan on contributing to the Git project itself. It is in no shape or
>     form required reading for regular Git users.
>
> But this document is relevant to *all* Git users. Everyone should have
> as easy access to it as the other doc and guide pages.

Sorry for not mentioning this earlier, but you can (depending on your distribution's package?) find the document under "git --html-path" for example

I agree that's drastically less discoverable, though, and I welcome making it a manual in the spirit of datamodel and others.

I don't think the message needs updated, so not worth a re-roll, just something to point out for folks that like interesting corners of Git ;) (cf. https://github.com/benknoble/Dotfiles/blob/master/links/bin/git-doc and accompanying completion https://github.com/benknoble/Dotfiles/blob/master/links/zshfns/_git_doc).

-- 
D. Ben Knoble
Kristoffer Haugsbakk· Oct 9, 2026, 08:24 UTC · re: D. Ben Knoble · lore

Re: [PATCH v2 1/5] doc: BreakingChanges: transform to a manpage

On Thu, Oct 8, 2026, at 21:46, D. Ben Knoble wrote:
Show 24 quoted lines
> On Thu, Oct 8, 2026 at 3:38 PM <kristofferhaugsbakk@fastmail.com> wrote:
>>
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> The breaking changes document is not a regular Git documentation page.
>> That means that you cannot navigate to the doc with git(1), i.e. with:
>>
>>     git help BreakingChanges
>>
>> You instead have to download the Git project source. Or go to
>> git-scm.com.[1] Then you get this disclaimer:[2]
>>
>>     This information is specific to the Git project
>>
>>     Please note that this information is only relevant to you if you
>>     plan on contributing to the Git project itself. It is in no shape or
>>     form required reading for regular Git users.
>>
>> But this document is relevant to *all* Git users. Everyone should have
>> as easy access to it as the other doc and guide pages.
>
> Sorry for not mentioning this earlier, but you can (depending on your
> distribution's package?) find the document under "git --html-path" for
> example
That’s handy. Thanks!

I wonder why `git help help` has nothing to say about “html-path” or “html path”.

>[snip]
kristofferhaugsbakk@fastmail.com· Oct 8, 2026, 19:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 2/5] doc: gitbreaking-changes: create from BreakingChanges

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We can rename to gitbreaking-changes(7) now that we have changed to the required format in the preceding commit.

But we also need to keep `BreakingChanges.adoc` in order to point to the new document. That way old links and whatnot are still serviceable.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/BreakingChanges.adoc     | 379 +------------------------
 Documentation/Makefile                 |   1 +
 Documentation/gitbreaking-changes.adoc | 378 ++++++++++++++++++++++++
 Documentation/meson.build              |   1 +
 command-list.txt                       |   1 +
 5 files changed, 382 insertions(+), 378 deletions(-)
 create mode 100644 Documentation/gitbreaking-changes.adoc
Show changes to 5 files +382 −372

Documentation/BreakingChanges.adoc, Documentation/Makefile, Documentation/gitbreaking-changes.adoc, Documentation/meson.build, command-list.txt

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index c6b974b6d8c..d35850a08e4 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -1,378 +1 @@
-gitbreaking-changes(7)
-======================
-
-NAME
-----
-gitbreaking-changes - Breaking changes for upcoming Git 3.0
-
-SYNOPSIS
---------
-*
-
-DESCRIPTION
------------
-*
-
-== Introduction: Upcoming breaking changes
-
-The Git project aims to ensure backwards compatibility to the best extent
-possible. Minor releases will not break backwards compatibility unless there is
-a very strong reason to do so, like for example a security vulnerability.
-
-Regardless of that, due to the age of the Git project, it is only natural to
-accumulate a backlog of backwards-incompatible changes that will eventually be
-required to keep the project aligned with a changing world. These changes fall
-into several categories:
-
-* Changes to long established defaults.
-* Concepts that have been replaced with a superior design.
-* Concepts, commands, configuration or options that have been lacking in major
-  ways and that cannot be fixed and which will thus be removed without any
-  replacement.
-
-Explicitly not included in this list are fixes to minor bugs that may cause a
-change in user-visible behavior.
-
-The Git project irregularly releases breaking versions that deliberately break
-backwards compatibility with older versions. This is done to ensure that Git
-remains relevant, safe and maintainable going forward. The release cadence of
-breaking versions is typically measured in multiple years. We had the following
-major breaking releases in the past:
-
-* Git 1.6.0, released in August 2008.
-* Git 2.0, released in May 2014.
-
-We use <major>.<minor> release numbers these days, starting from Git 2.0. For
-future releases, our plan is to increment <major> in the release number when we
-make the next breaking release. Before Git 2.0, the release numbers were
-1.<major>.<minor> with the intention to increment <major> for "usual" breaking
-releases, reserving the jump to Git 2.0 for really large backward-compatibility
-breaking changes.
-
-The intent of this document is to track upcoming deprecations for future
-breaking releases. Furthermore, this document also tracks what will _not_ be
-deprecated. This is done such that the outcome of discussions document both
-when the discussion favors deprecation, but also when it rejects a deprecation.
-
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by references to relevant mailing list threads
-where the deprecation was discussed. These references use message-IDs, which
-can visited via
-
-  https://lore.kernel.org/git/$message_id/
-
-to see the message and its surrounding discussion. Such a reference is there to
-make it easier for you to find how the project reached consensus on the
-described item back then.
-
-This is a living document as the environment surrounding the project changes
-over time. If circumstances change, an earlier decision to deprecate or change
-something may need to be revisited from time to time. So do not take items on
-this list to mean "it is settled, do not waste our time bringing it up again".
-
-== Procedure
-
-Discussing the desire to make breaking changes, declaring that breaking
-changes are made at a certain version boundary, and recording these
-decisions in this document, are necessary but not sufficient.
-Because such changes are expected to be numerous, and the design and
-implementation of them are expected to span over time, they have to
-be deployable trivially at such a version boundary, prepared over long
-time.
-
-The breaking changes MUST be guarded with the a compile-time switch,
-WITH_BREAKING_CHANGES, to help this process.  When built with it,
-the resulting Git binary together with its documentation would
-behave as if these breaking changes slated for the next big version
-boundary are already in effect.  We also have a CI job to exercise
-the work-in-progress version of Git with these breaking changes.
-
-
-== Git 3.0
-
-The following subsections document upcoming breaking changes for Git 3.0. There
-is no planned release date for this breaking version yet.
-
-Proposed changes and removals only include items which are "ready" to be done.
-In other words, this is not supposed to be a wishlist of features that should
-be changed to or replaced in case the alternative was implemented already.
-
-=== Changes
-
-* The default hash function for new repositories will be changed from "sha1"
-  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
-  recommended against in FIPS 140-2 and similar certifications. Furthermore,
-  there are practical attacks on SHA-1 that weaken its cryptographic properties:
-+
-  ** The SHAppening (2015). The first demonstration of a practical attack
-     against SHA-1 with 2^57 operations.
-  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
-  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
-     attacks with 2^68 operations.
-  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
-     operations.
-+
-While we have protections in place against known attacks, it is expected
-that more attacks against SHA-1 will be found by future research. Paired
-with the ever-growing capability of hardware, it is only a matter of time
-before SHA-1 will be considered broken completely. We want to be prepared
-and will thus change the default hash algorithm to "sha256" for newly
-initialized repositories.
-+
-An important requirement for this change is that the ecosystem is ready to
-support the "sha256" object format. This includes popular Git libraries,
-applications and forges.
-+
-There is no plan to deprecate the "sha1" object format at this point in time.
-+
-Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
-<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
-
-* The default storage format for references in newly created repositories will
-  be changed from "files" to "reftable". The "reftable" format provides
-  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 common
-     on Windows and macOS platforms. As the "reftable" backend does not use
-     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,
-     this is not an issue with the "reftable" backend.
-  ** Deleting references with the "files" backend requires Git to rewrite the
-     complete "packed-refs" file. In large repositories with many references
-     this file can easily be dozens of megabytes in size, in extreme cases it
-     may be gigabytes. The "reftable" backend uses tombstone markers for
-     deleted references and thus does not have to rewrite all of its data.
-  ** Repository housekeeping with the "files" backend typically performs
-     all-into-one repacks of references. This can be quite expensive, and
-     consequently housekeeping is a tradeoff between the number of loose
-     references that accumulate and slow down operations that read references,
-     and compressing those loose references into the "packed-refs" file. The
-     "reftable" backend uses geometric compaction after every write, which
-     amortizes costs and ensures that the backend is always in a
-     well-maintained state.
-  ** Operations that write multiple references at once are not atomic with the
-     "files" backend. Consequently, Git may see in-between states when it reads
-     references while a reference transaction is in the process of being
-     committed to disk.
-  ** Writing many references at once is slow with the "files" backend because
-     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"
-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.
-
-* In new repositories, the default branch name will be `main`. We have been
-  warning that the default name will change since 675704c74dd (init:
-  provide useful advice about init.defaultBranch, 2020-12-11).  The new name
-  matches the default branch name used in new repositories by many of the
-  big Git forges.
-
-* Git will require Rust as a mandatory part of the build process. While Git
-  already started to adopt Rust in Git 2.49, all parts written in Rust are
-  optional for the time being. This includes:
-+
-  ** The Rust wrapper around libgit.a that is part of "contrib/" and which has
-     been introduced in Git 2.49.
-  ** Subsystems that have an alternative implementation in Rust to test
-     interoperability between our C and Rust codebase.
-  ** Newly written features that are not mission critical for a fully functional
-     Git client.
-+
-These changes are meant as test balloons to allow distributors of Git to prepare
-for Rust becoming a mandatory part of the build process. There will be multiple
-milestones for the introduction of Rust:
-+
---
-1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and
-   disabled in our Makefile so that the project can sort out the initial
-   infrastructure.
-2. In Git 2.55, both build systems will default-enable support for Rust.
-   Consequently, builds will break by default if Rust is not available on the
-   build host. The use of Rust can still be explicitly disabled via build
-   flags.
-3. In Git 3.0, the build options will be removed and support for Rust is
-   mandatory.
---
-+
-You can explicitly ask both Meson and our Makefile-based system to enable Rust
-by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`,
-respectively.
-+
-The Git project will declare the last version before Git 3.0 to be a long-term
-support release. This long-term release will receive important bug fixes for at
-least four release cycles and security fixes for six release cycles. The Git
-project will hand over maintainership of the long-term release to distributors
-in case they need to extend the life of that long-term release even further.
-Details of how this long-term release will be handed over to the community will
-be discussed once the Git project decides to stop officially supporting it.
-+
-We will evaluate the impact on downstream distributions before making Rust
-mandatory in Git 3.0. If we see that the impact on downstream distributions
-would be significant, we may decide to defer this change to a subsequent minor
-release. This evaluation will also take into account our own experience with
-how painful it is to keep Rust an optional component.
-
-* The default value of `safe.bareRepository` will change from `all` to
-  `explicit`. It is all too easy for an attacker to trick a user into cloning a
-  repository that contains an embedded bare repository with malicious hooks
-  configured. If the user enters that subdirectory and runs any Git command, Git
-  discovers the bare repository and the hooks fire. The user does not even need
-  to run a Git command explicitly: many shell prompts run `git status` in the
-  background to display branch and dirty state information, and `git status` in
-  turn may invoke the fsmonitor hook if so configured, making the user
-  vulnerable the moment they `cd` into the directory. The `safe.bareRepository`
-  configuration variable was introduced in 8959555cee (setup_git_directory():
-  add an owner check for the top-level directory, 2022-03-02) with a default of
-  `all` to preserve backwards compatibility.
-+
-Changing the default to `explicit` means that Git will refuse to work with bare
-repositories that are discovered implicitly by walking up the directory tree.
-Bare repositories specified explicitly via the `--git-dir` command-line option
-or the `GIT_DIR` environment variable continue to work regardless of this
-setting. Repositories that look like a `.git` directory, a worktree, or a
-submodule directory are also unaffected.
-+
-Users who rely on implicit discovery of bare repositories can restore the
-previous behavior by setting `safe.bareRepository=all` in their global or
-system configuration.
-
-=== Removals
-
-* Support for grafting commits has long been superseded by git-replace(1).
-  Grafts are inferior to replacement refs:
-+
-  ** Grafts are a local-only mechanism and cannot be shared across
-     repositories.
-  ** Grafts can lead to hard-to-diagnose problems when transferring objects
-     between repositories.
-+
-The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
-info/grafts as outdated, 2014-03-05) and will be removed.
-+
-Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
-
-* The git-pack-redundant(1) command can be used to remove redundant pack files.
-  The subcommand is unusably slow and the reason why nobody reports it as a
-  performance bug is suspected to be the absence of users. We have nominated
-  the command for removal and have started to emit a user-visible warning in
-  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
-  2020-08-25) whenever the command is executed.
-+
-So far there was a single complaint about somebody still using the command, but
-that complaint did not cause us to reverse course. On the contrary, we have
-doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
-escalate deprecation warning to an error, 2023-03-23), the command dies unless
-the user passes the `--i-still-use-this` option.
-+
-There have not been any subsequent complaints, so this command will finally be
-removed.
-+
-Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
-    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
-    <20230323204047.GA9290@coredump.intra.peff.net>,
-
-* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
-  and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
-  the repository configuration.
-+
-The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
-short-hand notation for remote repositories., 2005-07-16) and was superseded by
-6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
-2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
-commit already mentions an upcoming deprecation of the ".git/branches/"
-directory, and starting with a1d4aa7424 (Add repository-layout document.,
-2005-09-01) we have also marked this layout as deprecated. Eventually we also
-started to migrate away from ".git/remotes/" in favor of config-based remotes,
-and we have marked the directory as legacy in 3d3d282146 (Documentation:
-Grammar correction, wording fixes and cleanup, 2011-08-23)
-+
-As our documentation mentions, these directories are unlikely to be used in
-modern repositories and most users aren't even aware of these mechanisms. They
-have been deprecated for almost 20 years and 14 years respectively, and we are
-not aware of any active users that have complained about this deprecation.
-Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
-may cause confusion as "branches" are almost exclusively used in the context of
-references.
-+
-These features will be removed.
-
-* Support for "--stdin" option in the "name-rev" command was
-  deprecated (and hidden from the documentation) in the Git 2.40
-  timeframe, in preference to its synonym "--annotate-stdin".  Git 3.0
-  removes the support for "--stdin" altogether.
-
-* The git-whatchanged(1) command has outlived its usefulness more than
-  10 years ago, and takes more keystrokes to type than its rough
-  equivalent `git log --raw`.  We have nominated the command for
-  removal, have changed the command to refuse to work unless the
-  `--i-still-use-this` option is given, and asked the users to report
-  when they do so.
-+
-The command will be removed.
-
-* Support for `core.commentString=auto` has been deprecated and will
-  be removed in Git 3.0.
-+
-cf. <xmqqa59i45wc.fsf@gitster.g>
-
-* Support for `core.preferSymlinkRefs=true` has been deprecated and will be
-  removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
-  out in favor of using plain files using the textual representation of
-  symbolic refs.
-+
-Symbolic references were initially always stored as a symbolic link. This was
-changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a
-textfile., 2005-09-25), where a new textual symref format was introduced to
-store those symbolic refs in a plain file. In 9f0bb90d16
-(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git
-project switched the default to use the textual symrefs in favor of symbolic
-links.
-+
-The migration away from symbolic links has happened almost 20 years ago by now,
-and there is no known reason why one should prefer them nowadays. Furthermore,
-symbolic links are not supported on some platforms.
-+
-Note that only the writing side for such symbolic links is deprecated. Reading
-such symbolic links is still supported for now.
-
-== Superseded features that will not be deprecated
-
-Some features have gained newer replacements that aim to improve the design in
-certain ways. The fact that there is a replacement does not automatically mean
-that the old way of doing things will eventually be removed. This section tracks
-those features with newer alternatives.
-
-* The features git-checkout(1) offers are covered by the pair of commands
-  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
-  widespread, and it is not expected that this will change anytime soon, all
-  three commands will stay.
-+
-This decision may get revisited in case we ever figure out that there are
-almost no users of any of the commands anymore.
-+
-Cf. <xmqqttjazwwa.fsf@gitster.g>,
-<xmqqleeubork.fsf@gitster.g>,
-<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
-
-GIT
----
-Part of the linkgit:git[1] suite
+This document as been moved to linkgit:gitbreaking-changes[7].
diff --git a/Documentation/Makefile b/Documentation/Makefile
index f8dea4b3953..8b0390ac0fc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -49,6 +49,7 @@ MAN5_TXT += gitprotocol-v2.adoc
 MAN5_TXT += gitrepository-layout.adoc
 MAN5_TXT += gitweb.conf.adoc
 
+MAN7_TXT += gitbreaking-changes.adoc
 MAN7_TXT += gitcli.adoc
 MAN7_TXT += gitcore-tutorial.adoc
 MAN7_TXT += gitcredentials.adoc
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
new file mode 100644
index 00000000000..c6b974b6d8c
--- /dev/null
+++ b/Documentation/gitbreaking-changes.adoc
@@ -0,0 +1,378 @@
+gitbreaking-changes(7)
+======================
+
+NAME
+----
+gitbreaking-changes - Breaking changes for upcoming Git 3.0
+
+SYNOPSIS
+--------
+*
+
+DESCRIPTION
+-----------
+*
+
+== Introduction: Upcoming breaking changes
+
+The Git project aims to ensure backwards compatibility to the best extent
+possible. Minor releases will not break backwards compatibility unless there is
+a very strong reason to do so, like for example a security vulnerability.
+
+Regardless of that, due to the age of the Git project, it is only natural to
+accumulate a backlog of backwards-incompatible changes that will eventually be
+required to keep the project aligned with a changing world. These changes fall
+into several categories:
+
+* Changes to long established defaults.
+* Concepts that have been replaced with a superior design.
+* Concepts, commands, configuration or options that have been lacking in major
+  ways and that cannot be fixed and which will thus be removed without any
+  replacement.
+
+Explicitly not included in this list are fixes to minor bugs that may cause a
+change in user-visible behavior.
+
+The Git project irregularly releases breaking versions that deliberately break
+backwards compatibility with older versions. This is done to ensure that Git
+remains relevant, safe and maintainable going forward. The release cadence of
+breaking versions is typically measured in multiple years. We had the following
+major breaking releases in the past:
+
+* Git 1.6.0, released in August 2008.
+* Git 2.0, released in May 2014.
+
+We use <major>.<minor> release numbers these days, starting from Git 2.0. For
+future releases, our plan is to increment <major> in the release number when we
+make the next breaking release. Before Git 2.0, the release numbers were
+1.<major>.<minor> with the intention to increment <major> for "usual" breaking
+releases, reserving the jump to Git 2.0 for really large backward-compatibility
+breaking changes.
+
+The intent of this document is to track upcoming deprecations for future
+breaking releases. Furthermore, this document also tracks what will _not_ be
+deprecated. This is done such that the outcome of discussions document both
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
+where the deprecation was discussed. These references use message-IDs, which
+can visited via
+
+  https://lore.kernel.org/git/$message_id/
+
+to see the message and its surrounding discussion. Such a reference is there to
+make it easier for you to find how the project reached consensus on the
+described item back then.
+
+This is a living document as the environment surrounding the project changes
+over time. If circumstances change, an earlier decision to deprecate or change
+something may need to be revisited from time to time. So do not take items on
+this list to mean "it is settled, do not waste our time bringing it up again".
+
+== Procedure
+
+Discussing the desire to make breaking changes, declaring that breaking
+changes are made at a certain version boundary, and recording these
+decisions in this document, are necessary but not sufficient.
+Because such changes are expected to be numerous, and the design and
+implementation of them are expected to span over time, they have to
+be deployable trivially at such a version boundary, prepared over long
+time.
+
+The breaking changes MUST be guarded with the a compile-time switch,
+WITH_BREAKING_CHANGES, to help this process.  When built with it,
+the resulting Git binary together with its documentation would
+behave as if these breaking changes slated for the next big version
+boundary are already in effect.  We also have a CI job to exercise
+the work-in-progress version of Git with these breaking changes.
+
+
+== Git 3.0
+
+The following subsections document upcoming breaking changes for Git 3.0. There
+is no planned release date for this breaking version yet.
+
+Proposed changes and removals only include items which are "ready" to be done.
+In other words, this is not supposed to be a wishlist of features that should
+be changed to or replaced in case the alternative was implemented already.
+
+=== Changes
+
+* The default hash function for new repositories will be changed from "sha1"
+  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
+  recommended against in FIPS 140-2 and similar certifications. Furthermore,
+  there are practical attacks on SHA-1 that weaken its cryptographic properties:
++
+  ** The SHAppening (2015). The first demonstration of a practical attack
+     against SHA-1 with 2^57 operations.
+  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
+  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
+     attacks with 2^68 operations.
+  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
+     operations.
++
+While we have protections in place against known attacks, it is expected
+that more attacks against SHA-1 will be found by future research. Paired
+with the ever-growing capability of hardware, it is only a matter of time
+before SHA-1 will be considered broken completely. We want to be prepared
+and will thus change the default hash algorithm to "sha256" for newly
+initialized repositories.
++
+An important requirement for this change is that the ecosystem is ready to
+support the "sha256" object format. This includes popular Git libraries,
+applications and forges.
++
+There is no plan to deprecate the "sha1" object format at this point in time.
++
+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
+* The default storage format for references in newly created repositories will
+  be changed from "files" to "reftable". The "reftable" format provides
+  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 common
+     on Windows and macOS platforms. As the "reftable" backend does not use
+     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,
+     this is not an issue with the "reftable" backend.
+  ** Deleting references with the "files" backend requires Git to rewrite the
+     complete "packed-refs" file. In large repositories with many references
+     this file can easily be dozens of megabytes in size, in extreme cases it
+     may be gigabytes. The "reftable" backend uses tombstone markers for
+     deleted references and thus does not have to rewrite all of its data.
+  ** Repository housekeeping with the "files" backend typically performs
+     all-into-one repacks of references. This can be quite expensive, and
+     consequently housekeeping is a tradeoff between the number of loose
+     references that accumulate and slow down operations that read references,
+     and compressing those loose references into the "packed-refs" file. The
+     "reftable" backend uses geometric compaction after every write, which
+     amortizes costs and ensures that the backend is always in a
+     well-maintained state.
+  ** Operations that write multiple references at once are not atomic with the
+     "files" backend. Consequently, Git may see in-between states when it reads
+     references while a reference transaction is in the process of being
+     committed to disk.
+  ** Writing many references at once is slow with the "files" backend because
+     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"
+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.
+
+* In new repositories, the default branch name will be `main`. We have been
+  warning that the default name will change since 675704c74dd (init:
+  provide useful advice about init.defaultBranch, 2020-12-11).  The new name
+  matches the default branch name used in new repositories by many of the
+  big Git forges.
+
+* Git will require Rust as a mandatory part of the build process. While Git
+  already started to adopt Rust in Git 2.49, all parts written in Rust are
+  optional for the time being. This includes:
++
+  ** The Rust wrapper around libgit.a that is part of "contrib/" and which has
+     been introduced in Git 2.49.
+  ** Subsystems that have an alternative implementation in Rust to test
+     interoperability between our C and Rust codebase.
+  ** Newly written features that are not mission critical for a fully functional
+     Git client.
++
+These changes are meant as test balloons to allow distributors of Git to prepare
+for Rust becoming a mandatory part of the build process. There will be multiple
+milestones for the introduction of Rust:
++
+--
+1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and
+   disabled in our Makefile so that the project can sort out the initial
+   infrastructure.
+2. In Git 2.55, both build systems will default-enable support for Rust.
+   Consequently, builds will break by default if Rust is not available on the
+   build host. The use of Rust can still be explicitly disabled via build
+   flags.
+3. In Git 3.0, the build options will be removed and support for Rust is
+   mandatory.
+--
++
+You can explicitly ask both Meson and our Makefile-based system to enable Rust
+by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`,
+respectively.
++
+The Git project will declare the last version before Git 3.0 to be a long-term
+support release. This long-term release will receive important bug fixes for at
+least four release cycles and security fixes for six release cycles. The Git
+project will hand over maintainership of the long-term release to distributors
+in case they need to extend the life of that long-term release even further.
+Details of how this long-term release will be handed over to the community will
+be discussed once the Git project decides to stop officially supporting it.
++
+We will evaluate the impact on downstream distributions before making Rust
+mandatory in Git 3.0. If we see that the impact on downstream distributions
+would be significant, we may decide to defer this change to a subsequent minor
+release. This evaluation will also take into account our own experience with
+how painful it is to keep Rust an optional component.
+
+* The default value of `safe.bareRepository` will change from `all` to
+  `explicit`. It is all too easy for an attacker to trick a user into cloning a
+  repository that contains an embedded bare repository with malicious hooks
+  configured. If the user enters that subdirectory and runs any Git command, Git
+  discovers the bare repository and the hooks fire. The user does not even need
+  to run a Git command explicitly: many shell prompts run `git status` in the
+  background to display branch and dirty state information, and `git status` in
+  turn may invoke the fsmonitor hook if so configured, making the user
+  vulnerable the moment they `cd` into the directory. The `safe.bareRepository`
+  configuration variable was introduced in 8959555cee (setup_git_directory():
+  add an owner check for the top-level directory, 2022-03-02) with a default of
+  `all` to preserve backwards compatibility.
++
+Changing the default to `explicit` means that Git will refuse to work with bare
+repositories that are discovered implicitly by walking up the directory tree.
+Bare repositories specified explicitly via the `--git-dir` command-line option
+or the `GIT_DIR` environment variable continue to work regardless of this
+setting. Repositories that look like a `.git` directory, a worktree, or a
+submodule directory are also unaffected.
++
+Users who rely on implicit discovery of bare repositories can restore the
+previous behavior by setting `safe.bareRepository=all` in their global or
+system configuration.
+
+=== Removals
+
+* Support for grafting commits has long been superseded by git-replace(1).
+  Grafts are inferior to replacement refs:
++
+  ** Grafts are a local-only mechanism and cannot be shared across
+     repositories.
+  ** Grafts can lead to hard-to-diagnose problems when transferring objects
+     between repositories.
++
+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
+info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
+
+* The git-pack-redundant(1) command can be used to remove redundant pack files.
+  The subcommand is unusably slow and the reason why nobody reports it as a
+  performance bug is suspected to be the absence of users. We have nominated
+  the command for removal and have started to emit a user-visible warning in
+  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
+  2020-08-25) whenever the command is executed.
++
+So far there was a single complaint about somebody still using the command, but
+that complaint did not cause us to reverse course. On the contrary, we have
+doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
+escalate deprecation warning to an error, 2023-03-23), the command dies unless
+the user passes the `--i-still-use-this` option.
++
+There have not been any subsequent complaints, so this command will finally be
+removed.
++
+Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
+    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
+    <20230323204047.GA9290@coredump.intra.peff.net>,
+
+* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
+  and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
+  the repository configuration.
++
+The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
+short-hand notation for remote repositories., 2005-07-16) and was superseded by
+6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
+2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
+commit already mentions an upcoming deprecation of the ".git/branches/"
+directory, and starting with a1d4aa7424 (Add repository-layout document.,
+2005-09-01) we have also marked this layout as deprecated. Eventually we also
+started to migrate away from ".git/remotes/" in favor of config-based remotes,
+and we have marked the directory as legacy in 3d3d282146 (Documentation:
+Grammar correction, wording fixes and cleanup, 2011-08-23)
++
+As our documentation mentions, these directories are unlikely to be used in
+modern repositories and most users aren't even aware of these mechanisms. They
+have been deprecated for almost 20 years and 14 years respectively, and we are
+not aware of any active users that have complained about this deprecation.
+Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
+may cause confusion as "branches" are almost exclusively used in the context of
+references.
++
+These features will be removed.
+
+* Support for "--stdin" option in the "name-rev" command was
+  deprecated (and hidden from the documentation) in the Git 2.40
+  timeframe, in preference to its synonym "--annotate-stdin".  Git 3.0
+  removes the support for "--stdin" altogether.
+
+* The git-whatchanged(1) command has outlived its usefulness more than
+  10 years ago, and takes more keystrokes to type than its rough
+  equivalent `git log --raw`.  We have nominated the command for
+  removal, have changed the command to refuse to work unless the
+  `--i-still-use-this` option is given, and asked the users to report
+  when they do so.
++
+The command will be removed.
+
+* Support for `core.commentString=auto` has been deprecated and will
+  be removed in Git 3.0.
++
+cf. <xmqqa59i45wc.fsf@gitster.g>
+
+* Support for `core.preferSymlinkRefs=true` has been deprecated and will be
+  removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
+  out in favor of using plain files using the textual representation of
+  symbolic refs.
++
+Symbolic references were initially always stored as a symbolic link. This was
+changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a
+textfile., 2005-09-25), where a new textual symref format was introduced to
+store those symbolic refs in a plain file. In 9f0bb90d16
+(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git
+project switched the default to use the textual symrefs in favor of symbolic
+links.
++
+The migration away from symbolic links has happened almost 20 years ago by now,
+and there is no known reason why one should prefer them nowadays. Furthermore,
+symbolic links are not supported on some platforms.
++
+Note that only the writing side for such symbolic links is deprecated. Reading
+such symbolic links is still supported for now.
+
+== Superseded features that will not be deprecated
+
+Some features have gained newer replacements that aim to improve the design in
+certain ways. The fact that there is a replacement does not automatically mean
+that the old way of doing things will eventually be removed. This section tracks
+those features with newer alternatives.
+
+* The features git-checkout(1) offers are covered by the pair of commands
+  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
+  widespread, and it is not expected that this will change anytime soon, all
+  three commands will stay.
++
+This decision may get revisited in case we ever figure out that there are
+almost no users of any of the commands anymore.
++
+Cf. <xmqqttjazwwa.fsf@gitster.g>,
+<xmqqleeubork.fsf@gitster.g>,
+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/meson.build b/Documentation/meson.build
index f4854f802d4..af436b2d5e9 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -192,6 +192,7 @@ manpages = {
   'gitweb.conf.adoc' : 5,
 
   # Category 7.
+  'gitbreaking-changes.adoc' : 7,
   'gitcli.adoc' : 7,
   'gitcore-tutorial.adoc' : 7,
   'gitcredentials.adoc' : 7,
diff --git a/command-list.txt b/command-list.txt
index 63ae2a67c94..1b7236a62fd 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -213,6 +213,7 @@ git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
 git-write-tree                          plumbingmanipulators
 gitattributes                           userinterfaces
+gitbreaking-changes                     guide
 gitcli                                  userinterfaces
 gitcore-tutorial                        guide
 gitcredentials                          guide
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Oct 8, 2026, 19:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 3/5] doc: gitbreaking-changes: replace msg-ids with URLs

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This document has used msg-ids to reference emails since its inception.[1] This makes the text a bit more terse, and is perhaps also convenient for people who can use msg-ids to link to messages in their inbox. But we should consider how convenient this is for people in general, now that this is a more public-facing page (see previous commit). And I suspect that most people will be forced to paste the msg-id according to the described URL template:

    https://lore.kernel.org/git/$message_id/

Let’s instead replace all of the msg-ids with complete links. That way everyone can jump right to the discussions.

† 1: 57ec9254 (docs: introduce document to announce breaking changes, 2024-06-14)
Note that we have to URL encode this msg-id:
     CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com
Lore can handle it just fine, but asciidoctor(1) cannot.

Worse yet, this msg-id can be handled by asciidoctor(1) but not by asciidoc:

     CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com

URL encoding does not help. So compromise by linking to the only second-level reply:

    CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com

Which properly quotes the first message. So no loss of fidelity in my opinion.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    v2:
    • Fix accidental introduction of two spaces[1]
      🔗 1: https://lore.kernel.org/git/ar0OltAkeTiCx81c@pks.im/#t
    • Fix two other unintended space changes. I don’t know why the URLs
      after [1] are aligned like that. But it makes no difference to the
      output. So leave them alone.
      [1]: Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
    • Changing the linking scheme so that the links could use the
      msg-ids as text was discussed. But technical difficulties and
      other concerns lead to no changes on this front.[2]
      † 2: <xmqqeceaa5h9.fsf@gitster.g>
    • ... but, and bad news for my linking scheme: I found out that
      asciidoc(1) (shakes fist) cannot seem to manage to render this URL
      as a URL:
    
          https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%2BDiUQ@mail.gmail.com/
    
      And, well see the commit message.
 Documentation/gitbreaking-changes.adoc | 33 +++++++++++++-------------
 1 file changed, 16 insertions(+), 17 deletions(-)
Show changes to Documentation/gitbreaking-changes.adoc +16 −17
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index c6b974b6d8c..2bb9f877256 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -59,15 +59,14 @@ make the described change that can be easily understood without having to read
 the mailing list discussions. If there are alternatives to the changed feature,
 those alternatives should be pointed out to our users.
 
-All items should be accompanied by references to relevant mailing list threads
-where the deprecation was discussed. These references use message-IDs, which
-can visited via
+All items should be accompanied by links to relevant mailing list threads
+where the deprecation was discussed. These links use this format:
 
   https://lore.kernel.org/git/$message_id/
 
-to see the message and its surrounding discussion. Such a reference is there to
-make it easier for you to find how the project reached consensus on the
-described item back then.
+I.e. they link to the `Message-ID` of the email on the mailing
+list. These references are there to make it easier for you to find how
+the project reached consensus on the described item back then.
 
 This is a living document as the environment surrounding the project changes
 over time. If circumstances change, an earlier decision to deprecate or change
@@ -129,9 +128,9 @@ applications and forges.
 +
 There is no plan to deprecate the "sha1" object format at this point in time.
 +
-Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
-<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
+https://lore.kernel.org/git/20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain,
+https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com.
 
 * The default storage format for references in newly created repositories will
   be changed from "files" to "reftable". The "reftable" format provides
@@ -268,7 +267,7 @@ system configuration.
 The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
 info/grafts as outdated, 2014-03-05) and will be removed.
 +
-Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
+Cf. https://lore.kernel.org/git/20140304174806.GA11561@sigill.intra.peff.net.
 
 * The git-pack-redundant(1) command can be used to remove redundant pack files.
   The subcommand is unusably slow and the reason why nobody reports it as a
@@ -286,9 +285,9 @@ the user passes the `--i-still-use-this` option.
 There have not been any subsequent complaints, so this command will finally be
 removed.
 +
-Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
-    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
-    <20230323204047.GA9290@coredump.intra.peff.net>,
+Cf. https://lore.kernel.org/git/xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com,
+https://lore.kernel.org/git/CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ%3DKAKhtpDNTvHJFuX1NA%40mail.gmail.com,
+https://lore.kernel.org/git/20230323204047.GA9290@coredump.intra.peff.net,
 
 * Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
   and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
@@ -332,7 +331,7 @@ The command will be removed.
 * Support for `core.commentString=auto` has been deprecated and will
   be removed in Git 3.0.
 +
-cf. <xmqqa59i45wc.fsf@gitster.g>
+cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
 
 * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
   removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
@@ -369,9 +368,9 @@ those features with newer alternatives.
 This decision may get revisited in case we ever figure out that there are
 almost no users of any of the commands anymore.
 +
-Cf. <xmqqttjazwwa.fsf@gitster.g>,
-<xmqqleeubork.fsf@gitster.g>,
-<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
+    https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
+    https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
 
 GIT
 ---
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Oct 8, 2026, 19:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 4/5] doc: gitbreaking-changes: add note about living document

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This document has always stated that it is a “living document”, subject to change. With that in mind, we should be mindful of a potentially larger readerbase now that this is a more public-facing page. One could imagine that someone reads this document on a released version, disagrees with a point there, and posts feedback to the project—but this decision could have already been reverted in the live document.[1]

Let’s add a note (admonition) following the “live document” with such a reminder. Let’s keep it short and simple though and not go into how to fetch the source. They can figure that out themselves.

† 1: Let’s say that someone on Git for Debian Stable reads about the
     breaking changes for Git 3.0. They don’t like something about it
     so they post it to the mailing list. Then the mailing list informs
     them that Git 3.0 was released two years ago and that the current
     document is about Git 4.0.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/gitbreaking-changes.adoc | 10 ++++++++++
 1 file changed, 10 insertions(+)
Show changes to Documentation/gitbreaking-changes.adoc +10 −0
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index 2bb9f877256..b94759260d9 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -73,6 +73,16 @@ over time. If circumstances change, an earlier decision to deprecate or change
 something may need to be revisited from time to time. So do not take items on
 this list to mean "it is settled, do not waste our time bringing it up again".
 
+[NOTE]
+--
+In case you are reading this document from a released version: this
+being a _living document_ means that you might want to consult what
+the current, development version of the document looks like in case
+anything here motivates you to post some feedback to the project.
+Because specific details you read here might have been changed in the
+development version.
+--
+
 == Procedure
 
 Discussing the desire to make breaking changes, declaring that breaking
-- 
2.55.0.793.gc667de3f2c5
kristofferhaugsbakk@fastmail.com· Oct 8, 2026, 19:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 5/5] doc: gitbreaking-changes: move new-items discussion to the end

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The target audience for this page is expanding. That means that this discussion about how to add new entries will not be as relevant to the average reader. Let’s move it to the end of the page.

Suggested-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    v2:
    • New: <ar0OltAkeTiCx81c@pks.im>
 Documentation/gitbreaking-changes.adoc | 30 ++++++++++++++------------
 1 file changed, 16 insertions(+), 14 deletions(-)
Show changes to Documentation/gitbreaking-changes.adoc +16 −14
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index b94759260d9..e984c2c8ca5 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -54,20 +54,6 @@ breaking releases. Furthermore, this document also tracks what will _not_ be
 deprecated. This is done such that the outcome of discussions document both
 when the discussion favors deprecation, but also when it rejects a deprecation.
 
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by links to relevant mailing list threads
-where the deprecation was discussed. These links use this format:
-
-  https://lore.kernel.org/git/$message_id/
-
-I.e. they link to the `Message-ID` of the email on the mailing
-list. These references are there to make it easier for you to find how
-the project reached consensus on the described item back then.
-
 This is a living document as the environment surrounding the project changes
 over time. If circumstances change, an earlier decision to deprecate or change
 something may need to be revisited from time to time. So do not take items on
@@ -382,6 +368,22 @@ Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
     https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
     https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
 
+== Adding new items
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by links to relevant mailing list threads
+where the deprecation was discussed. These links use this format:
+
+  https://lore.kernel.org/git/$message_id/
+
+I.e. they link to the `Message-ID` of the email on the mailing
+list. These references are there to make it easier for you to find how
+the project reached consensus on the described item back then.
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.55.0.793.gc667de3f2c5
Kristoffer Haugsbakk· Oct 20, 2026, 13:31 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Thu, Oct 8, 2026, at 21:27, kristofferhaugsbakk@fastmail.com wrote:
Show 8 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Topic name: kh/doc-gitbreaking-changes7
>
> Topic summary: Move BreakingChanges document to a manpage for easier
> visibility.
>
>[snip]
Is there any interest in continuing this series?
D. Ben Knoble· Oct 20, 2026, 13:48 UTC · re: Kristoffer Haugsbakk · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Tue, Oct 20, 2026 at 9:41 AM Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote:

Show 12 quoted lines
>
> On Thu, Oct 8, 2026, at 21:27, kristofferhaugsbakk@fastmail.com wrote:
> > From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> >
> > Topic name: kh/doc-gitbreaking-changes7
> >
> > Topic summary: Move BreakingChanges document to a manpage for easier
> > visibility.
> >
> >[snip]
>
> Is there any interest in continuing this series?
For myself, I favor making more of Git's documentation accessible to folks.

I haven't reviewed the series, and I know there was some conversation on how to handle links, but I'm in favor of the direction.

-- 
D. Ben Knoble
Kristoffer Haugsbakk· Oct 20, 2026, 13:53 UTC · re: D. Ben Knoble · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Tue, Oct 20, 2026, at 15:48, D. Ben Knoble wrote:
Show 11 quoted lines
> On Tue, Oct 20, 2026 at 9:41 AM Kristoffer Haugsbakk
> <kristofferhaugsbakk@fastmail.com> wrote:
>> On Thu, Oct 8, 2026, at 21:27, kristofferhaugsbakk@fastmail.com wrote:
>> >[snip of a snip]
>>
>> Is there any interest in continuing this series?
>
> For myself, I favor making more of Git's documentation accessible to folks.
>
> I haven't reviewed the series, and I know there was some conversation
> on how to handle links, but I'm in favor of the direction.

Thanks. Yeah the link thing turned out to be the most work here. I can of course drop it if people don’t think it’s an improvement. Because as far as making the documentation more accessible, all the info is there with instructions on how to use the references. Just with an extra step.

Junio C Hamano· Oct 21, 2026, 16:50 UTC · re: D. Ben Knoble · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

"D. Ben Knoble" <ben.knoble@gmail.com> writes:
>> Is there any interest in continuing this series?
>
> For myself, I favor making more of Git's documentation accessible to folks.

I do not know about "manual pages", but making this available from "git help" would be good. It raises a huge question about what to do when Git 3.0 comes, though. Are we going to change every section and rewrite them to say "we used to do this differently before 3.0"?

Kristoffer Haugsbakk· Oct 21, 2026, 18:01 UTC · re: Junio C Hamano · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote:
Show 10 quoted lines
> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>
>>> Is there any interest in continuing this series?
>>
>> For myself, I favor making more of Git's documentation accessible to folks.
>
> I do not know about "manual pages", but making this available from
> "git help" would be good.  It raises a huge question about what to
> do when Git 3.0 comes, though.  Are we going to change every section
> and rewrite them to say "we used to do this differently before 3.0"?
See me and Patrick’s subthread: <ar0OicAaDipYx-xU@pks.im>
You could transform it into a section at the end for “what happened in 3.0” then introduce it with
    These things changed in 3.0. They are written in the future tense
    [?] is reading about what will happen coming from version 2.98 to
    3.0.
Then you wouldn’t need to change any of the rest of the text.
Junio C Hamano· Oct 21, 2026, 21:00 UTC · re: Kristoffer Haugsbakk · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 21 quoted lines
> On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote:
>> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>>
>>>> Is there any interest in continuing this series?
>>>
>>> For myself, I favor making more of Git's documentation accessible to folks.
>>
>> I do not know about "manual pages", but making this available from
>> "git help" would be good.  It raises a huge question about what to
>> do when Git 3.0 comes, though.  Are we going to change every section
>> and rewrite them to say "we used to do this differently before 3.0"?
>
> See me and Patrick’s subthread: <ar0OicAaDipYx-xU@pks.im>
>
> You could transform it into a section at the end for “what happened in 3.0” then introduce it with
>
>     These things changed in 3.0. They are written in the future tense
>     [?] is reading about what will happen coming from version 2.98 to
>     3.0.
>
> Then you wouldn’t need to change any of the rest of the text.

The rewriting effort is not a major concern. Rather, the question is whether keeping such a historical document is worth it. Do you still care about what the major issues were when we transitioned from Git 1.x to 2.0, for example?

Kristoffer Haugsbakk· Oct 22, 2026, 05:18 UTC · re: Junio C Hamano · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Wed, Oct 21, 2026, at 23:00, Junio C Hamano wrote:
Show 25 quoted lines
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>> On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote:
>>> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>>>> [snip]
>>>
>>> I do not know about "manual pages", but making this available from
>>> "git help" would be good.  It raises a huge question about what to
>>> do when Git 3.0 comes, though.  Are we going to change every section
>>> and rewrite them to say "we used to do this differently before 3.0"?
>>
>> See me and Patrick’s subthread: <ar0OicAaDipYx-xU@pks.im>
>>
>> You could transform it into a section at the end for “what happened in 3.0” then introduce it with
>>
>>     These things changed in 3.0. They are written in the future tense
>>     [?] is reading about what will happen coming from version 2.98 to
>>     3.0.
>>
>> Then you wouldn’t need to change any of the rest of the text.
>
> The rewriting effort is not a major concern.  Rather, the question
> is whether keeping such a historical document is worth it.  Do you
> still care about what the major issues were when we transitioned
> from Git 1.x to 2.0, for example?

I’ve mostly just outlined how either approach can be handled. Personally I’m fine either way.

As far as being a living document is concerned, discussions of old versions could be promptly deleted. People who are on older versions will have the relevant discussion in their installation. Beyond that people can use the power of version control spelunking.

As an alternative you could keep just the previous breaking change discussion like mentioned in <ar0cjf3rdrp6NAba@pks.im>. Like, when you’re approaching Git 5.0 there will just be Git 5.0 and Git 4.0 discussions left in the doc.

Junio C Hamano· Oct 22, 2026, 16:38 UTC · re: Kristoffer Haugsbakk · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 39 quoted lines
> On Wed, Oct 21, 2026, at 23:00, Junio C Hamano wrote:
>> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>>
>>> On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote:
>>>> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>>>>> [snip]
>>>>
>>>> I do not know about "manual pages", but making this available from
>>>> "git help" would be good.  It raises a huge question about what to
>>>> do when Git 3.0 comes, though.  Are we going to change every section
>>>> and rewrite them to say "we used to do this differently before 3.0"?
>>>
>>> See me and Patrick’s subthread: <ar0OicAaDipYx-xU@pks.im>
>>>
>>> You could transform it into a section at the end for “what happened in 3.0” then introduce it with
>>>
>>>     These things changed in 3.0. They are written in the future tense
>>>     [?] is reading about what will happen coming from version 2.98 to
>>>     3.0.
>>>
>>> Then you wouldn’t need to change any of the rest of the text.
>>
>> The rewriting effort is not a major concern.  Rather, the question
>> is whether keeping such a historical document is worth it.  Do you
>> still care about what the major issues were when we transitioned
>> from Git 1.x to 2.0, for example?
>
> I’ve mostly just outlined how either approach can be handled. Personally
> I’m fine either way.
>
> As far as being a living document is concerned, discussions of old
> versions could be promptly deleted. People who are on older versions
> will have the relevant discussion in their installation. Beyond that
> people can use the power of version control spelunking.
>
> As an alternative you could keep just the previous breaking change
> discussion like mentioned in <ar0cjf3rdrp6NAba@pks.im>. Like, when
> you’re approaching Git 5.0 there will just be Git 5.0 and Git 4.0
> discussions left in the doc.

OK. I was merely expressing my worry that it might be awkward post the transition, but if the manpages (where? in section 7 perhaps) is the easiest to arrange and will not be awkward to have after the transition, then let's do that.

Thanks.
Kristoffer Haugsbakk· Nov 20, 2026, 14:38 UTC · re: Junio C Hamano · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Thu, Oct 22, 2026, at 18:38, Junio C Hamano wrote:
Show 12 quoted lines
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>>[snip]
>>
>> As an alternative you could keep just the previous breaking change
>> discussion like mentioned in <ar0cjf3rdrp6NAba@pks.im>. Like, when
>> you’re approaching Git 5.0 there will just be Git 5.0 and Git 4.0
>> discussions left in the doc.
>
> OK.  I was merely expressing my worry that it might be awkward post
> the transition, but if the manpages (where? in section 7 perhaps) is
> the easiest to arrange and will not be awkward to have after the
> transition, then let's do that.

Back to my question of “Is there any interest in continuing this series?” This topic never got included in `seen`/What’s Cooking and there isn’t any actionable feedback on my latest round. What’s next?

Patrick Steinhardt· Oct 22, 2026, 05:54 UTC · re: Junio C Hamano · lore

Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

On Wed, Oct 21, 2026 at 02:00:52PM -0700, Junio C Hamano wrote:
Show 28 quoted lines
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
> 
> > On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote:
> >> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
> >>
> >>>> Is there any interest in continuing this series?
> >>>
> >>> For myself, I favor making more of Git's documentation accessible to folks.
> >>
> >> I do not know about "manual pages", but making this available from
> >> "git help" would be good.  It raises a huge question about what to
> >> do when Git 3.0 comes, though.  Are we going to change every section
> >> and rewrite them to say "we used to do this differently before 3.0"?
> >
> > See me and Patrick’s subthread: <ar0OicAaDipYx-xU@pks.im>
> >
> > You could transform it into a section at the end for “what happened in 3.0” then introduce it with
> >
> >     These things changed in 3.0. They are written in the future tense
> >     [?] is reading about what will happen coming from version 2.98 to
> >     3.0.
> >
> > Then you wouldn’t need to change any of the rest of the text.
> 
> The rewriting effort is not a major concern.  Rather, the question
> is whether keeping such a historical document is worth it.  Do you
> still care about what the major issues were when we transitioned
> from Git 1.x to 2.0, for example?

Probably not two decades later, but at least for the next couple of years I'd assume. It's likely that upgrades jump multiple versions at a time, for example because the user upgraded from one LTS release to the next one. So they may or may not land on Git 3.0 directly, but it's more likely to assume that they'l land on 3.x where x != 0. And these users would still want to learn about what has changed in the major release.

So I'd say that it makes sense to keep it until at least all of our supported distributions have upgraded to Git 3.0 already.

Patrick

← back to recent threads