lint-staged — Run Linters on Staged Git Files Before Commit

Introduction

lint-staged runs configured linters and formatters only on the files that are staged in git, rather than scanning the entire project. This makes pre-commit checks fast regardless of project size and ensures that every committed file passes quality gates. Combined with a git hook manager like Husky or Lefthook, it creates a seamless guardrail that catches issues before they reach code review.

What lint-staged Does

• Filters staged files by glob patterns and runs matched commands against them
• Automatically re-stages files after formatters modify them in place
• Supports running multiple commands per file pattern in sequence or in parallel
• Integrates with any linter, formatter, or script that accepts file paths as arguments
• Aborts the commit if any configured command exits with a non-zero status

Architecture Overview

When invoked, lint-staged reads its configuration from package.json, a dedicated config file, or CLI flags. It queries git for the list of currently staged files, matches them against the configured glob patterns, and spawns the associated commands with matching file paths as arguments. If a formatter modifies a file, lint-staged automatically re-adds it to the staging area. The tool runs in a Node.js process and uses listr2 for concurrent task orchestration and progress display.

Self-Hosting & Configuration

• Install as a dev dependency: npm install --save-dev lint-staged
• Configure via "lint-staged" key in package.json or a .lintstagedrc file
• Glob patterns support brace expansion: "*.{js,jsx,ts,tsx}": "eslint --fix"
• Pair with Husky: npx husky add .husky/pre-commit "npx lint-staged"
• Use --concurrent false to run tasks sequentially when order matters

Key Features

• Only processes staged files, keeping pre-commit hooks fast on large repos
• Auto-restages files modified by formatters so the commit includes fixes
• Works with any CLI tool that accepts file paths — ESLint, Prettier, Stylelint, etc.
• Supports concurrent task execution for independent linter groups
• Partial staging support — preserves unstaged changes in modified files

Comparison with Similar Tools

• Husky — manages git hooks but does not filter staged files; use both together
• pre-commit (Python) — language-agnostic hook framework with its own plugin ecosystem; lint-staged is npm-native
• Lefthook — Go-based git hooks manager with built-in glob filtering; lint-staged is more widely used in JS ecosystems
• pretty-quick — Prettier-only staged file runner; lint-staged is tool-agnostic
• nano-staged — lighter alternative with a similar API; lint-staged has broader adoption and edge-case handling

FAQ

Q: Does lint-staged work with monorepos? A: Yes. Place a lint-staged config in each package directory or use a root-level config with appropriate glob patterns.

Q: Can I run type checking with lint-staged? A: TypeScript type-checking typically requires the full project context, not individual files. Use tsc --noEmit in a separate hook rather than in lint-staged.

Q: What happens if a linter fails? A: lint-staged exits with a non-zero code, which aborts the git commit when used as a pre-commit hook.

Q: Does lint-staged support partially staged files? A: Yes. It stashes unstaged changes before running tasks and restores them afterward, so only the staged version is checked.

Sources

• https://github.com/lint-staged/lint-staged
• https://github.com/lint-staged/lint-staged/blob/main/README.md