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

[Junio C Hamano <gitster@pobox.com>]

Sebastian Schuberth <sschuberth@gmail.com> writes:

> 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.

Every time I read the above (which is essentially the same from your
first edition I think) I find the "ignoring the changes a merge
commit introduces altogether" and "as if the merge commit was
skipped" somehow contradicting with each other.  If the latter were
"as if the side branch that was merged was skipped or dropped", I do
not see the room for such a misinterpretation.

That is, at least to me,

         D---E---F
        /         \
    ---A---B---C---G---H

the former, i.e. "the changes the merge G introdues", is "diff C G",
while "merge commit was skipped" would mean a history like this:

    ---A---B---C---D'--E'--F'--H'

And I think with "as if the side branch that was merged was
dropped", this misinterpretation will become impossible.  It can
only mean this history:

    ---A---B---C---.---H'

> 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 <sschuberth@gmail.com>
> ---
>  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.

The patch text itself reads fine.

>  +
>  This uses the `--interactive` machinery internally, but combining it
>  with the `--interactive` option explicitly is generally not a good