chore: add mdbook

.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,72 @@
+# 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` (global)](./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)

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,2 @@
+## Git hook
+

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
+
+```

docs/mdbook/configuration/env.md

@@ -0,0 +1,43 @@
+### `env`
+
+You can specify some ENV variables for the command or script.
+
+**Example**
+
+```yml
+# lefthook.yml
+
+pre-commit:
+  commands:
+    test:
+      env:
+        RAILS_ENV: test
+      run: bundle exec rspec
+```
+
+#### Extending PATH
+
+If your hook is run by GUI program, and you use some PATH tweaks in your ~/.<shell>rc, you might see an error saying *executable not found*. In that case You can extend the **$PATH** variable with `lefthook-local.yml` configuration the following way.
+
+```yml
+# lefthook.yml
+
+pre-commit:
+  commands:
+    test:
+      run: yarn test
+```
+
+```yml
+# lefthook-local.yml
+
+pre-commit:
+  commands:
+    test:
+      env:
+        PATH: $PATH:/home/me/path/to/yarn
+```
+
+**Notes**
+
+This option is useful when using lefthook on different OSes or shells where ENV variables are set in different ways.