Re: [PATCH v5 1/5] doc: git-rebase: start with an example

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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> - Start with an example that mirrors the example in the `git-merge` man
>   page, to make it easier for folks to understand the difference between
>   a rebase and a merge.
> - Mention that rebase can combine or reorder commits

The new comment added by this second point looks somewhat out of
place.  With this patch as-is, the text talks only about the best
case of the basic usage, tell the reader to go elsewhere if they are
not interested in learning the basic usage, and then switches back
to the basic usage topic and talks about conflict resolution.

It may be easier to read if you covered the fact that there are two
major use cases upfront, perhaps like:

    DESCRIPTION
    -----------
    Transplant a series of commits onto a different starting point.
    You can also use `git rebase` to reorder or combine commits: see
    INTERACTIVE MODE below for how to do that.

    For example, imagine ...