On 15/08/2025 22:05, Junio C Hamano wrote:
"Julia Evans via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
From: Julia Evans <julia@xxxxxxx>
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@xxxxxxx>
---
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.
