[PATCH/RFC 3/5] history.adoc: describe merge-replay support and its limits
- From
Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com>
- Date
- May 6, 2026, 22:43 UTC
- Message-ID
- <1dfbd26d757e7e610f8ef8058d839f103059b733.1778107405.git.gitgitgadget@gmail.com>
- In-Reply-To
- <pull.2106.git.1778107405.gitgitgadget@gmail.com>
From: Johannes Schindelin <johannes.schindelin@gmx.de>
Replace the blanket "does not (yet) work with histories that contain merges" caveat now that 2-parent merges are supported via the R/O/N algorithm. Spell out what works (the user's manual conflict resolution and any semantic edits inside the merge are preserved through the replay), what is intentionally out of scope (octopus merges; symbol-level extrapolation when rewriting parents pulls in genuinely new content), and what still requires interactive rebase (merges that would actually conflict on replay).
Assisted-by: Claude Opus 4.7 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> --- Documentation/git-history.adoc | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-history.adoc b/Documentation/git-history.adoc index 24dc907033..56328a7c59 100644 --- a/Documentation/git-history.adoc +++ b/Documentation/git-history.adoc @@ -40,13 +40,26 @@ at once. LIMITATIONS ----------- -This command does not (yet) work with histories that contain merges. You -should use linkgit:git-rebase[1] with the `--rebase-merges` flag instead. - -Furthermore, the command does not support operations that can result in merge -conflicts. This limitation is by design as history rewrites are not intended to -be stateful operations. The limitation can be lifted once (if) Git learns about -first-class conflicts. +This command supports two-parent merge commits in the rewrite path: +the auto-remerged tree of the original parents, the merge commit +itself, and the auto-merged tree of the rewritten parents are +combined so that the user's manual conflict resolution (textual or +semantic) is preserved through the replay. Octopus merges (more than +two parents) are not supported and are rejected with an error. + +The replay propagates the textual diffs the user actually made in +the merge commit. It does _not_ extrapolate symbol-level intent: if +rewriting the parents pulls in genuinely new content (for example, a +new caller of a function that the merge renamed), that new content +is _not_ rewritten by the replay and may need a follow-up edit. +Symbol-aware refactoring is out of scope here, just as it is for +plain rebase. + +The command does not support operations that can result in merge +conflicts on the replayed merge itself. This limitation is by design +as history rewrites are not intended to be stateful operations. Use +linkgit:git-rebase[1] with the `--rebase-merges` flag when the +rewrite is expected to require interactive conflict resolution. COMMANDS --------
-- gitgitgadget