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

Sebastian Schuberth [off-list ref] 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'

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

On Mon, Mar 30, 2015 at 7:23 PM, Junio C Hamano [off-list ref] wrote:

quoted

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",

To me, too. In other words, this is the combined diff of all commits
reachable from all parents of the merge (other than the first parent).
In your example, that would be the combined diff of D, E and F, which
equals "git diff C G".

However, I'm used to thinking that a non-conflicting merge itself has
no diff, but introduces commits that have diffs. This way of seeing it
probably comes from my intensive use of gitk which does not display a
diff when selecting a merge commit unless it has conflicts resolved.

while "merge commit was skipped" would mean a history like this:

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

This is where your interpretation differs. If a merge commit was
skipped, it is non-existent. If it is non-existent, it also has no
parents. If it has no parents, there are no commits that D, E, F could
be replayed on to of C. Thus for me, skipping merge commit G in your
example would result in:

    ---A---B---C---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'

I think we need to generalize the wording a bit for merges with more
than two parents. How about making the the first paragraph of the
commit message simply read:

Ignoring a merge sounds like dropping the merge commit and all side
branches it merges from history. But that is not what happens if "-p" is
not specified.

-- 
Sebastian Schuberth