chore(docs): improves the documentation

Clairifies:
 * install options
 * some differences between v4 and v8
 * how to create and manage githooks
 * how husky relates to git
 * how husky relates to npm/yarn

.github/README.md

@@ -8,34 +8,64 @@ Husky improves your commits and more 🐶 _woof!_
 
 # Install
 
-```
-npm install husky -D
+## Easy install (reccomended)
+
+`husky-init` is a one-time command to configure a project with husky.
+
+It installs husky into your project and auto-configures your package.json,
+ensuring that every time you run `yarn|npm install` git is then configured to
+use your hooks (so you don't have to worry about it again).
+
+```shell
+npx husky-init && npm install       # npm
+npx husky-init && yarn              # Yarn 1
+yarn dlx husky-init --yarn2 && yarn # Yarn 2+
+pnpm dlx husky-init && pnpm install # pnpm
 ```
 
-# Usage
+It will:
+* install husky
+* modify `package.json` (adding a
+[`prepare`](https://docs.npmjs.com/cli/v8/using-npm/scripts#prepare-and-prepublish)
+script)
+* create a sample `pre-commit` hook that you can edit. By default this runs
+  `npm test` when you commit.
 
-Edit `package.json > prepare` script and run it once:
+## Manual Install
 
-```sh
-npm set-script prepare "husky install"
-npm run prepare
+1. Install `husky`
+
+```shell
+npm install husky --save-dev
+yarn add --dev husky
 ```
 
-Add a hook:
+2. Enable Git hooks
 
-```sh
-npx husky add .husky/pre-commit "npm test"
-git add .husky/pre-commit
+```shell
+npx husky install # will configure git to use .husky/ by default
 ```
 
-Make a commit:
+3. To automatically have Git hooks enabled after every npm/yarn install, edit
+`package.json` to use one of the [npm/yarm lifecyle
+hooks](https://docs.npmjs.com/cli/v8/using-npm/scripts#prepare-and-prepublish)
+e.g. `prepare`.
+
 
-```sh
-git commit -m "Keep calm and commit"
-# `npm test` will run every time you commit
+```shell
+npm set-script prepare "husky install"
 ```
 
-_For more use cases (project in sub-directory, custom directory, CI support, ...), see documentation._
+You should have:
+
+```js
+// package.json
+{
+  "scripts": {
+    "prepare": "husky install"
+  }
+}
+```
 
 ## Documentation
 

README.md

@@ -6,31 +6,63 @@ Husky improves your commits and more 🐶 *woof!*
 
 # Install
 
+## Easy install (reccomended)
+
+`husky-init` is a one-time command to configure a project with husky.
+
+It installs husky into your project and auto-configures your package.json,
+ensuring that every time you run `yarn|npm install` git is then configured to
+use your hooks (so you don't have to worry about it again).
+
+```shell
+npx husky-init && npm install       # npm
+npx husky-init && yarn              # Yarn 1
+yarn dlx husky-init --yarn2 && yarn # Yarn 2+
+pnpm dlx husky-init && pnpm install # pnpm
 ```
+
+It will:
+* install husky
+* modify `package.json` (adding a
+[`prepare`](https://docs.npmjs.com/cli/v8/using-npm/scripts#prepare-and-prepublish)
+script)
+* create a sample `pre-commit` hook that you can edit. By default this runs
+  `npm test` when you commit.
+
+## Manual Install
+
+1. Install `husky`
+
+```shell
 npm install husky --save-dev
+yarn add --dev husky
 ```
 
-# Usage
-
-Edit `package.json > prepare` script and run it once:
+2. Enable Git hooks
 
-```sh
-npm pkg set scripts.prepare="husky install"
-npm run prepare
+```shell
+npx husky install # will configure git to use .husky/ by default
 ```
 
-Add a hook:
+3. To automatically have Git hooks enabled after every npm/yarn install, edit
+`package.json` to use one of the [npm/yarm lifecyle
+hooks](https://docs.npmjs.com/cli/v8/using-npm/scripts#prepare-and-prepublish)
+e.g. `prepare`.
 
-```sh
-npx husky add .husky/pre-commit "npm test"
-git add .husky/pre-commit
+
+```shell
+npm pkg set scripts.prepare="husky install"
 ```
 
-Make a commit:
+You should have:
 
-```sh
-git commit -m "Keep calm and commit"
-# `npm test` will run
+```js
+// package.json
+{
+  "scripts": {
+    "prepare": "husky install"
+  }
+}
 ```
 
 # Documentation