Merge branch 'ss/pull-rebase-preserve' into maint

* ss/pull-rebase-preserve:
  docs: clarify what git-rebase's "-p" / "--preserve-merges" does
  docs: clarify "preserve" option wording for git-pull

2 files changed, 5 insertions, 4 deletions

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 200eb22260..4064452b06 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -111,9 +111,8 @@ include::merge-options.txt[]
 	was rebased since last fetched, the rebase uses that information
 	to avoid rebasing non-local changes.
 +
-When preserve, also rebase the current branch on top of the upstream
-branch, but pass `--preserve-merges` along to `git rebase` so that
-locally created merge commits will not be flattened.
+When set to preserve, rebase with the `--preserve-merges` option passed
+to `git rebase` so that locally created merge commits will not be flattened.
 +
 When false, merge the current branch into the upstream branch.
 +
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 924827dc2e..c8ab48d6aa 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -362,7 +362,9 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`.
 
 -p::
 --preserve-merges::
-	Instead of ignoring merges, try to recreate them.
+	Recreate merge commits instead of flattening the history by replaying
+	commits a merge commit introduces. Merge conflict resolutions or manual
+	amendments to merge commits are not preserved.
 +
 This uses the `--interactive` machinery internally, but combining it
 with the `--interactive` option explicitly is generally not a good