Lefthook Setup Guide

Why Lefthook?

Lefthook runs automated checks before each commit — catching bugs, formatting issues, and lint errors before they reach production. Unlike Git hooks that live in .git/hooks (not tracked by Git), Lefthook stores its configuration in lefthook.yml which gets committed to the repository, so every team member gets the same hooks automatically.

If any check fails, the commit is rejected.


Prerequisites

Verify your versions:

node -v
npm -v
go version

Install Lefthook

From your project root:

npm install --save-dev lefthook
npx lefthook install

The output will show sync hooks: pre-commit, commit-msg (or whichever hooks are configured).


Verify Installation

npx lefthook run pre-commit

This runs all checks configured for the pre-commit hook without waiting for an actual commit.


Normal Development Flow

Before committing:

git add .
git commit -m "your message"

Lefthook runs automatically. If any check fails, the commit is rejected. Fix the issue and commit again.


Troubleshooting

If Lefthook is not running on commit:

npx lefthook install

Skip hooks temporarily (emergency only):

git commit --no-verify -m "message"

Configuration

The configuration lives in lefthook.yml at the project root. Here is an example with frontend and backend checks:

pre-commit:
  jobs:
    backend-test:
      root: backend/
      run: go test ./...
    frontend-lint:
      root: customer/
      run: npm run lint

After changing lefthook.yml, run npx lefthook install to sync the hooks.


Team Setup

All developers must install Lefthook before contributing. Commit package.json, package-lock.json, and lefthook.yml to Git. Do not commit .git/hooks. When other developers clone the repository, they run npm install and then npx lefthook install to get the same hooks.

A.M. Rinas

Written by A.M. Rinas

Full-Stack Software Engineer working on web applications, DevOps automation, and databases. More about me on the about page, or say hi through the contact page and LinkedIn.

← Back to all articles