Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits

"Philip Oakley" [off-list ref] writes:

From: "Junio C Hamano" <redacted>
Sent: Monday, May 20, 2013 5:43 AM

quoted

Jonathan Nieder [off-list ref] writes:

quoted

Philip Oakley wrote:

quoted

Describe rebase in the description section.

It already does that. :)  I think you mean "start with a summary",
which is a valuable improvement.

It indeed is a good idea to give the "high-level introduction" at
the very beginning, but I do not think it should describe only one
of the three major modes of "git rebase" (i.e. no -m, no -i), like
the proposed patch text does.  We should instead say what it is used
for and why the user would want to use it that is common across
these modes at a very high level.

That would repeat the NAME issue (of trying too hard to be exact &
precise). This introductory text is that "summary".

If that is "summary", it should never talk about "skips merges",
which only applies to the mode without -m, no?

The highest level view of what the command is for (the motivation
why the user would want to consider learning how to use the command)
is "You have a history built on top of some commit, and you want to
rebuild the history on top of another commit, e.g. you earlier built
on the tip of a branch that has some other work, and you want to
rebuild the history on top of the updated tip of that other branch".

The details of how the history is "rebuilt" can differ while using
various modes of operation.  Some may skip merges, some may try to
preserve the topology, some may even let you insert new commits by
letting you tell it to stop in the middle.  That is not "summary"
but is part of mode specific description.