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>
Jonathan Nieder committed
May 31, 2010 at 20:43 UTC
cddb42d2c58a9de9b2b5ef68817778e7afaace3e
2 files changed
+33
Documentation/git-rebase.txt
+27
@@ -310,6 +310,11 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details).
310
-p::
311
--preserve-merges::
312
Instead of ignoring merges, try to recreate them.
313
++
314
+This uses the `--interactive` machinery internally, but combining it
315
+with the `--interactive` option explicitly is generally not a good
316
+idea unless you know what you are doing (see BUGS below).
317
+
318
319
--root::
320
Rebase all commits reachable from <branch>, instead of
@@ -611,6 +616,28 @@ The ripple effect of a "hard case" recovery is especially bad:
616
case" recovery too!
617
618
619
+BUGS
620
+----
621
+The todo list presented by `--preserve-merges --interactive` does not
622
+represent the topology of the revision graph. Editing commits and
623
+rewording their commit messages should work fine, but attempts to
624
+reorder commits tend to produce counterintuitive results.
625
+
626
+For example, an attempt to rearrange
627
+------------
628
+1 --- 2 --- 3 --- 4 --- 5
629
+------------
630
+to
631
+------------
632
+1 --- 2 --- 4 --- 3 --- 5
633
+------------
634
+by moving the "pick 4" line will result in the following history:
635
+------------
636
+ 3
637
+ /
638
+1 --- 2 --- 4 --- 5
639
+------------
640
+
641
Authors
642
------
643
Written by Junio C Hamano <gitster@pobox.com> and
t/t3404-rebase-interactive.sh
+6
@@ -181,6 +181,12 @@ test_expect_success '-p handles "no changes" gracefully' '
181
test $HEAD = $(git rev-parse HEAD)
182
'
183
184
+test_expect_failure 'exchange two commits with -p' '
185
+ FAKE_LINES="2 1" git rebase -i -p HEAD~2 &&
186
+ test H = $(git cat-file commit HEAD^ | sed -ne \$p) &&
187
+ test G = $(git cat-file commit HEAD | sed -ne \$p)
188
+'
189
+
190
test_expect_success 'preserve merges with -p' '
191
git checkout -b to-be-preserved master^ &&
192
: > unrelated-file &&