chore: add mdbook (#894)

* chore: add mdbook

* fix: fill the usage

* ci: add auto deploy

.github/workflows/gh-pages.yml

@@ -0,0 +1,29 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  gh-pages:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - run: mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/master' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book

.gitignore

@@ -5,6 +5,7 @@
 
 tmp/
 dist/
+book/
 
 # Packages
 packaging/pypi/lefthook/__pycache__/

book.toml

@@ -0,0 +1,12 @@
+[book]
+authors = ["Evil Martians"]
+language = "en"
+multilingual = false
+src = "docs/mdbook"
+title = "Lefthook"
+
+[output.html]
+no-section-label = true
+
+[output.html.fold]
+enable = true

docs/mdbook/SUMMARY.md

@@ -0,0 +1,75 @@
+# Lefthook
+
+# User guide
+
+- [Installation](./install.md)
+  - [Ruby](./installation/ruby.md)
+  - [Node.js](./installation/node.md)
+  - [Go](./installation/go.md)
+  - [Python](./installation/python.md)
+  - [Swift](./installation/swift.md)
+  - [Scoop](./installation/scoop.md)
+  - [Homebrew](./installation/homebrew.md)
+  - [Winget](./installation/winget.md)
+  - [Snap](./installation/snap.md)
+  - [Debian-based distro](./installation/deb.md)
+  - [RPM-based distro](./installation/rpm.md)
+  - [Alpine](./installation/alpine.md)
+  - [Arch Linux](./installation/arch.md)
+  - [Manual](./installation/manual.md)
+- [Configuration](./configuration/README.md)
+  - [`assert_lefthook_installed`](./configuration/assert_lefthook_installed.md)
+  - [`colors`](./configuration/colors.md)
+  - [`no_tty`](./configuration/no_tty.md)
+  - [`extends`](./configuration/extends.md)
+  - [`min_version`](./configuration/min_version.md)
+  - [`output`](./configuration/output.md)
+  - [`skip_output`](./configuration/skip_output.md)
+  - [`source_dir`](./configuration/source_dir.md)
+  - [`source_dir_local`](./configuration/source_dir_local.md)
+  - [`rc`](./configuration/rc.md)
+  - [`remotes`](./configuration/remotes.md)
+    - [`git_url`](./configuration/git_url.md)
+    - [`ref`](./configuration/ref.md)
+    - [`refetch`](./configuration/refetch.md)
+    - [`refetch_frequency`](./configuration/refetch_frequency.md)
+    - [`configs`](./configuration/configs.md)
+  - [Git hook](./configuration/Hook.md)
+    - [`files`](./configuration/files-global.md)
+    - [`parallel`](./configuration/parallel.md)
+    - [`piped`](./configuration/piped.md)
+    - [`follow`](./configuration/follow.md)
+    - [`exclude_tags`](./configuration/exclude_tags.md)
+    - [`skip`](./configuration/skip.md)
+    - [`only`](./configuration/only.md)
+    - [`commands`](./configuration/Commands.md)
+      - [`run`](./configuration/run.md)
+      - [`skip`](./configuration/skip.md)
+      - [`only`](./configuration/only.md)
+      - [`tags`](./configuration/tags.md)
+      - [`glob`](./configuration/glob.md)
+      - [`files`](./configuration/files.md)
+      - [`file_types`](./configuration/file_types.md)
+      - [`env`](./configuration/env.md)
+      - [`root`](./configuration/root.md)
+      - [`exclude`](./configuration/exclude.md)
+      - [`fail_text`](./configuration/fail_text.md)
+      - [`stage_fixed`](./configuration/stage_fixed.md)
+      - [`interactive`](./configuration/interactive.md)
+      - [`use_stdin`](./configuration/use_stdin.md)
+      - [`priority`](./configuration/priority.md)
+    - [`scripts`](./configuration/Scripts.md)
+      - [`runner`](./configuration/runner.md)
+      - [`skip`](./configuration/skip.md)
+      - [`only`](./configuration/only.md)
+      - [`tags`](./configuration/tags.md)
+      - [`env`](./configuration/env.md)
+      - [`fail_text`](./configuration/fail_text.md)
+      - [`stage_fixed`](./configuration/stage_fixed.md)
+      - [`interactive`](./configuration/interactive.md)
+      - [`use_stdin`](./configuration/use_stdin.md)
+      - [`priority`](./configuration/priority.md)
+- [Usage](./usage.md)
+  - [Commands](./usage/commands.md)
+  - [ENV variables](./usage/env.md)
+  - [Tips](./usage/tips.md)

docs/mdbook/configuration/Commands.md

@@ -0,0 +1,32 @@
+### `commands`
+
+Commands to be executed for the hook. Each command has a name and associated run [options](#command).
+
+**Example**
+
+```yml
+# lefthook.yml
+
+pre-commit:
+  commands:
+    lint:
+      ... # command options
+```
+
+### Command options
+
+- [`run`](./run.md)
+- [`skip`](./skip.md)
+- [`only`](./only.md)
+- [`tags`](./tags.md)
+- [`glob`](./glob.md)
+- [`files`](./files.md)
+- [`file_types`](./file_types.md)
+- [`env`](./env.md)
+- [`root`](./root.md)
+- [`exclude`](./exclude.md)
+- [`fail_text`](./fail_text.md)
+- [`stage_fixed`](./stage_fixed.md)
+- [`interactive`](./interactive.md)
+- [`use_stdin`](./use_stdin.md)
+- [`priority`](./priority.md)

docs/mdbook/configuration/Hook.md

@@ -0,0 +1,40 @@
+## Git hook
+
+Contains settings for the git hook (commands, scripts, skip rules, etc.). You can specify any Git hook or your own custom, e.g. `test`
+
+### Hook options
+
+- [`files`](./files-global.md)
+- [`parallel`](./parallel.md)
+- [`piped`](./piped.md)
+- [`follow`](./follow.md)
+- [`exclude_tags`](./exclude_tags.md)
+- [`skip`](./skip.md)
+- [`only`](./only.md)
+- [`commands`](./Commands.md)
+  - [`run`](./run.md)
+  - [`skip`](./skip.md)
+  - [`only`](./only.md)
+  - [`tags`](./tags.md)
+  - [`glob`](./glob.md)
+  - [`files`](./files.md)
+  - [`file_types`](./file_types.md)
+  - [`env`](./env.md)
+  - [`root`](./root.md)
+  - [`exclude`](./exclude.md)
+  - [`fail_text`](./fail_text.md)
+  - [`stage_fixed`](./stage_fixed.md)
+  - [`interactive`](./interactive.md)
+  - [`use_stdin`](./use_stdin.md)
+  - [`priority`](./priority.md)
+- [`scripts`](./Scripts.md)
+  - [`runner`](./runner.md)
+  - [`skip`](./skip.md)
+  - [`only`](./only.md)
+  - [`tags`](./tags.md)
+  - [`env`](./env.md)
+  - [`fail_text`](./fail_text.md)
+  - [`stage_fixed`](./stage_fixed.md)
+  - [`interactive`](./interactive.md)
+  - [`use_stdin`](./use_stdin.md)
+  - [`priority`](./priority.md)

docs/mdbook/configuration/README.md

@@ -0,0 +1,53 @@
+# Config options
+
+- [`assert_lefthook_installed`](./assert_lefthook_installed.md)
+- [`colors`](./colors.md)
+- [`no_tty`](./no_tty.md)
+- [`extends`](./extends.md)
+- [`min_version`](./min_version.md)
+- [`output`](./output.md)
+- [`skip_output`](./skip_output.md)
+- [`source_dir`](./source_dir.md)
+- [`source_dir_local`](./source_dir_local.md)
+- [`rc`](./rc.md)
+- [`remotes`](./remotes.md)
+  - [`git_url`](./git_url.md)
+  - [`ref`](./ref.md)
+  - [`refetch`](./refetch.md)
+  - [`refetch_frequency`](./refetch_frequency.md)
+  - [`configs`](./configs.md)
+- [Git hook](./Hook.md)
+  - [`files` (global)](./files-global.md)
+  - [`parallel`](./parallel.md)
+  - [`piped`](./piped.md)
+  - [`follow`](./follow.md)
+  - [`exclude_tags`](./exclude_tags.md)
+  - [`skip`](./skip.md)
+  - [`only`](./only.md)
+  - [`commands`](./Commands.md)
+    - [`run`](./run.md)
+    - [`skip`](./skip.md)
+    - [`only`](./only.md)
+    - [`tags`](./tags.md)
+    - [`glob`](./glob.md)
+    - [`files`](./files.md)
+    - [`file_types`](./file_types.md)
+    - [`env`](./env.md)
+    - [`root`](./root.md)
+    - [`exclude`](./exclude.md)
+    - [`fail_text`](./fail_text.md)
+    - [`stage_fixed`](./stage_fixed.md)
+    - [`interactive`](./interactive.md)
+    - [`use_stdin`](./use_stdin.md)
+    - [`priority`](./priority.md)
+  - [`scripts`](./Scripts.md)
+    - [`runner`](./runner.md)
+    - [`skip`](./skip.md)
+    - [`only`](./only.md)
+    - [`tags`](./tags.md)
+    - [`env`](./env.md)
+    - [`fail_text`](./fail_text.md)
+    - [`stage_fixed`](./stage_fixed.md)
+    - [`interactive`](./interactive.md)
+    - [`use_stdin`](./use_stdin.md)
+    - [`priority`](./priority.md)

docs/mdbook/configuration/Scripts.md

@@ -0,0 +1,58 @@
+## Scripts
+
+Scripts are stored under `<source_dir>/<hook-name>/` folder. These scripts are your own executables which are being run in the project root.
+
+To add a script for a `pre-commit` hook:
+
+1. Run `lefthook add -d pre-commit`
+1. Edit `.lefthook/pre-commit/my-script.sh`
+1. Add an entry to `lefthook.yml`
+   ```yml
+   # lefthook.yml
+
+   pre-commit:
+     scripts:
+       "my-script.sh":
+         runner: bash
+   ```
+
+**Example**
+
+Let's create a bash script to check commit templates `.lefthook/commit-msg/template_checker`:
+
+```bash
+INPUT_FILE=$1
+START_LINE=`head -n1 $INPUT_FILE`
+PATTERN="^(TICKET)-[[:digit:]]+: "
+if ! [[ "$START_LINE" =~ $PATTERN ]]; then
+  echo "Bad commit message, see example: TICKET-123: some text"
+  exit 1
+fi
+```
+
+Now we can ask lefthook to run our bash script by adding this code to
+`lefthook.yml` file:
+
+```yml
+# lefthook.yml
+
+commit-msg:
+  scripts:
+    "template_checker":
+      runner: bash
+```
+
+When you try to commit `git commit -m "bad commit text"` script `template_checker` will be executed. Since commit text doesn't match the described pattern the commit process will be interrupted.
+
+### Script options
+
+- [`runner`](./runner.md)
+- [`skip`](./skip.md)
+- [`only`](./only.md)
+- [`tags`](./tags.md)
+- [`env`](./env.md)
+- [`fail_text`](./fail_text.md)
+- [`stage_fixed`](./stage_fixed.md)
+- [`interactive`](./interactive.md)
+- [`use_stdin`](./use_stdin.md)
+- [`priority`](./priority.md)

docs/mdbook/configuration/assert_lefthook_installed.md

@@ -0,0 +1,5 @@
+# `assert_lefthook_installed`
+
+**Default: `false`**
+
+When set to `true`, fail (with exit status 1) if `lefthook` executable can't be found in $PATH, under node_modules/, as a Ruby gem, or other supported method. This makes sure git hook won't omit `lefthook` rules if `lefthook` ever was installed.

docs/mdbook/configuration/colors.md

@@ -0,0 +1,29 @@
+### `colors`
+
+**Default: `auto`**
+
+Whether enable or disable colorful output of Lefthook. This option can be overwritten with `--colors` option. You can also provide your own color codes.
+
+**Example**
+
+Disable colors.
+
+```yml
+# lefthook.yml
+
+colors: false
+```
+
+Custom color codes. Can be hex or ANSI codes.
+
+```yml
+# lefthook.yml
+
+colors:
+  cyan: 14
+  gray: 244
+  green: '#32CD32'
+  red: '#FF1493'
+  yellow: '#F0E68C'
+```
+

docs/mdbook/configuration/configs.md

@@ -0,0 +1,40 @@
+### `configs`
+
+**Default:** `[lefthook.yml]`
+
+An optional array of config paths from remote's root.
+
+**Example**
+
+```yml
+# lefthook.yml
+
+remotes:
+  - git_url: [email protected]:evilmartians/lefthook
+    ref: v1.0.0
+    configs:
+      - examples/ruby-linter.yml
+      - examples/test.yml
+```
+
+Example with multiple remotes merging multiple configurations.
+
+```yml
+# lefthook.yml
+
+remotes:
+  - git_url: [email protected]:org/lefthook-configs
+    ref: v1.0.0
+    configs:
+      - examples/ruby-linter.yml
+      - examples/test.yml
+  - git_url: https://github.com/org2/lefthook-configs
+    configs:
+      - lefthooks/pre_commit.yml
+      - lefthooks/post_merge.yml
+  - git_url: https://github.com/org3/lefthook-configs
+    ref: feature/new
+    configs:
+      - configs/pre-push.yml
+
+```