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

[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
Previous: Johannes Schindelin via GitGitGadgetNext: Johannes Schindelin via GitGitGadget
Message 11 of 19 in “replay: support replaying 2-parent merges”
  1. 0/5 replay: support replaying 2-parent mergesJohannes Schindelin via GitGitGadget, May 6, 2026
  2. 1/5 replay: support replaying 2-parent mergesJohannes Schindelin via GitGitGadget, May 6, 2026
  3. Phillip WoodMay 8, 2026
  4. Phillip WoodMay 8, 2026
  5. Johannes SchindelinMay 17, 2026
  6. Johannes SchindelinMay 17, 2026
  7. Kristoffer HaugsbakkMay 26, 2026
  8. Philippe BlainNov 5, 2026
  9. Philippe BlainNov 13, 2026
  10. 2/5 replay: short-circuit merge replay when parent and base trees are unchangedJohannes Schindelin via GitGitGadget, May 6, 2026
  11. 3/5 history.adoc: describe merge-replay support and its limitsJohannes Schindelin via GitGitGadget, May 6, 2026
  12. 5/5 t3454: cover merge-replay scenarios with the historian helperJohannes Schindelin via GitGitGadget, May 6, 2026
  13. 4/5 test-tool: add a "historian" subcommand for building merge fixturesJohannes Schindelin via GitGitGadget, May 6, 2026
  14. Toon ClaesMay 12, 2026
  15. Johannes SchindelinMay 17, 2026
  16. D. Ben KnobleMay 7, 2026
  17. Johannes SchindelinMay 7, 2026
  18. Ben KnobleMay 7, 2026
  19. Johannes SchindelinMay 17, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.