rebase -i -p: document shortcomings

The rebase --preserve-merges facility presents a list of commits
in its instruction sheet and uses a separate table to keep
track of their parents.  Unfortunately, in practice this means
that with -p after most attempts to rearrange patches, some
commits have the "wrong" parent and the resulting history is
rarely what the caller expected.

Yes, it would be nice to fix that.  But first, add a warning to the
manual to help the uninitiated understand what is going on.

Reported-by: Jiří Paleček <jpalecek@web.de>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 50ba2e469f48f1bc16c3f6e3b6f6451a9e29637a..be23ad2359b486e4da2ef85962d73cdfed7097fe 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -310,6 +310,11 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details).
 -p::
 --preserve-merges::
        Instead of ignoring merges, try to recreate them.
++
+This uses the `--interactive` machinery internally, but combining it
+with the `--interactive` option explicitly is generally not a good
+idea unless you know what you are doing (see BUGS below).
+
 
 --root::
        Rebase all commits reachable from <branch>, instead of
@@ -611,6 +616,28 @@ The ripple effect of a "hard case" recovery is especially bad:
 case" recovery too!
 
 
+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.
+
+For example, an attempt to rearrange
+------------
+1 --- 2 --- 3 --- 4 --- 5
+------------
+to
+------------
+1 --- 2 --- 4 --- 3 --- 5
+------------
+by moving the "pick 4" line will result in the following history:
+------------
+       3
+       /
+1 --- 2 --- 4 --- 5
+------------
+
 Authors
 ------
 Written by Junio C Hamano <gitster@pobox.com> and

diff --git a/t/t3404-rebase-interactive.sh b/t/t3404-rebase-interactive.sh
index f20ea38411d0ca67709dbde0bfd1108e28c0dd71..6668907ec5c5ba196c39fd9a2097050d92ccbe57 100755 (executable)
--- a/t/t3404-rebase-interactive.sh
+++ b/t/t3404-rebase-interactive.sh
@@ -181,6 +181,12 @@ test_expect_success '-p handles "no changes" gracefully' '
        test $HEAD = $(git rev-parse HEAD)
 '
 
+test_expect_failure 'exchange two commits with -p' '
+       FAKE_LINES="2 1" git rebase -i -p HEAD~2 &&
+       test H = $(git cat-file commit HEAD^ | sed -ne \$p) &&
+       test G = $(git cat-file commit HEAD | sed -ne \$p)
+'
+
 test_expect_success 'preserve merges with -p' '
        git checkout -b to-be-preserved master^ &&
        : > unrelated-file &&