[PATCH v9 0/5] doc: git-rebase: clarify DESCRIPTION section

["Julia Evans via GitGitGadget" <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