rebase: introduce the --rebase-merges option

[thirdparty/git.git] / Documentation / git-rebase.txt

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index dd852068b1d06f8f40566da65579564144fef718..7f1756f1ebaceeec39c65e087cb0f4af200e4a84 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -379,6 +379,24 @@ The commit list format can be changed by setting the configuration option
 rebase.instructionFormat.  A customized instruction format will automatically
 have the long commit hash prepended to the format.
 
+-r::
+--rebase-merges::
+       By default, a rebase will simply drop merge commits from the todo
+       list, and put the rebased commits into a single, linear branch.
+       With `--rebase-merges`, the rebase will instead try to preserve
+       the branching structure within the commits that are to be rebased,
+       by recreating the merge commits. Any resolved merge conflicts or
+       manual amendments in these merge commits will have to be
+       resolved/re-applied manually.
++
+This mode is similar in spirit to `--preserve-merges`, but in contrast to
+that option works well in interactive rebases: commits can be reordered,
+inserted and dropped at will.
++
+It is currently only possible to recreate the merge commits using the
+`recursive` merge strategy; Different merge strategies can be used only via
+explicit `exec git merge -s <strategy> [...]` commands.
+
 -p::
 --preserve-merges::
        Recreate merge commits instead of flattening the history by replaying
@@ -781,7 +799,8 @@ BUGS
 The todo list presented by `--preserve-merges --interactive` does not
 represent the topology of the revision graph.  Editing commits and
 rewording their commit messages should work fine, but attempts to
-reorder commits tend to produce counterintuitive results.
+reorder commits tend to produce counterintuitive results. Use
+`--rebase-merges` in such scenarios instead.
 
 For example, an attempt to rearrange
 ------------