diff --git a/doc/source/gitwash/branch_dropdown.png b/doc/source/gitwash/branch_dropdown.png
new file mode 100644
index 00000000..1bb7a577
Binary files /dev/null and b/doc/source/gitwash/branch_dropdown.png differ
diff --git a/doc/source/gitwash/branch_list.png b/doc/source/gitwash/branch_list.png
deleted file mode 100644
index 1196eb75..00000000
Binary files a/doc/source/gitwash/branch_list.png and /dev/null differ
diff --git a/doc/source/gitwash/branch_list_compare.png b/doc/source/gitwash/branch_list_compare.png
deleted file mode 100644
index 336afa37..00000000
Binary files a/doc/source/gitwash/branch_list_compare.png and /dev/null differ
diff --git a/doc/source/gitwash/configure_git.txt b/doc/source/gitwash/configure_git.txt
index 260898db..0e18b666 100644
--- a/doc/source/gitwash/configure_git.txt
+++ b/doc/source/gitwash/configure_git.txt
@@ -9,81 +9,150 @@
 Overview
 ========
 
-::
+Your personal git configurations are saved in the ``.gitconfig`` file in
+your home directory.
 
-  git config --global user.email you@yourdomain.example.com
-  git config --global user.name "Your Name Comes Here"
+Here is an example ``.gitconfig`` file::
 
-
-In detail
-=========
-
-This is to tell git_ who you are, for labeling any changes you make to
-the code.  The simplest way to do this is from the command line::
-
-  git config --global user.email you@yourdomain.example.com
-  git config --global user.name "Your Name Comes Here"
-
-This will write the settings into your git configuration file - a file
-called ``.gitconfig`` in your home directory. 
-
-Advanced git configuration
-==========================
-
-You might well benefit from some aliases to common commands.
-
-For example, you might well want to be able to shorten ``git checkout`` to ``git co``. 
-
-The easiest way to do this, is to create a ``.gitconfig`` file in your
-home directory, with contents like this::
-
-  [core]
-          editor = emacs
   [user]
+          name = Your Name
           email = you@yourdomain.example.com
-          name = Your Name Comes Here
+
   [alias]
+          ci = commit -a
+          co = checkout
           st = status
           stat = status
-          co = checkout
-  [color]
-          diff = auto
-          status = true
+          br = branch
+          wdiff = diff --color-words
 
-(of course you'll need to set your email and name, and may want to set
-your editor).  If you prefer, you can do the same thing from the command
-line::
+  [core]
+          editor = vim
 
-  git config --global core.editor emacs
+  [merge]
+          summary = true
+
+You can edit this file directly or you can use the ``git config --global``
+command::
+
+  git config --global user.name "Your Name"
   git config --global user.email you@yourdomain.example.com
-  git config --global user.name "Your Name Comes Here"
-  git config --global alias.st status
-  git config --global alias.stat status
+  git config --global alias.ci "commit -a"
   git config --global alias.co checkout
-  git config --global color.diff auto
-  git config --global color.status true
-
-These commands will write to your user's git configuration file
-``~/.gitconfig``.
+  git config --global alias.st "status -a"
+  git config --global alias.stat "status -a"
+  git config --global alias.br branch
+  git config --global alias.wdiff "diff --color-words"
+  git config --global core.editor vim
+  git config --global merge.summary true
 
 To set up on another computer, you can copy your ``~/.gitconfig`` file,
 or run the commands above.
 
-Other configuration recommended by Yarik
-========================================
+In detail
+=========
 
-In your ``~/.gitconfig`` file alias section::
+user.name and user.email
+------------------------
 
-   wdiff = diff --color-words
+It is good practice to tell git_ who you are, for labeling any changes
+you make to the code.  The simplest way to do this is from the command
+line::
 
-so that ``git wdiff`` gives a nicely formatted output of the diff. 
+  git config --global user.name "Your Name"
+  git config --global user.email you@yourdomain.example.com
 
-To enforce summaries when doing merges(``~/.gitconfig`` file again)::
+This will write the settings into your git configuration file,  which
+should now contain a user section with your name and email::
+
+  [user]
+        name = Your Name
+        email = you@yourdomain.example.com
+
+Of course you'll need to replace ``Your Name`` and ``you@yourdomain.example.com``
+with your actual name and email address.
+
+Aliases
+-------
+
+You might well benefit from some aliases to common commands.
+
+For example, you might well want to be able to shorten ``git checkout``
+to ``git co``.  Or you may want to alias ``git diff --color-words``
+(which gives a nicely formatted output of the diff) to ``git wdiff``
+
+The following ``git config --global`` commands::
+
+  git config --global alias.ci "commit -a"
+  git config --global alias.co checkout
+  git config --global alias.st "status -a"
+  git config --global alias.stat "status -a"
+  git config --global alias.br branch
+  git config --global alias.wdiff "diff --color-words"
+
+will create an ``alias`` section in your ``.gitconfig`` file with contents
+like this::
+
+  [alias]
+          ci = commit -a
+          co = checkout
+          st = status -a
+          stat = status -a
+          br = branch
+          wdiff = diff --color-words
+
+Editor
+------
+
+You may also want to make sure that your editor of choice is used ::
+
+  git config --global core.editor vim
+
+Merging
+-------
+
+To enforce summaries when doing merges (``~/.gitconfig`` file again)::
 
    [merge]
-      summary = true
+      log = true
 
+Or from the command line::
 
-.. include:: git_links.txt
+  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::
+
+    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!)::
+
+    * 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/source/gitwash/development_workflow.txt b/doc/source/gitwash/development_workflow.txt
index 8536d700..5578882e 100644
--- a/doc/source/gitwash/development_workflow.txt
+++ b/doc/source/gitwash/development_workflow.txt
@@ -1,47 +1,102 @@
 .. _development-workflow:
 
-====================
+####################
 Development workflow
-====================
+####################
 
 You already have your own forked copy of the scikits.image_ repository, by
-following :ref:`forking`, :ref:`set-up-fork`, and you have configured
-git_ by following :ref:`configure-git`.
+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.
 
 Workflow summary
 ================
 
-* Keep your ``master`` branch clean of edits that have not been merged
-  to the main scikits.image_ development repo.  Your ``master`` then will follow
-  the main scikits.image_ repository.
-* Start a new *feature branch* for each set of edits that you do.
-* If you can avoid it, try not to merge other branches into your feature
-  branch while you are working.
-* Ask for review!
+In what follows we'll refer to the upstream scikits.image ``master`` branch, as
+"trunk".
 
-This way of working really helps to keep work well organized, and in
-keeping history as clear as possible.
+* 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 `scikits.image mailing list`_ if you get stuck.
+* Ask for code review!
 
-See - for example - `linux git workflow`_. 
+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.
 
-Making a new feature branch
-===========================
+See `linux git workflow`_ and `ipython git workflow`_ for some explanation.
+
+Consider deleting your master branch
+====================================
+
+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.
+
+.. _update-mirror-trunk:
+
+Update the mirror of trunk
+==========================
+
+First make sure you have done :ref:`linking-to-upstream`.
+
+From time to time you should fetch the upstream (trunk) changes from github::
+
+   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'.
+
+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.
+
+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``.
 
 ::
 
-   git branch my-new-feature
-   git checkout my-new-feature
+    # 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 this also on your public github_ fork
-of scikits.image_.  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::
+Generally, you will want to keep your feature branches on your public github_
+fork of scikits.image_.  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
 
-From now on git_ will know that ``my-new-feature`` is related to the
-``my-new-feature`` branch in the github_ repo.
+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
+
+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
 ====================
@@ -78,101 +133,46 @@ In more detail
 
 #. Check what the actual changes are with ``git diff`` (`git diff`_).
 #. Add any new files to version control ``git add new_file_name`` (see
-   `git add`_). 
+   `git add`_).
 #. To commit all modified files into the local copy of your repo,, do
    ``git commit -am 'A commit message'``.  Note the ``-am`` options to
    ``commit``. The ``m`` flag just signals that you're going to type a
-   message on the command line.  The ``a`` flag - you can just take on
-   faith - or see `why the -a flag?`_. See also the `git commit`_ manual
-   page.
-#. To push the changes up to your forked repo on github_, do a ``git
-   push`` (see `git push`). 
+   message on the command line.  The ``a`` flag |emdash| you can just take on
+   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`_).
 
-Asking for code review
-======================
+Ask for your changes to be reviewed or merged
+=============================================
 
-#. Go to your repo URL - e.g. ``http://github.com/your-user-name/scikits.image``.
-#. Click on the *Branch list* button:
-
-   .. image:: branch_list.png
-
-#. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
-
-   .. image:: branch_list_compare.png
-
-#. If asked, select the *base* and *comparison* branch names you want to
-   compare.  Usually these will be ``master`` and ``my-new-feature``
-   (where that is your feature branch name).
-#. At this point you should get a nice summary of the changes.  Copy the
-   URL for this, and post it to the `scikits.image mailing list`_, asking for
-   review.  The URL will look something like:
-   ``http://github.com/your-user-name/scikits.image/compare/master...my-new-feature``.
-   There's an example at
-   http://github.com/matthew-brett/nipy/compare/master...find-install-data
-   See: http://github.com/blog/612-introducing-github-compare-view for
-   more detail.
-
-The generated comparison, is between your feature branch
-``my-new-feature``, and the place in ``master`` from which you branched
-``my-new-feature``.  In other words, you can keep updating ``master``
-without interfering with the output from the comparison.  More detail?
-Note the three dots in the URL above (``master...my-new-feature``) and
-see :ref:`dot2-dot3`.
-
-Asking for your changes to be merged with the main repo
-=======================================================
-
-When you are ready to ask for the merge of your code:
+When you are ready to ask for someone to review your code and consider a merge:
 
 #. Go to the URL of your forked repo, say
-   ``http://github.com/your-user-name/scikits.image.git``.
+   ``http://github.com/your-user-name/scikits.image``.
+#. Use the 'Switch Branches' dropdown menu near the top left of the page to
+   select the branch with your changes:
+
+   .. image:: branch_dropdown.png
+
 #. Click on the 'Pull request' button:
 
    .. image:: pull_button.png
 
-   Enter a message; we suggest you select only ``scikits.image`` as the
-   recipient.  The message will go to the `scikits.image mailing list`_.  Please
-   feel free to add others from the list as you like.
+   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.
 
-Merging from trunk
-==================
+   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.
 
-This updates your code from the upstream `scikits.image github`_  repo. 
+Some other things you might want to do
+======================================
 
-Overview
---------
-
-::
-
-   # go to your master branch
-   git checkout master
-   # pull changes from github
-   git fetch upstream
-   # merge from upstream
-   git merge upstream master
-
-In detail
----------
-
-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::
-
-   git checkout master
-
-Make sure you have done :ref:`linking-to-upstream`.
-
-Merge the upstream code into your current development by first pulling
-the upstream repo to a copy on your local machine::
-
-   git fetch upstream
-
-then merging into your current branch::
-
-   git merge upstream/master
-
-Deleting a branch on github_
-============================
+Delete a branch on github
+-------------------------
 
 ::
 
@@ -186,11 +186,11 @@ Deleting a branch on github_
 http://github.com/guides/remove-a-remote-branch
 
 Several people sharing a single repository
-==========================================
+------------------------------------------
 
 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_.
+share it via github.
 
 First fork scikits.image into your account, as from :ref:`forking`.
 
@@ -215,8 +215,8 @@ usual::
      git commit -am 'ENH - much better code'
      git push origin master # pushes directly into your repo
 
-Exploring your repository
-=========================
+Explore your repository
+-----------------------
 
 To see a graphical representation of the repository branches and
 commits::
@@ -227,7 +227,189 @@ To see a linear list of commits for this branch::
 
    git log
 
-You can also look at the `network graph visualizer`_ for your github_
+You can also look at the `network graph visualizer`_ for your github
 repo.
 
-.. include:: git_links.txt
+Finally the :ref:`fancy-log` ``lg`` alias will give you a reasonable text-based
+graph of the repository.
+
+.. _rebase-on-trunk:
+
+Rebasing on trunk
+-----------------
+
+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::
+
+          A---B---C cool-feature
+         /
+    D---E---F---G trunk
+
+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.
+
+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::
+
+                  A'--B'--C' cool-feature
+                 /
+    D---E---F---G trunk
+
+See `rebase without tears`_ for more detail.
+
+To do a rebase on trunk::
+
+    # 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
+
+In this situation, where you are already on branch ``cool-feature``, the last
+command can be written more succinctly as::
+
+    git rebase upstream/master
+
+When all looks good you can delete your backup branch::
+
+   git branch -D tmp
+
+If it doesn't look good you may need to have a look at
+:ref:`recovering-from-mess-up`.
+
+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`_.
+
+.. _recovering-from-mess-up:
+
+Recovering from mess-ups
+------------------------
+
+Sometimes, you mess up merges or rebases. Luckily, in git it is
+relatively straightforward to recover from such mistakes.
+
+If you mess up during a rebase::
+
+   git rebase --abort
+
+If you notice you messed up after the rebase::
+
+   # reset branch back to the saved point
+   git reset --hard tmp
+
+If you forgot to make a backup branch::
+
+   # look at the reflog of the branch
+   git reflog show cool-feature
+
+   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
+   ...
+
+   # reset the branch to where it was before the botched rebase
+   git reset --hard cool-feature@{2}
+
+.. _rewriting-commit-history:
+
+Rewriting commit history
+------------------------
+
+.. note::
+
+   Do this only for your own feature branches.
+
+There's an embarassing typo in a commit you made? Or perhaps the you
+made several false starts you would like the posterity not to see.
+
+This can be done via *interactive rebasing*.
+
+Suppose that the commit history looks like this::
+
+    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.
+    ...
+
+and ``6ad92e5`` is the last commit in the ``cool-feature`` branch. Suppose we
+want to make the following changes:
+
+* Rewrite the commit message for ``13d7934`` to something more sensible.
+* Combine the commits ``2dec1ac``, ``a815645``, ``eadc391`` into a single one.
+
+We do as follows::
+
+    # 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::
+
+    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.
+    #
+
+To achieve what we want, we will make the following changes to it::
+
+    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
+
+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.
+
+Git will then immediately bring up an editor for editing the commit
+message. After revising it, we get the output::
+
+    [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.
+
+and the history looks now like this::
+
+     0f22701 Fix a few bugs + disable
+     721fc64 ENH: Sophisticated feature
+     6ad92e5 * masked is now an instance of a new object, MaskedConstant
+
+If it went wrong, recovery is again possible as explained :ref:`above
+<recovering-from-mess-up>`.
+
+.. include:: links.inc
diff --git a/doc/source/gitwash/dot2_dot3.txt b/doc/source/gitwash/dot2_dot3.txt
deleted file mode 100644
index 7759e2e6..00000000
--- a/doc/source/gitwash/dot2_dot3.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-.. _dot2-dot3:
-
-========================================
- Two and three dots in difference specs
-========================================
-
-Thanks to Yarik Halchenko for this explanation.
-
-Imagine a series of commits A, B, C, D...  Imagine that there are two
-branches, *topic* and *master*.  You branched *topic* off *master* when
-*master* was at commit 'E'.  The graph of the commits looks like this::
-
-
-        A---B---C topic
-        /
-   D---E---F---G master
-
-Then::
-
-   git diff master..topic
-
-will output the difference from G to C (i.e. with effects of F and G),
-while::
-
-   git diff master...topic
-
-would output just differences in the topic branch (i.e. only A, B, and
-C).
diff --git a/doc/source/gitwash/following_latest.txt b/doc/source/gitwash/following_latest.txt
index 6a7b3e11..bdf07f4a 100644
--- a/doc/source/gitwash/following_latest.txt
+++ b/doc/source/gitwash/following_latest.txt
@@ -10,7 +10,7 @@ These are the instructions if you just want to follow the latest
 The steps are:
 
 * :ref:`install-git`
-* get local copy of the git repository from github_
+* get local copy of the git repository from github
 * update local copy from time to time
 
 Get the local copy of the code
@@ -33,4 +33,4 @@ From time to time you may want to pull down the latest code.  Do this with::
 The tree in ``scikits.image`` will now have the latest changes from the initial
 repository.
 
-.. include:: git_links.txt
+.. include:: links.inc
diff --git a/doc/source/gitwash/forking_hell.txt b/doc/source/gitwash/forking_hell.txt
index 8ef86ffc..f6f3ff29 100644
--- a/doc/source/gitwash/forking_hell.txt
+++ b/doc/source/gitwash/forking_hell.txt
@@ -1,26 +1,26 @@
 .. _forking:
 
-============================================
+==========================================
 Making your own copy (fork) of scikits.image
-============================================
+==========================================
 
 You need to do this only once.  The instructions here are very similar
-to the instructions at http://help.github.com/forking/ - please see that
-page for more detail.  We're repeating some of it here just to give the
+to the instructions at http://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 scikits.image_ 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 - see the
-``Generating SSH keys`` help on `github help`_.
+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 scikits.image_
-=============================================
+===========================================
 
-#. Log into your github_ account.
+#. Log into your github account.
 #. Go to the scikits.image_ github home at `scikits.image github`_.
 #. Click on the *fork* button:
 
@@ -29,5 +29,5 @@ Create your own forked copy of scikits.image_
    Now, after a short pause and some 'Hardcore forking action', you
    should find yourself at the home page for your own forked copy of scikits.image_.
 
-.. include:: git_links.txt
+.. include:: links.inc
 
diff --git a/doc/source/gitwash/git_development.txt b/doc/source/gitwash/git_development.txt
index 64522c65..c5b910d8 100644
--- a/doc/source/gitwash/git_development.txt
+++ b/doc/source/gitwash/git_development.txt
@@ -13,4 +13,4 @@ Contents:
    set_up_fork
    configure_git
    development_workflow
-   
+   maintainer_workflow
diff --git a/doc/source/gitwash/git_install.txt b/doc/source/gitwash/git_install.txt
index 6c6a57c0..72a6b911 100644
--- a/doc/source/gitwash/git_install.txt
+++ b/doc/source/gitwash/git_install.txt
@@ -17,10 +17,10 @@ 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: http://book.git-scm.com/2_installing_git.html
 
-.. include:: git_links.txt
+.. include:: links.inc
diff --git a/doc/source/gitwash/git_intro.txt b/doc/source/gitwash/git_intro.txt
index f3bfc6fc..47c97102 100644
--- a/doc/source/gitwash/git_intro.txt
+++ b/doc/source/gitwash/git_intro.txt
@@ -8,11 +8,11 @@ project.
 There are several different workflows here, for different ways of
 working with *scikits.image*.
 
-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:: git_links.txt
+.. include:: links.inc
diff --git a/doc/source/gitwash/git_links.txt b/doc/source/gitwash/git_links.inc
similarity index 77%
rename from doc/source/gitwash/git_links.txt
rename to doc/source/gitwash/git_links.inc
index 27eb2be1..3822fd9d 100644
--- a/doc/source/gitwash/git_links.txt
+++ b/doc/source/gitwash/git_links.inc
@@ -2,35 +2,12 @@
    and name substitutions.  It may be included in many files,
    therefore it should only contain link targets and name
    substitutions.  Try grepping for "^\.\. _" to find plausible
-   candidates for this list.  
+   candidates for this list.
 
 .. NOTE: reST targets are
    __not_case_sensitive__, so only one target definition is needed for
    nipy, NIPY, Nipy, etc...
 
-.. scikits.image
-
-.. _`scikits.image`: http://stefanv.github.com/scikits.image
-
-.. _`scikits.image github`: http://github.com/stefanv/scikits.image
-
-.. _`scikits.image mailing list`: http://groups.google.com/group/scikits-image
-
-.. PROJECTNAME placeholders
-.. _PROJECTNAME: http://neuroimaging.scipy.org
-.. _`PROJECTNAME github`: http://github.com/nipy
-.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
-
-.. nipy
-.. _nipy: http://neuroimaging.scipy.org
-.. _`nipy github`: http://github.com/nipy
-.. _`nipy mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
-
-.. ipython
-.. _ipython: http://ipython.scipy.org
-.. _`ipython github`: http://github.com/ipython
-.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
-
 .. git stuff
 .. _git: http://git-scm.com/
 .. _github: http://github.com
@@ -62,9 +39,23 @@
 .. _git log: http://www.kernel.org/pub/software/scm/git/docs/git-log.html
 .. _git branch: http://www.kernel.org/pub/software/scm/git/docs/git-branch.html
 .. _git remote: http://www.kernel.org/pub/software/scm/git/docs/git-remote.html
+.. _git rebase: http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html
 .. _git config: http://www.kernel.org/pub/software/scm/git/docs/git-config.html
 .. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
+.. _tangled working copy problem: http://tomayko.com/writings/the-thing-about-git 
 .. _git management: http://kerneltrap.org/Linux/Git_Management
 .. _linux git workflow: http://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.com/pydagogue/foundation.html
+.. _deleting master on github: http://matthew-brett.github.com/pydagogue/gh_delete_master.html
+.. _rebase without tears: http://matthew-brett.github.com/pydagogue/rebase_without_tears.html
+.. _resolving a merge: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#resolving-a-merge
+.. _ipython git workflow: http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html
+
+.. other stuff
+.. _python: http://www.python.org
+
+.. |emdash| unicode:: U+02014
+
+.. vim: ft=rst
diff --git a/doc/source/gitwash/git_resources.txt b/doc/source/gitwash/git_resources.txt
index 69e344ec..ba7b275e 100644
--- a/doc/source/gitwash/git_resources.txt
+++ b/doc/source/gitwash/git_resources.txt
@@ -1,8 +1,8 @@
 .. _git-resources:
 
-================
- git_ resources
-================
+=============
+git resources
+=============
 
 Tutorials and summaries
 =======================
@@ -14,18 +14,20 @@ Tutorials and summaries
 * The `git user manual`_ 
 * The `git tutorial`_
 * The `git community book`_
-* `git ready`_ - a nice series of tutorials
-* `git casts`_ - video snippets giving git how-tos.
-* `git magic`_ - extended introduction with intermediate detail
-* Fernando Perez' git page - `Fernando's git page`_ - many links and tips
+* `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.
+* `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`_
-* Th `git parable`_ is an easy read explaining the concepts behind git.
-* `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`_
@@ -54,4 +56,4 @@ online manual pages for some common commands:
 * `git remote`_
 * `git status`_
 
-.. include:: git_links.txt
+.. include:: links.inc
diff --git a/doc/source/gitwash/index.txt b/doc/source/gitwash/index.txt
index 0acb8fb9..c67e629f 100644
--- a/doc/source/gitwash/index.txt
+++ b/doc/source/gitwash/index.txt
@@ -1,7 +1,7 @@
 .. _using-git:
 
 Working with *scikits.image* source code
-========================================
+======================================
 
 Contents:
 
diff --git a/doc/source/gitwash/known_projects.inc b/doc/source/gitwash/known_projects.inc
new file mode 100644
index 00000000..29723528
--- /dev/null
+++ b/doc/source/gitwash/known_projects.inc
@@ -0,0 +1,41 @@
+.. Known projects
+
+.. PROJECTNAME placeholders
+.. _PROJECTNAME: http://neuroimaging.scipy.org
+.. _`PROJECTNAME github`: http://github.com/nipy
+.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
+
+.. numpy
+.. _numpy: hhttp://numpy.scipy.org
+.. _`numpy github`: http://github.com/numpy/numpy
+.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion
+
+.. scipy
+.. _scipy: http://www.scipy.org
+.. _`scipy github`: http://github.com/scipy/scipy
+.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev
+
+.. nipy
+.. _nipy: http://nipy.org/nipy
+.. _`nipy github`: http://github.com/nipy/nipy
+.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. ipython
+.. _ipython: http://ipython.scipy.org
+.. _`ipython github`: http://github.com/ipython/ipython
+.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
+
+.. dipy
+.. _dipy: http://nipy.org/dipy
+.. _`dipy github`: http://github.com/Garyfallidis/dipy
+.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. nibabel
+.. _nibabel: http://nipy.org/nibabel
+.. _`nibabel github`: http://github.com/nipy/nibabel
+.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. marsbar
+.. _marsbar: http://marsbar.sourceforge.net
+.. _`marsbar github`: http://github.com/matthew-brett/marsbar
+.. _`MarsBaR mailing list`: https://lists.sourceforge.net/lists/listinfo/marsbar-users
diff --git a/doc/source/gitwash/links.inc b/doc/source/gitwash/links.inc
new file mode 100644
index 00000000..20f4dcff
--- /dev/null
+++ b/doc/source/gitwash/links.inc
@@ -0,0 +1,4 @@
+.. compiling links file
+.. include:: known_projects.inc
+.. include:: this_project.inc
+.. include:: git_links.inc
diff --git a/doc/source/gitwash/maintainer_workflow.txt b/doc/source/gitwash/maintainer_workflow.txt
new file mode 100644
index 00000000..64a12d99
--- /dev/null
+++ b/doc/source/gitwash/maintainer_workflow.txt
@@ -0,0 +1,96 @@
+.. _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:scikits.image/scikits.image.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/scikits.image.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/source/gitwash/patching.txt b/doc/source/gitwash/patching.txt
index bdc64b5f..110666aa 100644
--- a/doc/source/gitwash/patching.txt
+++ b/doc/source/gitwash/patching.txt
@@ -2,16 +2,18 @@
  Making a patch
 ================
 
-You've discovered a bug or something else you want to change in scikits.image_ - excellent!
+You've discovered a bug or something else you want to change
+in scikits.image_ .. |emdash| excellent!
 
-You've worked out a way to fix it - even better!
+You've worked out a way to fix it |emdash| even better!
 
-You want to tell us about it - best of all!
+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.
+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:
 
@@ -42,24 +44,28 @@ Overview
    # make the patch files
    git format-patch -M -C master
 
-Then, send the generated patch files to the `scikits.image mailing list`_ - where we will thank you warmly.
+Then, send the generated patch files to the `scikits.image
+mailing list`_ |emdash| where we will thank you warmly.
 
 In detail
 ---------
 
-#. Tell git_ who you are so it can label the commits you've made::
+#. 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 scikits.image_ repository::
+#. If you don't already have one, clone a copy of the
+   scikits.image_ repository::
 
       git clone git://github.com/scikits.image/scikits.image.git
       cd scikits.image
 
-#. Make a 'feature branch'.  This will be where you work on your bug
-   fix.  It's nice and safe and leaves you with access to an unmodified
-   copy of the code in the main branch::
+#. Make a 'feature branch'.  This will be where you work on
+   your bug fix.  It's nice and safe and leaves you with
+   access to an unmodified copy of the code in the main
+   branch::
 
       git branch the-fix-im-thinking-of
       git checkout the-fix-im-thinking-of
@@ -74,16 +80,18 @@ In detail
       # hack hack, hack
       git commit -am 'BF - added fix for Funny bug'
 
-   Note the ``-am`` options to ``commit``. The ``m`` flag just signals
-   that you're going to type a message on the command line.  The ``a``
-   flag - you can just take on faith - or see `why the -a flag?`_.
+   Note the ``-am`` options to ``commit``. The ``m`` flag just
+   signals that you're going to type a message on the command
+   line.  The ``a`` flag |emdash| you can just take on faith |emdash|
+   or see `why the -a flag?`_.
 
-#. When you have finished, check you have committed all your changes::
+#. When you have finished, check you have committed all your
+   changes::
 
       git status
 
-#. Finally, make your commits into patches.  You want all the commits
-   since you branched from the ``master`` branch::
+#. Finally, make your commits into patches.  You want all the
+   commits since you branched from the ``master`` branch::
 
       git format-patch -M -C master
 
@@ -94,19 +102,21 @@ In detail
 
    Send these files to the `scikits.image mailing list`_.
 
-When you are done, to switch back to the main copy of the code, just
-return to the ``master`` branch::
+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.
+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 scikits.image_ repository on github_ - :ref:`forking`.  Then::
+Fork the scikits.image_ repository on github |emdash| :ref:`forking`.
+Then::
 
    # checkout and refresh master branch from main repo
    git checkout master
@@ -118,6 +128,7 @@ Fork the scikits.image_ repository on github_ - :ref:`forking`.  Then::
    # 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`.
+Then you can, if you want, follow the
+:ref:`development-workflow`.
 
-.. include:: git_links.txt
+.. include:: links.inc
diff --git a/doc/source/gitwash/set_up_fork.txt b/doc/source/gitwash/set_up_fork.txt
index 395fa130..fe4a7684 100644
--- a/doc/source/gitwash/set_up_fork.txt
+++ b/doc/source/gitwash/set_up_fork.txt
@@ -4,14 +4,14 @@
  Set up your fork
 ==================
 
-First you follow the instructions for :ref:`forking`. 
+First you follow the instructions for :ref:`forking`.
 
 Overview
 ========
 
 ::
 
-   git clone git@github.com/your-user-name/scikits.image.git
+   git clone git@github.com:your-user-name/scikits.image.git
    cd scikits.image
    git remote add upstream git://github.com/scikits.image/scikits.image.git
 
@@ -33,7 +33,7 @@ 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 `scikits.image github`_ repository, so
    you can merge in changes from trunk.
@@ -64,5 +64,5 @@ Just for your own satisfaction, show yourself that you now have a new
    origin	git@github.com:your-user-name/scikits.image.git (fetch)
    origin	git@github.com:your-user-name/scikits.image.git (push)
 
-.. include:: git_links.txt
+.. include:: links.inc
 
diff --git a/doc/source/gitwash/this_project.inc b/doc/source/gitwash/this_project.inc
new file mode 100644
index 00000000..f7c01aa2
--- /dev/null
+++ b/doc/source/gitwash/this_project.inc
@@ -0,0 +1,5 @@
+.. scikits.image
+.. _scikits.image: http://scikits-image.org
+.. _`scikits.image github`: http://github.com/scikits.image/scikits.image
+
+.. _`scikits.image mailing list`: http://groups.google.com/group/scikits-image