Overview
Lefthook is a fast, polyglot Git hooks manager distributed as a single Go binary (current major version: 2.x). It does not need Node.js — you can install it with npm, Homebrew, Go, RubyGems or pipx — and it runs hook tasks in parallel, filters files by glob, and reads its settings from a YAML file in the repository root.
Instructions
Step 1: Install
# Node projects: dev dependency (the package downloads the right binary)
npm install --save-dev lefthook
# pnpm: pnpm add -D lefthook (then allow its build script, see Guidelines)
# Any project
brew install lefthook
go install github.com/evilmartians/lefthook/v2@latest
gem install lefthook
pipx install lefthook
Write the config (Step 2), then install the hooks into .git/hooks:
npx lefthook install # or: lefthook install
If lefthook.yml does not exist yet, lefthook install creates an empty one.
Step 2: Configure
Config lives in lefthook.yml (also accepted: .lefthook.yml, .config/lefthook.yml, and .yaml, .toml, .json, .jsonc variants — keep only one file per project). The current format is a jobs list under each hook; the older commands map still works.
# lefthook.yml — Git hooks configuration
pre-commit:
parallel: true
jobs:
- name: lint
glob: "*.{ts,tsx,js,jsx}"
run: npx eslint --fix {staged_files}
stage_fixed: true
- name: format
glob: "*.{ts,tsx,js,jsx,css,md,json}"
run: npx prettier --write {staged_files}
stage_fixed: true
- name: typecheck
run: npx tsc --noEmit
pre-push:
jobs:
- name: test
run: npm test
commit-msg:
jobs:
- name: commitlint
run: npx commitlint --edit {1}
Parallel jobs that rewrite the same files can race; if lint and format both modify files, drop parallel: true and list them in order (see Example 2).
Step 3: Check and run
npx lefthook validate # check the config for errors
npx lefthook run pre-commit # run a hook by hand, without committing
npx lefthook dump # print the final merged config
LEFTHOOK=0 git commit -m "wip" # skip hooks once (LEFTHOOK_VERBOSE=1 for detail)
Examples
Example 1: Replace Husky in a Node project
Request: "Move our repo from Husky + lint-staged to lefthook."
npm uninstall husky lint-staged
npm install --save-dev lefthook
Delete the .husky/ folder and the lint-staged block from package.json, add the lefthook.yml from Step 2, then run npx lefthook install. Check it with npx lefthook run pre-commit: it lists each job with its result, and exits non-zero if any job fails.
Example 2: Python and Go monorepo without Node
Request: "Add pre-commit checks for our Python API and Go worker, but only on changed files."
# lefthook.yml
pre-commit:
jobs:
- name: ruff
root: "api/"
glob: "*.py"
run: ruff check --fix {staged_files}
stage_fixed: true
- name: gofmt
root: "worker/"
glob: "*.go"
run: gofmt -l -w {staged_files}
stage_fixed: true
brew install lefthook && lefthook install
Committing a change that touches only worker/*.go runs only the gofmt job; the ruff job is skipped because no file matches its glob.
Guidelines
{staged_files}expands to the files staged for the commit,{push_files}to the files in the push,{all_files}to every tracked file, and{1}to the hook's first argument (the commit-message file incommit-msg). Useglobandrootto narrow them; no lint-staged needed.stage_fixed: truere-adds files a formatter changed, so fixes land in the same commit.- Hooks are installed per clone. With the npm package, installing dependencies runs
lefthook installfor you; with pnpm you must allow the build script (addlefthooktoonlyBuiltDependenciesinpnpm-workspace.yaml), otherwise no hooks are installed. With other install methods, tell contributors to runlefthook install. - Personal overrides go in
lefthook-local.yml(add it to.gitignore); it can also be used without a main config. lefthook runandlefthook validateneed a Git repository; outside one they exit with "not a git repository".- Keep pre-commit fast (lint and format on changed files); put slow test suites on
pre-pushor in CI, becauseLEFTHOOK=0andgit commit --no-verifycan bypass local hooks.