From: Phillip Wood Date: Mon, 18 Aug 2025 13:42:57 GMT Subject: Re: [PATCH v8 4/5] doc: git-rebase: move --onto explanation down Message-ID: <51468411-8251-4f13-90f2-5cd5184d7c52@gmail.com> In-Reply-To: On 15/08/2025 22:05, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" writes: > >> From: Julia Evans >> >> 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 >> --- >> 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.