aaronflorey Lefthook
Use this skill to configure fast, maintainable Git hooks with Lefthook.
Start Here
- Match install instructions to the project ecosystem: npm, Go, Ruby, Python, Homebrew, or standalone binary.
- Prefer
jobsfor new configs;commandsandscriptsare still valid and common. - Keep hooks fast and file-scoped with
{staged_files},{push_files},glob,file_types, androot. - Run
lefthook validatefor syntax checks andlefthook dumpwhen debugging merged config. - Remember:
lefthook installis usually one-time setup; config changes are read on each hook execution.
Fast Routing
| Need | Read |
|---|---|
| Install and official docs map | references/official-docs.md |
| CLI, config model, templates, merge order | references/api-surface.md |
| Common real-world patterns | references/common-use-cases.md |
| Why a hook is skipped or behaving oddly | references/troubleshooting-workarounds.md |
| Ready-to-copy configs | examples/basic-lefthook.yml, examples/monorepo-jobs.yml, examples/commit-message.yml, examples/lefthook-local.yml |
| Bad patterns and fixes | examples/anti-patterns.md |
Recommended Workflow
- Inspect existing package scripts, linters, test commands, and current Git hook tooling.
- Choose the smallest useful hook surface: usually
pre-commit,commit-msg, andpre-push. - Pick
jobs,commands, orscriptsbased on whether you need grouping, named merges, or external executables. - Scope work to changed files unless the check truly needs the whole repository.
- Add
lefthook-local.yml,extends, orremotesonly when you need local overrides or shared policy.
Core Rules
- Prefer deterministic, non-interactive hooks unless the workflow explicitly requires prompts.
- Use
stage_fixed: trueonly forpre-commitfixers that modify staged files. - Remember that
globis evaluated from the Git repo root, even whenrootchanges the working directory. - Use
LEFTHOOK=0for tools that would otherwise recurse back into Git hooks. - Use
lefthook run <hook>to debug a hook directly before testing the full Git flow.