diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index 81ac702..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,22 +0,0 @@
-
-HOW TO INSTALL git-subtree
-==========================
-
-You simply need to copy the file 'git-subtree.sh' to where
-the rest of the git scripts are stored. 
-
-From the Git bash window just run:
-
-install.sh 
-
-Or if you have the full Cygwin installed, you can use make:
-
-make install
-
-That will make a 'git subtree' (note: space instead of dash) command
-available.  See the file git-subtree.txt for more.
-
-You can also install the man page by doing:
-
-	make doc
-	cp git-subtree.1 /usr/share/man/man1/
diff --git a/README b/README
deleted file mode 100644
index c686b4a..0000000
--- a/README
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Please read git-subtree.txt for documentation.
-
-Please don't contact me using github mail; it's slow, ugly, and worst of
-all, redundant. Email me instead at apenwarr@gmail.com and I'll be happy to
-help.
-
-Avery
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4c331e6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# git-subtree
+
+git-subtree allows subprojects to be included within a sub-directory of a main project, optionally including the sub-project's entire history.
+
+## Installation
+
+Choose **one** of the following ways to install git-subtree:
+
+1. Copy the file `git-subtree.sh` to where all other git scripts are stored.
+1. Run `install.sh` in a Git-enabled shell (that's "Git Bash" on Windows).
+1. Run `make install` in a Cygwin-enabled shell.
+
+Any *one* of these actions makes the `git subtree` command available (note: space instead of dash).
+
+To additionally install the man page:
+
+    make doc
+    cp git-subtree.1 /usr/share/man/man1/
+
+
+## Usage
+
+See `git-subtree.txt` for details.
+
+## Known issues
+
+See `todo`.
+
+## License
+
+You may use this software under the terms of the GNU General Public License (GPL), Version 2.
+
+See `COPYING`.
+
+## Credits
+
+Originally authored by Avery Pennarun, <http://apenwarr.ca/log>
+
+Please do not contact the author using github mail. Instead, <mailto:apenwarr@gmail.com>
diff --git a/git-subtree.txt b/git-subtree.txt
index 0c44fda..a127817 100644
--- a/git-subtree.txt
+++ b/git-subtree.txt
@@ -269,7 +269,7 @@ git-extensions repository in ~/git-extensions/:
 name
 
 You can omit the --squash flag, but doing so will increase the number
-of commits that are incldued in your local repository.
+of commits that are included in your local repository.
 
 We now have a ~/git-extensions/git-subtree directory containing code
 from the master branch of git://github.com/apenwarr/git-subtree.git
@@ -356,6 +356,44 @@ Then push the new branch onto the new empty repository:
 	$ git push <new-repo> split:master
 
 
+EXAMPLE 4. Re-integrate an already extracted subtree
+----------------------------------------------------
+Suppose you have extracted a sub-directory containing a library into an own
+repository through other means (without git-subtree) already, but it still
+exists in your mainline/original repository.  Here's how you re-integrate
+that back into your source/mainline:
+
+Let's assume that 'master' is our mainline branch in the original repo,
+containing the library in the lib/ sub-directory, which we want to split into
+a new 'class' branch and rejoin afterwards.
+
+First, split the local library into an own branch:
+
+  $ git checkout master
+  $ git subtree split --prefix=lib --rejoin -b split
+
+Second, add the library's existing upstream repo as remote 'vendor'.  To
+achieve an identical history, we checkout the upstream master into 'library',
+merge the history of 'split' into it, and push the result upstream:
+
+  $ git remote add vendor git@github.com:vendor/library.git
+  $ git fetch vendor
+  $ git checkout -b library vendor/master
+  $ git merge split
+  $ git push vendor library:master
+
+Third, merge any upstream library changes into your mainline:
+
+  $ git checkout master
+  $ git subtree merge --prefix=lib library
+  $ git push origin master
+
+To push changes in your local library to the vendor repo in the future, it's
+as simple as:
+
+  $ git subtree push --prefix=lib vendor master
+
+
 AUTHOR
 ------
 Written by Avery Pennarun <apenwarr@gmail.com>
diff --git a/install.sh b/install.sh
old mode 100644
new mode 100755