Lefthook & Husky

Why Manage Hooks?

Raw Git hooks in .git/hooks/ have two problems: they are not tracked by Git, and every developer on your team must set them up manually. If a new developer forgets to copy a hook, that person's commits bypass all team standards. A hook manager solves both problems — it stores hooks in version control and installs them automatically when developers clone or install dependencies.

• Hooks are stored in version control (not in .git/hooks/).
• New team members get hooks automatically on install.
• Hooks can run in parallel for speed.
• Configuration is centralized in a single file.

Lefthook

Lefthook is a hook manager written in Go. It is fast, cross-platform, and supports parallel execution out of the box. It uses a single lefthook.toml file for configuration and can run multiple hook scripts simultaneously.

# Install Lefthook (Go binary)
brew install Lefthook/homebrew-lefthook/lefthook

# Or via npm (for Node.js projects)
npm install --save-dev lefthook

# Initialize in your repo
lefthook install

Lefthook Configuration

All Lefthook configuration lives in lefthook.toml at the repo root. Each key in the file maps to a Git hook name. Inside each hook, you define commands — individual scripts that run for that hook.

[pre-commit]
parallel = true
jobs:
  lint:
    glob: "*.{ts,tsx,js,jsx}"
    run: npx eslint --fix {staged_files}
    stage_fixed: true

  format:
    glob: "*.{ts,tsx,js,jsx,json,css}"
    run: npx prettier --write {staged_files}
    stage_fixed: true

  typecheck:
    glob: "*.{ts,tsx}"
    run: npx tsc --noEmit

[commit-msg]
jobs:
  commitlint:
    run: npx commitlint --edit {1}

[pre-push]
jobs:
  test:
    run: npx vitest run
    tags: [test]

• parallel = true — Run all commands simultaneously instead of sequentially.
• glob — Only run the command if staged files match the pattern.
• {staged_files} — A Lefthook variable that expands to the list of staged files.
• stage_fixed: true — Automatically re-stage files that Lefthook modifies (e.g., after formatting).

Husky

Husky is a lightweight hook manager popular in the JavaScript ecosystem. It stores hook scripts as plain shell files in a .husky/ directory, making them easy to read and edit. It works with npm, yarn, and pnpm.

# Install Husky
npm install --save-dev husky

# Initialize Husky in your repo
npx husky init

# This creates a .husky/ directory and sets up
# the prepare script in package.json.

Husky Setup

Each hook is a separate file in .husky/. The file name matches the Git hook name (e.g., pre-commit, commit-msg). The file is a plain shell script.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx commitlint --edit "$1"

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,css,md}": [
      "prettier --write"
    ]
  }
}

Lefthook vs Husky

Choose Lefthook if you want maximum speed, parallel execution, and a language-agnostic setup. Choose Husky if your team is all JavaScript and you want a simpler, more familiar configuration.