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 6d02648a9b3c..d041d87f270b 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -114,87 +114,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`.
-
-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
------------
@@ -240,6 +159,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
@@ -1018,6 +939,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
