# Proposal to turn BreakingChanges into a manpage, gitbreaking-changes(7)

_Kristoffer Haugsbakk argues the planned breaking changes concern all users and should be reachable through git help._

Section: Patches. Edition of 2026-10-09. Written by an AI editor from the thread "[RFC PATCH 0/4] doc: move BreakingChanges to a manpage" (25 messages): https://gitlist.dev/t/66404

Kristoffer Haugsbakk argues that the breaking changes document matters most to users who will be affected, not only to developers who follow project discussions. Today it cannot be opened with git help and requires the source tree or git-scm.com, where a disclaimer says the page is relevant only to contributors. The series renames it to gitbreaking-changes(7) and leaves a BreakingChanges.adoc stub so old links keep working. It also adds the Makefile, meson.build and command-list.txt entries and mentions the page in git(1).

Two patches adapt the text for a wider readership. One replaces msg-ids with complete lore.kernel.org links. Another adds an admonition that the page is a living document, because a reader of a released version might disagree with a point that has since been reverted in the live document. At Patrick Steinhardt's suggestion, a later revision moves the discussion of how to add entries to the end of the page.

D. Ben Knoble welcomed making it a manual in the spirit of datamodel and others. He noted the file can already be found under git --html-path, though that is much less discoverable. The cover letter notes conflicts with ps/ref-storage-format in master and bc/restrict-hex-to-lowercase in seen, both of which edit BreakingChanges.adoc.