Lefthook: A Fast and Powerful Git Hooks Manager for Any Project

Introduction

Lefthook, developed by Evil Martians, is an incredibly fast and powerful Git hooks manager. Written in Go, it provides a simple, dependency-free binary that works seamlessly in any environment, making it an ideal solution for managing pre-commit, pre-push, and other Git hooks. Whether you're working with Node.js, Ruby, Python, or other project types, Lefthook helps automate code quality checks and maintain consistency across your team.

Installation

Lefthook offers multiple installation methods to suit your development environment. Here are a few common ways to get started:

With Go (>= 1.25):

go install github.com/evilmartians/lefthook/v2@v2.0.13

With NPM:

npm install lefthook --save-dev

For Ruby:

gem install lefthook

For Python:

pipx install lefthook

For a comprehensive list of installation options, including apt, brew, and winget, please refer to the official installation guide.

Examples

Lefthook's power lies in its flexible configuration and diverse features. Here are some examples demonstrating its capabilities:

Parallel Execution

Speed up your hook execution by running commands in parallel. This is particularly useful for multiple independent checks.

pre-push:
  parallel: true

Flexible File Lists

Control which files are passed to your commands, using staged_files, all_files, or custom Git diff commands.

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

Filter the list of files using glob patterns or regular expressions to apply specific checks only where needed.

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

Support for Docker

Integrate Lefthook with your Docker environment to run commands inside containers.

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

Local Configuration Overrides

Use lefthook-local.yml to skip unnecessary commands or override configurations for specific development environments.

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

Why Use Lefthook?

Lefthook stands out as a superior Git hooks manager due to several key advantages:

• Speed: Written in Go, it's incredibly fast and supports parallel execution of commands.
• Power: Offers fine-grained control over command execution, file filtering, and custom scripting.
• Simplicity: A single, dependency-free binary that's easy to install and integrate into any project.
• Flexibility: Supports various languages and environments, including Docker, and allows for local configuration overrides.
• Maintainability: Helps enforce consistent code standards and automated checks across development teams.

Links

• Official Documentation
• Configuration Guide
• Usage Commands
• Discussions on GitHub