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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 15, 2025, 21:05 UTC
Message-ID: <xmqqh5y8nvmv.fsf@gitster.g>
In-Reply-To: <4686417b28e4ab386983ad68e4d4d4798a467811.1755276751.git.gitgitgadget@gmail.com>

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

Show 11 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> 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 <julia@jvns.ca>
> ---
>  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.

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.

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.