lint-staged

Run linters and formatters only against the files staged in git, so a slow full-project lint never blocks a commit.

Tool
npm
v17.6.0
14,757 stars
MIT License

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
89 /100 Excellent
Development Activity 96
Maintenance 96
Community 64
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
81 /100 Excellent
Architecture 88
Code Quality 92
Innovation 72
Learning Curve 70

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.

Used by 116 apps in this directory

Rust
93%
Other

Tabby

AI Code Assistants

33,922

Self-hosted AI coding assistant — run GitHub Copilot-grade code completion on your own hardware with no cloud dependency.

View details
55
Repo Health
78
Technical
61
Dependency
Built with
Rust 93%
Updated 4 months ago
TypeScript
99%
Other

Teable

Databases · No Code Platforms

21,957

A no-code PostgreSQL database with spreadsheet UX, real-time collaboration, and native AI agents — built for teams that outgrow Airtable.

View details
80
Repo Health
76
Technical
62
Dependency
Built with
TypeScript 99%
Updated 1 weeks ago
TypeScript
95%
Other

Termix

Devops

15,870

Manage all your servers — SSH terminals, remote desktops, file transfers, and Docker containers — from a single self-hosted browser interface.

View details
84
Repo Health
67
Technical
73
Dependency
Built with
TypeScript 95%
Updated 1 weeks ago
HTML
65%
AGPL 3.0

ToolJet

AI Agents · Low Code Platforms · No Code Platforms

41,204

Open-source AI-native platform to build and deploy internal tools, workflows, and AI agents with a visual drag-and-drop builder and 80+ data source integrations.

View details
94
Repo Health
81
Technical
63
Dependency
Built with
HTML 65%
JavaScript 21%
TypeScript 11%
Updated 1 weeks ago
Go
94%
MIT

Traefik

Automation · Devops · Security

65,483

A cloud-native reverse proxy and load balancer that auto-configures itself from Docker, Kubernetes, and other orchestrators — zero manual routing required.

View details
93
Repo Health
85
Technical
64
Dependency
Built with
Go 94%
Updated 1 weeks ago
TypeScript
97%
Apache 2.0

Unleash

Ab Testing Experimentation · Developer Tools · Devops

14,123

The open-source feature management platform that lets you ship code to production and control who sees it — without redeploying.

View details
91
Repo Health
84
Technical
69
Dependency
Built with
TypeScript 97%
Updated 1 weeks ago
TypeScript
79%
AGPL 3.0

VoidAuth

Authentication · Security

2,905

Self-hosted SSO with OIDC, LDAP, passkeys, and proxy auth for your entire self-hosted stack

View details
83
Repo Health
77
Technical
72
Dependency
Built with
TypeScript 79%
HTML 15%
Updated 1 weeks ago
Go
74%
AGPL 3.0

ZITADEL

Authentication

15,536

Open-source, API-first identity platform delivering multi-tenancy, Passkeys, OIDC, SAML, and SCIM without vendor lock-in.

View details
91
Repo Health
81
Technical
65
Dependency
Built with
Go 74%
TypeScript 12%
Updated 2 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers