README cleanup

1 files changed, 48 insertions, 31 deletions

diff --git a/README.md b/README.md
index 6320b90..c342c5c 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,44 @@
 ## Description
 
 **Git-deploy-cache** is a bash script intended to be called by a git
-post-receive hook. It requires three arguments from STDIN: newrev, oldrev, and
-refname. These are the three variables passed to git post-receive hooks.
+post-receive hook. At execution time, it parses various information handed it
+by the git post-receive process (old ref, new ref, refname), and uses that
+information to clone the modified branch to a cache location for use by later
+scripts.
 
-When this script deploys the given bare repo, it does so to two layers
-of directories: the repo name and the branch name. An example would be...
+A few ideas might be to use this script as a starting point to deploy app code,
+trigger test jobs, deploy a blog, manage a system (if you really wanted to).
+The posibilities are endless.
 
-From within the _foo_ repository, a push is issue to the master branch
+
+## Usage
+
+Usage of git-deploy-cache is simple. In the post-receive hook file of a bare
+git repository, simply source this script, providing a deployment base path as
+the first argument.
+
+For example, if you wanted all deployments to show up in ~/deploy/...
+
+__\<repo\>/hooks/post-receive__
+
+    # Source the git-deploy-cache script here
+    . ~/bin/git-deploy-cache ~/deploy/
+
+
+### Arguments
+
+This script requires three arguments from STDIN: newrev, oldrev, and refname.
+These are the three variables passed to git post-receive hooks, which are
+passed by git on post-receive hook calls. It also requires one additional
+argument as the first argument: the base deploy path.
+
+
+### Effect
+
+When this script deploys the given bare repo, it does so through two layers of
+directories: the repo name and the branch name. An example would be...
+
+From within the _foo_ repository, a push is issued to the master branch
 
     git push origin master
 
@@ -15,34 +46,20 @@ From the deploy base, this directory structure will show up.
 
     <deploy-base>
     |
-    |-> foo
+    `-> foo
         |
-        |-> master
+        `-> master
 
 If a deployment was done to the dev branch, the directory structure would now
 look like...
 
     <deploy-base>
     |
-    |-> foo
+    `-> foo
         |
-        |-> master
+        `-> master
         |
-        |-> dev
-
-
-## Usage
-
-Usage of git-deploy-cache is simple. In the post-receive hook file of a bare
-git repository, simply source this script, providing a deployment base path as
-the first argument.
-
-For example, if you wanted all deployments to show up in ~/deploy/...
-
-__<repo>/hooks/post-receive__
-
-    # Source the git-deploy-cache script here
-    . ~/bin/git-deploy-cache ~/deploy/
+        `-> dev
 
 
 ### Variables
@@ -55,10 +72,10 @@ given commit).
 
 The variables made available by this function are...
 
-*   REPOSITORY: Repository that was pushed to
-*   BRANCH: Name of the branch that was modified
-*   FILES_A: List of __A__dded files
-*   FILES_M: List of __M__odified files
-*   FILES_D: List of __D__eleted files
-*   FILES_E: List of all files __E__xisting in the commit, modified or new.
-             Does not include deleted files.
+* **REPOSITORY**: Repository that was pushed to
+* **BRANCH**: Name of the branch that was modified
+* **FILES_A**: List of **A**dded files
+* **FILES_M**: List of **M**odified files
+* **FILES_D**: List of **D**eleted files
+* **FILES_E**: List of all files **E**xisting in the commit, modified or new.
+               Does not include deleted files.