From bc0e9257d3fac8429fa3f60bb87f5c4c96d41947 Mon Sep 17 00:00:00 2001 From: Valentin Kiselev Date: Wed, 18 Dec 2024 11:39:04 +0300 Subject: [PATCH 1/3] docs: improve mdbook docs --- docs/mdbook/SUMMARY.md | 22 +++++-- docs/mdbook/configuration/Commands.md | 2 +- docs/mdbook/configuration/README.md | 19 +++++- .../assert_lefthook_installed.md | 2 +- docs/mdbook/configuration/colors.md | 2 +- docs/mdbook/configuration/configs.md | 2 +- docs/mdbook/configuration/env.md | 2 +- docs/mdbook/configuration/exclude.md | 8 +-- docs/mdbook/configuration/exclude_tags.md | 2 +- docs/mdbook/configuration/extends.md | 2 +- docs/mdbook/configuration/fail_text.md | 2 +- docs/mdbook/configuration/file_types.md | 6 +- docs/mdbook/configuration/files-global.md | 2 +- docs/mdbook/configuration/files.md | 2 +- docs/mdbook/configuration/follow.md | 6 +- docs/mdbook/configuration/git_url.md | 2 +- docs/mdbook/configuration/glob.md | 2 +- docs/mdbook/configuration/interactive.md | 6 +- docs/mdbook/configuration/min_version.md | 2 +- docs/mdbook/configuration/no_tty.md | 2 +- docs/mdbook/configuration/only.md | 6 +- docs/mdbook/configuration/output.md | 2 +- docs/mdbook/configuration/parallel.md | 6 +- docs/mdbook/configuration/piped.md | 6 +- docs/mdbook/configuration/priority.md | 6 +- docs/mdbook/configuration/rc.md | 2 +- docs/mdbook/configuration/ref.md | 6 +- docs/mdbook/configuration/refetch.md | 2 +- .../mdbook/configuration/refetch_frequency.md | 2 +- docs/mdbook/configuration/root.md | 2 +- docs/mdbook/configuration/run.md | 6 +- docs/mdbook/configuration/runner.md | 2 +- docs/mdbook/configuration/skip.md | 2 +- docs/mdbook/configuration/skip_output.md | 2 +- docs/mdbook/configuration/source_dir.md | 2 +- docs/mdbook/configuration/source_dir_local.md | 2 +- docs/mdbook/configuration/stage_fixed.md | 4 +- docs/mdbook/configuration/tags.md | 2 +- docs/mdbook/configuration/use_stdin.md | 6 +- docs/mdbook/examples/README.md | 6 ++ docs/mdbook/examples/commitlint.md | 66 +++++++++++++++++++ docs/mdbook/examples/filters.md | 42 ++++++++++++ docs/mdbook/examples/remotes.md | 12 ++++ docs/mdbook/examples/stage_fixed.md | 15 +++++ docs/mdbook/file_name.md | 17 ----- docs/mdbook/install.md | 20 ------ docs/mdbook/installation/README.md | 18 +++++ docs/mdbook/installation/node.md | 3 +- docs/mdbook/intro.md | 21 ++++++ docs/mdbook/usage.md | 28 -------- docs/mdbook/usage/README.md | 29 ++++++++ docs/mdbook/usage/commands.md | 6 +- docs/mdbook/usage/env.md | 2 + docs/mdbook/usage/tips.md | 2 + 54 files changed, 302 insertions(+), 148 deletions(-) create mode 100644 docs/mdbook/examples/README.md create mode 100644 docs/mdbook/examples/commitlint.md create mode 100644 docs/mdbook/examples/filters.md create mode 100644 docs/mdbook/examples/remotes.md create mode 100644 docs/mdbook/examples/stage_fixed.md delete mode 100644 docs/mdbook/file_name.md delete mode 100644 docs/mdbook/install.md create mode 100644 docs/mdbook/installation/README.md create mode 100644 docs/mdbook/intro.md delete mode 100644 docs/mdbook/usage.md create mode 100644 docs/mdbook/usage/README.md diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md index 53902c8c..42c91238 100644 --- a/docs/mdbook/SUMMARY.md +++ b/docs/mdbook/SUMMARY.md @@ -1,8 +1,10 @@ # Lefthook +[Introduction](./intro.md) + # User guide -- [Installation](./install.md) +- [Installation](./installation/README.md) - [Ruby](./installation/ruby.md) - [Node.js](./installation/node.md) - [Go](./installation/go.md) @@ -17,7 +19,14 @@ - [Alpine](./installation/alpine.md) - [Arch Linux](./installation/arch.md) - [Manual](./installation/manual.md) -- [Configuration](./configuration/README.md) +- [Usage](./usage/README.md) + - [Commands](./usage/commands.md) + - [ENV variables](./usage/env.md) + - [Tips](./usage/tips.md) + +# Reference guide + +- [Config options](./configuration/README.md) - [`assert_lefthook_installed`](./configuration/assert_lefthook_installed.md) - [`colors`](./configuration/colors.md) - [`no_tty`](./configuration/no_tty.md) @@ -69,7 +78,8 @@ - [`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) +- [Examples](./examples/README.md) + - [Commitlint](./examples/commitlint.md) + - [Remotes](./examples/remotes.md) + - [Auto stage changed files](./examples/stage_fixed.md) + - [Filter files](./examples/filters.md) diff --git a/docs/mdbook/configuration/Commands.md b/docs/mdbook/configuration/Commands.md index ef4c216e..6d2ba6b8 100644 --- a/docs/mdbook/configuration/Commands.md +++ b/docs/mdbook/configuration/Commands.md @@ -1,4 +1,4 @@ -### `commands` +## `commands` Commands to be executed for the hook. Each command has a name and associated run [options](#command). diff --git a/docs/mdbook/configuration/README.md b/docs/mdbook/configuration/README.md index c7095ea4..69e34b7b 100644 --- a/docs/mdbook/configuration/README.md +++ b/docs/mdbook/configuration/README.md @@ -1,4 +1,21 @@ -# Config options +## Config file name + +Lefthook supports the following file names for the main config: + +- `lefthook.yml` +- `.lefthook.yml` +- `lefthook.yaml` +- `.lefthook.yaml` +- `lefthook.toml` +- `.lefthook.toml` +- `lefthook.json` +- `.lefthook.json` + +If there are more than 1 file in the project, only one will be used, and you'll never know which one. So, please, use one format in a project. + +Lefthook also merges an extra config with the name `lefthook-local`. All supported formats can be applied to this `-local` config. If you name your main config with the leading dot, like `.lefthook.json`, the `-local` config also must be named with the leading dot: `.lefthook-local.json`. + +## Options - [`assert_lefthook_installed`](./assert_lefthook_installed.md) - [`colors`](./colors.md) diff --git a/docs/mdbook/configuration/assert_lefthook_installed.md b/docs/mdbook/configuration/assert_lefthook_installed.md index ace5a136..f22e54b9 100644 --- a/docs/mdbook/configuration/assert_lefthook_installed.md +++ b/docs/mdbook/configuration/assert_lefthook_installed.md @@ -1,4 +1,4 @@ -# `assert_lefthook_installed` +## `assert_lefthook_installed` **Default: `false`** diff --git a/docs/mdbook/configuration/colors.md b/docs/mdbook/configuration/colors.md index 204828b8..fdbe0048 100644 --- a/docs/mdbook/configuration/colors.md +++ b/docs/mdbook/configuration/colors.md @@ -1,4 +1,4 @@ -### `colors` +## `colors` **Default: `auto`** diff --git a/docs/mdbook/configuration/configs.md b/docs/mdbook/configuration/configs.md index 2b93172c..48fbfdd7 100644 --- a/docs/mdbook/configuration/configs.md +++ b/docs/mdbook/configuration/configs.md @@ -1,4 +1,4 @@ -### `configs` +## `configs` **Default:** `[lefthook.yml]` diff --git a/docs/mdbook/configuration/env.md b/docs/mdbook/configuration/env.md index 3b1aa88b..212af511 100644 --- a/docs/mdbook/configuration/env.md +++ b/docs/mdbook/configuration/env.md @@ -1,4 +1,4 @@ -### `env` +## `env` You can specify some ENV variables for the command or script. diff --git a/docs/mdbook/configuration/exclude.md b/docs/mdbook/configuration/exclude.md index ed714563..278b930b 100644 --- a/docs/mdbook/configuration/exclude.md +++ b/docs/mdbook/configuration/exclude.md @@ -1,4 +1,4 @@ -### `exclude` +## `exclude` For the `exclude` option two variants are supported: @@ -6,9 +6,7 @@ For the `exclude` option two variants are supported: - A single regular expression (deprecated) -> NOTE -> -> The regular expression is matched against full paths to files in the repo, +> **Note:** The regular expression is matched against full paths to files in the repo, > relative to the repo root, using `/` as the directory separator on all platforms. > File paths do not begin with the separator or any other prefix. @@ -44,7 +42,7 @@ pre-commit: run: bundle exec rubocop --force-exclusion {staged_files} ``` -**Notes** +**Important** Be careful with the config file format's string quoting and escaping rules when writing regexps in it. For YAML, single quotes are often the simplest choice. diff --git a/docs/mdbook/configuration/exclude_tags.md b/docs/mdbook/configuration/exclude_tags.md index 671c639d..bc256564 100644 --- a/docs/mdbook/configuration/exclude_tags.md +++ b/docs/mdbook/configuration/exclude_tags.md @@ -1,4 +1,4 @@ -### `exclude_tags` +## `exclude_tags` [Tags](./tags.md) or command names that you want to exclude. This option can be overwritten with `LEFTHOOK_EXCLUDE` env variable. diff --git a/docs/mdbook/configuration/extends.md b/docs/mdbook/configuration/extends.md index 9b66f4f3..b67fc822 100644 --- a/docs/mdbook/configuration/extends.md +++ b/docs/mdbook/configuration/extends.md @@ -1,4 +1,4 @@ -### `extends` +## `extends` You can extend your config with another one YAML file. Its content will be merged. Extends for `lefthook.yml`, `lefthook-local.yml`, and [`remotes`](./remotes.md) configs are handled separately, so you can have different extends in these files. diff --git a/docs/mdbook/configuration/fail_text.md b/docs/mdbook/configuration/fail_text.md index 3173762f..175773b9 100644 --- a/docs/mdbook/configuration/fail_text.md +++ b/docs/mdbook/configuration/fail_text.md @@ -1,4 +1,4 @@ -### `fail_text` +## `fail_text` You can specify a text to show when the command or script fails. diff --git a/docs/mdbook/configuration/file_types.md b/docs/mdbook/configuration/file_types.md index 7f5f1c76..f371aa35 100644 --- a/docs/mdbook/configuration/file_types.md +++ b/docs/mdbook/configuration/file_types.md @@ -1,4 +1,4 @@ -### `file_types` +## `file_types` Filter files in a [`run`](./run.md) templates by their type. Supported types: @@ -11,9 +11,7 @@ Filter files in a [`run`](./run.md) templates by their type. Supported types: |`symlink` | A symlink file. | |`not symlink` | Any non-symlink file. | -> IMPORTANT -> -> When passed multiple file types all constraints will be applied to the resulting list of files. +> **Important:** When passed multiple file types all constraints will be applied to the resulting list of files **Examples** diff --git a/docs/mdbook/configuration/files-global.md b/docs/mdbook/configuration/files-global.md index edc60e19..b882cbec 100644 --- a/docs/mdbook/configuration/files-global.md +++ b/docs/mdbook/configuration/files-global.md @@ -1,4 +1,4 @@ -### `files` (global) +## `files` (global) A custom git command for files to be referenced in `{files}` template. See [`run`](#run) and [`files`](#files). diff --git a/docs/mdbook/configuration/files.md b/docs/mdbook/configuration/files.md index 490b3763..ede33f66 100644 --- a/docs/mdbook/configuration/files.md +++ b/docs/mdbook/configuration/files.md @@ -1,4 +1,4 @@ -### `files` +## `files` A custom git command for files or directories to be referenced in `{files}` template for [`run`](./run.md) setting. diff --git a/docs/mdbook/configuration/follow.md b/docs/mdbook/configuration/follow.md index 85338784..adc71afb 100644 --- a/docs/mdbook/configuration/follow.md +++ b/docs/mdbook/configuration/follow.md @@ -1,4 +1,4 @@ -### `follow` +## `follow` **Default: `false`** @@ -18,6 +18,4 @@ pre-push: run: yarn test ``` -> NOTE -> -> If used with [`parallel`](#parallel) the output can be a mess, so please avoid setting both options to `true`. +> **Note:** If used with [`parallel`](#parallel) the output can be a mess, so please avoid setting both options to `true` diff --git a/docs/mdbook/configuration/git_url.md b/docs/mdbook/configuration/git_url.md index 9a45b7b7..7b6556f9 100644 --- a/docs/mdbook/configuration/git_url.md +++ b/docs/mdbook/configuration/git_url.md @@ -1,4 +1,4 @@ -### `git_url` +## `git_url` A URL to Git repository. It will be accessed with privileges of the machine lefthook runs on. diff --git a/docs/mdbook/configuration/glob.md b/docs/mdbook/configuration/glob.md index 2e7a7004..3ad70bb1 100644 --- a/docs/mdbook/configuration/glob.md +++ b/docs/mdbook/configuration/glob.md @@ -1,4 +1,4 @@ -### `glob` +## `glob` You can set a glob to filter files for your command. This is only used if you use a file template in [`run`](./run.md) option or provide your custom [`files`](./files.md) command. diff --git a/docs/mdbook/configuration/interactive.md b/docs/mdbook/configuration/interactive.md index de1e316c..d9ed31fe 100644 --- a/docs/mdbook/configuration/interactive.md +++ b/docs/mdbook/configuration/interactive.md @@ -1,10 +1,8 @@ -### `interactive` +## `interactive` **Default: `false`** -> NOTE -> -> If you want to pass stdin to your command or script but don't need to get the input from CLI, use [`use_stdin`](./use_stdin.md) option instead. +> **Note:** If you want to pass stdin to your command or script but don't need to get the input from CLI, use [`use_stdin`](./use_stdin.md) option instead. Whether to use interactive mode. This applies the certain behavior: diff --git a/docs/mdbook/configuration/min_version.md b/docs/mdbook/configuration/min_version.md index 8de390ce..8b56507d 100644 --- a/docs/mdbook/configuration/min_version.md +++ b/docs/mdbook/configuration/min_version.md @@ -1,4 +1,4 @@ -### `min_version` +## `min_version` If you want to specify a minimum version for lefthook binary (e.g. if you need some features older versions don't have) you can set this option. diff --git a/docs/mdbook/configuration/no_tty.md b/docs/mdbook/configuration/no_tty.md index 470eb034..a4eeeb3b 100644 --- a/docs/mdbook/configuration/no_tty.md +++ b/docs/mdbook/configuration/no_tty.md @@ -1,4 +1,4 @@ -### `no_tty` +## `no_tty` **Default: `false`** diff --git a/docs/mdbook/configuration/only.md b/docs/mdbook/configuration/only.md index b833c7bd..f6ecf093 100644 --- a/docs/mdbook/configuration/only.md +++ b/docs/mdbook/configuration/only.md @@ -1,10 +1,8 @@ -### `only` +## `only` You can force a command, script, or the whole hook to execute only in certain conditions. This option acts like the opposite of [`skip`](./skip.md). It accepts the same values but skips execution only if the condition is not satisfied. -> NOTE -> -> `skip` option takes precedence over `only` option, so if you have conflicting conditions the execution will be skipped. +> **Note:** `skip` option takes precedence over `only` option, so if you have conflicting conditions the execution will be skipped. **Example** diff --git a/docs/mdbook/configuration/output.md b/docs/mdbook/configuration/output.md index 66967219..409fcb2d 100644 --- a/docs/mdbook/configuration/output.md +++ b/docs/mdbook/configuration/output.md @@ -1,4 +1,4 @@ -### `output` +## `output` You can manage verbosity using the `output` config. You can specify what to print in your output by setting these values, which you need to have diff --git a/docs/mdbook/configuration/parallel.md b/docs/mdbook/configuration/parallel.md index c549cb26..384165e1 100644 --- a/docs/mdbook/configuration/parallel.md +++ b/docs/mdbook/configuration/parallel.md @@ -1,9 +1,7 @@ -### `parallel` +## `parallel` **Default: `false`** -> NOTE -> -> Lefthook runs commands and scripts **sequentially** by default. +> **Note:** Lefthook runs commands and scripts **sequentially** by default Run commands and scripts concurrently. diff --git a/docs/mdbook/configuration/piped.md b/docs/mdbook/configuration/piped.md index e660d7f3..21da74d2 100644 --- a/docs/mdbook/configuration/piped.md +++ b/docs/mdbook/configuration/piped.md @@ -1,10 +1,8 @@ -### `piped` +## `piped` **Default: `false`** -> NOTE -> -> Lefthook will return an error if both `piped: true` and `parallel: true` are set. +> **Note:** Lefthook will return an error if both `piped: true` and `parallel: true` are set Stop running commands and scripts if one of them fail. diff --git a/docs/mdbook/configuration/priority.md b/docs/mdbook/configuration/priority.md index 763d5ba5..706d2ad4 100644 --- a/docs/mdbook/configuration/priority.md +++ b/docs/mdbook/configuration/priority.md @@ -1,10 +1,8 @@ -### `priority` +## `priority` **Default: `0`** -> NOTE -> -> This option makes sense only when `parallel: false` or `piped: true` is set. +> **Note:** This option makes sense only when `parallel: false` or `piped: true` is set. > > Value `0` is considered an `+Infinity`, so commands or scripts with `priority: 0` or without this setting will be run at the very end. diff --git a/docs/mdbook/configuration/rc.md b/docs/mdbook/configuration/rc.md index 3d9c5c8f..2b93b4fd 100644 --- a/docs/mdbook/configuration/rc.md +++ b/docs/mdbook/configuration/rc.md @@ -1,4 +1,4 @@ -### `rc` +## `rc` Provide an [**rc**](https://www.baeldung.com/linux/rc-files) file, which is actually a simple `sh` script. Currently it can be used to set ENV variables that are not accessible from non-shell programs. diff --git a/docs/mdbook/configuration/ref.md b/docs/mdbook/configuration/ref.md index b797a66b..5648ad12 100644 --- a/docs/mdbook/configuration/ref.md +++ b/docs/mdbook/configuration/ref.md @@ -1,10 +1,8 @@ -### `ref` +## `ref` An optional *branch* or *tag* name. -> NOTE -> -> If you initially had `ref` option, ran `lefthook install`, and then removed it, lefthook won't decide which branch/tag to use as a ref. So, if you added it once, please, use it always to avoid issues in local setups. +> **Note:** If you initially had `ref` option, ran `lefthook install`, and then removed it, lefthook won't decide which branch/tag to use as a ref. So, if you added it once, please, use it always to avoid issues in local setups. **Example** diff --git a/docs/mdbook/configuration/refetch.md b/docs/mdbook/configuration/refetch.md index cdf45d38..a063c881 100644 --- a/docs/mdbook/configuration/refetch.md +++ b/docs/mdbook/configuration/refetch.md @@ -1,4 +1,4 @@ -### `refetch` +## `refetch` **Default:** `false` diff --git a/docs/mdbook/configuration/refetch_frequency.md b/docs/mdbook/configuration/refetch_frequency.md index b6e10009..87a199b8 100644 --- a/docs/mdbook/configuration/refetch_frequency.md +++ b/docs/mdbook/configuration/refetch_frequency.md @@ -1,4 +1,4 @@ -### `refetch_frequency` +## `refetch_frequency` **Default:** Not set diff --git a/docs/mdbook/configuration/root.md b/docs/mdbook/configuration/root.md index 8d038e5f..b8221910 100644 --- a/docs/mdbook/configuration/root.md +++ b/docs/mdbook/configuration/root.md @@ -1,4 +1,4 @@ -### `root` +## `root` You can change the CWD for the command you execute using `root` option. diff --git a/docs/mdbook/configuration/run.md b/docs/mdbook/configuration/run.md index 05c9c486..06100419 100644 --- a/docs/mdbook/configuration/run.md +++ b/docs/mdbook/configuration/run.md @@ -1,4 +1,4 @@ -### `run` +## `run` This is a mandatory option for a command. This is actually a command that is executed for the hook. @@ -72,9 +72,7 @@ pre-push: Simply run `bundle exec rubocop` on all files with `.rb` extension excluding `application.rb` and `routes.rb` files. -> NOTE -> -> `--force-exclusion` will apply `Exclude` configuration setting of Rubocop. +> **Note:** `--force-exclusion` will apply `Exclude` configuration setting of Rubocop ```yml # lefthook.yml diff --git a/docs/mdbook/configuration/runner.md b/docs/mdbook/configuration/runner.md index 23b3245a..46f6ff86 100644 --- a/docs/mdbook/configuration/runner.md +++ b/docs/mdbook/configuration/runner.md @@ -1,4 +1,4 @@ -### `runner` +## `runner` You should specify a runner for the script. This is a command that should execute a script file. It will be called the following way: ` ` (e.g. `ruby .lefthook/pre-commit/lint.rb`). diff --git a/docs/mdbook/configuration/skip.md b/docs/mdbook/configuration/skip.md index d10d6673..bae5aee8 100644 --- a/docs/mdbook/configuration/skip.md +++ b/docs/mdbook/configuration/skip.md @@ -1,4 +1,4 @@ -### `skip` +## `skip` You can skip all or specific commands and scripts using `skip` option. You can also skip when merging, rebasing, or being on a specific branch. Globs are available for branches. diff --git a/docs/mdbook/configuration/skip_output.md b/docs/mdbook/configuration/skip_output.md index 2c775c89..5dc72fbc 100644 --- a/docs/mdbook/configuration/skip_output.md +++ b/docs/mdbook/configuration/skip_output.md @@ -1,4 +1,4 @@ -### `skip_output` +## `skip_output` > **DEPRECATED** This feature is deprecated and might be removed in future versions. Please, use `[output]` instead for managing verbosity. diff --git a/docs/mdbook/configuration/source_dir.md b/docs/mdbook/configuration/source_dir.md index 4c20fd60..5fda4b52 100644 --- a/docs/mdbook/configuration/source_dir.md +++ b/docs/mdbook/configuration/source_dir.md @@ -1,4 +1,4 @@ -### `source_dir` +## `source_dir` **Default: `.lefthook/`** diff --git a/docs/mdbook/configuration/source_dir_local.md b/docs/mdbook/configuration/source_dir_local.md index 415b1356..745ea615 100644 --- a/docs/mdbook/configuration/source_dir_local.md +++ b/docs/mdbook/configuration/source_dir_local.md @@ -1,4 +1,4 @@ -### `source_dir_local` +## `source_dir_local` **Default: `.lefthook-local/`** diff --git a/docs/mdbook/configuration/stage_fixed.md b/docs/mdbook/configuration/stage_fixed.md index 17ef7c38..52a36c6b 100644 --- a/docs/mdbook/configuration/stage_fixed.md +++ b/docs/mdbook/configuration/stage_fixed.md @@ -1,8 +1,8 @@ -### `stage_fixed` +## `stage_fixed` **Default: `false`** -> Used **only for `pre-commit`** hook. Is ignored for other hooks. +> Works **only for `pre-commit`** hook When set to `true` lefthook will automatically call `git add` on files after running the command or script. For a command if [`files`](./files.md) option was specified, the specified command will be used to retrieve files for `git add`. For scripts and commands without [`files`](./files.md) option `{staged_files}` template will be used. All filters ([`glob`](./glob.md), [`exclude`](./exclude.md)) will be applied if specified. diff --git a/docs/mdbook/configuration/tags.md b/docs/mdbook/configuration/tags.md index 5d8c4212..370c740b 100644 --- a/docs/mdbook/configuration/tags.md +++ b/docs/mdbook/configuration/tags.md @@ -1,4 +1,4 @@ -### `tags` +## `tags` You can specify tags for commands and scripts. This is useful for [excluding](./exclude_tags.md). You can specify more than one tag using comma. diff --git a/docs/mdbook/configuration/use_stdin.md b/docs/mdbook/configuration/use_stdin.md index 17753d32..30c2d216 100644 --- a/docs/mdbook/configuration/use_stdin.md +++ b/docs/mdbook/configuration/use_stdin.md @@ -1,8 +1,6 @@ -### `use_stdin` +## `use_stdin` -> NOTE -> -> With many commands or scripts having `use_stdin: true`, only one will receive the data. The others will have nothing. If you need to pass the data from stdin to every command or script, please, submit a [feature request](https://github.com/evilmartians/lefthook/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.md). +> **Note:** With many commands or scripts having `use_stdin: true`, only one will receive the data. The others will have nothing. If you need to pass the data from stdin to every command or script, please, submit a [feature request](https://github.com/evilmartians/lefthook/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.md). Pass the stdin from the OS to the command/script. diff --git a/docs/mdbook/examples/README.md b/docs/mdbook/examples/README.md new file mode 100644 index 00000000..ce0ab8bb --- /dev/null +++ b/docs/mdbook/examples/README.md @@ -0,0 +1,6 @@ +# Examples + +- [Commitlint](./commitlint.md) +- [Remotes](./remotes.md) +- [Auto stage changed files](./stage_fixed.md) +- [Filter files](./filters.md) diff --git a/docs/mdbook/examples/commitlint.md b/docs/mdbook/examples/commitlint.md new file mode 100644 index 00000000..08d63861 --- /dev/null +++ b/docs/mdbook/examples/commitlint.md @@ -0,0 +1,66 @@ +## Commitlint and commitzen + +> 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 +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 +``` + +If you are using commitzen, make sure to add this in `package.json`: + +```json +"config": { + "commitizen": { + "path": "./node_modules/cz-conventional-changelog" + } +} +``` + +## 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' +``` + +--- + +```yml +# lefthook.yml + +# Use this to build commit messages +prepare-commit-msg: + commands: + commitzen: + interactive: true + run: yarn run cz --hook # Or npx cz --hook + env: + LEFTHOOK: 0 + +# Use this to 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']}; +``` diff --git a/docs/mdbook/examples/filters.md b/docs/mdbook/examples/filters.md new file mode 100644 index 00000000..a78c3bc1 --- /dev/null +++ b/docs/mdbook/examples/filters.md @@ -0,0 +1,42 @@ +## Filters + +Files passed to your hooks can be filtered with the following options + +- [`glob`](../configuration/glob.md) +- [`exclude`](../configuration/exclude.md) +- [`file_types`](../configuration/file_types.md) +- [`root`](../configuration/root.md) + +In this example all **staged files** will pass through these filters. + +```yml +# lefthook.yml + +pre-commit: + commands: + lint: + run: yarn lint {staged_files} --fix + glob: "*.{js,ts}" + root: frontend + exclude: + - *.config.js + - *.config.ts + file_types: + - not executable +``` + +Imagine you've staged the following files + +```bash +backend/asset.js +frontend/src/index.ts +frontend/bin/cli.js # <- executable +frontend/eslint.config.js +frontend/README.md +``` + +After all filters applied the `lint` command will execute the following: + +```bash +yarn lint frontend/src/index.ts --fix +``` diff --git a/docs/mdbook/examples/remotes.md b/docs/mdbook/examples/remotes.md new file mode 100644 index 00000000..ff262c97 --- /dev/null +++ b/docs/mdbook/examples/remotes.md @@ -0,0 +1,12 @@ +## Remotes + +> 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: + - git_url: https://github.com/evilmartians/lefthook + configs: + - examples/remote/ping.yml +``` diff --git a/docs/mdbook/examples/stage_fixed.md b/docs/mdbook/examples/stage_fixed.md new file mode 100644 index 00000000..3fec7fc3 --- /dev/null +++ b/docs/mdbook/examples/stage_fixed.md @@ -0,0 +1,15 @@ +## Stage fixed files + +> Works only for `pre-commit` Git hook + +Sometimes your linter fixes the changes and you usually want to commit them automatically. To enable auto-staging of the fixed files use [`stage_fixed`](../configuration/stage_fixed.md) option. + +```yml +# lefthook.yml + +pre-commit: + commands: + lint: + run: yarn lint {staged_files} --fix + stage_fixed: true +``` diff --git a/docs/mdbook/file_name.md b/docs/mdbook/file_name.md deleted file mode 100644 index c4b88492..00000000 --- a/docs/mdbook/file_name.md +++ /dev/null @@ -1,17 +0,0 @@ -## Config file name - -Lefthook supports the following file names for the main config: - -- `lefthook.yml` -- `.lefthook.yml` -- `lefthook.yaml` -- `.lefthook.yaml` -- `lefthook.toml` -- `.lefthook.toml` -- `lefthook.json` -- `.lefthook.json` - -If there are more than 1 file in the project, only one will be used, and you'll never know which one. So, please, use one format in a project. - -Lefthook also merges an extra config with the name `lefthook-local`. All supported formats can be applied to this `-local` config. If you name your main config with the leading dot, like `.lefthook.json`, the `-local` config also must be named with the leading dot: `.lefthook-local.json`. - diff --git a/docs/mdbook/install.md b/docs/mdbook/install.md deleted file mode 100644 index ff935837..00000000 --- a/docs/mdbook/install.md +++ /dev/null @@ -1,20 +0,0 @@ -# Install lefthook - -Choose your fighter: - -- [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) - -Have a question? – Start a [discussion](https://github.com/evilmartians/lefthook/discussions) diff --git a/docs/mdbook/installation/README.md b/docs/mdbook/installation/README.md new file mode 100644 index 00000000..8820a982 --- /dev/null +++ b/docs/mdbook/installation/README.md @@ -0,0 +1,18 @@ +# Install lefthook + +Choose your fighter: + +- [Ruby](./ruby.md) +- [Node.js](./node.md) +- [Go](./go.md) +- [Python](./python.md) +- [Swift](./swift.md) +- [Scoop](./scoop.md) +- [Homebrew](./homebrew.md) +- [Winget](./winget.md) +- [Snap](./snap.md) +- [Debian-based distro](./deb.md) +- [RPM-based distro](./rpm.md) +- [Alpine](./alpine.md) +- [Arch Linux](./arch.md) +- [Manual](./manual.md) diff --git a/docs/mdbook/installation/node.md b/docs/mdbook/installation/node.md index a17c482c..28465ad8 100644 --- a/docs/mdbook/installation/node.md +++ b/docs/mdbook/installation/node.md @@ -26,5 +26,4 @@ Lefthook is available on NPM in the following flavors: yarn add -D @evilmartians/lefthook-installer ``` -> NOTE -> If you use `pnpm` package manager make sure you set `side-effects-cache = false` in your .npmrc, otherwise the postinstall script of the lefthook package won't be executed and hooks won't be installed. +> **Note:** If you use `pnpm` package manager make sure you set `side-effects-cache = false` in your .npmrc, otherwise the postinstall script of the lefthook package won't be executed and hooks won't be installed. diff --git a/docs/mdbook/intro.md b/docs/mdbook/intro.md new file mode 100644 index 00000000..d7bc59e0 --- /dev/null +++ b/docs/mdbook/intro.md @@ -0,0 +1,21 @@ +# Introduction + +**Lefthook** is a Git hooks manager. This documentation provides the reference for installing, configuring and using the lefthook. + +Maybe you are looking for + +- **[Installation instructions](./installation)** to install lefthook to your system or just project. + +- **[Examples](./examples)** of lefthook common usage. + +- **[Configuration](./configuration)** with details explanation of lefthook options. + +--- + + +Sponsored by Evil Martians + + + +❓If you have a question or found a mistake in the documentation, please create a new [discussion](https://github.com/evilmartians/lefthook/discussions/new/choose). Small contributions help maintaining the quality of the project. + diff --git a/docs/mdbook/usage.md b/docs/mdbook/usage.md deleted file mode 100644 index 253db533..00000000 --- a/docs/mdbook/usage.md +++ /dev/null @@ -1,28 +0,0 @@ -# Usage - -- [Commands](./usage/commands.md) - - [`lefthook install`](./usage/commands.md#lefthook-install) - - [`lefthook uninstall`](./usage/commands.md#lefthook-uninstall) - - [`lefthook add`](./usage/commands.md#lefthook-add) - - [`lefthook run`](./usage/commands.md#lefthook-run) - - [`lefthook version`](./usage/commands.md#lefthook-version) - - [`lefthook self-update`](./usage/commands.md#lefthook-self-update) -- [ENV variables](./usage/env.md) - - [`LEFTHOOK`](./usage/env.md#lefthook) - - [`LEFTHOOK_EXCLUDE`](./usage/env.md#lefthook_exclude) - - [`LEFTHOOK_OUTPUT`](./usage/env.md#lefthook_output) - - [`LEFTHOOK_QUIET`](./usage/env.md#lefthook_quiet) - - [`LEFTHOOK_VERBOSE`](./usage/env.md#lefthook_verbose) - - [`LEFTHOOK_BIN`](./usage/env.md#lefthook_bin) - - [`NO_COLOR`](./usage/env.md#no_color) - - [`CLICOLOR_FORCE`](./usage/env.md#clicolor_force) -- [Tips](./usage/tips.md) - - [Local config](./usage/tips.md#local-config) - - [Disable lefthook in CI](./usage/tips.md#disable-lefthook-in-ci) - - [Commitlint example](./usage/tips.md#commitlint-example) - - [Parallel execution](./usage/tips.md#parallel-execution) - - [Concurrent files overrides](./usage/tips.md#concurrent-files-overrides) - - [Capture ARGS from git in the script](./usage/tips.md#capture-args-from-git-in-the-script) - - [Git LFS support](./usage/tips.md#git-lfs-support) - - [Pass stdin to a command or script](./usage/tips.md#pass-stdin-to-a-command-or-script) - - [Using an interactive command or script](./usage/tips.md#using-an-interactive-command-or-script) diff --git a/docs/mdbook/usage/README.md b/docs/mdbook/usage/README.md new file mode 100644 index 00000000..3e23157e --- /dev/null +++ b/docs/mdbook/usage/README.md @@ -0,0 +1,29 @@ +# Usage + +- [Commands](./commands.md) + - [`lefthook install`](./commands.md#lefthook-install) + - [`lefthook uninstall`](./commands.md#lefthook-uninstall) + - [`lefthook add`](./commands.md#lefthook-add) + - [`lefthook run`](./commands.md#lefthook-run) + - [`lefthook version`](./commands.md#lefthook-version) + - [`lefthook self-update`](./commands.md#lefthook-self-update) +- [ENV variables](./env.md) + - [`LEFTHOOK`](./env.md#lefthook) + - [`LEFTHOOK_EXCLUDE`](./env.md#lefthook_exclude) + - [`LEFTHOOK_OUTPUT`](./env.md#lefthook_output) + - [`LEFTHOOK_QUIET`](./env.md#lefthook_quiet) + - [`LEFTHOOK_VERBOSE`](./env.md#lefthook_verbose) + - [`LEFTHOOK_BIN`](./env.md#lefthook_bin) + - [`NO_COLOR`](./env.md#no_color) + - [`CLICOLOR_FORCE`](./env.md#clicolor_force) +- [Tips](./tips.md) + - [Local config](./tips.md#local-config) + - [Disable lefthook in CI](./tips.md#disable-lefthook-in-ci) + - [Commitlint example](./tips.md#commitlint-example) + - [Parallel execution](./tips.md#parallel-execution) + - [Concurrent files overrides](./tips.md#concurrent-files-overrides) + - [Capture ARGS from git in the script](./tips.md#capture-args-from-git-in-the-script) + - [Git LFS support](./tips.md#git-lfs-support) + - [Pass stdin to a command or script](./tips.md#pass-stdin-to-a-command-or-script) + - [Using an interactive command or script](./tips.md#using-an-interactive-command-or-script) + diff --git a/docs/mdbook/usage/commands.md b/docs/mdbook/usage/commands.md index ed2971d7..76176665 100644 --- a/docs/mdbook/usage/commands.md +++ b/docs/mdbook/usage/commands.md @@ -1,12 +1,14 @@ ## Commands -Use `lefthook help` or `lefthook -h/--help` to discover available commands and their options. +> **tip** +> +> Use `lefthook help` or `lefthook -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 +> **note** > > NPM package `lefthook` installs the hooks in a postinstall script automatically. diff --git a/docs/mdbook/usage/env.md b/docs/mdbook/usage/env.md index b8c469ec..ff63f105 100644 --- a/docs/mdbook/usage/env.md +++ b/docs/mdbook/usage/env.md @@ -1,5 +1,7 @@ ## ENV variables +> ENV variables can be used to control lefthook behavior. Most of them have the alternative CLI or config options. + ### `LEFTHOOK` Use `LEFTHOOK=0 git ...` or `LEFTHOOK=false git ...` to disable lefthook when running git commands. diff --git a/docs/mdbook/usage/tips.md b/docs/mdbook/usage/tips.md index 02f64f53..79632b96 100644 --- a/docs/mdbook/usage/tips.md +++ b/docs/mdbook/usage/tips.md @@ -1,5 +1,7 @@ ## Tips +> Small tips for better experience with lefthook + ### Local config Use `lefthook-local.yml` to overwrite or extend options from the main config. (Don't forget to add this file to `.gitignore`) From c39631a2bf965d614eefb25ee7777c106e5579dd Mon Sep 17 00:00:00 2001 From: Valentin Kiselev Date: Wed, 18 Dec 2024 11:41:10 +0300 Subject: [PATCH 2/3] chore: put the link to new docs into README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ecf545f4..4105c525 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ A Git hooks manager for Node.js, Ruby, Python and many other types of projects. * **Powerful.** It allows to control execution and files you pass to your commands. * **Simple.** It is single dependency-free binary which can work in any environment. +📖 [Check the docs](https://evilmartians.github.io/lefthook/) 📖 [Read the introduction post](https://evilmartians.com/chronicles/lefthook-knock-your-teams-code-back-into-shape?utm_source=lefthook) From 66167447111cb2fef30b57b2c21ff6e31889e106 Mon Sep 17 00:00:00 2001 From: Valentin Kiselev Date: Wed, 18 Dec 2024 11:45:29 +0300 Subject: [PATCH 3/3] docs: use lefthook documentation as a top level title --- book.toml | 2 +- docs/mdbook/SUMMARY.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/book.toml b/book.toml index 470eba59..8cc71316 100644 --- a/book.toml +++ b/book.toml @@ -3,7 +3,7 @@ authors = ["Evil Martians"] language = "en" multilingual = false src = "docs/mdbook" -title = "Lefthook" +title = "Lefthook Documentation" [output.html] no-section-label = true diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md index 42c91238..c5fa3028 100644 --- a/docs/mdbook/SUMMARY.md +++ b/docs/mdbook/SUMMARY.md @@ -1,5 +1,3 @@ -# Lefthook - [Introduction](./intro.md) # User guide