From a3da17cb61616cbe3049b6ee628731a3f7fe84fe Mon Sep 17 00:00:00 2001 From: Valentin Kiselev Date: Thu, 19 Dec 2024 11:11:31 +0300 Subject: [PATCH] docs: add more examples (#898) --- docs/mdbook/SUMMARY.md | 11 ++-- docs/mdbook/configuration/README.md | 3 +- docs/mdbook/configuration/skip_lfs.md | 18 ++++++ docs/mdbook/examples/commitlint.md | 38 ++++++------ docs/mdbook/examples/lefthook-local.md | 86 ++++++++++++++++++++++++++ docs/mdbook/examples/remotes.md | 6 +- docs/mdbook/examples/skip.md | 34 ++++++++++ docs/mdbook/installation/arch.md | 2 +- docs/mdbook/installation/manual.md | 2 +- docs/mdbook/usage/commands.md | 8 +-- docs/mdbook/usage/env.md | 2 +- docs/mdbook/usage/tips.md | 4 +- 12 files changed, 176 insertions(+), 38 deletions(-) create mode 100644 docs/mdbook/configuration/skip_lfs.md create mode 100644 docs/mdbook/examples/lefthook-local.md create mode 100644 docs/mdbook/examples/skip.md diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md index c5fa3028..1a8092b4 100644 --- a/docs/mdbook/SUMMARY.md +++ b/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) diff --git a/docs/mdbook/configuration/README.md b/docs/mdbook/configuration/README.md index 69e34b7b..9513bd1b 100644 --- a/docs/mdbook/configuration/README.md +++ b/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) diff --git a/docs/mdbook/configuration/skip_lfs.md b/docs/mdbook/configuration/skip_lfs.md new file mode 100644 index 00000000..56b39af6 --- /dev/null +++ b/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 +``` diff --git a/docs/mdbook/examples/commitlint.md b/docs/mdbook/examples/commitlint.md index 08d63861..ff03d20d 100644 --- a/docs/mdbook/examples/commitlint.md +++ b/docs/mdbook/examples/commitlint.md @@ -1,12 +1,13 @@ ## 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 ``` @@ -14,8 +15,10 @@ yarn add -D commitizen cz-conventional-changelog 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' ``` diff --git a/docs/mdbook/examples/lefthook-local.md b/docs/mdbook/examples/lefthook-local.md new file mode 100644 index 00000000..53c7d8aa --- /dev/null +++ b/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 +``` diff --git a/docs/mdbook/examples/remotes.md b/docs/mdbook/examples/remotes.md index ff262c97..95176b13 100644 --- a/docs/mdbook/examples/remotes.md +++ b/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: diff --git a/docs/mdbook/examples/skip.md b/docs/mdbook/examples/skip.md new file mode 100644 index 00000000..05ae4cc7 --- /dev/null +++ b/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 +``` diff --git a/docs/mdbook/installation/arch.md b/docs/mdbook/installation/arch.md index 27aa4599..2984b322 100644 --- a/docs/mdbook/installation/arch.md +++ b/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 diff --git a/docs/mdbook/installation/manual.md b/docs/mdbook/installation/manual.md index 656a97c1..b72d9ea5 100644 --- a/docs/mdbook/installation/manual.md +++ b/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) diff --git a/docs/mdbook/usage/commands.md b/docs/mdbook/usage/commands.md index 76176665..57c4eb64 100644 --- a/docs/mdbook/usage/commands.md +++ b/docs/mdbook/usage/commands.md @@ -1,16 +1,12 @@ ## Commands -> **tip** -> -> 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** -> -> 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` diff --git a/docs/mdbook/usage/env.md b/docs/mdbook/usage/env.md index ff63f105..2bbe4e13 100644 --- a/docs/mdbook/usage/env.md +++ b/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` diff --git a/docs/mdbook/usage/tips.md b/docs/mdbook/usage/tips.md index 79632b96..3ee8d475 100644 --- a/docs/mdbook/usage/tips.md +++ b/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).