Rebasing a Pull Request (PR)

When working on a PR, changes may occur in the parent branch (usually master).

This can lead to conflict with changes in your branch. The conflicts can be

trivial: for example both the parent branch and your branch add an entry to

the top of `CHANGELOG`. Git can not unambiguously tell what to with both

changes (should one go above the other? if so, which order? should it try to

merge them?) so it declares the branches can not be merged

cleanly. Github can only automatically merge PR without conflicts, so you will

need to manually 'rebase'. This is the process of updating your branch with

upstream changes, and resolving conflicts.

In git, rebasing is a mild form of re-writing history: it effectively forwards

all your commits to the updated upstream commit. For a much more detailed

explanation (with pictures!) see `this nice write up

<http://git-scm.com/book/en/Git-Branching-Rebasing>`. The numpy team has also

`documented how to do this

<http://docs.scipy.org/doc/numpy/dev/gitwash/development_workflow.html#rebasing-on-master>`

In general, re-writing history, particularly published history, is considered

bad practice, but in this case it is very useful.

The following example assumes that the remote of _your_ github

repository is called `github` and the remote of the official

repository is called `matplotlib`.

The first step is to make sure that your local copy of the upstream repository is

up-to-date::

This updates your local copy of the repository, but does not change any files

in your working copy. Next, switch to the branch that you want to update::

You are now ready to start the rebase of your branch onto the target

parent branch, in this case `matplotlib/master` ::

and git will then give a bunch of feed back::

A number of commits could be cleanly applied to

the tip of `matplotlib/master`, however, git eventually hits a commit

that had conflicts. In this case in the file

`lib/matplotlib/backends/backend_gtk3.py`. For more verbose information run ::

This tells you exactly where the conflict is and provides some advice

on how to proceed. Opening up the file in question, you will see

blocks that look something like this::

The block of code between `<<<<<<<` and `=======` is the code on the

target branch (in this case nothing) and the code between `=======`

and `>>>>>>>` is the code on your branch. The rest of the code is the

same between the two branches. You need to determine how to resolve the

conflict (in this case, the code on HEAD is correct). Once you have

resolved all the conflicts, `add` the file to the index::

Repeat this for all of the files that have conflicts. When you are done with

that you can check the status::

which shows us that we have resolved all of the conflicts with this

commit and can continue::

You now iterate the until you have made it through all of the commits

which have conflicts. Once you have successfully rebased your branch,

be sure to re-run the tests to make sure everything is still working

properly.

Your branch is now rebased, however, because of the way git

determines the hash of each commit, it now shares no commits with your

old branch published on github so you can not push to that branch as

you would when simply adding commits. In order to publish your newly

rebased (and tested!) branch you need to use the `--force` flag::

which will _replace_ all of the commits under your branch on github

with the new versions of the commit.

Congratulations, you have rebased your branch!