On Fri, Aug 8, 2025 at 9:14 PM Julia Evans via GitGitGadget <gitgitgadget@xxxxxxxxx> wrote: > > 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(-) > > diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc > index 914f743ae00f..50c84f138212 100644 > --- a/Documentation/git-rebase.adoc > +++ b/Documentation/git-rebase.adoc > @@ -111,87 +111,6 @@ will result in: > D---E---A'---F master > ------------ > > -Here is how you would transplant a topic branch based on one > -branch to another, to pretend that you forked the topic branch > -from the latter branch, using `rebase --onto`. I wonder if we should leave a pointer to the reader to the new section here, also? The onto mode is not quite as common in my workflow as the other modes, but when helping less experienced users out I often end up using it, so keeping some reference to it early might be nice. IDK where a natural point is, though. > - > -First let's assume your 'topic' is based on branch 'next'. > -For example, a feature developed in 'topic' depends on some > -functionality which is found in 'next'. > - > ------------- > - o---o---o---o---o master > - \ > - o---o---o---o---o next > - \ > - o---o---o topic > ------------- > - > -We want to make 'topic' forked from branch 'master'; for example, > -because the functionality on which 'topic' depends was merged into the > -more stable 'master' branch. We want our tree to look like this: > - > ------------- > - o---o---o---o---o master > - | \ > - | o'--o'--o' topic > - \ > - o---o---o---o---o next > ------------- > - > -We can get this using the following command: > - > - git rebase --onto master next topic > - > - > -Another example of --onto option is to rebase part of a > -branch. If we have the following situation: > - > ------------- > - H---I---J topicB > - / > - E---F---G topicA > - / > - A---B---C---D master > ------------- > - > -then the command > - > - git rebase --onto master topicA topicB > - > -would result in: > - > ------------- > - H'--I'--J' topicB > - / > - | E---F---G topicA > - |/ > - A---B---C---D master > ------------- > - > -This is useful when topicB does not depend on topicA. > - > -A range of commits could also be removed with rebase. If we have > -the following situation: > - > ------------- > - E---F---G---H---I---J topicA > ------------- > - > -then the command > - > - git rebase --onto topicA~5 topicA~3 topicA > - > -would result in the removal of commits F and G: > - > ------------- > - E---H'---I'---J' topicA > ------------- > - > -This is useful if F and G were flawed in some way, or should not be > -part of topicA. Note that the argument to `--onto` and the `<upstream>` > -parameter can be any valid commit-ish. > - > MODE OPTIONS > ------------ > > @@ -237,6 +156,8 @@ As a special case, you may use "A\...B" as a shortcut for the > merge base of A and B if there is exactly one merge base. You can > leave out at most one of A and B, in which case it defaults to HEAD. > > +See TRANSPLANTING A TOPIC BRANCH WITH --ONTO below for examples. > + > --keep-base:: > Set the starting point at which to create the new commits to the > merge base of `<upstream>` and `<branch>`. Running > @@ -1015,6 +936,91 @@ consistent (they compile, pass the testsuite, etc.) you should use > after each commit, test, and amend the commit if fixes are necessary. > > > +TRANSPLANTING A TOPIC BRANCH WITH --ONTO > +---------------------------------------- > + > +Here is how you would transplant a topic branch based on one > +branch to another, to pretend that you forked the topic branch > +from the latter branch, using `rebase --onto`. > + > +First let's assume your 'topic' is based on branch 'next'. > +For example, a feature developed in 'topic' depends on some > +functionality which is found in 'next'. > + > +------------ > + o---o---o---o---o master > + \ > + o---o---o---o---o next > + \ > + o---o---o topic > +------------ > + > +We want to make 'topic' forked from branch 'master'; for example, > +because the functionality on which 'topic' depends was merged into the > +more stable 'master' branch. We want our tree to look like this: > + > +------------ > + o---o---o---o---o master > + | \ > + | o'--o'--o' topic > + \ > + o---o---o---o---o next > +------------ > + > +We can get this using the following command: > + > + git rebase --onto master next topic > + > + > +Another example of --onto option is to rebase part of a > +branch. If we have the following situation: > + > +------------ > + H---I---J topicB > + / > + E---F---G topicA > + / > + A---B---C---D master > +------------ > + > +then the command > + > + git rebase --onto master topicA topicB > + > +would result in: > + > +------------ > + H'--I'--J' topicB > + / > + | E---F---G topicA > + |/ > + A---B---C---D master > +------------ > + > +This is useful when topicB does not depend on topicA. > + > +A range of commits could also be removed with rebase. If we have > +the following situation: > + > +------------ > + E---F---G---H---I---J topicA > +------------ > + > +then the command > + > + git rebase --onto topicA~5 topicA~3 topicA > + > +would result in the removal of commits F and G: > + > +------------ > + E---H'---I'---J' topicA > +------------ > + > +This is useful if F and G were flawed in some way, or should not be > +part of topicA. Note that the argument to `--onto` and the `<upstream>` > +parameter can be any valid commit-ish. > + > + > RECOVERING FROM UPSTREAM REBASE > ------------------------------- > > -- > gitgitgadget > > -- D. Ben Knoble
