On 2017-09-02 02:04, Jonathan Nieder wrote:

quoted

Anyway, this should really more explicitly say *what* you need to know
about, that is, reordering commits does not work.

It tries to explain that, even with an example.  If you have ideas for
improving the wording, that would be welcome.

As a first step, I indeed believe the wording must the stronger / clearer. How about this:

From f69854ce7b9359603581317d152421ff6d89f345 Mon Sep 17 00:00:00 2001
From: Sebastian Schuberth <redacted>
Date: Mon, 11 Sep 2017 10:41:27 +0200
Subject: [PATCH] docs: use a stronger wording when describing bugs with rebase -i -p

Signed-off-by: Sebastian Schuberth <redacted>
---
 Documentation/git-rebase.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 6805a74aec..ccd0a04d54 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt

@@ -782,10 +782,11 @@ 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.
+Be careful when combining the `-i` / `--interactive` and `-p` /
+`--preserve-merges` options.  Reordering commits will drop commits from the
+main line. This is because the todo list does not represent the topology of the
+revision graph in this case.  However, editing commits and rewording their
+commit messages 'should' work fine.
 
 For example, an attempt to rearrange
 ------------

-- 
2.14.1.windows.1