lint-staged

lint-staged is a small CLI that filters git’s staged files through glob patterns and runs whatever formatters, linters, or scripts you configure against just that subset, instead of the whole repository. It’s almost always wired into a pre-commit git hook (commonly via Husky) so that every commit is automatically checked or auto-fixed before it lands in history.

What sets it apart from a naive “run eslint on changed files” script is its git-state safety net: before running any task it creates a git stash backup of the working tree, can hide unstaged or partially-staged hunks so auto-fixing tasks never touch code that wasn’t actually staged, then re-stages only the files the tasks modified and restores everything else exactly as it was. If a task fails or reverts staged changes entirely, lint-staged can roll the working tree back to its original state.

Configuration is a simple glob-to-command map (in package.json, a lintstagedrc file, or a JS/YAML config), supports running multiple commands in sequence per glob, plain JS functions as tasks, and multiple independent configs across monorepo packages.

What You Get

• Glob-to-command configuration mapping staged file patterns to shell commands or JS functions
• Automatic git stash backup before running tasks, with restore-on-failure
• Partial-stage awareness that hides unstaged hunks so auto-fixers only touch staged content
• Support for running multiple sequential commands per glob pattern
• Monorepo support via multiple independent lint-staged configs grouped by directory
• A programmatic Node.js API (in addition to the CLI) for custom tooling integrations

Common Use Cases

• Running Prettier and ESLint automatically on every git commit via a pre-commit hook
• Enforcing stylelint or oxlint checks only on the CSS/JS files actually being committed
• Blocking commits that fail type-checking or tests on the changed files
• Auto-fixing formatting issues without reformatting untouched parts of the repository
• Running independent lint configurations per package in a JS monorepo

Under The Hood

Architecture

Execution starts in bin/lint-staged.js, which parses CLI flags and calls lib/index.js’s default export; that function validates options then hands off to runAll.js, which is the real orchestrator. runAll resolves the git repo root (resolveGitRepo.js), fetches staged files (getStagedFiles.js) and any lint-staged configs (searchConfigs.js) in parallel, groups matched files by which config governs them (groupFilesByConfig.js), and expands each config into concrete tasks via generateTasks.js (glob matching lives in matchFiles.js/picomatch). Each task is either a plain function (getFunctionTask.js) or a spawned child process (getSpawnedTask.js/getSpawnedTasks.js), all wired to a shared AbortController so a failure or Ctrl+C can cancel every in-flight task. All git-state mutation — creating the backup stash, hiding partially staged hunks, updating the index after tasks run, and restoring unstaged/untracked files or the original state on error — is centralized in a single GitWorkflow class (gitWorkflow.js), keeping git plumbing cleanly separated from task-execution and glob-matching logic; nearly every later step depends on the ctx state GitWorkflow maintains, so that class is the one abstraction the rest of the pipeline can’t function without.

Tech Stack

A modern ESM-only Node package (“type”: “module”, requires Node >=22.22.1) with no TypeScript compilation step — instead it ships hand-authored .d.ts declaration files alongside plain JS, checked via tsc in a typecheck script. Runtime dependencies are deliberately minimal: picomatch for glob matching, string-argv for parsing shell-style argument strings, tinyexec for lightweight child-process spawning, and an optional yaml dependency for YAML-based config files. Tooling leans on the Rust-based oxlint/oxfmt pair instead of ESLint/Prettier, vitest with istanbul coverage for testing, and changesets for release versioning, with GitHub Actions running dedicated release, security, npm-publish, and pull-request workflows.

Code Quality

The test suite is extensive and layered: 41 unit test files, 39 integration test files exercising real git repositories, and 7 end-to-end tests, plus shared utils and types directories, all run through vitest. Errors are modeled as typed Symbol tags (symbols.js: ConfigNotFoundError, GitError, IntentToAddError, and others) accumulated in a ctx.errors Set and mapped to dedicated message formatters, giving callers structured, matchable failure modes rather than generic thrown strings. Naming is consistently camelCase with one exported concern per file, type safety comes from JSDoc annotations checked by tsc, and both linting (oxlint) and formatting (oxfmt) run in CI alongside the test suite on every pull request.

What Makes It Unique

The distinguishing technical choice is how carefully it handles partial git staging: rather than assuming staged and working-tree content match, it can hide unstaged hunks before running auto-fixing tasks and then surgically restore only what wasn’t touched, backed by a git stash checkpoint it can roll back to on any failure. Configurable function-based tasks and per-directory config grouping for monorepos extend this further. The category of tool (“lint only what’s staged”) isn’t new, but the depth of its safety net around auto-fixing and partial staging is more careful than typical alternatives in this space.