npm / lint-staged
lint-staged
What changed in lint-staged 16 to 17, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
6 breaking5 new APIs and options11 behavior and defaults25 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initlint-staged 1739 changes
Breaking changes 6
lint-staged now stages changes to all tracked files modified by tasks, including files not originally staged or matching configured globs.
Lint-staged refuses to run when files were staged with this flag, because Git stash does not support them.
Failed JS function tasks now kill other tasks unless --continue-on-error is used.
lint-staged now verifies that the installed Git version is at least 2.32.0 before running.
Node.js 20 is no longer supported; lint-staged now requires Node.js 22.22.1 or newer.
On POSIX systems, scripts with the
#!/usr/bin/env nodeshebang now run with the same Node.js version that lint-staged itself was started with.
New APIs and options 5
Use this option to hide unstaged changes while tasks run, preventing edits by a task from staging those changes too.
Task functions receive a log() function for emitting output while the task runs; output is visible by default only when the task fails, and rejected-task errors are shown.
Includes all Git-tracked files instead of only staged files; implies --no-stash and --allow-empty.
Added a helper for type-checking the lint-staged configuration, imported from lint-staged/config.
Hides all unstaged changes and untracked files before running tasks; untracked files are included in the backup stash and restored afterward.
Behavior and default changes 10
Lint-staged now honors the FORCE_COLOR environment variable.
During an in-progress merge, files unchanged from the branch being merged are skipped; files are included only if they have staged changes against both HEAD and MERGE_HEAD.
Nested task arrays let a glob run tasks in parallel within a sequential task list.
Chunking is based on the final generated command string rather than only the staged-file list, making it more precise, especially on Windows.
Native JavaScript/Node.js function tasks are no longer chunked or run multiple times when many files are staged.
Accepts Infinity to disable chunking tasks by the number of staged files; parsing and validation have also been improved.
Output uses fewer interactive spinners and more explicit messages such as “Started…” and “Done!”.
The default value is now set based on the running platform, controlling how very long lists of staged files are split into chunks.
lint-staged runs this command after tasks instead of adding the originally staged files, improving compatibility with non-default indexes and pathspec commits.
The yaml dependency is optional and probably won't be installed by default; install it separately when using a YAML configuration file.
Fixes and other changes 18
Nested arrays of tasks returned by a function now run inner tasks in parallel, consistent with task arrays defined directly.
Partially staged changes are hidden in uniquely named patch files, avoiding overwrites between lint-staged invocations and making concurrent runs in multiple worktrees safer.
Changes the signature from const to a function to fix TypeScript issue TS1254.
Lint-staged does not try to restore untracked files when this flag is used and there is no initial commit.
Local binaries from node_modules/.bin are resolved starting from the directory of each lint-staged configuration file in monorepo setups.
Color support is handled better in non-TTY streams.
Its behavior was improved when lint-staged runs in multiple worktrees in parallel; parallel instances in the same tree should still be avoided.
Parsing was rewritten to avoid inconsistent behavior between CLI flags and Node.js API options.
Parsing and validation of this numeric CLI option have been improved.
Console output colors are enabled or disabled more consistently.
lint-staged tries to restore hidden unstaged changes when --no-revert is used.
Using this option no longer causes lint-staged to discard the ongoing merge conflict status in .git/MERGE_HEAD.
Using this option no longer causes lint-staged to discard the ongoing merge conflict status in .git/MERGE_HEAD.
Output on stderr is ignored for successful Git commands, avoiding issues when commands emit warnings despite exiting with code 0.
lint-staged uses git add again to stage task modifications, fixing a performance regression in very large Git repositories.
lint-staged now correctly adds task modifications to the commit when files are explicitly staged, committed with --all, or committed using a pathspec.
Fixes lint-staged behavior when files are implicitly staged by git commit -am or git commit with a pathspec, without using git add.
When Node.js is installed from Ubuntu App Center, scripts with the
#!/usr/bin/env nodeshebang are now spawned with the real Node.js binary instead of the Snap symlink.
lint-staged 168 changes
Behavior and default changes 1
When a task fails, its subprocesses are killed more efficiently via the process group on Unix systems and the taskkill command on Windows.
Fixes and other changes 7
Commands prefer local node_modules/.bin locations over global locations.
Git's warning about CRLF line endings no longer interferes with creating the initial backup stash.
On Windows, tasks are spawned without the detached option to hide the extra cmd window.
Incorrect brace expansions like
*.{js}are detected exhaustively instead of in a single pass.The “failed to spawn” error message is no longer displayed when a task fails normally; it is reserved for failures to spawn the task.
Fixes problems where tasks might still have been killed with SIGINT when one of them failed.
Fixes unhandled promise rejections when tasks fail to spawn; previously lint-staged could fail and the backup stash might not be automatically restored.