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

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

Summary

Lefthook is a robust Git hooks manager written in Go, designed for speed and flexibility across various project types. It simplifies the process of enforcing code quality and consistency, supporting parallel execution and custom command configurations. This tool ensures your team's code stays in shape with minimal setup and powerful features.

Repository Info

Updated on December 31, 2025
View on GitHub

Tags

gitgogolanghooksmanagerdevelopmentautomationdevops

Click on any tag to explore related repositories

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