evilmartians
Lefthook
A Git hooks manager for Node.js, Ruby, Python and many other types of projects.
- Fast. It is written in Go. Can run commands in parallel.
- 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.
Install
With Go (>= 1.24):
go install github.com/evilmartians/lefthook@latest
- or as a go tool
go get -tool github.com/evilmartians/lefthook
With NPM:
npm install lefthook --save-dev
For Ruby:
gem install lefthook
For Python:
pip install lefthook
Installation guide with more ways to install lefthook: apt, brew, winget, and others.
Usage
Configure your hooks, install them once and forget about it: rely on the magic underneath.
TL;DR
# 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 '...'
More details
- Configuration for
lefthook.ymlconfig options. - Usage for lefthook CLI options, supported ENVs, and usage tips.
- Discussions for questions, ideas, suggestions.
Why Lefthook
Parallel execution
Gives you more speed. docs
pre-push:
parallel: true
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}
Glob and regexp filters
If you want to filter list of files. You could find more glob pattern examples here.
pre-commit:
jobs:
- name: lint backend
glob: "*.rb" # glob filter
exclude: '(^|/)(application|routes)\.rb$' # regexp filter
run: bundle exec rubocop --force-exclusion {all_files}
Execute in sub-directory
If you want to execute the commands in a relative path
pre-commit:
jobs:
- name: lint backend
root: "api/" # Careful to have only trailing slash
glob: "*.rb" # glob filter
run: bundle exec rubocop {all_files}
Run scripts
If oneline commands are not enough, you can execute files. docs
commit-msg:
jobs:
- script: "template_checker"
runner: bash
Tags
If you want to control a group of commands. docs
pre-push:
jobs:
- name: audit packages
tags:
- frontend
- linters
run: yarn lint
- name: audit gems
tags:
- backend
- security
run: bundle audit
Support Docker
If you are in the Docker environment. docs
pre-commit:
jobs:
- script: "good_job.js"
runner: docker run -it --rm <container_id_or_name> {cmd}
Local config
If you are a frontend/backend developer and want to skip unnecessary commands or override something in Docker. docs
# lefthook-local.yml
pre-push:
exclude_tags:
- frontend
jobs:
- name: audit packages
skip: true
Direct control
If you want to run hooks group directly.
$ lefthook run pre-commit
Your own tasks
If you want to run specific group of commands directly.
fixer:
jobs:
- run: bundle exec rubocop --force-exclusion --safe-auto-correct {staged_files}
- run: yarn eslint --fix {staged_files}
$ lefthook run fixer
Control output
You can control what lefthook prints with output option.
output:
- execution
- failure
Guides
- Install with Node.js
- Install with Ruby
- Install with Homebrew
- Install with Winget
- Install for Debian-based Linux
- Install for RPM-based Linux
- Install for Arch Linux
- Install for Alpine Linux
- Usage
- Configuration
Examples
Check examples
Articles
- 5 cool (and surprising) ways to configure Lefthook for automation joy
- Lefthook: Knock your team’s code back into shape
- Lefthook + Crystalball
- Keeping OSS documentation in check with docsify, Lefthook, and friends
- Automatically linting docker containers
- Smooth PostgreSQL upgrades in DockerDev environments with Lefthook
- Lefthook for React/React Native apps