[PATCH v9 0/5] doc: git-rebase: clarify DESCRIPTION section
- From
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
- Date
- Aug 23, 2025, 00:42 UTC
- Message-ID
- <pull.1949.v9.git.1755909782.gitgitgadget@gmail.com>
- In-Reply-To
- <pull.1949.v8.git.1755276750.gitgitgadget@gmail.com>
Move the "TRANSPLANTING A TOPIC BRANCH WITH --ONTO" back up: now it's in the exact same place it was before, just now with a section heading.
Julia Evans (5): doc: git-rebase: start with an example doc: git rebase: dedup merge conflict discussion doc: git rebase: clarify arguments syntax doc: git-rebase: move --onto explanation down doc: git-rebase: update discussion of internals
Documentation/git-rebase.adoc | 149 +++++++++++++--------------------- 1 file changed, 58 insertions(+), 91 deletions(-)
base-commit: 64cbe5e2e8a7b0f92c780b210e602496bd5cad0f Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1949%2Fjvns%2Fclarify-rebase-v9 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1949/jvns/clarify-rebase-v9 Pull-Request: https://github.com/gitgitgadget/git/pull/1949
Range-diff vs v8:
1: e7a8fbbe53c = 1: ea1438e094e doc: git-rebase: start with an example
2: ad63f69918d = 2: 339b7a1bc5b doc: git rebase: dedup merge conflict discussion
3: 7ee6b0afe88 = 3: f42c2c794a9 doc: git rebase: clarify arguments syntax
4: 4686417b28e ! 4: 9c2a54ab9fa doc: git-rebase: move --onto explanation down
@@ Documentation/git-rebase.adoc: 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`.
--
--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
- ------------
-
++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`.
@@ Documentation/git-rebase.adoc: 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.
++See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.
+
--keep-base::
Set the starting point at which to create the new commits to the
merge base of `<upstream>` and `<branch>`. Running
-@@ Documentation/git-rebase.adoc: 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
- -------------------------------
-
5: cb85642bb9d ! 5: 5a1dd8df29b doc: git-rebase: update discussion of internals
@@ Documentation/git-rebase.adoc: linkgit:git-config[1] for details) and the `--for
+tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,
+see linkgit:gitrevisions[7].
- MODE OPTIONS
- ------------
+ TRANSPLANTING A TOPIC BRANCH WITH --ONTO
+ ------------------------------------------ gitgitgadget