Lefthook

https://github.com/evilmartians/lefthook
Admin
Lefthook is a Git hooks manager for any project, configured in lefthook.yml with jobs, commands and...
Tokens:52,829
Snippets:609
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: setup with conditional install in lefthook.yml

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/setup.md

Shows a `pre-commit` hook with a `setup` step that checks if `golangci-lint` is installed and installs it if not, before running the lint job on staged Go files.

```yaml
# lefthook.yml

pre-commit:
  setup:
    - run: |
        if ! command -v golangci-lint >/dev/null 2>&1; then
          go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1
        fi
  jobs:
    - run: golangci-lint -- {staged_files}
      glob: "*.go"
```

--------------------------------

### Setup: Initialize repository and install Lefthook

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/restore_unstaged_on_conflict.txt

Initializes a git repository, configures user, installs Lefthook, and makes an initial commit.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec lefthook install
exec git add -A
exec git commit --no-verify -m 'initial'
```

--------------------------------

### Initialize Git and Install Lefthook

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/setup_instructions.txt

Run these commands to set up a Git repository, configure user identity, stage all files, install Lefthook, and create a test commit. The expected stderr output matches the pattern 'Setup 1', 'Setup 2', and 'Hi there from Lefthook'.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec lefthook install
exec git commit -m 'test'
stderr '\s*Setup 1\s*Setup 2\s*Hi there from Lefthook\s*'
```

--------------------------------

### Test setup commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/run_interrupt.txt

Initializes a git repository, configures user, installs Lefthook, and stages files.

```bash
chmod 0700 hook.sh
chmod 0700 commit-with-interrupt.sh
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec lefthook install
exec git add -A
```

--------------------------------

### Install as Go tool

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Install Lefthook as a Go tool using go get.

```bash
go get -tool github.com/evilmartians/lefthook/v2@v2.2.2
```

--------------------------------

### Directory tree for root example (bash)

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/root.md

Shows the folder structure for the example: a client/ folder with package.json and node_modules, and a server/ folder. This tree is the setup for the subsequent lefthook.yml configuration.

```bash
$ tree .
.
├── client/
│   ├── package.json
│   ├── node_modules/
|   ├── ...
├── server/
|   ...
```

--------------------------------

### Git and lefthook setup commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/hide_unstaged.txt

Initializes a git repository, installs lefthook, configures user, and makes an initial commit.

```bash
exec git init
exec lefthook install
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec git commit -m 'initial commit'
```

--------------------------------

### Integration test setup commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/remotes.txt

Commands to initialize a git repository, install Lefthook, and dump the configuration for comparison.

```shell
exec git init
exec lefthook install

exec lefthook dump
cmp stdout lefthook-dump.yml
```

--------------------------------

### Install and configure Lefthook hooks

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Quick start workflow: edit lefthook.yml, install hooks with `lefthook install`, then commit normally.

```bash
# Configure your hooks
vim lefthook.yml

# Install them to the git project
lefthook install

# Enjoy your work with git
git add -A && git commit -m '...'
```

--------------------------------

### Install Lefthook via APT on Debian/Ubuntu

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/deb.md

Run these two commands in sequence to add the Cloudsmith repository and install Lefthook. The first command downloads and executes the setup script with sudo, and the second installs the package.

```sh
curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.deb.sh' | sudo -E bash
sudo apt install lefthook
```

--------------------------------

### Setup and run Lefthook commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/env_overwrite_issue_1137.txt

Commands to initialize a git repository, configure user, stage files, install Lefthook, and run the test hook.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec lefthook install
exec lefthook run test
```

--------------------------------

### Setup commands for Lefthook integration test

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/fail_on_changes.txt

Initializes a git repository, installs Lefthook, sets git user configuration, and stages a file for testing.

```bash
exec git init
exec lefthook install
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add file.txt
```

--------------------------------

### Install Lefthook via RPM repository

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/rpm.md

Run the setup script to configure the Cloudsmith RPM repository, then install Lefthook with yum. Requires sudo privileges.

```sh
curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.rpm.sh' | sudo -E bash
sudo yum install lefthook
```

--------------------------------

### Install with pipx

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Install Lefthook using pipx.

```bash
pipx install lefthook
```

--------------------------------

### Test setup commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/run_script.txt

Commands to initialize a git repository, set user config, stage files, install Lefthook, and commit. The test expects stderr to contain 'Hi there from script'.

```bash
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec lefthook install
exec git commit -m 'test'
stderr '\s*Hi there from script\s*'
```

--------------------------------

### Install with RubyGems

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Install Lefthook using gem.

```bash
gem install lefthook
```

--------------------------------

### Git and Lefthook setup commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/run_script_with_args.txt

Commands to initialize a git repository, configure user, stage files, install Lefthook, and commit. The commit triggers the pre-commit hook.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec lefthook install
exec git commit -m 'test'
stderr '\s*Args: lefthook.yml\s*'
```

--------------------------------

### Lefthook Configuration with Setup and Command

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/setup_instructions.txt

This lefthook.yml defines a pre-commit hook with two setup steps that echo 'Setup 1' and 'Setup 2', and a command that echoes 'Hi there from Lefthook'. The output section lists 'setup' and 'execution_out' to capture the output.

```yaml
-- lefthook.yml --
output:
  - setup
  - execution_out

pre-commit:
  setup:
    - run: echo 'Setup 1'
    - run: echo 'Setup 2'
  commands:
    echo:
      run: echo Hi there from Lefthook
```

--------------------------------

### Test setup: git init and add

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/files_from_stdin.txt

Initializes a git repository and stages all files for the integration test.

```shell
exec git init
exec git add -A
```

--------------------------------

### Setup: Initialize main repo and submodule repo

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/fail_on_changes_submodule_issue_1562.txt

Initializes a git repository 'foo' with a commit, then initializes the main app repository, configures user, adds files, commits, adds a submodule, and creates a symlink to the submodule directory.

```bash
exec git init foo
exec git -C foo -c user.email=you@example.com -c user.name=Name commit --allow-empty -m init

cd app
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add lefthook.yml file.txt
exec git commit -m "firstcommit"
exec git -c protocol.file.allow=always submodule add ../foo bar
exec ln -s bar bar-link
```

```bash
# A staged submodule and an untracked symlink to a directory must not break the changeset
exec lefthook run pre-commit
! stderr 'Unable to hash'

# Changes made by a hook are still detected next to a submodule
! exec lefthook run modify-file
stderr 'Error: files were modified by a hook, and fail_on_changes is enabled'
```

--------------------------------

### Setup and run lefthook pre-commit with fail_on_changes

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/fail_on_changes_issue_1125.txt

Commands to initialize a git repository, configure user, commit initial files, install lefthook, and run the pre-commit hook. The final command is expected to fail because the hook modifies README.md and fail_on_changes is enabled.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add .
exec git commit -m "firstcommit"
exec lefthook install

# This should fail because README.md is modified
! exec lefthook run pre-commit --all-files
stderr 'Error: files were modified by a hook, and fail_on_changes is enabled'
```

--------------------------------

### Install lefthook

Source: https://github.com/evilmartians/lefthook/wiki/Migration-from-overcommit

Install lefthook gem and set up its hooks.

```bash
gem install lefthook && lefthook install
```

--------------------------------

### Sync new hooks and test

Source: https://github.com/evilmartians/lefthook/wiki/Migration-from-overcommit

Install lefthook hooks and run the pre-commit hook to verify the migration.

```bash
lefthook install && lefthook run pre-commit
```

--------------------------------

### Install commitlint and commitzen dependencies

Source: https://github.com/evilmartians/lefthook/blob/master/examples/commitlint/README.md

Install @commitlint/cli and @commitlint/config-conventional, and optionally commitizen with cz-conventional-changelog.

```bash
yarn add -D @commitlint/cli @commitlint/config-conventional
# If using commitzen
yarn add -D commitizen cz-conventional-changelog
```

--------------------------------

### Run jobs in Docker

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Use a Docker runner to execute scripts inside a container.

```yaml
pre-commit:
  jobs:
    - script: "good_job.js"
      runner: docker run -it --rm <container_id_or_name> {cmd}
```

--------------------------------

### Install commitlint and commitzen dependencies

Source: https://github.com/evilmartians/lefthook/blob/master/docs/examples/commitlint.md

Install @commitlint/cli, @commitlint/config-conventional, commitizen, and cz-conventional-changelog as dev dependencies using yarn.

```bash
yarn add -D @commitlint/cli @commitlint/config-conventional

# For commitzen
yarn add -D commitizen cz-conventional-changelog
```

--------------------------------

### Run hooks and Git commit examples

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage/commands/run.md

Shows how to run a specific hook with `lefthook run`, and how Git commit triggers the pre-commit hook automatically.

```bash
$ lefthook run test # will run 'yarn test'
$ git commit # will run pre-commit hook ('yarn lint --fix')
$ lefthook run pre-commit # will run pre-commit hook (`yarn lint --fix`)

```

--------------------------------

### Flexible file list with pre-commit jobs

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Define multiple jobs with custom file lists using `{staged_files}`, `{all_files}`, and `{files}`.

```yaml
pre-commit:
  jobs:
    - name: lint frontend
      run: yarn eslint {staged_files}

    - name: lint backend
      run: bundle exec rubocop --force-exclusion -- {all_files}

    - name: stylelint frontend
      files: git diff --name-only HEAD @{push}
      run: yarn stylelint {files}
```

--------------------------------

### Install Lefthook globally with gem install

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/ruby.md

Installs the lefthook gem globally using the gem install command. This makes lefthook available system-wide.

```bash
gem install lefthook
```

--------------------------------

### Shell commands to set up repository and test merge commit skip

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/skip_merge_commit.txt

Initializes a git repository, configures user, installs Lefthook, creates a branch with a commit, runs the pre-commit hook with --force to confirm the command runs, then merges the branch and runs the hook again to confirm the command is skipped.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec git commit -m 'commit 1'
exec lefthook install

exec git checkout -b merge-me
exec touch file.A
exec git add -A
exec git commit -m 'commit A'

exec lefthook run pre-commit --force
stdout 'skip-merge-commit'

exec git checkout -
exec touch file.B
exec git add -A
exec git commit -m 'commit B'

exec git merge merge-me

exec lefthook run pre-commit --force
! stdout 'skip-merge-commit'
```

--------------------------------

### Add Lefthook as a Go tool in your project

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/go.md

Adds Lefthook as a project-level Go tool using go get -tool. Requires Go 1.27 or higher.

```bash
go get -tool github.com/evilmartians/lefthook/v2
```

--------------------------------

### Install lefthook package

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/node.md

Install the standard lefthook package, which installs one executable for your system.

```bash
npm install --save-dev lefthook
```

--------------------------------

### Local configuration to skip or override jobs

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Create lefthook-local.yml to exclude tags or skip specific jobs for local development.

```yaml
# lefthook-local.yml
pre-push:
  exclude_tags:
    - frontend
  jobs:
    - name: audit packages
      skip: true
```

--------------------------------

### Install Git hooks with Lefthook

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/php.md

Run this command to install the Git hooks. After this, Lefthook should automatically find its path via composer exec on Git hooks.

```sh
vendor/bin/lefthook install
```

--------------------------------

### Install legacy @evilmartians/lefthook-installer package

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/node.md

Install the legacy @evilmartians/lefthook-installer package, which fetches the right executable on installation. Legacy distributions are still maintained but will be shut down in the future.

```bash
npm install --save-dev @evilmartians/lefthook-installer
```

--------------------------------

### Install lefthook on Alpine via APK

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/alpine.md

Installs the APK repository and then installs the lefthook package on Alpine Linux. Run these steps in order on a machine with sudo access.

```sh
sudo apk add --no-cache bash curl
```

```sh
curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.alpine.sh' | sudo -E bash
```

```sh
sudo apk add lefthook
```

--------------------------------

### Install Lefthook with pip

Source: https://github.com/evilmartians/lefthook/blob/master/packaging/registries/pypi/README.md

Install Lefthook using pip. This is the recommended installation method for Python environments.

```bash
pip install lefthook
```

--------------------------------

### Run a hook group directly

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Use `lefthook run` to execute a specific hook group manually.

```bash
$ lefthook run pre-commit
```

--------------------------------

### Install Lefthook as a global Go package

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/go.md

Installs Lefthook v2.2.2 globally using the go install command. Requires Go 1.27 or higher.

```bash
go install github.com/evilmartians/lefthook/v2@v2.2.2
```

--------------------------------

### lefthook.yml pre-push hook configuration

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/uninstall.txt

Example lefthook.yml configuration defining a pre-push hook that runs the echo command. Used in the integration test to verify hook installation and uninstallation behavior.

```yaml
pre-push:
  commands:
    echo:
      run: echo pre-push
```

--------------------------------

### Check Lefthook version

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/php.md

Run this command to verify that Lefthook is installed correctly.

```sh
vendor/bin/lefthook version
```

--------------------------------

### Define and run custom task groups

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Create a custom group (e.g., `fixer`) with multiple jobs and run it with `lefthook run`.

```yaml
fixer:
  jobs:
    - run: bundle exec rubocop --force-exclusion --safe-auto-correct -- {staged_files}
    - run: yarn eslint --fix {staged_files}
```

```bash
$ lefthook run fixer
```

--------------------------------

### Shell commands to set up and run the test

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/filter_by_file_type.txt

Commands to initialize a git repository, configure user, install Lefthook, create test files, and run the 'filters' command. The stdout assertions verify the output of each filter command.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec lefthook install
chmod 777 executable
symlink symlink -> results
exec git add -A
exec git commit -m 'test'
exec lefthook run filters
stdout '.*all ❯\s+executable lefthook.yml results symlink\s+┃.*'
stdout '.*filter_text ❯\s+executable lefthook.yml results\s+┃.*'
stdout '.*filter_executable ❯\s+executable\s+┃.*'
stdout '.*filter_symlink ❯\s+symlink\s+┃.*'
stdout '.*filter_not_symlink ❯\s+executable lefthook.yml results\s+┃.*'
stdout '.*filter_not_executable ❯\s+lefthook.yml results symlink\s*'
```

--------------------------------

### Example: Setting ref in lefthook.yml

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/ref.md

Shows a lefthook.yml configuration with a remote using `git_url` and `ref: v1.0.0`. Use this to pin a remote to a specific branch or tag. Note: if you remove `ref` after having it installed, lefthook won't decide which ref to use.

```yaml
# lefthook.yml

remotes:
  - git_url: git@github.com:evilmartians/lefthook
    ref: v1.0.0

```

--------------------------------

### Run echo_files hook and verify output

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/sh_syntax_in_files.txt

Initializes a git repository, installs lefthook, sets git user configuration, runs the echo_files hook, and verifies that the output is '1.txt 10.txt'.

```shell
exec git init
exec lefthook install
exec git config user.email "you@example.com"
exec git config user.name "Your Name"

exec lefthook run echo_files

stdout '1.txt 10.txt'
```

--------------------------------

### Install lefthook via yay on Arch Linux

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/arch.md

Install lefthook on Arch Linux using the AUR helper yay. The first command compiles from sources, while the second installs the pre-compiled binary package.

```sh
# To compile from sources
yay -S lefthook

# To install only executable
yay -S lefthook-bin
```

--------------------------------

### Install lefthook

Source: https://github.com/evilmartians/lefthook/wiki/Migration-from-husky-with-lint-staged

Install lefthook as a dev dependency using npm.

```bash
npm install @arkweid/lefthook --save-dev
```

--------------------------------

### Install lefthook hook

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage/commands/run.md

Command to install the Git hooks so that `lefthook run` is called implicitly on Git events.

```bash
$ lefthook install

```

--------------------------------

### Run lefthook-plugin with Mint

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/swift.md

Use the Mint package manager to run the lefthook-plugin. This command fetches and executes the plugin from the csjones/lefthook-plugin repository.

```bash
mint run csjones/lefthook-plugin
```

--------------------------------

### Install git hooks with lefthook install -f

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/rc.md

Command to update git hooks after setting up the rc file. This is important to ensure the hooks are installed with the new environment.

```bash
# Make sure you updated git hooks. This is important.
$ lefthook install -f
```

--------------------------------

### Install Lefthook with pip

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/python.md

Installs Lefthook for the current user using pip. Use this when you want to install the package without requiring system-wide permissions.

```sh
python -m pip install --user lefthook
```

--------------------------------

### Install lefthook with mise

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/mise.md

Use this command to install the latest version of lefthook via mise. The mise plugin is community-maintained; the lefthook team does not provide direct support for mise-specific issues.

```bash
mise use lefthook@latest
```

--------------------------------

### Shell commands to set up and run the test

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/restore_unstaged.txt

Commands to initialize a git repository, configure user, install lefthook, commit initial state, stage a change, add an unstaged change, and commit to trigger the hook. The final grep commands verify that the staged change was committed and the unstaged change is preserved.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec lefthook install
exec git add -A
exec git commit -m 'initial'

# Stage first change
exec echo lineStaged
cp stdout a.txt
exec git add -A
exec echo lineUnstaged
cp stdout a.txt

# Change that line in the hook
exec git commit -m 'test'

# Must successfully apply the hook
! grep lineStaged a.txt
grep lineUnstaged a.txt
grep lineNew a.txt
grep lineNew b.txt
```

--------------------------------

### Shell commands to set up and test Lefthook

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/run_jsonc.txt

Initializes a Git repository, sets user config, stages files, installs Lefthook, and commits. The commit triggers the pre-commit hook, and the test expects stderr to contain 'Hi there from Lefthook'.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec lefthook install
exec git commit -m 'test'
stderr '\s*Hi there from Lefthook\s*'
```

--------------------------------

### Move hooks from package.json to lefthook.yml

Source: https://github.com/evilmartians/lefthook/wiki/Migration-from-husky-with-lint-staged

Replace the husky and lint-staged configuration in package.json with the equivalent lefthook.yml configuration. The package.json block shows the old setup, and the lefthook.yml block shows the new setup.

```json
// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,jsx}": "eslint"
  }
}
```

```yml
# lefthook.yml
pre-commit:
  commands:
    eslint:
      glob: "*.{js,jsx}"
      run: npx eslint {staged_files} && git add {staged_files}
```

--------------------------------

### Install legacy @evilmartians/lefthook package

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/node.md

Install the legacy @evilmartians/lefthook package, which installs executables for all operating systems. Legacy distributions are still maintained but will be shut down in the future.

```bash
npm install --save-dev @evilmartians/lefthook
```

--------------------------------

### Basic lefthook CLI commands

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage.md

Basic CLI commands for lefthook: install, run, validate, and dump. Use these to manage Git hooks and configuration.

```bash
# Create/update Git hooks based on lefthook.yml, or create an empty lefthook.yml
lefthook install

# Run pre-commit hook commands and scripts (requires lefthook.yml)
lefthook run pre-commit

# Validate the configuration
lefthook validate

# Dump the configuration (useful when you have remotes, extends that overwrite the configuration)
lefthook dump
```

--------------------------------

### Test commit message generation and validation

Source: https://github.com/evilmartians/lefthook/blob/master/docs/examples/commitlint.md

Test the setup by running git commit with or without a message, depending on whether commitzen is used.

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

--------------------------------

### Shell script: Set up worktree and test partially staged file

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/worktree_partially_staged_issue_1580.txt

This shell script initializes a git repository, configures user, commits initial state, installs lefthook, creates a linked worktree, stages a change, adds an unstaged change, commits, and verifies the unstaged change is restored and no patch files remain.

```shell
exec git init main
cd main
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec git commit -m 'initial'
exec lefthook install
exec git worktree add ../wt -b feature
cd ../wt

# Stage a change, then add an unstaged change to the same file
exec echo lineStaged
cp stdout a.txt
exec git add a.txt
exec echo lineUnstaged
cp stdout a.txt

exec git commit -m 'test'

# Unstaged change must be restored after the hook
grep lineUnstaged a.txt
! exists ../main/.git/info/lefthook-unstaged.patch
! exists ../main/.git/info/lefthook-unstaged-all.patch
```

--------------------------------

### Example lefthook.yml configuration for pre-commit hook

Source: https://github.com/evilmartians/lefthook/blob/master/docs/index.md

Configure Lefthook to run linters on the pre-commit hook. The example runs stylelint on CSS files and eslint on TypeScript/JavaScript files in parallel, with stage_fixed enabled to automatically stage fixed files.

```yaml
# lefthook.yml

pre-commit:
  parallel: true
  jobs:
    - run: yarn run stylelint --fix '{staged_files}'
      glob: "*.css"
      stage_fixed: true

    - run: yarn run eslint --fix '{staged_files}'
      glob:
        - "*.ts"
        - "*.js"
        - "*.tsx"
        - "*.jsx"
      stage_fixed: true
```

--------------------------------

### Reinstall Lefthook hooks with -a or -f flags

Source: https://github.com/evilmartians/lefthook/wiki/Troubleshooting

Use `lefthook install -a` to completely refresh the .git/hooks directory. If you have important files in .git/hooks, use `lefthook install -f` instead to force reinstall without deleting them.

```bash
# This command completely refresh .git/hooks directory
lefthook install -a

# Or if you have important files in .git/hooks directory
lefthook install -f
```

--------------------------------

### YAML configuration: assigning tags to commands

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/tags.md

Example lefthook.yml configuration demonstrating the `tags` key for commands within `pre-commit` hooks. Each command can specify multiple tags using a list, useful for excluding with `exclude_tags`. The example shows `lint` with tags `frontend` and `js`, and `test` with tags `backend` and `ruby`.

```yaml
# lefthook.yml

pre-commit:
  commands:
    lint:
      tags:
        - frontend
        - js
      run: yarn lint
    test:
      tags:
        - backend
        - ruby
      run: bundle exec rspec

```

--------------------------------

### Install Lefthook with pipx

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/python.md

Installs Lefthook in an isolated environment using pipx. This avoids dependency conflicts and makes the command available globally.

```sh
pipx install lefthook
```

--------------------------------

### Set LEFTHOOK_OUTPUT to summary and run pre-commit

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage/envs/LEFTHOOK_OUTPUT.md

Use LEFTHOOK_OUTPUT=summary to print only a summary of the run. The example shows the command and its output, including a checkmark and the time taken.

```bash
$ LEFTHOOK_OUTPUT=summary lefthook run pre-commit
summary: (done in 0.52 seconds)
✔️  lint
```

--------------------------------

### Configure lefthook jobs with piped group and parallel execution

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/jobs.md

Example configuration for lefthook jobs. It defines a piped group named 'migrate' that runs bundle install and rails db:migrate sequentially, while other jobs (yarn lint, rubocop, golangci-lint, and a bash script) run in parallel. Only root, glob, exclude, env, and files options are applied to group jobs; other options must be set per job.

```yaml
# lefthook.yml

pre-commit:
  parallel: true
  jobs:
    - name: migrate
      root: backend/
      glob: "db/migrations/*"
      group:
        piped: true
        jobs:
          - run: bundle install
          - run: rails db:migrate
    - run: yarn lint --fix {staged_files}
      root: frontend/
      stage_fixed: true
    - run: bundle exec rubocop
      root: backend/
    - run: golangci-lint
      root: proxy/
    - script: verify.sh
      runner: bash
```

--------------------------------

### git diff command for files template

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/files.md

A Lefthook configuration example for a pre-push hook, showing how to use `git diff --name-only master` to list files for the `{files}` template in the `run` command. If the command returns nothing, execution is skipped.

```yaml
# lefthook.yml

pre-push:
  commands:
    stylelint:
      tags:
        - frontend
        - style
      files: git diff --name-only master
      glob: "*.js"
      run: yarn stylelint {files}
```

--------------------------------

### Shell script to set up and test Lefthook stage_fixed

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/job_stage_fixed.txt

Initializes a git repository, installs Lefthook, configures git user, stages all files, and commits with a message 'test stage_fixed'. The output shows the git status after commit.

```shell
exec git init
exec lefthook install
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec git status --short
exec git commit -m 'test stage_fixed'
exec git status --short
! stdout .
```

--------------------------------

### Example: Setting a job name in lefthook.yml

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/name.md

Shows a `pre-commit` job with a `name` of "lint and fix" and a `run` command. The name will appear in the summary output.

```yaml
# lefthook.yml

pre-commit:
  jobs:
    - name: lint and fix
      run: yarn run eslint --fix {staged_files}
```

--------------------------------

### file.txt content for fail_on_changes test

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/fail_on_changes.txt

Initial content of the file that gets modified by the hooks.

```text
-- file.txt --
1
```

--------------------------------

### Example of Git hook and custom hook configuration in lefthook.yml

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/Hook.md

Shows a pre-commit hook with a job that runs yarn lint on staged files and stages fixed files, and a custom hook 'check-docs' with two jobs. The comment indicates you can specify any Git hook or your own custom hook.

```yaml
# lefthook.yml

# Git hook
pre-commit:
  jobs:
    - run: yarn lint {staged_files} --fix
      stage_fixed: true

# Custom hook
check-docs:
  jobs:
    - run: yarn check-docs
    - run: typos

```

--------------------------------

### Example JavaScript file content

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/stage_fixed_505.txt

Initial content of the file that the hook modifies. This file is staged and then appended with 'newline' by the hook.

```javascript
-- [file].js --
somecode
```

--------------------------------

### Uninstall husky

Source: https://github.com/evilmartians/lefthook/wiki/Migration-from-husky-with-lint-staged

Run this command to remove husky from your project before installing lefthook.

```bash
npm uninstall husky
```

--------------------------------

### lefthook.yml configuration for pre-commit and test hooks

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage/commands/run.md

Example configuration defining a pre-commit hook with a lint job and a test hook with a test job. The pre-commit job uses the {staged_files} template.

```yaml
# lefthook.yml

pre-commit:
  jobs:
    - name: lint
      run: yarn lint --fix {staged_files}

test:
  jobs:
    - name: test
      run: yarn test

```

--------------------------------

### Control output with output option

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Specify which output types to show (e.g., execution, failure).

```yaml
output:
  - execution
  - failure
```

--------------------------------

### lefthook.yml with remote configurations

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/remotes.txt

Configuration file defining remote sources for Lefthook hooks, referencing external example configs.

```yaml
remotes:
  - git_url: https://github.com/evilmartians/lefthook
    configs:
      - examples/with_scripts/lefthook.yml
    ref: v1.4.0
  - git_url: https://github.com/evilmartians/lefthook
    configs:
      - examples/verbose/lefthook.yml
      - examples/remote/ping.yml
```

--------------------------------

### .lefthook-local.toml pre-commit hook configuration

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/uninstall.txt

Example .lefthook-local.toml configuration defining a pre-commit hook that runs the echo command. Used in the integration test to verify local configuration handling during uninstall.

```toml
[pre-commit.commands.echo]
run = "echo pre-commit"
```

--------------------------------

### Custom script for files listing

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/files.md

A Lefthook configuration example for a pre-push hook, using a custom Node.js script (`node ./lefthook-scripts/ls-files.js`) to list files for the `{files}` template. The comment notes you can call your own scripts. An empty result will skip execution.

```yaml
# lefthook.yml

pre-push:
  commands:
    rubocop:
      tags: backend
      glob: "**/*.rb"
      files: node ./lefthook-scripts/ls-files.js # you can call your own scripts
      run: bundle exec rubocop --force-exclusion --parallel -- {files}
```

--------------------------------

### Control groups of commands with tags

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Assign tags to jobs to selectively run or skip groups.

```yaml
pre-push:
  jobs:
    - name: audit packages
      tags:
        - frontend
        - linters
      run: yarn lint

    - name: audit gems
      tags:
        - backend
        - security
      run: bundle audit
```

--------------------------------

### Run a script with a custom runner

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Execute a script file using a specified runner (e.g., bash).

```yaml
commit-msg:
  jobs:
    - script: "template_checker"
      runner: bash
```

--------------------------------

### Sample file [file].js

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/job_stage_fixed.txt

Contains the text 'somecode'.

```javascript
somecode
```

--------------------------------

### Sample file file.txt

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/job_stage_fixed.txt

Contains the text 'sometext'.

```text
sometext
```

--------------------------------

### Execute commands in a sub-directory

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Set `root` to run the command from a relative path; ensure trailing slash.

```yaml
pre-commit:
  jobs:
    - name: lint backend
      root: "api/" # Careful to have only trailing slash
      glob: "*.rb" # glob filter
      run: bundle exec rubocop -- {all_files}
```

--------------------------------

### Filter files with glob and exclude patterns

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Use `glob` and `exclude` to filter which files are passed to the command.

```yaml
pre-commit:
  jobs:
    - name: lint backend
      glob: "*.rb" # glob filter
      exclude:
        - "*/application.rb"
        - "*/routes.rb"
      run: bundle exec rubocop --force-exclusion -- {all_files}
```

--------------------------------

### Example: stage_fixed in pre-commit command

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/stage_fixed.md

Configures the `lint` command to run `npm run lint --fix` on staged files and then automatically stage the fixed files with `git add`. This option works only for the `pre-commit` hook. If `git add` fails, the hook fails.

```yaml
# lefthook.yml

pre-commit:
  commands:
    lint:
      run: npm run lint --fix {staged_files}
      stage_fixed: true
```

--------------------------------

### Enable parallel execution for pre-push hook

Source: https://github.com/evilmartians/lefthook/blob/master/README.md

Set `parallel: true` to run jobs concurrently for faster execution.

```yaml
pre-push:
  parallel: true
```

--------------------------------

### Sample file 1.txt

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/sh_syntax_in_files.txt

Sample file 1.txt containing the text '1.txt'.

```text
-- 1.txt --
1.txt
```

--------------------------------

### Execute lefthook test commands with expected stdout

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/exclude.txt

Shell commands that initialize a Git repository, install lefthook, configure a test user, stage all files, and run the lefthook commands defined in the lefthook.yml. The tests verify that the exclude and group configurations produce the expected staged files output.

```shell
exec git init
exec lefthook install
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec git add -A
exec lefthook run -f all
stdout '^a.txt b.txt dir/a.txt dir/b.txt lefthook.yml\s*$'
exec lefthook run -f oneline
stdout '^lefthook.yml\s*$'
exec lefthook run -f array
stdout '^dir/a.txt dir/b.txt\s*$'
exec lefthook run -f nested
stdout '^lefthook.yml\s+dir/b.txt lefthook.yml\s+b.txt dir/b.txt lefthook.yml\s+b.txt dir/b.txt\s*$'
```

--------------------------------

### Git initialization and commit commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/pre-commit_issue_919.txt

Commands to initialize a git repository, stage files, set user config, and create an initial commit.

```bash
exec git init
```

```bash
exec git add -A
```

```bash
exec git config user.email "you@example.com"
```

```bash
exec git config user.name "Your Name"
```

```bash
exec git add -A
```

```bash
exec git commit -m 'first commit'
```

--------------------------------

### Configure commitlint.config.js

Source: https://github.com/evilmartians/lefthook/blob/master/docs/examples/commitlint.md

Create a commitlint.config.js file with the conventional configuration.

```js
// commitlint.config.js

module.exports = {extends: ['@commitlint/config-conventional']};
```

--------------------------------

### Initial file contents: a.txt, b.txt, c.txt

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/restore_unstaged_on_conflict.txt

Initial contents of the files used in the test.

```text
-- a.txt --
line1
line2
line3
```

```text
-- b.txt --
line1
lineCommitted
line3
```

```text
-- c.txt --
committed content
```

--------------------------------

### Skip LFS hooks in lefthook.yml with skip_lfs: true

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/skip_lfs.md

Set 'skip_lfs' to true in lefthook.yml to prevent Lefthook from running LFS hooks even if git-lfs is installed. This example configures a pre-push hook that runs 'yarn test' with LFS skipping enabled.

```yml
# lefthook.yml

skip_lfs: true

pre-push:
  commands:
    test:
      run: yarn test
```

--------------------------------

### Make commands for build, test, lint, and schema generation

Source: https://github.com/evilmartians/lefthook/blob/master/AGENTS.md

Use these Make targets to compile, run unit and integration tests, lint with golangci-lint, and regenerate schema.json after config changes. Requires Go 1.27+ and Git.

```makefile
make build            # compile
make test             # unit tests
make test-integration # integration tests
make lint             # golangci-lint
make jsonschema       # regenerate schema.json after config changes
```

--------------------------------

### Sample file 10.txt

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/sh_syntax_in_files.txt

Sample file 10.txt containing the text '10.txt'.

```text
-- 10.txt --
10.txt
```

--------------------------------

### Initialize and run lefthook test

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/templates.txt

Initializes a git repository, runs the lefthook test hook, and verifies that the output matches the expected pattern.

```text
exec git init
```

```text
exec lefthook run test
```

```text
stdout '^\s*hello\s*$'
```

--------------------------------

### Force hook installation with LEFTHOOK=1

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage/envs/LEFTHOOK.md

Forces lefthook to install hooks during package manager installs. Use when CI sets CI=true automatically and you need hooks installed in the postinstall script.

```bash
LEFTHOOK=1 npm install
```

```bash
LEFTHOOK=1 yarn install
```

```bash
LEFTHOOK=1 pnpm install
```

--------------------------------

### Sample file 20.txt

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/sh_syntax_in_files.txt

Sample file 20.txt containing the text '20.txt'.

```text
-- 20.txt --
20.txt
```

--------------------------------

### Shell commands to initialize git and run Lefthook test

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/files_skip_if_empty.txt

Initializes a git repository, sets user email and name, runs the Lefthook 'test' hook, and asserts that the output contains 'FILES DETECTED'.

```shell
exec git init
exec git config user.email "you@example.com"
exec git config user.name "Your Name"
exec lefthook run test
! stdout 'FILES DETECTED'
```

--------------------------------

### Run Lefthook skip and no-skip commands

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/skip_run.txt

Initializes a git repository, stages files, and runs Lefthook commands to test skip behavior. The 'skip' command is expected to be skipped (no output), while 'no-skip' should output 'Ha-ha!'.

```shell
exec git init
exec git add -A
exec lefthook run skip
! stdout 'Ha-ha!'
exec lefthook run no-skip
stdout 'Ha-ha!'
```

--------------------------------

### Test commands: git init, lefthook dump, and comparison

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/job_merging.txt

Commands to initialize a git repository, dump the effective Lefthook configuration, and compare the output to the expected dump file. The test expects no stderr output.

```bash
exec git init
exec lefthook dump
cmp stdout dump.yml
! stderr .
```

--------------------------------

### Create commitlint.config.js with conventional config

Source: https://github.com/evilmartians/lefthook/blob/master/examples/commitlint/README.md

Creates a commitlint.config.js file that extends the conventional configuration.

```bash
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
```

--------------------------------

### Initialize git and run lefthook validate

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/validate.txt

Run these commands in a terminal to initialize a git repository and then validate the lefthook configuration. The validate command checks the lefthook.yml file for errors.

```bash
exec git init
exec lefthook validate
```

--------------------------------

### Set CI=true for NPM, Yarn, and pnpm package managers

Source: https://github.com/evilmartians/lefthook/blob/master/docs/usage/envs/CI.md

This snippet shows how to run package installation commands with the CI=true environment variable to prevent lefthook from installing hooks automatically. Use this in CI environments where hooks are unnecessary. Set LEFTHOOK=1 to override this behavior and force hook installation.

```bash
CI=true npm install
```

```bash
CI=true yarn install
```

```bash
CI=true pnpm install
```

--------------------------------

### Install lefthook with npm, yarn, or pnpm

Source: https://github.com/evilmartians/lefthook/blob/master/docs/installation/node.md

Install the lefthook package as a dev dependency using npm, yarn, or pnpm. For pnpm, you must also update pnpm-workspace.yaml's onlyBuiltDependencies and add lefthook to pnpm.onlyBuiltDependencies in your root package.json, otherwise the postinstall script won't run and hooks won't be installed.

```bash
npm install --save-dev lefthook
```

```bash
yarn add --dev lefthook
```

```bash
pnpm add -D lefthook
```

--------------------------------

### a.txt: Initial file content

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/worktree_partially_staged_issue_1580.txt

This is the initial content of the file a.txt, which is used in the test to stage and unstage changes.

```text
line
```

--------------------------------

### Create test fixture files a.txt, b.txt, dir/a.txt, and dir/b.txt

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/exclude.txt

Test fixture files used as staged files in the lefthook tests. Each file contains its name or directory prefix as content.

```yaml
-- a.txt --
a
```

```yaml
-- b.txt --
b
```

```yaml
-- dir/a.txt --
dir-a
```

```yaml
-- dir/b.txt --
dir-b
```

--------------------------------

### New file content

Source: https://github.com/evilmartians/lefthook/blob/master/tests/integration/run_interrupt.txt

Initial content of newfile.txt.

```text
staged
```

--------------------------------

### Using {files} template with go vet

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/run.md

Runs `go vet` only on files listed by `git ls-files -m` with a `.go` extension. The `{files}` template is substituted with the file list.

```yaml
# lefthook.yml

pre-commit:
  commands:
    govet:
      files: git ls-files -m
      glob: "*.go"
      run: go vet -- {files}
```

--------------------------------

### Example linter.sh script

Source: https://github.com/evilmartians/lefthook/blob/master/docs/configuration/script.md

Bash script that echoes a success message. It is the target of the `script` key in the YAML configuration, located at `.lefthook/pre-commit/linter.sh`.

```bash
# .lefthook/pre-commit/linter.sh

echo "Everything is OK"
```

--------------------------------

### Run pre-commit hooks in bash

Source: https://github.com/evilmartians/lefthook/wiki/Benchmark-lefthook-vs-pre-commit

Executes all configured pre-commit hooks.

```bash
pre-commit run
```
Tokens:
Raw