@evilmartians/lefthook

Lefthook

The fastest polyglot Git hooks manager out there

Fast and powerful Git hooks manager for Node.js, Ruby or any other type of projects.

• Fast. It is written in Go. Can run commands in parallel.
• Powerful. With a few lines in the config you can check only the changed files on pre-push hook.
• Simple. It is single dependency-free binary which can work in any environment.

📖 Read the introduction post

# On `git push` lefthook will run spelling and links check for all of the changed files
pre-push:
  parallel: true
  commands:
    spelling:
      files: git diff --name-only HEAD @{push}
      glob: "*.md"
      run: npx yaspeller {files}
    check-links:
      files: git diff --name-only HEAD @{push}
      glob: "*.md"
      run: npx markdown-link-check {files}

Usage

Choose your environment:

• Node.js
• Ruby
• Other environments

Then you can find all Lefthook features in the full guide and explore wiki.

---

Why Lefthook

• Parallel execution

If you want more speed. Example

pre-push:
  parallel: true

• Flexible list of files

If you want your own list. Custom and prebuilt examples.

pre-commit:
  commands:
    frontend-linter:
      run: yarn eslint {staged_files}
    backend-linter:
      run: bundle exec rubocop --force-exclusion {all_files}
    frontend-style:
      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:
  commands:
    backend-linter:
      glob: "*.rb" # glob filter
      exclude: "application.rb|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:
  commands:
    backend-linter:
      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. Example.

commit-msg:
  scripts:
    "template_checker":
      runner: bash

• Tags

If you want to control a group of commands. Example.

pre-push:
  commands:
    packages-audit:
      tags: frontend security
      run: yarn audit
    gems-audit:
      tags: backend security
      run: bundle audit

• Support Docker

If you are in the Docker environment. Example.

pre-commit:
  scripts:
    "good_job.js":
      runner: docker run -it --rm <container_id_or_name> {cmd}

• Local config

If you a frontend/backend developer and want to skip unnecessary commands or override something into Docker. Description.

# lefthook-local.yml
pre-push:
  exclude_tags:
    - frontend
  commands:
    packages-audit:
      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:
  commands:
    ruby-fixer:
      run: bundle exec rubocop --force-exclusion --safe-auto-correct {staged_files}
    js-fixer:
      run: yarn eslint --fix {staged_files}

$ lefthook run fixer

• Optional output

If you don't want to see supporting information:

skip_output:
  - meta #(version and which hook running)
  - success #(output from runners with exit code 0)

---

Table of contents:

Guides

• Node.js
• Ruby
• Other environments
• Full features guide
• Troubleshooting

Migrate from

• Husky
• Husky and lint-staged
• Overcommit

Examples

• Simple script
• Full features

Benchmarks

• vs Overcommit
• vs pre-commit

Comparison list

• vs Overcommit, Husky, pre-commit

Articles

• 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

Changelog

1.1.0 (2022-08-13)

• Add goreleaser action (PR #307 by @mrexox)
• Windows escaping issues (PR #314 by @mrexox)
• Check for lefthook.bat in hook template (PR #316 by @mrexox)
• Update node.md docs (PR #312 by @fantua)
• Move postinstall script to main lefthook NPM package (PR #311 by @mrexox)
• Allow suppressing execution output (PR #309 by @mrexox)
• Update dependencies (PR #308 by @mrexox)
• Add support for Git LFS (PR #306 by @mrexox)
• Bump Go version to 1.19 (PR #305 by @mrexox)
• Add tests on runner (PR #304 by @mrexox)
• Add fail text option (PR #301 by @mrexox)
• Store lefthook checksum in non-hook file (PR #280 by @mrexox)