Update README.md

README.md

@@ -1,66 +1,100 @@
 # gith
 
-githOOKS - simple node server that responds to github post-receive events
+gith[ooks] - a simple node server that responds to github post-receive events with meaningful data
 
 ## Getting Started
+
+### Install
+
 Install the module with: `npm install gith`
 
+### Require
+
+In your node application, require gith and create a gith server. You can specify a port now, or 
+you can use the `.listen( portNumber )` method later. 
+
 ```javascript
 // create a gith server on port 9001
 var gith = require('gith').create( 9001 );
-
-gith( filterMap ).on( actionString, hollabackFn );
 ```
 
-## Documentation
-_(Coming soon)_
+### Use
 
-## Examples
+Pass an object of how you want to filter gith (if at all) and subscribe to an event.
 
 ```javascript
-// do something whenever a file is added on danheberden/gith:master
 gith({
-  repo: 'danheberden/gith',
-  branch: 'master',
-  file: '*'
-}).on( 'add', function( event, payload ) {
-  // do something with event data 
+  repo: 'danheberden/gith'
+}).on( 'all', function( payload ) {
+  console.log( 'Post-receive happened!' );
 });
+```
 
-// do someting when a repository is added
-gith({
-  repo: '*'
-}).on( 'add', function( event, payload ) {
-  // do something with event data 
-});
+## Filtering
 
-// do something when files are removed from any repo
-gith({
-  repo: 'danheberden/gith',
-  file: '*'
-}).on( 'remove', function( event, payload ) {
-  // do something with event data
-});
+The object passed into `gith()` can utilize four parameters (`repo`, `branch`, `file` and `tag`). 
+All of these can either be an exact match string, a regular expression or a function.
 
-// do something when files have been modified on 
-// danheberden/gith in branches starting with 'issue_'
+For example:
+
+```javascript
 gith({
   repo: 'danheberden/gith',
-  branch: /^issue_/,
-  file: '*'
-}).on( 'modify', function( event, payload ) {
-  // do something with event data
+  branch: /issue_(\d+)/
+}).on( 'branch:add', function( payload ) {
+  console.log( 'A branch matching /issue_(\d+)/ was added!' );
+  console.log( 'The issue # is', payload.matches.branch[1] );
 });
+```
 
-// do something when master gets tagged or a tag gets removed
-gith({
-  repo: 'danheberden/repo',
-  branch: 'master',
-  tag: '*'
-}).on( '*', function( event, payload ) {
-  // do something with event data
-});
+You can either omit the key that you don't want to filter (e.g., we would get every file and tag in the above
+example) or use `*` to specifiy that it's a wildcard.
+
+## Events
 
+Events available are:
+
+* `all` - as long as the filtering passed, this will get fired
+* `branch:add`
+* `branch:delete`
+* `file:add`
+* `file:modify`
+* `file:delete`
+* `file:all`
+* `tag:add`
+* `tag:delete`
+
+## Payload
+
+The github payload is very detailed, but can be a bit excessive. 
+
+This is the payload that gith gives you:
+
+```javascript
+{
+  original: the-original-github-payload,
+  files: {
+    all: [],
+    added: [],
+    deleted: [],
+    modified: []
+  },
+  tag: tag, /* if a tagging operation */
+  branch: branch, /* if working on a branch */
+  repo: the-repo-name,
+  sha: the-now-current-sha,
+  time: when-it-was-pushed,
+  urls: {
+    head: current-sha
+    branch: branch-url-if-available,
+    tag: sha-url-of-tag-if-available,
+    repo: repo-url,
+    compare: compare-url
+  },
+  reset: did-the-head-get-reset,
+  pusher: github-username-of-pusher,
+  owner: github-username-of-repo-owner
+}
 ```
 
 ## License