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

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

Sebastian Schuberth <sschuberth@gmail.com> writes:

> Also, do not say that merge commits are *tried* to be recreated.

Good point.  "We will try but it might fail" is better left unsaid
as that is true almost everywhere.


> Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
> ---
>  Documentation/git-rebase.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index d728030..3a6d139 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -362,7 +362,7 @@ 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 replaying commits a merge
> commit introduces.

Hmm, is this line-wrapped?

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

	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.

or something along that line, perhaps?

This reminds me a related tangent discussion we had long time ago (I
thought j6t was involved hence a new Cc:, but my apologies to j6t if
I am misremembering), about what exactly is "recreate merges instead
of replaying commits".

I think the current preserve-merges considers everything between
<upstream> and <branch> as "commits to be rebased", and recreate
merges across these rebased tips of branches that are merged.  There
however were repeated wishes (or wishful misunderstandings ;-) that
there were a mode to rebuild the trunk, considering only the commits
on the first-parent chain as "commits to be rebased", recreating the
history by replaying the merge commits (whose first parent might be
rewritten during the rebase, but the tips of side branches these
merges bring into the history are kept intact).

Surely there is no such mode right now, but I am fairly sure that I
wouldn't have any objection against a patch to implement such a
feature (perhaps "--first-parent --preserve-merges"?), and with or
without such a feature in the system, I would be happier if we made
sure that the description we are discussing to update makes it clear
that the current behaviour is "everything between <upstream> and
<branch>", and cannot be misread as "do not touch side branches
instead of dropping merged commits".

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