Git Hooks and Pre-Commit Tools Compared: Husky, Lefthook, and lint-staged
githuskylefthooklint-stagedpre-commitdeveloper-productivity

Git Hooks and Pre-Commit Tools Compared: Husky, Lefthook, and lint-staged

DDev Tools Cloud Editorial Team
2026-11-16
7 min read

Compare Husky, Lefthook, and lint-staged, then use a practical checklist to build fast, portable Git hooks and reliable CI checks.

Choosing a Git hook workflow is less about picking a fashionable package and more about assigning the right checks to the right stage. This guide compares Husky, Lefthook, and lint-staged, then provides a reusable checklist for running formatting, linting, tests, and secret checks without making every commit unnecessarily slow.

Overview

Git hooks are scripts that run at specific points in the Git lifecycle. A pre-commit hook runs before a commit is created, while pre-push runs before local commits are sent to a remote repository. These hooks can catch problems early, but they should complement—not replace—continuous integration.

Husky and Lefthook are hook managers. They help a project install, organize, and run Git hooks consistently for contributors. lint-staged serves a different role: it selects files that are staged for commit and passes those files to commands such as formatters and linters. It is often paired with Husky or Lefthook rather than used as a complete hook-management solution by itself.

The practical division of responsibility is straightforward:

  • Pre-commit: run fast, deterministic checks on changed or staged files.
  • Pre-push: run broader tests that are useful locally but may take longer.
  • CI: run the authoritative checks in a clean, reproducible environment.

For most JavaScript and TypeScript repositories, a sensible starting point is a hook manager plus staged-file handling. The exact choice depends on team familiarity, repository size, monorepo layout, supported operating systems, and whether configuration should live primarily in package files or dedicated hook files.

ConsiderationHuskyLefthooklint-staged
Primary roleGit hook managementGit hook management and task orchestrationRun commands against staged files
Pre-commit speedUsually fast when paired with targeted commandsDesigned for parallel and grouped task executionFast when commands are limited to staged files
Staged-file handlingRequires a separate strategy or toolCan use file patterns and task configurationCore feature
Monorepo fitWorks with deliberate root and package boundariesUseful for centralized or distributed task layoutsWorks well when patterns are carefully scoped
Cross-platform behaviorRelies on portable scripts and package-manager commandsProvides structured task execution, but commands still need testingGenerally portable when shell-specific syntax is avoided
CI compatibilityHook commands can be reused in CI scriptsTask definitions can be reused in CIBest treated as a local file-selection layer, not a CI system
Configuration styleHook files plus package scriptsDedicated configuration or package configurationPackage configuration or a dedicated config file
Best fitTeams wanting a familiar, focused hook managerTeams needing richer task orchestrationProjects that need precise staged-file targeting

Package commands and configuration syntax change over time, so verify the current documentation for the versions selected by your repository. The design principles in this checklist are more stable than any individual installation command.

Checklist by scenario

Scenario 1: You are creating a new JavaScript repository

  1. Define the commands that already work without Git hooks: formatting, linting, unit tests, type checking, and secret scanning.
  2. Put those commands behind named package scripts such as format, lint, test, and typecheck.
  3. Choose Husky or Lefthook as the hook manager. Prefer the tool your team can maintain and explain to new contributors.
  4. Add a fast pre-commit hook. Format and lint staged files first; avoid running the entire end-to-end suite on every commit.
  5. Add a pre-push hook only for checks that provide enough local value to justify their runtime.
  6. Duplicate the important checks in CI. A developer can bypass a local hook, use another client, or work in an environment where hooks are not installed.

Scenario 2: You need formatting and linting only on changed files

This is the clearest use case for lint-staged. Configure file patterns by language or file type, then map each pattern to a command. For example, JavaScript and TypeScript files might receive formatting and linting, while stylesheet files receive formatting and a stylesheet linter.

Check whether each command modifies files. Formatters commonly do. The workflow should allow those modifications to be added back to the commit, then re-evaluate the final staged state. Avoid combining commands in a way that causes a formatter and linter to fight over the same file.

Scenario 3: You are working in a monorepo

  • Decide whether hooks are installed once at the repository root or separately for packages.
  • Make file patterns explicit so a change in one package does not trigger every package's full toolchain.
  • Use package-level scripts where configuration differs, but keep the hook entry point easy to discover.
  • Test changes from the repository root and from a package directory if both workflows are supported.
  • Document the expected package manager and workspace command; mixed invocation styles are a common source of failures.

Scenario 4: Commits are becoming slow

Measure before changing tools. Record which command is slow, how often it runs, and whether it needs the entire repository. Move broad tests to pre-push or CI, narrow pre-commit commands to staged files, and consider parallel execution only when the commands are independent and produce understandable failures. A faster hook manager cannot compensate for an unnecessarily broad task selection.

Scenario 5: You are adding secret or security checks

Use local checks as an early warning, not as the only control. A pre-commit secret scan can inspect changed files, while CI should perform a clean, repeatable scan over the relevant repository state. Define how developers request an approved exception, and ensure the process does not encourage bypassing every failure. Never place actual credentials in test fixtures or example configuration merely to test the scanner.

What to double-check

  • Installation behavior: Confirm that a fresh clone installs hooks after dependencies are installed, and document any required setup step.
  • Git version assumptions: Test with the oldest Git version your project supports rather than only the version on the maintainer's machine.
  • Package-manager consistency: Check npm, pnpm, Yarn, or another selected manager using the repository's lockfile and documented scripts.
  • Operating systems: Test on the operating systems used by contributors. Avoid Bash-only syntax, undeclared environment variables, and path assumptions when a portable command will work.
  • Staging semantics: Verify that partially staged files, renamed files, deleted files, and formatter changes behave as expected.
  • Failure messages: A failed hook should identify the command and provide a direct next step. Suppress unnecessary output, but do not hide the actual error.
  • Bypass controls: Git allows users to bypass hooks. Treat bypasses as an escape hatch for exceptional situations, not as proof that local hooks enforce policy.
  • CI parity: Run the same underlying package scripts in CI where practical. Local convenience wrappers should not become a second, incompatible definition of quality.
  • Secrets and logs: Ensure failed commands do not print tokens, connection strings, or sensitive environment values.

For broader quality workflows, connect these checks to the rest of your toolchain. Browser testing decisions can be reviewed alongside the Playwright, Cypress, and WebdriverIO comparison, while API-focused teams may also benefit from a consistent API testing workflow.

Common mistakes

Running the entire test suite on every commit

This creates friction and encourages bypasses. Keep pre-commit checks focused on quick feedback, then use pre-push or CI for broader coverage. The right boundary depends on project size and test speed, but every command should have a clear reason for its location.

Using lint-staged as if it manages Git hooks

lint-staged selects files and runs commands; it does not replace the hook manager in a typical setup. Pair it with Husky, Lefthook, or another mechanism that actually invokes the pre-commit task.

Putting business logic inside hook files

Keep hook files small. They should call named package scripts or task definitions rather than contain long shell programs. This makes the workflow easier to run manually, debug in CI, and migrate later.

Assuming local hooks guarantee repository quality

Hooks can be skipped, omitted from a clone, or affected by a local environment. CI remains the reliable enforcement point for checks that protect the shared branch.

Ignoring partial staging

Developers often stage only part of a file. Confirm that formatting and lint fixes do not accidentally add unrelated edits to the commit. If they do, document a safer workflow or adjust the command strategy.

When to revisit

Review the hook workflow before seasonal planning cycles, after changing package managers, and whenever the repository adds a language, workspace, formatter, test framework, or security scanner. Also revisit it when contributors report slow commits, inconsistent results across operating systems, or repeated hook bypasses.

Use this short maintenance checklist:

  1. Run the hook from a clean clone using the documented setup path.
  2. Test a normal change, a partially staged change, a deleted file, and a deliberately failing check.
  3. Compare local results with the corresponding CI job.
  4. Measure the slowest pre-commit command and decide whether it still belongs at that stage.
  5. Review tool versions, configuration syntax, package-manager commands, and supported Git versions against current project requirements.
  6. Update contributor documentation when the installation or bypass process changes.

In most repositories, the best setup is not the one with the most checks. It is the one that gives developers fast, actionable feedback before a commit while keeping comprehensive, non-bypassable validation in CI.

Related Topics

#git#husky#lefthook#lint-staged#pre-commit#developer-productivity
D

Dev Tools Cloud Editorial Team

Technical Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.