lint-staged
Run linters and formatters only against the files staged in git, so a slow full-project lint never blocks a commit.
Repository Health
Technical Analysis
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
Tabby
AI Code Assistants
Self-hosted AI coding assistant — run GitHub Copilot-grade code completion on your own hardware with no cloud dependency.
Teable
Databases · No Code Platforms
A no-code PostgreSQL database with spreadsheet UX, real-time collaboration, and native AI agents — built for teams that outgrow Airtable.
Termix
Devops
Manage all your servers — SSH terminals, remote desktops, file transfers, and Docker containers — from a single self-hosted browser interface.
ToolJet
AI Agents · Low Code Platforms · No Code Platforms
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.
Traefik
Automation · Devops · Security
A cloud-native reverse proxy and load balancer that auto-configures itself from Docker, Kubernetes, and other orchestrators — zero manual routing required.
Unleash
Ab Testing Experimentation · Developer Tools · Devops
The open-source feature management platform that lets you ship code to production and control who sees it — without redeploying.
VoidAuth
Authentication · Security
Self-hosted SSO with OIDC, LDAP, passkeys, and proxy auth for your entire self-hosted stack
ZITADEL
Authentication
Open-source, API-first identity platform delivering multi-tenancy, Passkeys, OIDC, SAML, and SCIM without vendor lock-in.