Subject: Re: [PATCH] docs: Clarify what git-rebase's "--preserve-merges" does

From: Sebastian Schuberth <[email-masked]>
Date: Mon, 30 Mar 2015 11:29:46 +0200

On 3/26/2015 19:18, Junio C Hamano wrote:

> Although I fully agree that the new text is better than the original,
> I think the new text fails to point out one major aspect by not
> mentioning "linear" or "flatten" anywhere.  The point of "git rebase"
> without "-p" is not just to replay but to flatten

I think it's a bit odd to say that "-p" does not flatten if the whole current rebase docs do not use the terms flattening / linearize at all. If we say that that "-p" does not flatten, we should say that a "standard" rebase wihtout "-p" does. I plan to send a patch for that later.

> 	Instead of flattening the history by replaying each
> 	non-merge commit to be rebased, preserve the shape of the
> 	rebased history by recreating merge commits as well.

Personally, I like "positive logic" better here, i.e. start with saying what the option does, not what it does not do.

So how about:

[PATCH] docs: Clarify what git-rebase's "-p" / "--preserve-merges" does

Ignoring a merge sounds like ignoring the changes a merge commit
introduces altogether, as if the merge commit was skipped or dropped from
history. But that is not what happens if "-p" is not specified.

Instead, what happens is that the individual commits a merge commit
introduces are replayed in order, and only any possible merge conflict
resolutions or manual amendments to the merge commit are ignored. Get this
straight in the docs.

Also, do not say that merge commits are *tried* to be recreated. As that is
true almost everywhere it is better left unsaid.

Signed-off-by: Sebastian Schuberth <[email-masked]>
---
 Documentation/git-rebase.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index d728030..47984e8 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
-- 
1.9.5.msysgit.1