diff --git a/doc/devel/README.txt b/doc/devel/README.txt
new file mode 100644
index 000000000000..3fc074035aff
--- /dev/null
+++ b/doc/devel/README.txt
@@ -0,0 +1,9 @@
+All documentation in the gitwash directory are automatically generated by running the gitwash_dumper.py
+script in the project's root directory using the following parameters:
+
+python gitwash_dumper.py doc/devel Matplotlib --repo-name=matplotlib --github-user=matplotlib \
+   --project-url=http://matplotlib.org \
+   --project-ml-url=https://mail.python.org/mailman/listinfo/matplotlib-devel
+
+The script is hosted at https://raw.githubusercontent.com/matthew-brett/gitwash/master/gitwash_dumper.py.
+For more information please visit https://github.com/matthew-brett/gitwash
\ No newline at end of file
diff --git a/doc/devel/gitwash/branch_dropdown.png b/doc/devel/gitwash/branch_dropdown.png
new file mode 100644
index 000000000000..1bb7a577732c
Binary files /dev/null and b/doc/devel/gitwash/branch_dropdown.png differ
diff --git a/doc/devel/gitwash/configure_git.rst b/doc/devel/gitwash/configure_git.rst
index 70c6a5a37b63..3a172d5ba44d 100644
--- a/doc/devel/gitwash/configure_git.rst
+++ b/doc/devel/gitwash/configure_git.rst
@@ -1,3 +1,5 @@
+.. highlight:: bash
+
 .. _configure-git:
 
 ===============
@@ -9,9 +11,12 @@
 Overview
 ========
 
-Your personal git_ configurations are saved in the ``.gitconfig`` file in
+Your personal git configurations are saved in the ``.gitconfig`` file in
 your home directory.
-Here is an example ``.gitconfig`` file::
+
+Here is an example ``.gitconfig`` file:
+
+.. code-block:: none
 
   [user]
           name = Your Name
@@ -20,8 +25,8 @@ Here is an example ``.gitconfig`` file::
   [alias]
           ci = commit -a
           co = checkout
-          st = status -a
-          stat = status -a
+          st = status
+          stat = status
           br = branch
           wdiff = diff --color-words
 
@@ -31,13 +36,6 @@ Here is an example ``.gitconfig`` file::
   [merge]
           summary = true
 
-  [apply]
-          whitespace = fix
-
-  [core]
-          autocrlf = input
-
-
 You can edit this file directly or you can use the ``git config --global``
 command::
 
@@ -69,7 +67,9 @@ line::
   git config --global user.email you@yourdomain.example.com
 
 This will write the settings into your git configuration file,  which
-should now contain a user section with your name and email::
+should now contain a user section with your name and email:
+
+.. code-block:: none
 
   [user]
         name = Your Name
@@ -97,7 +97,9 @@ The following ``git config --global`` commands::
   git config --global alias.wdiff "diff --color-words"
 
 will create an ``alias`` section in your ``.gitconfig`` file with contents
-like this::
+like this:
+
+.. code-block:: none
 
   [alias]
           ci = commit -a
@@ -117,7 +119,9 @@ You may also want to make sure that your editor of choice is used ::
 Merging
 -------
 
-To enforce summaries when doing merges (``~/.gitconfig`` file again)::
+To enforce summaries when doing merges (``~/.gitconfig`` file again):
+
+.. code-block:: none
 
    [merge]
       log = true
@@ -126,5 +130,43 @@ Or from the command line::
 
   git config --global merge.log true
 
+.. _fancy-log:
+
+Fancy log output
+----------------
+
+This is a very nice alias to get a fancy log output; it should go in the
+``alias`` section of your ``.gitconfig`` file:
+
+.. code-block:: none
+
+    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)[%an]%Creset' --abbrev-commit --date=relative
+
+You use the alias with::
+
+    git lg
+
+and it gives graph / text output something like this (but with color!):
+
+.. code-block:: none
+
+    * 6d8e1ee - (HEAD, origin/my-fancy-feature, my-fancy-feature) NF - a fancy file (45 minutes ago) [Matthew Brett]
+    *   d304a73 - (origin/placeholder, placeholder) Merge pull request #48 from hhuuggoo/master (2 weeks ago) [Jonathan Terhorst]
+    |\  
+    | * 4aff2a8 - fixed bug 35, and added a test in test_bugfixes (2 weeks ago) [Hugo]
+    |/  
+    * a7ff2e5 - Added notes on discussion/proposal made during Data Array Summit. (2 weeks ago) [Corran Webster]
+    * 68f6752 - Initial implimentation of AxisIndexer - uses 'index_by' which needs to be changed to a call on an Axes object - this is all very sketchy right now. (2 weeks ago) [Corr
+    *   376adbd - Merge pull request #46 from terhorst/master (2 weeks ago) [Jonathan Terhorst]
+    |\  
+    | * b605216 - updated joshu example to current api (3 weeks ago) [Jonathan Terhorst]
+    | * 2e991e8 - add testing for outer ufunc (3 weeks ago) [Jonathan Terhorst]
+    | * 7beda5a - prevent axis from throwing an exception if testing equality with non-axis object (3 weeks ago) [Jonathan Terhorst]
+    | * 65af65e - convert unit testing code to assertions (3 weeks ago) [Jonathan Terhorst]
+    | *   956fbab - Merge remote-tracking branch 'upstream/master' (3 weeks ago) [Jonathan Terhorst]
+    | |\  
+    | |/
+
+Thanks to Yury V. Zaytsev for posting it.
 
 .. include:: links.inc
diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst
index 9251d4a413e3..6f499e5f358f 100644
--- a/doc/devel/gitwash/development_workflow.rst
+++ b/doc/devel/gitwash/development_workflow.rst
@@ -1,75 +1,104 @@
+.. highlight:: bash
+
 .. _development-workflow:
 
-=========================
-Git Development workflow
-=========================
+####################
+Development workflow
+####################
 
-You've discovered a bug or something else you want to change
-in matplotlib_ .. |emdash| excellent!
+You already have your own forked copy of the `Matplotlib`_ repository, by
+following :ref:`forking`. You have :ref:`set-up-fork`. You have configured
+git by following :ref:`configure-git`.  Now you are ready for some real work.
 
-You've worked out a way to fix it |emdash| even better!
+Workflow summary
+================
 
-You want to tell us about it |emdash| best of all!
+In what follows we'll refer to the upstream Matplotlib ``master`` branch, as
+"trunk".
 
-The easiest way to contribute to matplotlib_ is through github_.  If
-for some reason you don't want to use github, see
-:ref:`making-patches` for instructions on how to email patches to the
-mailing list.
+* Don't use your ``master`` branch for anything.  Consider deleting it.
+* When you are starting a new set of changes, fetch any changes from trunk,
+  and start a new *feature branch* from that.
+* Make a new branch for each separable set of changes |emdash| "one task, one
+  branch" (`ipython git workflow`_).
+* Name your branch for the purpose of the changes - e.g.
+  ``bugfix-for-issue-14`` or ``refactor-database-code``.
+* If you can possibly avoid it, avoid merging trunk or any other branches into
+  your feature branch while you are working.  
+* If you do find yourself merging from trunk, consider :ref:`rebase-on-trunk`
+* Ask on the `Matplotlib mailing list`_ if you get stuck.
+* Ask for code review!
 
-You already have your own forked copy of the matplotlib_ repository, by
-following :ref:`forking`, :ref:`set-up-fork`, and you have configured
-git_ by following :ref:`configure-git`.
+This way of working helps to keep work well organized, with readable history.
+This in turn makes it easier for project maintainers (that might be you) to see
+what you've done, and why you did it.
 
-Workflow summary
-================
+See `linux git workflow`_ and `ipython git workflow`_ for some explanation.
 
-* Keep your ``master`` branch clean of edits that have not been merged
-  to the main matplotlib_ development repo.  Your ``master`` then will follow
-  the main matplotlib_ repository.
-* Start a new *feature branch* for each set of edits that you do.
-* Do not merge the ``master`` branch or maintenance tracking branches
-  into your feature branch.  If you need to include commits from upstream
-  branches (either to pick up a bug fix or to resolve a conflict) please
-  *rebase* your branch on the upstream branch.
-* Ask for review!
+Consider deleting your master branch
+====================================
 
-This way of working really helps to keep work well organized, and in
-keeping history as clear as possible.
+It may sound strange, but deleting your own ``master`` branch can help reduce
+confusion about which branch you are on.  See `deleting master on github`_ for
+details.
 
-See |emdash| for example |emdash| `linux git workflow`_.
+.. _update-mirror-trunk:
 
-Making a new feature branch
-===========================
+Update the mirror of trunk
+==========================
 
-::
+First make sure you have done :ref:`linking-to-upstream`.
 
-   git checkout -b my-new-feature master
+From time to time you should fetch the upstream (trunk) changes from github::
 
-This will create and immediately check out a feature branch based on
-``master``.  To create a feature branch based on a maintenance branch,
-use::
+   git fetch upstream
+
+This will pull down any commits you don't have, and set the remote branches to
+point to the right commit.  For example, 'trunk' is the branch referred to by
+(remote/branchname) ``upstream/master`` - and if there have been commits since
+you last checked, ``upstream/master`` will change after you do the fetch.
+
+.. _make-feature-branch:
+
+Make a new feature branch
+=========================
+
+When you are ready to make some changes to the code, you should start a new
+branch.  Branches that are for a collection of related edits are often called
+'feature branches'.
 
-   git fetch origin
-   git checkout -b my-new-feature origin/v1.0.x
+Making an new branch for each set of related changes will make it easier for
+someone reviewing your branch to see what you are doing.
 
-Generally, you will want to keep this also on your public GitHub_ fork
-of matplotlib_.  To do this, you `git push`_ this new branch up to your GitHub_
-repo.  Generally (if you followed the instructions in these pages, and
-by default), git will have a link to your GitHub_ repo, called
-``origin``.  You push up to your own repo on GitHub_ with::
+Choose an informative name for the branch to remind yourself and the rest of us
+what the changes in the branch are for.  For example ``add-ability-to-fly``, or
+``buxfix-for-issue-42``.
+
+::
+
+    # Update the mirror of trunk
+    git fetch upstream
+    # Make new feature branch starting at current trunk
+    git branch my-new-feature upstream/master
+    git checkout my-new-feature
+
+Generally, you will want to keep your feature branches on your public github_
+fork of `Matplotlib`_.  To do this, you `git push`_ this new branch up to your
+github repo.  Generally (if you followed the instructions in these pages, and by
+default), git will have a link to your github repo, called ``origin``.  You push
+up to your own repo on github with::
 
    git push origin my-new-feature
 
-You will need to use this exact command, rather than simply ``git
-push`` every time you want to push changes on your feature branch to
-your GitHub_ repo.  However, in git >1.7 you can set up a link by
-using the ``--set-upstream`` option::
+In git >= 1.7 you can ensure that the link is correctly set by using the
+``--set-upstream`` option::
 
    git push --set-upstream origin my-new-feature
 
-and then next time you need to push changes to your branch a simple
-``git push`` will suffice. Note that ``git push`` pushes out all
-branches that are linked to a remote branch.
+From now on git will know that ``my-new-feature`` is related to the
+``my-new-feature`` branch in the github repo.
+
+.. _edit-flow:
 
 The editing workflow
 ====================
@@ -89,19 +118,21 @@ In more detail
 
 #. Make some changes
 #. See which files have changed with ``git status`` (see `git status`_).
-   You'll see a listing like this one::
+   You'll see a listing like this one:
+
+   .. code-block:: none
 
      # On branch ny-new-feature
      # Changed but not updated:
      #   (use "git add <file>..." to update what will be committed)
      #   (use "git checkout -- <file>..." to discard changes in working directory)
      #
-     #  modified:   README
+     #	modified:   README
      #
      # Untracked files:
      #   (use "git add <file>..." to include in what will be committed)
      #
-     #  INSTALL
+     #	INSTALL
      no changes added to commit (use "git add" and/or "git commit -a")
 
 #. Check what the actual changes are with ``git diff`` (`git diff`_).
@@ -114,305 +145,279 @@ In more detail
    faith |emdash| or see `why the -a flag?`_ |emdash| and the helpful use-case
    description in the `tangled working copy problem`_. The `git commit`_ manual
    page might also be useful.
-#. To push the changes up to your forked repo on GitHub_, do a ``git
-   push`` (see `git push`).
+#. To push the changes up to your forked repo on github, do a ``git
+   push`` (see `git push`_).
 
-Asking for code review |emdash| open a Pull Request (PR)
-========================================================
+Ask for your changes to be reviewed or merged
+=============================================
 
-It's a good idea to consult the :ref:`pull-request-checklist` to make
-sure your pull request is ready for merging.
+When you are ready to ask for someone to review your code and consider a merge:
 
-
-#. Go to your repo URL |emdash| e.g.,
+#. Go to the URL of your forked repo, say
    ``https://github.com/your-user-name/matplotlib``.
+#. Use the 'Switch Branches' dropdown menu near the top left of the page to
+   select the branch with your changes:
 
-#. Select your feature branch from the drop down menu:
-
-#. Click on the green button:
-
-#. Make sure that you are requesting a pull against the correct branch
-
-#. Enter a PR heading and description (if there is only one commit in
-   the PR github will automatically fill these fields for you).  If
-   this PR is addressing a specific issue, please reference it by number
-   (ex #1325) which github will automatically make into links.
+   .. image:: branch_dropdown.png
 
-#. Click 'Create Pull Request' button!
+#. Click on the 'Pull request' button:
 
-#. Discussion of the change will take place in the pull request
-   thread.
+   .. image:: pull_button.png
 
+   Enter a title for the set of changes, and some explanation of what you've
+   done.  Say if there is anything you'd like particular attention for - like a
+   complicated change or some code you are not happy with.
 
-Rebasing a Pull Request (PR)
-============================
+   If you don't think your request is ready to be merged, just say so in your
+   pull request message.  This is still a good way of getting some preliminary
+   code review.
 
-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 do 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.
+Some other things you might want to do
+======================================
 
-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
-<https://git-scm.com/book/en/Git-Branching-Rebasing>`_.  The NumPy team has also
-`documented how to do this
-<https://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.
+Delete a branch on github
+-------------------------
 
-The following example assumes that the remote of _your_ GitHub
-repository is called `origin` 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::
+   git checkout master
+   # delete branch locally
+   git branch -D my-unwanted-branch
+   # delete branch on github
+   git push origin :my-unwanted-branch
 
-     $ git fetch matplotlib
+Note the colon ``:`` before ``my-unwanted-branch``.  See also:
+https://help.github.com/articles/pushing-to-a-remote/#deleting-a-remote-branch-or-tag
 
-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::
+Several people sharing a single repository
+------------------------------------------
 
-     $ git checkout backend_plt_refactor
+If you want to work on some stuff with other people, where you are all
+committing into the same repository, or even the same branch, then just
+share it via github.
 
-You are now ready to start the rebase of your branch onto the target
-parent branch, in this case `matplotlib/master` ::
+First fork Matplotlib into your account, as from :ref:`forking`.
 
-     $ git rebase matplotlib/master
+Then, go to your forked repository github page, say
+``https://github.com/your-user-name/matplotlib``
 
-and git will then give a bunch of feed back::
+Click on the 'Admin' button, and add anyone else to the repo as a
+collaborator:
 
-     First, rewinding head to replay your work on top of it...
-     Applying: first steps to extract FigureManager* and friends from pyplot
-     Applying: split backend_qt4 into two parts, with and without Gcf
-     ...
-     Applying: pep8 clean up on backend_gtk3.py
-     Using index info to reconstruct a base tree...
-     M       lib/matplotlib/backends/backend_gtk3.py
-     Falling back to patching base and 3-way merge...
-     Auto-merging lib/matplotlib/backends/backend_gtk3.py
-     CONFLICT (content): Merge conflict in lib/matplotlib/backends/backend_gtk3.py
-     Failed to merge in the changes.
-     Patch failed at 0013 pep8 clean up on backend_gtk3.py
-     The copy of the patch that failed is found in:
-        /home/tcaswell/other_source/matplotlib/.git/rebase-apply/patch
+   .. image:: pull_button.png
 
-     When you have resolved this problem, run "git rebase --continue".
-     If you prefer to skip this patch, run "git rebase --skip" instead.
-     To check out the original branch and stop rebasing, run "git rebase --abort".
+Now all those people can do::
 
-We see that a number of commits could be cleanly applied to the tip of
-`matplotlib/master`.  However, git may eventually hit a commit that
-had conflicts: in the example above, this happens in the file
-`lib/matplotlib/backends/backend_gtk3.py`).  For more verbose
-information run ::
+    git clone git@githhub.com:your-user-name/matplotlib.git
 
-     $ git status
+Remember that links starting with ``git@`` use the ssh protocol and are
+read-write; links starting with ``git://`` are read-only.
 
-     You are currently rebasing branch 'backend_plt_refactor' on 'e6f8993'.
-       (fix conflicts and then run "git rebase --continue")
-       (use "git rebase --skip" to skip this patch)
-       (use "git rebase --abort" to check out the original branch)
+Your collaborators can then commit directly into that repo with the
+usual::
 
-     Unmerged paths:
-       (use "git reset HEAD <file>..." to unstage)
-       (use "git add <file>..." to mark resolution)
+     git commit -am 'ENH - much better code'
+     git push origin master # pushes directly into your repo
 
-             both modified:      lib/matplotlib/backends/backend_gtk3.py
+Explore your repository
+-----------------------
 
-     no changes added to commit (use "git add" and/or "git commit -a")
+To see a graphical representation of the repository branches and
+commits::
 
-This tells you exactly where the conflict (caused by the target branch
-and your commits modifying the same lines of code) is and provides
-some advice on how to proceed.  Opening up the file in question, you
-will see blocks that look something like this::
+   gitk --all
 
-     <<<<<<< HEAD
-     =======
-             self.__dict__.clear()   # Is this needed? Other backends don't have it.
-     >>>>>>> pep8 clean up on backend_gtk3.py
+To see a linear list of commits for this branch::
 
-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 in the commit you are trying to rebase.  The
-rest of the code is either the same or the diff can be unambiguously
-applied.  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::
+   git log
 
-     $ git add lib/matplotlib/backends/backend_gtk3.py
+You can also look at the `network graph visualizer`_ for your github
+repo.
 
-Repeat this for all of the files that have conflicts.  When you are done with
-that you can check the status::
+Finally the :ref:`fancy-log` ``lg`` alias will give you a reasonable text-based
+graph of the repository.
 
-     $ git status
-     rebase in progress; onto e6f8993
-     You are currently rebasing branch 'backend_plt_refactor' on 'e6f8993'.
-       (all conflicts fixed: run "git rebase --continue")
+.. _rebase-on-trunk:
 
-     Changes to be committed:
-       (use "git reset HEAD <file>..." to unstage)
+Rebasing on trunk
+-----------------
 
-             modified:   lib/matplotlib/backends/backend_gtk3.py
+Let's say you thought of some work you'd like to do. You
+:ref:`update-mirror-trunk` and :ref:`make-feature-branch` called
+``cool-feature``. At this stage trunk is at some commit, let's call it E. Now
+you make some new commits on your ``cool-feature`` branch, let's call them A, B,
+C.  Maybe your changes take a while, or you come back to them after a while.  In
+the meantime, trunk has progressed from commit E to commit (say) G:
 
-which shows us that we have resolved all of the conflicts with this
-commit and can continue::
+.. code-block:: none
 
-     $ git rebase --continue
+          A---B---C cool-feature
+         /
+    D---E---F---G trunk
 
-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.
+At this stage you consider merging trunk into your feature branch, and you
+remember that this here page sternly advises you not to do that, because the
+history will get messy. Most of the time you can just ask for a review, and not
+worry that trunk has got a little ahead.  But sometimes, the changes in trunk
+might affect your changes, and you need to harmonize them.  In this situation
+you may prefer to do a rebase.
 
-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::
+rebase takes your changes (A, B, C) and replays them as if they had been made to
+the current state of ``trunk``.  In other words, in this case, it takes the
+changes represented by A, B, C and replays them on top of G. After the rebase,
+your history will look like this:
 
-    $ git push --force origin
+.. code-block:: none
 
-which will _replace_ all of the commits under your branch on GitHub
-with the new versions of the commit.
+                  A'--B'--C' cool-feature
+                 /
+    D---E---F---G trunk
 
-Congratulations, you have rebased your branch!
+See `rebase without tears`_ for more detail.
 
-Staying up to date with changes in the central repository
-=========================================================
+To do a rebase on trunk::
 
-This updates your working copy from the upstream `matplotlib GitHub`_
-repo.
+    # Update the mirror of trunk
+    git fetch upstream
+    # go to the feature branch
+    git checkout cool-feature
+    # make a backup in case you mess up
+    git branch tmp cool-feature
+    # rebase cool-feature onto trunk
+    git rebase --onto upstream/master upstream/master cool-feature
 
-Overview
---------
+In this situation, where you are already on branch ``cool-feature``, the last
+command can be written more succinctly as::
 
-::
+    git rebase upstream/master
 
-   # go to your master branch
-   git checkout master
-   # pull changes from github
-   git fetch matplotlib
-   # merge from matplotlib
-   git merge --ff-only matplotlib/master
+When all looks good you can delete your backup branch::
 
-In detail
----------
+   git branch -D tmp
 
-We suggest that you do this only for your ``master`` branch, and leave
-your 'feature' branches unmerged, to keep their history as clean as
-possible.  This makes code review easier::
+If it doesn't look good you may need to have a look at
+:ref:`recovering-from-mess-up`.
 
-   git checkout master
+If you have made changes to files that have also changed in trunk, this may
+generate merge conflicts that you need to resolve - see the `git rebase`_ man
+page for some instructions at the end of the "Description" section. There is
+some related help on merging in the git user manual - see `resolving a merge`_.
 
-Make sure you have done :ref:`linking-to-upstream`.
+.. _recovering-from-mess-up:
 
-Merge the upstream code into your current development by first pulling
-the upstream repo to a copy on your local machine::
+Recovering from mess-ups
+------------------------
 
-   git fetch upstream
+Sometimes, you mess up merges or rebases. Luckily, in git it is
+relatively straightforward to recover from such mistakes.
 
-then merging into your current branch::
+If you mess up during a rebase::
 
-   git merge --ff-only upstream/master
+   git rebase --abort
 
-The ``--ff-only`` option guarantees that if you have mistakenly
-committed code on your ``master`` branch, the merge fails at this point.
-If you were to merge ``upstream/master`` to your ``master``, you
-would start to diverge from the upstream. If this command fails, see
-the section on accidents_.
+If you notice you messed up after the rebase::
 
-The letters 'ff' in ``--ff-only`` mean 'fast forward', which is a
-special case of merge where git can simply update your branch to point
-to the other branch and not do any actual merging of files. For
-``master`` and other integration branches this is exactly what you
-want.
+   # reset branch back to the saved point
+   git reset --hard tmp
 
-Other integration branches
---------------------------
+If you forgot to make a backup branch::
 
-Some people like to keep separate local branches corresponding to the
-maintenance branches on GitHub. At the time of this writing, ``v1.0.x``
-is the active maintenance branch. If you have such a local branch,
-treat is just as ``master``: don't commit on it, and before starting
-new branches off of it, update it from upstream::
+   # look at the reflog of the branch
+   git reflog show cool-feature
 
-   git checkout v1.0.x
-   git fetch upstream
-   git merge --ff-only upstream/v1.0.x
+   8630830 cool-feature@{0}: commit: BUG: io: close file handles immediately
+   278dd2a cool-feature@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d
+   26aa21a cool-feature@{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj
+   ...
 
-But you don't necessarily have to have such a branch. Instead, if you
-are preparing a bugfix that applies to the maintenance branch, fetch
-from upstream and base your bugfix on the remote branch::
+   # reset the branch to where it was before the botched rebase
+   git reset --hard cool-feature@{2}
 
-   git fetch upstream
-   git checkout -b my-bug-fix upstream/v1.0.x
+.. _rewriting-commit-history:
 
-.. _accidents:
+Rewriting commit history
+------------------------
 
-Recovering from accidental commits on master
---------------------------------------------
+.. note::
 
-If you have accidentally committed changes on ``master`` and
-``git merge --ff-only`` fails, don't panic! First find out how much
-you have diverged::
+   Do this only for your own feature branches.
 
-   git diff upstream/master...master
+There's an embarrassing typo in a commit you made? Or perhaps the you
+made several false starts you would like the posterity not to see.
 
-If you find that you want simply to get rid of the changes, reset
-your ``master`` branch to the upstream version::
+This can be done via *interactive rebasing*.
 
-   git reset --hard upstream/master
+Suppose that the commit history looks like this::
 
-As you might surmise from the words 'reset' and 'hard', this command
-actually causes your changes to the current branch to be lost, so
-think twice.
+    git log --oneline
+    eadc391 Fix some remaining bugs
+    a815645 Modify it so that it works
+    2dec1ac Fix a few bugs + disable
+    13d7934 First implementation
+    6ad92e5 * masked is now an instance of a new object, MaskedConstant
+    29001ed Add pre-nep for a copule of structured_array_extensions.
+    ...
 
-If, on the other hand, you find that you want to preserve the changes,
-create a feature branch for them::
+and ``6ad92e5`` is the last commit in the ``cool-feature`` branch. Suppose we
+want to make the following changes:
 
-   git checkout -b my-important-changes
+* Rewrite the commit message for ``13d7934`` to something more sensible.
+* Combine the commits ``2dec1ac``, ``a815645``, ``eadc391`` into a single one.
 
-Now ``my-important-changes`` points to the branch that has your
-changes, and you can safely reset ``master`` as above |emdash| but
-make sure to reset the correct branch::
+We do as follows::
 
-   git checkout master
-   git reset --hard upstream/master
+    # make a backup of the current state
+    git branch tmp HEAD
+    # interactive rebase
+    git rebase -i 6ad92e5
 
+This will open an editor with the following text in it::
 
-Deleting a branch on GitHub_
-============================
+    pick 13d7934 First implementation
+    pick 2dec1ac Fix a few bugs + disable
+    pick a815645 Modify it so that it works
+    pick eadc391 Fix some remaining bugs
 
-::
+    # Rebase 6ad92e5..eadc391 onto 6ad92e5
+    #
+    # Commands:
+    #  p, pick = use commit
+    #  r, reword = use commit, but edit the commit message
+    #  e, edit = use commit, but stop for amending
+    #  s, squash = use commit, but meld into previous commit
+    #  f, fixup = like "squash", but discard this commit's log message
+    #
+    # If you remove a line here THAT COMMIT WILL BE LOST.
+    # However, if you remove everything, the rebase will be aborted.
+    #
 
-   git checkout master
-   # delete branch locally
-   git branch -D my-unwanted-branch
-   # delete branch on GitHub
-   git push origin :my-unwanted-branch
+To achieve what we want, we will make the following changes to it::
 
-Note the colon ``:`` before ``my-unwanted-branch``.  See also:
-https://help.github.com/articles/pushing-to-a-remote/#deleting-a-remote-branch-or-tag
+    r 13d7934 First implementation
+    pick 2dec1ac Fix a few bugs + disable
+    f a815645 Modify it so that it works
+    f eadc391 Fix some remaining bugs
 
-Exploring your repository
-=========================
+This means that (i) we want to edit the commit message for
+``13d7934``, and (ii) collapse the last three commits into one. Now we
+save and quit the editor.
 
-To see a graphical representation of the repository branches and
-commits::
+Git will then immediately bring up an editor for editing the commit
+message. After revising it, we get the output::
 
-   gitk --all
+    [detached HEAD 721fc64] FOO: First implementation
+     2 files changed, 199 insertions(+), 66 deletions(-)
+    [detached HEAD 0f22701] Fix a few bugs + disable
+     1 files changed, 79 insertions(+), 61 deletions(-)
+    Successfully rebased and updated refs/heads/my-feature-branch.
 
-To see a linear list of commits for this branch::
+and the history looks now like this::
 
-   git log
+     0f22701 Fix a few bugs + disable
+     721fc64 ENH: Sophisticated feature
+     6ad92e5 * masked is now an instance of a new object, MaskedConstant
 
-You can also look at the `network graph visualizer`_ for your GitHub_
-repo.
+If it went wrong, recovery is again possible as explained :ref:`above
+<recovering-from-mess-up>`.
 
 .. include:: links.inc
diff --git a/doc/devel/gitwash/following_latest.rst b/doc/devel/gitwash/following_latest.rst
index 4419abd82d69..03518ea52f44 100644
--- a/doc/devel/gitwash/following_latest.rst
+++ b/doc/devel/gitwash/following_latest.rst
@@ -1,3 +1,5 @@
+.. highlight:: bash
+
 .. _following-latest:
 
 =============================
@@ -5,12 +7,12 @@
 =============================
 
 These are the instructions if you just want to follow the latest
-*matplotlib* source, but you don't need to do any development for now.
+*Matplotlib* source, but you don't need to do any development for now.
 
 The steps are:
 
 * :ref:`install-git`
-* get local copy of the git repository from github_
+* get local copy of the `Matplotlib github`_ git repository
 * update local copy from time to time
 
 Get the local copy of the code
diff --git a/doc/devel/gitwash/forking_hell.rst b/doc/devel/gitwash/forking_hell.rst
index 50dda65f1642..b79e13400a62 100644
--- a/doc/devel/gitwash/forking_hell.rst
+++ b/doc/devel/gitwash/forking_hell.rst
@@ -1,32 +1,34 @@
+.. highlight:: bash
+
 .. _forking:
 
-==========================================
-Making your own copy (fork) of matplotlib
-==========================================
+======================================================
+Making your own copy (fork) of Matplotlib
+======================================================
 
 You need to do this only once.  The instructions here are very similar
 to the instructions at https://help.github.com/forking/ |emdash| please see
 that page for more detail.  We're repeating some of it here just to give the
-specifics for the matplotlib_ project, and to suggest some default names.
+specifics for the `Matplotlib`_ project, and to suggest some default names.
 
-Set up and configure a github_ account
-======================================
+Set up and configure a github account
+=====================================
 
-If you don't have a github_ account, go to the github_ page, and make one.
+If you don't have a github account, go to the github page, and make one.
 
 You then need to configure your account to allow write access |emdash| see
 the ``Generating SSH keys`` help on `github help`_.
 
-Create your own forked copy of matplotlib_
-===========================================
+Create your own forked copy of `Matplotlib`_
+======================================================
 
-#. Log into your github_ account.
-#. Go to the matplotlib_ github home at `matplotlib github`_.
+#. Log into your github account.
+#. Go to the `Matplotlib`_ github home at `Matplotlib github`_.
 #. Click on the *fork* button:
 
    .. image:: forking_button.png
 
-   Now, after a short pause you should find yourself at the home page
-   for your own forked copy of matplotlib_.
+   Now, after a short pause, you should find yourself at the home page for
+   your own forked copy of `Matplotlib`_.
 
 .. include:: links.inc
diff --git a/doc/devel/gitwash/git_development.rst b/doc/devel/gitwash/git_development.rst
new file mode 100644
index 000000000000..c5b910d86342
--- /dev/null
+++ b/doc/devel/gitwash/git_development.rst
@@ -0,0 +1,16 @@
+.. _git-development:
+
+=====================
+ Git for development
+=====================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   forking_hell
+   set_up_fork
+   configure_git
+   development_workflow
+   maintainer_workflow
diff --git a/doc/devel/gitwash/git_install.rst b/doc/devel/gitwash/git_install.rst
index 06f64c35c261..66eca8c29bde 100644
--- a/doc/devel/gitwash/git_install.rst
+++ b/doc/devel/gitwash/git_install.rst
@@ -1,3 +1,5 @@
+.. highlight:: bash
+
 .. _install-git:
 
 =============
@@ -8,8 +10,8 @@ Overview
 ========
 
 ================ =============
-Debian / Ubuntu  ``sudo apt-get install git-core``
-Fedora           ``sudo yum install git-core``
+Debian / Ubuntu  ``sudo apt-get install git``
+Fedora           ``sudo yum install git``
 Windows          Download and install msysGit_
 OS X             Use the git-osx-installer_
 ================ =============
@@ -17,9 +19,9 @@ OS X             Use the git-osx-installer_
 In detail
 =========
 
-See the git_ page for the most recent information.
+See the git page for the most recent information.
 
-Have a look at the github_ install help pages available from `github help`_
+Have a look at the github install help pages available from `github help`_
 
 There are good instructions here: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
 
diff --git a/doc/devel/gitwash/git_intro.rst b/doc/devel/gitwash/git_intro.rst
index 786eb84d5bd3..1f89b7e9fb51 100644
--- a/doc/devel/gitwash/git_intro.rst
+++ b/doc/devel/gitwash/git_intro.rst
@@ -1,18 +1,20 @@
+.. highlight:: bash
+
 ==============
  Introduction
 ==============
 
-These pages describe a git_ and github_ workflow for the matplotlib_
+These pages describe a git_ and github_ workflow for the `Matplotlib`_
 project.
 
 There are several different workflows here, for different ways of
-working with *matplotlib*.
+working with *Matplotlib*.
 
-This is not a comprehensive git_ reference, it's just a workflow for our
-own project.  It's tailored to the github_ hosting service. You may well
-find better or quicker ways of getting stuff done with git_, but these
+This is not a comprehensive git reference, it's just a workflow for our
+own project.  It's tailored to the github hosting service. You may well
+find better or quicker ways of getting stuff done with git, but these
 should get you started.
 
-For general resources for learning git_ see :ref:`git-resources`.
+For general resources for learning git, see :ref:`git-resources`.
 
 .. include:: links.inc
diff --git a/doc/devel/gitwash/git_links.inc b/doc/devel/gitwash/git_links.inc
index ee2dd9268796..d01ad7833c30 100644
--- a/doc/devel/gitwash/git_links.inc
+++ b/doc/devel/gitwash/git_links.inc
@@ -12,42 +12,48 @@
 .. _git: https://git-scm.com/
 .. _github: https://github.com
 .. _github help: https://help.github.com
-.. _msysgit: http://code.google.com/p/msysgit/downloads/list
-.. _git-osx-installer: https://code.google.com/archive/p/git-osx-installer/downloads
+.. _msysgit: https://git-scm.com/download/win
+.. _git-osx-installer: https://git-scm.com/download/mac
 .. _subversion: http://subversion.tigris.org/
-.. _git cheat sheet: http://cheat.errtheblog.com/s/git
-.. _pro git book: https://git-scm.com/book/en/v2
+.. _git cheat sheet: https://help.github.com/git-cheat-sheets/
+.. _pro git book: https://progit.org/
 .. _git svn crash course: https://git-scm.com/course/svn.html
-.. _learn.github: http://learn.github.com/
 .. _network graph visualizer: https://github.com/blog/39-say-hello-to-the-network-graph-visualizer
-.. _git user manual: https://schacon.github.com/git/user-manual.html
-.. _git tutorial: https://schacon.github.com/git/gittutorial.html
+.. _git user manual: https://schacon.github.io/git/user-manual.html
+.. _git tutorial: https://schacon.github.io/git/gittutorial.html
 .. _git community book: https://git-scm.com/book/en/v2
-.. _git ready: http://www.gitready.com/
-.. _git casts: http://www.gitcasts.com/
+.. _git ready: http://gitready.com/
 .. _Fernando's git page: http://www.fperez.org/py4science/git.html
 .. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html
 .. _git concepts: https://www.sbf5.com/~cduan/technical/git/
-.. _git clone: http://schacon.github.io/git/git-clone.html
-.. _git checkout: http://schacon.github.io/git/git-checkout.html
-.. _git commit: http://schacon.github.io/git/git-commit.html
-.. _git push: http://schacon.github.io/git/git-push.html
-.. _git pull: http://schacon.github.io/git/git-pull.html
-.. _git add: http://schacon.github.io/git/git-add.html
-.. _git status: http://schacon.github.io/git/git-status.html
-.. _git diff: http://schacon.github.io/git/git-diff.html
-.. _git log: http://schacon.github.io/git/git-log.html
-.. _git branch: http://schacon.github.io/git/git-branch.html
-.. _git remote: http://schacon.github.io/git/git-remote.html
-.. _git config: http://schacon.github.io/git/git-config.html
+.. _git clone: https://schacon.github.io/git/git-clone.html
+.. _git checkout: https://schacon.github.io/git/git-checkout.html
+.. _git commit: https://schacon.github.io/git/git-commit.html
+.. _git push: https://schacon.github.io/git/git-push.html
+.. _git pull: https://schacon.github.io/git/git-pull.html
+.. _git add: https://schacon.github.io/git/git-add.html
+.. _git status: https://schacon.github.io/git/git-status.html
+.. _git diff: https://schacon.github.io/git/git-diff.html
+.. _git log: https://schacon.github.io/git/git-log.html
+.. _git branch: https://schacon.github.io/git/git-branch.html
+.. _git remote: https://schacon.github.io/git/git-remote.html
+.. _git rebase: https://schacon.github.io/git/git-rebase.html
+.. _git config: https://schacon.github.io/git/git-config.html
 .. _why the -a flag?: http://gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _git staging area: http://gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _tangled working copy problem: http://2ndscale.com/rtomayko/2008/the-thing-about-git
-.. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html
+.. _git management: https://web.archive.org/web/20090224195437/http://kerneltrap.org/Linux/Git_Management
+.. _linux git workflow: https://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html
 .. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html
-.. _git foundation: http://matthew-brett.github.io/pydagogue/foundation.html
+.. _git foundation: https://matthew-brett.github.io/pydagogue/foundation.html
+.. _deleting master on github: https://matthew-brett.github.io/pydagogue/gh_delete_master.html
+.. _rebase without tears: https://matthew-brett.github.io/pydagogue/rebase_without_tears.html
+.. _resolving a merge: https://schacon.github.io/git/user-manual.html#resolving-a-merge
+.. _ipython git workflow: https://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html
 
 .. other stuff
-.. _python: http://www.python.org
+.. _python: https://www.python.org
 
 .. |emdash| unicode:: U+02014
+
+.. vim: ft=rst
diff --git a/doc/devel/gitwash/git_resources.rst b/doc/devel/gitwash/git_resources.rst
index dc63aef2bb97..2787a575cc43 100644
--- a/doc/devel/gitwash/git_resources.rst
+++ b/doc/devel/gitwash/git_resources.rst
@@ -1,35 +1,36 @@
+.. highlight:: bash
+
 .. _git-resources:
 
-================
- git_ resources
-================
+=============
+git resources
+=============
 
 Tutorials and summaries
 =======================
 
 * `github help`_ has an excellent series of how-to guides.
-* `learn.github`_ has an excellent series of tutorials
 * The `pro git book`_ is a good in-depth book on git.
 * A `git cheat sheet`_ is a page giving summaries of common commands.
 * The `git user manual`_
 * The `git tutorial`_
 * The `git community book`_
 * `git ready`_ |emdash| a nice series of tutorials
-* `git casts`_ |emdash| video snippets giving git how-tos.
 * `git magic`_ |emdash| extended introduction with intermediate detail
 * The `git parable`_ is an easy read explaining the concepts behind git.
-* Our own `git foundation`_ expands on the `git parable`_.
+* `git foundation`_ expands on the `git parable`_.
 * Fernando Perez' git page |emdash| `Fernando's git page`_ |emdash| many
   links and tips
 * A good but technical page on `git concepts`_
-* `git svn crash course`_: git_ for those of us used to subversion_
+* `git svn crash course`_: git for those of us used to subversion_
 
 Advanced git workflow
 =====================
 
-There are many ways of working with git_; here are some posts on the
+There are many ways of working with git; here are some posts on the
 rules of thumb that other projects have come up with:
 
+* Linus Torvalds on `git management`_
 * Linus Torvalds on `linux git workflow`_ .  Summary; use the git tools
   to make the history of your edits as clean as possible; merge from
   upstream edits as little as possible in branches where you are doing
diff --git a/doc/devel/gitwash/index.rst b/doc/devel/gitwash/index.rst
index 53d884e711be..9ee965d626ff 100644
--- a/doc/devel/gitwash/index.rst
+++ b/doc/devel/gitwash/index.rst
@@ -1,7 +1,7 @@
 .. _using-git:
 
-Working with *matplotlib* source code
-======================================
+Working with *Matplotlib* source code
+================================================
 
 Contents:
 
@@ -11,6 +11,9 @@ Contents:
    git_intro
    git_install
    following_latest
-   setting_up_for_development
-   git_resources
    patching
+   git_development
+   git_resources
+   dot2_dot3
+
+
diff --git a/doc/devel/gitwash/known_projects.inc b/doc/devel/gitwash/known_projects.inc
index 05a961d85198..710abe08e477 100644
--- a/doc/devel/gitwash/known_projects.inc
+++ b/doc/devel/gitwash/known_projects.inc
@@ -1,39 +1,39 @@
 .. Known projects
 
 .. PROJECTNAME placeholders
-.. _PROJECTNAME: http://neuroimaging.scipy.org
+.. _PROJECTNAME: http://nipy.org
 .. _`PROJECTNAME github`: https://github.com/nipy
-.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
+.. _`PROJECTNAME mailing list`: https://mail.python.org/mailman/listinfo/neuroimaging
 
 .. numpy
-.. _numpy: hhttp://numpy.scipy.org
+.. _numpy: http://www.numpy.org
 .. _`numpy github`: https://github.com/numpy/numpy
-.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion
+.. _`numpy mailing list`: https://mail.scipy.org/mailman/listinfo/numpy-discussion
 
 .. scipy
-.. _scipy: http://www.scipy.org
+.. _scipy: https://www.scipy.org
 .. _`scipy github`: https://github.com/scipy/scipy
-.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev
+.. _`scipy mailing list`: https://mail.scipy.org/mailman/listinfo/scipy-dev
 
 .. nipy
-.. _nipy: http://nipy.org/nipy
+.. _nipy: http://nipy.org/nipy/
 .. _`nipy github`: https://github.com/nipy/nipy
-.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+.. _`nipy mailing list`: https://mail.python.org/mailman/listinfo/neuroimaging
 
 .. ipython
-.. _ipython: http://ipython.org
+.. _ipython: https://ipython.org
 .. _`ipython github`: https://github.com/ipython/ipython
-.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
+.. _`ipython mailing list`: https://mail.scipy.org/mailman/listinfo/IPython-dev
 
 .. dipy
-.. _dipy: http://nipy.org/dipy
+.. _dipy: http://nipy.org/dipy/
 .. _`dipy github`: https://github.com/Garyfallidis/dipy
-.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+.. _`dipy mailing list`: https://mail.python.org/mailman/listinfo/neuroimaging
 
 .. nibabel
-.. _nibabel: http://nipy.org/nibabel
+.. _nibabel: http://nipy.org/nibabel/
 .. _`nibabel github`: https://github.com/nipy/nibabel
-.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+.. _`nibabel mailing list`: https://mail.python.org/mailman/listinfo/neuroimaging
 
 .. marsbar
 .. _marsbar: http://marsbar.sourceforge.net
diff --git a/doc/devel/gitwash/maintainer_workflow.rst b/doc/devel/gitwash/maintainer_workflow.rst
new file mode 100644
index 000000000000..302f75241399
--- /dev/null
+++ b/doc/devel/gitwash/maintainer_workflow.rst
@@ -0,0 +1,98 @@
+.. highlight:: bash
+
+.. _maintainer-workflow:
+
+###################
+Maintainer workflow
+###################
+
+This page is for maintainers |emdash| those of us who merge our own or other
+peoples' changes into the upstream repository.
+
+Being as how you're a maintainer, you are completely on top of the basic stuff
+in :ref:`development-workflow`.
+
+The instructions in :ref:`linking-to-upstream` add a remote that has read-only
+access to the upstream repo.  Being a maintainer, you've got read-write access.
+
+It's good to have your upstream remote have a scary name, to remind you that
+it's a read-write remote::
+
+    git remote add upstream-rw git@github.com:matplotlib/matplotlib.git
+    git fetch upstream-rw
+
+*******************
+Integrating changes
+*******************
+
+Let's say you have some changes that need to go into trunk
+(``upstream-rw/master``).
+
+The changes are in some branch that you are currently on.  For example, you are
+looking at someone's changes like this::
+
+    git remote add someone git://github.com/someone/matplotlib.git
+    git fetch someone
+    git branch cool-feature --track someone/cool-feature
+    git checkout cool-feature
+
+So now you are on the branch with the changes to be incorporated upstream.  The
+rest of this section assumes you are on this branch.
+
+A few commits
+=============
+
+If there are only a few commits, consider rebasing to upstream::
+
+    # Fetch upstream changes
+    git fetch upstream-rw
+    # rebase
+    git rebase upstream-rw/master
+
+Remember that, if you do a rebase, and push that, you'll have to close any
+github pull requests manually, because github will not be able to detect the
+changes have already been merged.
+
+A long series of commits
+========================
+
+If there are a longer series of related commits, consider a merge instead::
+
+    git fetch upstream-rw
+    git merge --no-ff upstream-rw/master
+
+The merge will be detected by github, and should close any related pull requests
+automatically.
+
+Note the ``--no-ff`` above.  This forces git to make a merge commit, rather than
+doing a fast-forward, so that these set of commits branch off trunk then rejoin
+the main history with a merge, rather than appearing to have been made directly
+on top of trunk.
+
+Check the history
+=================
+
+Now, in either case, you should check that the history is sensible and you have
+the right commits::
+
+    git log --oneline --graph
+    git log -p upstream-rw/master..
+
+The first line above just shows the history in a compact way, with a text
+representation of the history graph. The second line shows the log of commits
+excluding those that can be reached from trunk (``upstream-rw/master``), and
+including those that can be reached from current HEAD (implied with the ``..``
+at the end). So, it shows the commits unique to this branch compared to trunk.
+The ``-p`` option shows the diff for these commits in patch form.
+
+Push to trunk
+=============
+
+::
+
+    git push upstream-rw my-new-feature:master
+
+This pushes the ``my-new-feature`` branch in this repository to the ``master``
+branch in the ``upstream-rw`` repository.
+
+.. include:: links.inc
diff --git a/doc/devel/gitwash/patching.rst b/doc/devel/gitwash/patching.rst
index fb42e1ef3af3..e7f852758477 100644
--- a/doc/devel/gitwash/patching.rst
+++ b/doc/devel/gitwash/patching.rst
@@ -1,7 +1,22 @@
+.. highlight:: bash
+
 ================
  Making a patch
 ================
 
+You've discovered a bug or something else you want to change
+in `Matplotlib`_ .. |emdash| excellent!
+
+You've worked out a way to fix it |emdash| even better!
+
+You want to tell us about it |emdash| best of all!
+
+The easiest way is to make a *patch* or set of patches.  Here
+we explain how.  Making a patch is the simplest and quickest,
+but if you're going to be doing anything more than simple
+quick things, please consider following the
+:ref:`git-development` model instead.
+
 .. _making-patches:
 
 Making patches
@@ -31,20 +46,20 @@ Overview
    # make the patch files
    git format-patch -M -C master
 
-Then, send the generated patch files to the `matplotlib
+Then, send the generated patch files to the `Matplotlib
 mailing list`_ |emdash| where we will thank you warmly.
 
 In detail
 ---------
 
-#. Tell git_ who you are so it can label the commits you've
+#. Tell git who you are so it can label the commits you've
    made::
 
       git config --global user.email you@yourdomain.example.com
       git config --global user.name "Your Name Comes Here"
 
 #. If you don't already have one, clone a copy of the
-   matplotlib_ repository::
+   `Matplotlib`_ repository::
 
       git clone git://github.com/matplotlib/matplotlib.git
       cd matplotlib
@@ -82,16 +97,42 @@ In detail
 
       git format-patch -M -C master
 
-   You will now have several files named for the commits::
+   You will now have several files named for the commits:
+
+   .. code-block:: none
 
       0001-BF-added-tests-for-Funny-bug.patch
       0002-BF-added-fix-for-Funny-bug.patch
 
-   Send these files to the `matplotlib mailing list`_.
+   Send these files to the `Matplotlib mailing list`_.
 
 When you are done, to switch back to the main copy of the
 code, just return to the ``master`` branch::
 
    git checkout master
 
+Moving from patching to development
+===================================
+
+If you find you have done some patches, and you have one or
+more feature branches, you will probably want to switch to
+development mode.  You can do this with the repository you
+have.
+
+Fork the `Matplotlib`_ repository on github |emdash| :ref:`forking`.
+Then::
+
+   # checkout and refresh master branch from main repo
+   git checkout master
+   git pull origin master
+   # rename pointer to main repository to 'upstream'
+   git remote rename origin upstream
+   # point your repo to default read / write to your fork on github
+   git remote add origin git@github.com:your-user-name/matplotlib.git
+   # push up any branches you've made and want to keep
+   git push origin the-fix-im-thinking-of
+
+Then you can, if you want, follow the
+:ref:`development-workflow`.
+
 .. include:: links.inc
diff --git a/doc/devel/gitwash/pull_button.png b/doc/devel/gitwash/pull_button.png
new file mode 100644
index 000000000000..e5031681b97b
Binary files /dev/null and b/doc/devel/gitwash/pull_button.png differ
diff --git a/doc/devel/gitwash/set_up_fork.rst b/doc/devel/gitwash/set_up_fork.rst
index efe269a783c4..01f6eb2812ff 100644
--- a/doc/devel/gitwash/set_up_fork.rst
+++ b/doc/devel/gitwash/set_up_fork.rst
@@ -1,3 +1,5 @@
+.. highlight:: bash
+
 .. _set-up-fork:
 
 ==================
@@ -25,7 +27,9 @@ Clone your fork
    git@github.com:your-user-name/matplotlib.git``
 #. Investigate.  Change directory to your new repo: ``cd matplotlib``. Then
    ``git branch -a`` to show you all branches.  You'll get something
-   like::
+   like:
+
+   .. code-block:: none
 
       * master
       remotes/origin/master
@@ -33,9 +37,9 @@ Clone your fork
    This tells you that you are currently on the ``master`` branch, and
    that you also have a ``remote`` connection to ``origin/master``.
    What remote repository is ``remote/origin``? Try ``git remote -v`` to
-   see the URLs for the remote.  They will point to your github_ fork.
+   see the URLs for the remote.  They will point to your github fork.
 
-   Now you want to connect to the upstream `matplotlib github`_ repository, so
+   Now you want to connect to the upstream `Matplotlib github`_ repository, so
    you can merge in changes from trunk.
 
 .. _linking-to-upstream:
@@ -49,41 +53,21 @@ Linking your repository to the upstream repo
    git remote add upstream git://github.com/matplotlib/matplotlib.git
 
 ``upstream`` here is just the arbitrary name we're using to refer to the
-main matplotlib_ repository at `matplotlib github`_.
+main `Matplotlib`_ repository at `Matplotlib github`_.
 
 Note that we've used ``git://`` for the URL rather than ``git@``.  The
-``git://`` URL is read only.  This means that we can't accidentally
+``git://`` URL is read only.  This means we that we can't accidentally
 (or deliberately) write to the upstream repo, and we are only going to
 use it to merge into our own code.
 
-Note this command needs to be run on every clone of the repository
-that you make.  It is not tracked in your personal repository on
-github_.
-
 Just for your own satisfaction, show yourself that you now have a new
-'remote', with ``git remote -v``, giving you something like::
-
-   upstream     git://github.com/matplotlib/matplotlib.git (fetch)
-   upstream     git://github.com/matplotlib/matplotlib.git (push)
-   origin       git@github.com:your-user-name/matplotlib.git (fetch)
-   origin       git@github.com:your-user-name/matplotlib.git (push)
-
-
-Read-only remote / push access to ``matplotlib/matplotlib``
------------------------------------------------------------
-
-If you have commit rights to ``matplotlib/matplotlib`` the ``git://``
-protocol URL will still be read-only (due to it not supporting
-authentication and restrictions on github's side).  To reduce the
-chance of accidentally pushing to upstream, we suggest setting up a
-read-only remote of upstream as above and a read/write remote as ::
-
-   git remote add DANGER git@github.com:matplotlib/matplotlib.git
-
-or ::
-
-  git remote add HOLY_COMMIT_RIGHTS_BATMAN https://github.com/matplotlib/matplotlib.git
+'remote', with ``git remote -v show``, giving you something like:
 
+.. code-block:: none
 
+   upstream	git://github.com/matplotlib/matplotlib.git (fetch)
+   upstream	git://github.com/matplotlib/matplotlib.git (push)
+   origin	git@github.com:your-user-name/matplotlib.git (fetch)
+   origin	git@github.com:your-user-name/matplotlib.git (push)
 
 .. include:: links.inc
diff --git a/doc/devel/gitwash/setting_up_for_development.rst b/doc/devel/gitwash/setting_up_for_development.rst
deleted file mode 100644
index d49122db6dab..000000000000
--- a/doc/devel/gitwash/setting_up_for_development.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. _setting_up_for_development:
-
-==========================
-Setting up for development
-==========================
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   forking_hell
-   set_up_fork
-   configure_git
-   development_workflow
-   dot2_dot3
diff --git a/doc/devel/gitwash/this_project.inc b/doc/devel/gitwash/this_project.inc
index 471a9e9d10f2..e8863d5f78f0 100644
--- a/doc/devel/gitwash/this_project.inc
+++ b/doc/devel/gitwash/this_project.inc
@@ -1,5 +1,5 @@
-.. matplotlib
-.. _matplotlib: http://matplotlib.org
-.. _`matplotlib github`: https://github.com/matplotlib/matplotlib
+.. Matplotlib
+.. _`Matplotlib`: http://matplotlib.org
+.. _`Matplotlib github`: https://github.com/matplotlib/matplotlib
 
-.. _`matplotlib mailing list`: https://mail.python.org/mailman/listinfo/matplotlib-devel
+.. _`Matplotlib mailing list`: https://mail.python.org/mailman/listinfo/matplotlib-devel