Hi Junio,
On Tue, 24 Apr 2018, Junio C Hamano wrote:
> "Philip Oakley" <philipoakley@xxxxxxx> writes:
>
> >> +-r::
> >> +--rebase-merges::
> >> + By default, a rebase will simply drop merge commits and only rebase
> >> + the non-merge commits. With this option, it will try to preserve
> >> + the branching structure within the commits that are to be rebased,
> >> + by recreating the merge commits. If a merge commit resolved any merge
It is funny how nobody caught the missing "conflicts" in "If a merge
commit resolved any merge [conflicts]"...
> >> + or contained manual amendments, then they will have to be re-applied
> >> + manually.
> >> ++
> >> +This mode is similar in spirit to `--preserve-merges`, but in contrast to
> >> +that option works well in interactive rebases: commits can be reordered,
> >> +inserted and dropped at will.
> >> ++
> >> +It is currently only possible to recreate the merge commits using the
> >> +`recursive` merge strategy; Different merge strategies can be used only
> >> via
> >> +explicit `exec git merge -s <strategy> [...]` commands.
> >> +
> >> -p::
> >> --preserve-merges::
> >> Recreate merge commits instead of flattening the history by replaying
> >
> > Flatten is here in the context lines but its just a blunt statement that 'it
> > is what it is'...
>
> The first paragraph that explains --rebase-merges talks about what
> happens when the option is not given, and says "drop merge commits
> and only rebase the non-merge commits", which is not incorrect
> per-se but does not make it explicit how the resulting topology
> looks like.
Correct. And it would be the wrong place to describe in detail what a
rebase *without --rebase-merges* does, right?
> I think it is easier to understand if it mentioned "flattening" as well.
> If flatten is not the word you want, perhaps "make it linear" or
> something like that?
I fear that we all here are way too deeply in "Git think". If I ask a
random Git user what it means to "make commits linear", I am sure I would
get only puzzled, nervous looks as a response.
So I am rather certain that the suggested wording is something I want to
avoid.
Besides, we really should expect the reader to know a little about the way
the interactive rebase works by the time they read the explanation of
`--rebase-merges`.
Therefore, I think I can sidestep the entire thing by saying this instead:
-r::
--rebase-merges::
By default, a rebase will simply drop merge commits from the todo
list, and put the rebased commits into a single, linear branch.
With `--rebase-merges`, the rebase will instead try to preserve
the branching structure within the commits that are to be rebased,
by recreating the merge commits. Any resolved merge conflicts or
manual amendments in these merge commits will have to be
resolved/re-applied manually.
Thank you for helping me improve the documentation part of this patch,
which I think is really, really important,
Dscho
