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

From: Phillip Wood <[email-masked]>
Date: Mon, 18 Aug 2025 14:42:57 +0100

On 15/08/2025 22:05, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email-masked]> writes:
> 
>> From: Julia Evans <[email-masked]>
>>
>> There's a very clear explanation with examples of using --onto which is
>> currently buried in the very long DESCRIPTION section. This moves it to
>> its own section, so that we can reference the explanation from the
>> `--onto` option by name.
>>
>> Signed-off-by: Julia Evans <[email-masked]>
>> ---
>>   Documentation/git-rebase.adoc | 168 ++++++++++++++++++----------------
>>   1 file changed, 87 insertions(+), 81 deletions(-)
> 
> Deduplicating is very good idea.
> 
> I gave a read-through over the result of the entire series,
> including the parts that did not change, to see if the new
> organization is easy to read and coherently tells the story
> we want to tell, and what I saw was mostly very pleasing, except for
> one thing.

Yes the reworked DESCRIPTION section is very good.

> The new location of this section on "--onto" felt a bit off.
> Perhaps it is just me, but in case others have different opinions,
> I'd raise it here.

I agree that "--onto" is a fairly commonly used option and so it might 
be nice to mention it in the general description. 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. Maybe 
we could just add a sentence to the description explaining that it is 
possible to transplant the commits to a different base using "--onto". 
That would also keep the description fairly concise.

I've just built the html version and it would be nice if we could add a 
link to the TRANSPLANTING A TOPIC BRANCH WITH --ONTO when we mention it 
in the description of "--onto". The same goes for the mention of 
INTERACTIVE MODE in the DESCRIPTION section.

Thanks

Phillip

> The overall structure of the document with these patches becomes:
> 
>   - description that gives a simplified "what is achieved".
> 
>   - "mode options" that control what to do during a rebase once the
>     user is given control back
> 
>   - "options" that is given upfront
> 
>   - notes about incompatible options
> 
>   - discussions about apply/merge backends and how they differ
> 
>   - overall notes on advanced topics
> 
>     - interactive mode basics
> 
>     - splitting commits
> 
>     - use of --onto
> 
>     - dealing with rebased upstream
> 
>     - rebasing merges
> 
> Is it so exotic to use "--onto" to replay a topic to somewhere other
> than the direct descendant of the fork point, to make it a part of
> advanced topics?  I somehow doubt it.  It is a very basic and common
> thing to do while correcting a mistake of choosing a wrong base
> commit.  You often realize that your topic is basically good but has
> to work well with a different base commit.
> 
> I wonder if it gives the same understanding with a much shorter text
> and illustration if we get rid of that section, and mention --onto
> as a part of the early examples in the description section.  That
> way, we can reuse the "set up" of user's brain and context we
> already made with the existing example.
> 
> For example, after showing the rebase of A..C on top of G, we can
> mention that the range can be transplanted on top of commit other
> than G, say D.  Perhaps we can say that 'D' is still part of the
> maintenance track, and the topic being a fix for a bug that happened
> before D, it should not have forked from E that is a feature
> enhancement commit that is not eligible for being on the maintenance
> track.  That would be a good reason why the user may want to move
> A..C on top of D instead of E.