docs: add more examples (#898)

docs/mdbook/SUMMARY.md

@@ -24,7 +24,7 @@
 
 # Reference guide
 
-- [Config options](./configuration/README.md)
+- [Configuration](./configuration/README.md)
   - [`assert_lefthook_installed`](./configuration/assert_lefthook_installed.md)
   - [`colors`](./configuration/colors.md)
   - [`no_tty`](./configuration/no_tty.md)
@@ -35,13 +35,14 @@
   - [`source_dir`](./configuration/source_dir.md)
   - [`source_dir_local`](./configuration/source_dir_local.md)
   - [`rc`](./configuration/rc.md)
+  - [`skip_lfs`](./configuration/skip_lfs.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)
+  - [{Git hook name}](./configuration/Hook.md)
     - [`files`](./configuration/files-global.md)
     - [`parallel`](./configuration/parallel.md)
     - [`piped`](./configuration/piped.md)
@@ -77,7 +78,9 @@
       - [`use_stdin`](./configuration/use_stdin.md)
       - [`priority`](./configuration/priority.md)
 - [Examples](./examples/README.md)
-  - [Commitlint](./examples/commitlint.md)
-  - [Remotes](./examples/remotes.md)
+  - [lefthook-local.yml](./examples/lefthook-local.md)
   - [Auto stage changed files](./examples/stage_fixed.md)
   - [Filter files](./examples/filters.md)
+  - [Skip or run on condition](./examples/skip.md)
+  - [Use remote config](./examples/remotes.md)
+  - [Use commitlint](./examples/commitlint.md)

docs/mdbook/configuration/README.md

@@ -27,13 +27,14 @@ Lefthook also merges an extra config with the name `lefthook-local`. All support
 - [`source_dir`](./source_dir.md)
 - [`source_dir_local`](./source_dir_local.md)
 - [`rc`](./rc.md)
+- [`skip_lfs`](./skip_lfs.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)
+- [{Git hook name}](./Hook.md) (e.g. `pre-commit`)
   - [`files` (global)](./files-global.md)
   - [`parallel`](./parallel.md)
   - [`piped`](./piped.md)

docs/mdbook/configuration/skip_lfs.md

@@ -0,0 +1,18 @@
+## `skip_lfs`
+
+**Default:** `false`
+
+Skip running LFS hooks even if it exists on your system.
+
+### Example
+
+```yml
+# lefthook.yml
+
+skip_lfs: true
+
+pre-push:
+  commands:
+    test:
+      run: yarn test
+```

docs/mdbook/examples/commitlint.md

@@ -1,21 +1,24 @@
 ## Commitlint and commitzen
 
-> Use lefthook to generate commit messages using commitzen and validate them with commitlint.
+Use lefthook to generate commit messages using commitzen and validate them with commitlint.
 
 ## Install dependencies
 
 ```bash
 yarn add -D @commitlint/cli @commitlint/config-conventional
-# If using commitzen
+
+# For commitzen
 yarn add -D commitizen cz-conventional-changelog
 ```
 
 ## Configure
 
 Setup `commitlint.config.js`. Conventional configuration:
 
-```bash
-echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
+```js
+// commitlint.config.js
+
+module.exports = {extends: ['@commitlint/config-conventional']};
 ```
 
 If you are using commitzen, make sure to add this in `package.json`:
@@ -28,22 +31,12 @@ If you are using commitzen, make sure to add this in `package.json`:
 }
 ```
 
-## Test it
-
-```bash
-# You can type it without message, if you are using commitzen
-git commit
-
-# Or provide a commit message is using only commitlint
-git commit -am 'fix: typo'
-```
-
----
+Configure lefthook:
 
 ```yml
 # lefthook.yml
 
-# Use this to build commit messages
+# Build commit messages
 prepare-commit-msg:
   commands:
     commitzen:
@@ -52,15 +45,20 @@ prepare-commit-msg:
       env:
         LEFTHOOK: 0
 
-# Use this to validate commit messages
+# Validate commit messages
 commit-msg:
   commands:
     "lint commit message":
       run: yarn run commitlint --edit {1}
 ```
 
-```js
-# commitlint.config.js
 
-module.exports = {extends: ['@commitlint/config-conventional']};
+## Test it
+
+```bash
+# You can type it without message, if you are using commitzen
+git commit
+
+# Or provide a commit message is using only commitlint
+git commit -am 'fix: typo'
 ```

docs/mdbook/examples/lefthook-local.md

@@ -0,0 +1,86 @@
+## lefthook-local.yml
+
+`lefthook-local.yml` overrides and extends the configuration of your main `lefthook.yml` (or `lefthook.toml`, [etc.](../configuration)) file.
+
+> **Tip:** You can put `lefthook-local.yml` into your `~/.gitignore`, so in every project you can have your local-only overrides.
+
+*Special feature* of `lefthook-local.yml`: you can wrap the commands using `{cmd}` template.
+
+```yml
+# lefthook.yml
+
+pre-commit:
+  commands:
+    lint-frontend:
+      run: yarn lint
+      glob: ".{ts,tsx}"
+    lint-backend:
+      run: bundle exec rubocop {staged_files}
+      glob: "*.rb"
+    test-frontend:
+      run: yarn test
+      glob: "*.tsx"
+    test-backend:
+      run: bundle exec rspec
+      glob: "spec/*"
+    check-typos:
+      run: typos {staged_files}
+    check-links:
+      run: lychee {staged_files}
+```
+
+```yml
+# lefthook-local.yml
+
+pre-commit:
+  parallel: true # run all commands concurrently
+  commands:
+    lint-backend:
+      run: docker-compose run backend {cmd} # wrap the original command with docker-compose
+    test-backend:
+      run: docker-compose run backend {cmd}
+    check-links:
+      skip: true # skip checking links
+
+# Add another hook
+post-merge:
+  files: "git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD"
+  commands:
+    dependencies:
+      glob: "Gemfile*"
+      run: docker-compose run backend bundle install
+```
+
+---
+
+```yml
+# The resulting config would look like this
+
+pre-commit:
+  parallel: true
+  commands:
+    lint-frontend:
+      run: yarn lint
+      glob: "*.{ts,tsx}"
+    lint-backend:
+      run: docker-compose run backend bundle exec rubocop {staged_files}
+      glob: "*.rb"
+    test-frontend:
+      run: yarn test
+      glob: "*.tsx"
+    test-backend:
+      run: docker-compose run backend bundle exec rspec
+      glob: "spec/*"
+    check-links:
+      run: lychee {staged_files}
+      skip: true
+    check-typos:
+      run: typos {staged_files}
+
+post-merge:
+  files: "git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD"
+  commands:
+    dependencies:
+      glob: "Gemfile*"
+      run: docker-compose run backend bundle install
+```

docs/mdbook/examples/remotes.md

@@ -1,8 +1,8 @@
 ## Remotes
 
-> Use configurations from other Git repositories via `remotes` feature.
->
-> Lefthook will automatically download the remote config files and merge them into existing configuration.
+Use configurations from other Git repositories via `remotes` feature.
+
+Lefthook will automatically download the remote config files and merge them into existing configuration.
 
 ```yml
 remotes:

docs/mdbook/examples/skip.md

@@ -0,0 +1,34 @@
+## Skip or run on condition
+
+Here are two hooks.
+
+`pre-commit` hook will only be executed when you're committing something on a branch starting with `def/` prefix.
+
+In `pre-push` hook:
+- `test` command will be skipped if `NO_TEST` env variable is set to `1`
+- `lint` command will only be executed if you're pushing the `main` branch
+
+```yml
+# lefthook.yml
+
+pre-commit:
+  only:
+    - ref: dev/*
+  commands:
+    lint:
+      run: yarn lint {staged_files} --fix
+      glob: "*.{ts,js}"
+    test:
+      run: yarn test
+
+pre-push:
+  commands:
+    test:
+      run: yarn test
+      skip:
+        - run: test "$NO_TEST" -eq 1
+    lint:
+      run: yarn lint
+      only:
+        - ref: main
+```

docs/mdbook/installation/arch.md

@@ -1,6 +1,6 @@
 ## AUR for Arch
 
-You can install lefthook [package](https://aur.archlinux.org/packages/lefthook) from AUR.
+[AUR package](https://aur.archlinux.org/packages/lefthook)
 
 ```sh
 yay -S lefthook

docs/mdbook/installation/manual.md

@@ -1,6 +1,6 @@
 ## Manuall installation with prebuilt executable
 
-Or take it from [binaries](https://github.com/evilmartians/lefthook/releases) and install manually.
+Download from [binaries](https://github.com/evilmartians/lefthook/releases) and install manually.
 
 1. Download the executable for your OS and Arch
 1. Put the executable under the $PATH (for unix systems)

docs/mdbook/usage/commands.md

@@ -1,16 +1,12 @@
 ## Commands
 
-> **tip**
->
-> Use `lefthook help` or `lefthook <command> -h/--help` to discover available commands and their options
+> **Tip:** Use `lefthook help` or `lefthook <command> -h/--help` to discover available commands and their options
 
 ### `lefthook install`
 
 `lefthook install` creates an empty `lefthook.yml` if a configuration file does not exist and updates git hooks to use lefthook. Run `lefthook install` after cloning the git repo.
 
-> **note**
->
-> NPM package `lefthook` installs the hooks in a postinstall script automatically.
+> **Note:** NPM package `lefthook` installs the hooks in a postinstall script automatically
 
 ### `lefthook uninstall`
 

docs/mdbook/usage/env.md

@@ -1,6 +1,6 @@
 ## ENV variables
 
-> ENV variables can be used to control lefthook behavior. Most of them have the alternative CLI or config options.
+> ENV variables control some lefthook behavior. Most of them have the alternative CLI or config options.
 
 ### `LEFTHOOK`
 

docs/mdbook/usage/tips.md

@@ -110,7 +110,7 @@ SHA1=$3
 
 ### Git LFS support
 
-> If git-lfs binary is not installed and not required in your project, LFS hooks won't be executed, and you won't be warned about it.
+> **Note:** If git-lfs binary is not installed and not required in your project, LFS hooks won't be executed, and you won't be warned about it.
 
 Lefthook runs LFS hooks internally for the following hooks:
 
@@ -121,6 +121,8 @@ Lefthook runs LFS hooks internally for the following hooks:
 
 Errors are suppressed if git LFS is not required for the project. You can use [`LEFTHOOK_VERBOSE`](./env.md#lefthook_verbose) ENV to make lefthook show git LFS output.
 
+To avoid using LFS set [`skip_lfs: true`](../configuration/skip_lfs.md) in lefthook.yml or lefthook-local.yml
+
 ### Pass stdin to a command or script
 
 When you need to read the data from stdin – specify [`use_stdin: true`](../configuration/use_stdin.md). This option is good when you write a command or script that receives data from git using stdin (for the `pre-push` hook, for example).