Re: [PATCH v8 4/5] doc: git-rebase: move --onto explanation down

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

"Julia Evans" <julia@jvns.ca> writes:

>>> The existing
>>> examples are all good reasons why one might want to use "--onto" so
>>> I'm slightly wary of replacing them with a single example in the
>>> description.
>>
>> Then perhaps we should find a better place to put it.  The section
>> on advanced topics notes are mostly about operations using sequencer
>> machinery, except for the onto section.  Perhaps immediately after
>> the apply/merge comparison?
>
> I'm happy to move it anywhere: I couldn't figure out how the sections
> were meant to be organized (I didn't know that "operations about 
> sequencer machinery" was meant to be a theme) so I chose where
> to put it pretty arbitrarily.

I do not think it was meant to be a theme, but the topics there
ended up being around it as they were placed there organically.

If we were moving it, how about somewhere fairly early, like before
we start talking about mode options, where we teach the very basic
concept "rebase is to transplant a range history on top of a commit
that is different from where that history currently builds on"?  The
primary difference with and without "--onto" is if you explicitly
specify where to transplant your history, independent from how you
specify the range of history to be transplanted, or a single
<upstream> implicitly specifies both.