summaryrefslogtreecommitdiff
path: root/Documentation/git-rebase.txt
diff options
context:
space:
mode:
authorJonathan Nieder <jrnieder@gmail.com>2010-05-31 20:43:35 -0500
committerJunio C Hamano <gitster@pobox.com>2010-06-11 08:44:13 -0700
commitcddb42d2c58a9de9b2b5ef68817778e7afaace3e (patch)
treea84c9d248cc0af010f499a815a6d9a38997d0e85 /Documentation/git-rebase.txt
parent2543d9b609d158f611e317738644e67cacac6b9a (diff)
downloadgit-cddb42d2c58a9de9b2b5ef68817778e7afaace3e.tar.gz
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>
Diffstat (limited to 'Documentation/git-rebase.txt')
-rw-r--r--Documentation/git-rebase.txt27
1 files changed, 27 insertions, 0 deletions
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 50ba2e469f..be23ad2359 100644
--- 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