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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 19, 2025, 19:45 UTC
Message-ID: <xmqqwm6zccy4.fsf@gitster.g>
In-Reply-To: <106c4a6c-9239-4c67-8bed-5ec2c0987f21@app.fastmail.com>

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

Show 14 quoted lines

>>> 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.