Merge pull request #8561 from AThousandShips/rebase_onto

Add instructions for rebasing onto a branch

contributing/workflow/pr_workflow.rst

@@ -518,7 +518,7 @@ will raise an error:
     hint: Updates were rejected because the tip of your current branch is behind
     hint: its remote counterpart.
 
-This is a sane behavior, Git will not let you push changes that would
+This is reasonable behavior, Git will not let you push changes that would
 override remote content. But that's actually what we want to do here, so we
 will have to *force* it:
 
@@ -530,6 +530,31 @@ And tadaa! Git will happily *replace* your remote branch with what you had
 locally (so make sure that's what you wanted, using ``git log``). This will
 also update the PR accordingly.
 
+Rebasing onto another branch
+----------------------------
+
+If you have accidentally opened your PR on the wrong branch, or need to target another branch
+for some reason, you might need to filter out a lot of commits that differ between the old branch
+(for example ``4.2``) and the new branch (for example ``master``). This can make rebasing difficult
+and tedious. Fortunately ``git`` has a command just for this situation, ``git rebase --onto``.
+
+If your PR was created from the ``4.2`` branch and you want to update it to instead start at ``master``
+the following steps *should* fix this in one step:
+
+.. code-block:: text
+
+    $ git rebase -i --onto master 4.2
+
+This will take all the commits on your branch *after* the ``4.2`` branch, and then splice them on top of ``master``,
+ignoring any commits from the ``4.2`` branch not on the ``master`` branch. You may still need to do some fixing, but
+this command should save you a lot of tedious work removing commits.
+
+Just like above for the interactive rebase you need to force push your branch to handle the different changes:
+
+::
+
+    $ git push --force origin better-project-manager
+
 Deleting a Git branch
 ---------------------