[doc] Rework documentation

README.md

@@ -7,36 +7,45 @@
 [david]: https://img.shields.io/david/observing/pre-commit.svg?style=flat-square
 [cover]: http://img.shields.io/coveralls/observing/pre-commit/master.svg?style=flat-square
 
-A simple `pre-commit` hook installer for `git`. This will ensure that your
-test suite passes before you can commit your changes. In addition to running
-your `npm test` it also has the option to run custom scripts that you have
-specified in your `package.json`.
+**pre-commit** is a pre-commit hook installer for `git`. It will ensure that
+your `npm test` (or other specified scripts) passes before you can commit your
+changes. This all conveniently configured in your package.json.
+
+But don't worry, you can still force a commit by telling `git` to skip the
+`pre-commit` hooks by simply committing using `--no-verify`.
 
 ### Installation
 
-It's advised to install this module as `devDependency` in your `package.json`
-file so it doesn't get installed on production servers. Run:
+It's advised to install the **pre-commit** module as a `devDependencies` in your
+`package.json` as you only need this for development purposes. To install the
+module simply run:
 
 ```
 npm install --save-dev pre-commit
 ```
 
 To install it as `devDependency`. When this module is installed it will override
 the existing `pre-commit` file in your `.git/hooks` folder. Existing
-`pre-commit` hooks will be backed up.
+`pre-commit` hooks will be backed up as `pre-commit.old` in the same repository.
 
 ### Configuration
 
-`pre-commit` will try to run your `npm test` command by default. It does this by
-running `npm run test` in the root of your git repository. It will only run that
-command if it's not the default values that are entered when you issue an `npm
-init`.
+`pre-commit` will try to run your `npm test` command in the root of the git
+repository by default unless it's the default value that is set by the `npm
+init` script. 
 
 But `pre-commit` is not limited to just running your `npm test`'s during the
 commit hook. It's also capable of running every other script that you've
-specified in your `package.json` "scripts" field. The only thing you need to do
-is add a `pre-commit` array to your `package.json` that specifies which scripts
-you want to have ran and in which order:
+specified in your `package.json` "scripts" field. So before people commit you
+could ensure that:
+
+- You have 100% coverage
+- All stying passes.
+- JSHint passes.
+- Contribution licenses signed etc.
+
+The only thing you need to do is add a `pre-commit` array to your `package.json`
+that specifies which scripts you want to have ran and in which order:
 
 ```js
 {
@@ -45,33 +54,74 @@ you want to have ran and in which order:
   "description": "ERROR: No README.md file found!",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "echo \"Error: I SHOULD FAIL LOLOLOLOLOL \" && exit 1",
     "foo": "echo \"fooo\" && exit 0",
     "bar": "echo \"bar\" && exit 0"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://gist.github.com/437464d0899504fb6b7b.git"
-  },
   "pre-commit": [
     "foo",
     "bar",
     "test"
-  ],
-  "author": "",
-  "license": "BSD",
-  "gitHead": "6637d0771c3a89c4a60be087859dee5130f7a104"
+  ]
 }
 ```
 
 In the example above, it will first run: `npm run foo` then `npm run bar` and
 finally `npm run test` which will make the commit fail as it returns the error
-code `1`.
+code `1`.  If you prefer strings over arrays or `precommit` without a middle
+dash, that also works:
+
+```js
+{
+  "precommit": "foo, bar, test"
+  "pre-commit": "foo, bar, test"
+  "pre-commit": ["foo", "bar", "test"]
+  "precommit": ["foo", "bar", "test"],
+  "precommit": {
+    "run": "foo, bar, test",
+  },
+  "pre-commit": {
+    "run": ["foo", "bar", "test"],
+  },
+  "precommit": {
+    "run": ["foo", "bar", "test"],
+  },
+  "pre-commit": {
+    "run": "foo, bar, test",
+  }
+}
+```
+
+The examples above are all the same. In addition to configuring which scripts
+should be ran you can also configure the following options:
+
+- **silent** Don't output the prefixed `pre-commit:` messages when things fail
+  or when we have nothing to run. Should a boolean.
+- **colors** Don't output colors when we write messages. Should be a boolean.
+- **template** Path to a file who's content should be used as template for the
+  git commit body.
 
-To learn more about the scripts, please read the official `npm` documentation:
+These options can either be added in the `pre-commit`/`precommit` object as keys
+or as `"pre-commit.{key}` key properties in the `package.json`:
+
+```js
+{
+  "precommit.silent": true,
+  "pre-commit": {
+    "silent": true
+  }
+}
+```
+
+It's all the same. Different styles so use what matches your project. To learn
+more about the scripts, please read the official `npm` documentation:
 
 https://npmjs.org/doc/scripts.html
 
+And to learn more about git hooks read:
+
+http://githooks.com
+
 ### License
 
 MIT