wiki / raw / lint-staged-official-readme-2026
lint-staged official README
loading…
Original source: https://github.com/lint-staged/lint-staged SHA256: 6c106f06eb2a49c85cf5a15b12fb1a3da77c68444245bf111d2be27619b30abe
lint-staged official README
You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Uh oh!
There was an error while loading. Please reload this page.
lint-staged/ lint-staged Public
- Sponsor
Sponsor lint-staged/lint-staged
External links
opencollective.com/ lint-staged
Learn more about funding links in repositories.
- Notifications You must be signed in to change notification settings
- Fork\ 472
- Star\ 14.7k
main
Go to Branches pageGo to Tags page
Go to file
Code
Open more actions menu
Latest commit
Merge pull request #1841 from lint-staged/changeset-release/main
Open commit detailssuccess
2 days agoAug 27, 2026
d0c1517 · 2 days agoAug 27, 2026
History
Open commit details
View commit history for this file. 1,529 Commits
Folders and files
Repository files navigation
🚫💩 lint-staged
Run tasks like formatters and linters against staged git files and don’t let 💩 slip into your code base!
npm install --save-dev lint-staged # requires further setup$ git commit
⋯ Backing up original state…
✔ Done backing up original state (1f4c047d)!
⋯ Running tasks for staged files…
*.{json,md} — 1 file
⋯ prettier --write
✔ prettier --write
✔ Done running tasks for staged files!
⋯ Staging changes from tasks…
✔ Done staging changes from tasks!
⋯ Cleaning up temporary files…
✔ Done cleaning up temporary files!Tip
Do you only want to check staged files for errors, but not edit them automatically?
You might be interested in this simpler shell script: lint-staged.sh.
Table of Contents
- Why
- Installation and setup
- Changelog
- Command line flags
- Configuration
- Filtering files
- What commands are supported?
- Running multiple commands in a sequence
- Using JS configuration files
- Reformatting the code
- Examples
- Frequently Asked Questions
Why
Code quality tasks like formatters and linters make more sense when run before committing your code. By doing so you can ensure no errors go into the repository and enforce code style. But running a task on a whole project can be slow, and opinionated tasks such as linting can sometimes produce irrelevant results. Ultimately you only want to check files that will be committed.
This project contains a script that will run arbitrary shell tasks with a list of staged files as an argument, filtered by a specified glob pattern.
Related blog posts and talks
Permalink: Related blog posts and talks
- Introductory Medium post - Andrey Okonetchnikov, 2016
- Running Jest Tests Before Each Git Commit - Ben McCormick, 2017
- AgentConf presentation - Andrey Okonetchnikov, 2018
- SurviveJS interview - Juho Vepsäläinen and Andrey Okonetchnikov, 2018
- Prettier your CSharp with
dotnet-formatandlint-staged
Installation and setup
Permalink: Installation and setup
To install lint-staged in the recommended way, you need to:
-
Install lint-staged itself:
npm install --save-dev lint-staged
-
Set up the
pre-commitgit hook to run lint-staged -
Configure lint-staged to run code checkers and other tasks:
- for example:
{ "*.js": "eslint" }to run ESLint for all staged JS files - See Configuration for more info
- for example:
Don’t forget to commit changes to package.json and .husky to share this setup with your team!
Now change a few files, git add or git add --patch some of them to your commit, and try to git commit them.
See examples and configuration for more information.
Caution
Lint-staged runs git operations affecting the files in your repository. By default lint-staged creates a git stash as a backup of the original state before running any configured tasks to help prevent data loss.
Changelog
See Releases.
Migration
For breaking changes, see MIGRATION.md.
Command line flags
❯ npx lint-staged --help
Usage: lint-staged [options]
-h, --help display this help message
-V, --version display the current version number
--all include all files tracked in Git instead of only staged (default: false). Implies "--no-stash" and "--allow-empty".
--allow-empty allow empty commits when tasks revert all staged changes (default: false)
-p, --concurrent <number|boolean> the number of tasks to run concurrently, or false for serial (default: true)
-c, --config [path] path to configuration file, or - to read from stdin
--continue-on-error run all tasks to completion even if one fails (default: false)
--cwd [path] run all tasks in specific directory, instead of the current
-d, --debug print additional debug information (default: false)
--diff [string] override the default "--staged" flag of "git diff" to get list of files. Implies "--no-stash".
--diff-filter [string] override the default "--diff-filter=ACMR" flag of "git diff" to get list of files
--fail-on-changes fail with exit code 1 when tasks modify tracked files (default: false)
--no-hide-partially-staged hide unstaged changes from partially staged files (default: true)
--hide-unstaged hide all unstaged changes, instead of just partially staged (default: false)
--hide-all hide all unstaged changes and untracked files (default: false)
--max-arg-length [number] maximum length of the command-line argument string (default: 0)
-q, --quiet disable lint-staged's own console output (default: false)
-r, --relative pass relative filepaths to tasks (default: false)
--no-revert revert to original state in case of errors (default: true)
--no-stash enable the backup stash (default: true)
-v, --verbose show task output even when tasks succeed; by default only failed output is shown (default: false)
Any lost modifications can be restored from a git stash:
> git stash list --format="%h %s"
<git-hash> On main: lint-staged automatic backup
> git apply --index <git-hash>--all
By default lint-staged only runs tasks on files that include staged changes (hence the name). Use this flag to include all files tracked in Git version control (standard exclusions apply). Using this flag implies the --no-stash flag, disabling the automatic backup, and the --allow-empty flag so that lint-staged doesn’t fail when there are no changes after running. This makes it easier to run npx lint-staged --all on a clean state, for example in CI.
--allow-empty
By default, when tasks undo all staged changes, lint-staged will exit with an error and abort the commit. Use this flag to allow creating empty git commits.
--concurrent [number|boolean]
Permalink: —concurrent [number|boolean]
Controls the concurrency of tasks being run by lint-staged. NOTE: This does NOT affect the concurrency of subtasks (they will always be run sequentially). Possible values are:
false: Run all tasks seriallytrue(default) : Infinite concurrency. Runs as many tasks in parallel as possible.{number}: Run the specified number of tasks in parallel, where1is equivalent tofalse.
--config [path]
Manually specify a path to a config file or npm package name. Note: when used, lint-staged won’t perform the config file search and will print an error if the specified file cannot be found. If ’-’ is provided as the filename then the config will be read from stdin, allowing piping in the config like cat my-config.json | npx lint-staged --config -.
--cwd [path]
Change the working directory lint-staged runs tasks in. Defaults to process.cwd() and the value can be absolute or relative to the default value.
--debug
Log additional information about staged files, commands being executed, location of binaries, etc.
--diff
By default tasks are filtered against all files staged in git, generated from git diff --staged. This option allows you to override the --staged flag with arbitrary revisions. For example to get a list of changed files between two branches, use --diff="branch1...branch2". You can also read more from about git diff and gitrevisions. This option also implies --no-stash.
--diff-filter [string]
Permalink: —diff-filter [string]
By default only files that are added, copied, modified, or renamed are included. Use this flag to override the default ACMR value with something else: added (A), copied (C), deleted (D), modified (M), renamed (R), type changed (T), unmerged (U), unknown (X), or pairing broken (B). See also the git diff docs for —diff-filter.
--continue-on-error
By default lint-staged will “exit early” when any of the configured tasks fails, to make sure the runtime is short. With this flag, lint-staged will instead run all tasks to completion and only fail at the end, allowing all task output to be seen.
--fail-on-changes
By default changes made by tasks are automatically staged and added to the commit. This flag disables the behavior and makes lint-staged exit with code 1, failing the commit instead. Using this flag also implies the --no-revert flag which means any changes made my tasks will be left in the working tree after failing, so that they can be manually staged and the commit tried again.
--max-arg-length [number]
Permalink: —max-arg-length [number]
The list of staged files are appended to configured tasks as arguments, and the resulting string might be too long for the current shell, especially on Windows. Lint-staged tries to avoid this by splitting the list of staged files into chunks resulting in the commands being run multiple times. This behavior affects all tasks, including functions. Use the --max-arg-length to override the platform-specific default value if you want to avoid this. Setting --max-arg-length=Infinity will disable chunking completely.
--no-stash
By default a backup stash will be created before running the tasks, and all task modifications will be reverted in case of an error. This option will disable creating the stash, and instead leave all modifications in the index when aborting the commit.
--no-hide-partially-staged
Permalink: —no-hide-partially-staged
By default, unstaged changes from partially staged files will be hidden and applied back after running tasks. This option will disable this behavior, causing those changes to also be committed.
--hide-unstaged
Use this option to hide all unstaged changes in tracked files, instead of just those which are also partially staged, before running tasks. The changes will be applied back after running the tasks.
--hide-all
Add new option --hide-all for hiding all unstaged changes and untracked files, before running tasks. This makes it easier to run tools like Knip which check for unused code. Untracked files are included in the backup stash and restored automatically after running.
--quiet
Suppress all CLI output, except from tasks.
--relative
Pass filepaths relative to process.cwd() (where lint-staged runs) to tasks. Default is false.
--no-revert
By default all task modifications will be reverted in case of an error. This option will disable the behavior, and apply task modifications to the index before aborting the commit.
--verbose
Show task output even when tasks succeed. By default only failed output is shown.
Configuration
Lint-staged can be configured in many ways:
-
lint-stagedobject in yourpackage.json, orpackage.yaml -
.lintstagedrcfile in JSON or YML format, or you can be explicit with the file extension:.lintstagedrc.json.lintstagedrc.yaml.lintstagedrc.yml
-
.lintstagedrc.mjsorlint-staged.config.mjsfile in ESM format- the default export value should be a configuration:
export default { ... }
- the default export value should be a configuration:
-
.lintstagedrc.cjsorlint-staged.config.cjsfile in CommonJS format- the exports value should be a configuration:
module.exports = { ... }
- the exports value should be a configuration:
-
lint-staged.config.jsor.lintstagedrc.jsin either ESM or CommonJS format, depending on whether your project’s package.json contains the"type": "module"option or not. -
Pass a configuration file using the
--configor-cflag
Configuration should be an object where each value is a command to run and its key is a glob pattern to use for this command. This package uses picomatch for glob patterns. JavaScript files can also export advanced configuration as a function. See Using JS configuration files for more info.
You can also place multiple configuration files in different directories inside a project. For a given staged file, the closest configuration file will always be used and tasks will by default run in the directory of the config (for example, the directory of a specific package in a monorepo). See “How to use lint-staged in a multi-package monorepo?” for more info and an example.
package.json example:
Permalink: package.json example:
{
"lint-staged": {
"*": "your-cmd"
}
}.lintstagedrc.json example
Permalink: .lintstagedrc.json example
{
"*": "your-cmd"
}This config will execute your-cmd with the list of currently staged files passed as arguments.
So, considering you did git add file1.ext file2.ext, lint-staged will run the following command:
your-cmd file1.ext file2.ext
TypeScript
Lint-staged provides TypeScript types for the configuration and main Node.js API. You can use the defineConfig helper in your JS configuration files:
import { defineConfig } from 'lint-staged/config'
export default defineConfig({
'*': 'prettier --write',
})It’s also possible to use the .ts file extension for the configuration if your Node.js version supports it. The --experimental-strip-types flag was introduced in Node.js v22.6.0 and unflagged in v23.6.0, enabling Node.js to execute TypeScript files without additional configuration.
export NODE_OPTIONS="--experimental-strip-types"
npx lint-staged --config lint-staged.config.tsTask concurrency
By default lint-staged will run configured tasks concurrently. This means that for every glob, all the commands will be started at the same time. With the following config, both eslint and prettier will run at the same time:
{
"*.ts": "eslint",
"*.md": "prettier --list-different"
}This is typically not a problem since the globs do not overlap, and the commands do not make changes to the files, but only report possible errors (aborting the git commit). If you want to run multiple commands for the same set of files, you can use the array syntax to make sure commands are run in order. In the following example, prettier will run for both globs, and in addition eslint will run for *.ts files after it. Both sets of commands (for each glob) are still started at the same time (but do not overlap).
{
"*.ts": ["prettier --list-different", "eslint"],
"*.md": "prettier --list-different"
}If you want to run tasks parallely for a specific glob, you can nest one extra layer of arrays, inside the array. In the following example, prettier and eslint will run in parallel for *.ts files, while the two globs also run in parallel.
{
"*.ts": [["prettier --list-different", "eslint"]],
"*.md": "prettier --list-different"
}Pay extra attention when the configured globs overlap, and tasks make edits to files. For example, in this configuration prettier and eslint might try to make changes to the same *.ts file at the same time, causing a race condition:
{
"*": "prettier --write",
"*.ts": "eslint --fix"
}You can solve it using the negation pattern and the array syntax:
{
"!(*.ts)": "prettier --write",
"*.ts": ["eslint --fix", "prettier --write"]
}Another example in which tasks make edits to files and globs match multiple files but don’t overlap:
{
"*.css": ["stylelint --fix", "prettier --write"],
"*.{js,jsx}": ["eslint --fix", "prettier --write"],
"!(*.css|*.js|*.jsx)": ["prettier --write"]
}Or, if necessary, you can limit the concurrency using --concurrent <number> or disable it entirely with --concurrent false.
Filtering files
Task commands work on a subset of all staged files, defined by a glob pattern. lint-staged uses picomatch for matching files with the following rules:
-
If the glob pattern contains no slashes (
/), picomatch’smatchBaseoption will be enabled, so globs match a file’s basename regardless of directory:"*.js"will match all JS files, like/test.jsand/foo/bar/test.js"!(*test).js"will match all JS files, except those ending intest.js, sofoo.jsbut notfoo.test.js"!(*.css|*.js)"will match all files except CSS and JS files
-
If the glob pattern does contain a slash (
/), it will match for paths as well:"./*.js"will match all JS files in the git repo root, so/test.jsbut not/foo/bar/test.js"foo/**/*.js"will match all JS files inside the/foodirectory, so/foo/bar/test.jsbut not/test.js
When matching, lint-staged will do the following
- Resolve the git root automatically, no configuration needed.
- Pick the staged files which are present inside the project directory.
- Filter them using the specified glob patterns.
- Pass absolute paths to the tasks as arguments.
NOTE:lint-staged will pass absolute paths to the tasks to avoid any confusion in case they’re executed in a different working directory (i.e. when your .git directory isn’t the same as your package.json directory).
Also see How to use lint-staged in a multi-package monorepo?
Ignoring files
The concept of lint-staged is to run configured linter tasks (or other tasks) on files that are staged in git. lint-staged will always pass a list of all staged files to the task, and ignoring any files should be configured in the task itself.
Consider a project that uses prettier to keep code format consistent across all files. The project also stores minified 3rd-party vendor libraries in the vendor/ directory. To keep prettier from throwing errors on these files, the vendor directory should be added to prettier’s ignore configuration, the .prettierignore file. Running npx prettier . will ignore the entire vendor directory, throwing no errors. When lint-staged is added to the project and configured to run prettier, all modified and staged files in the vendor directory will be ignored by prettier, even though it receives them as input.
[… middle omitted — see footer …]
Using with JetBrains IDEs (WebStorm, PyCharm, IntelliJ IDEA, RubyMine, etc.)
Permalink: Using with JetBrains IDEs (WebStorm, PyCharm, IntelliJ IDEA, RubyMine, etc.)
Click to expand
Update: The latest version of JetBrains IDEs now support running hooks as you would expect.
When using the IDE’s GUI to commit changes with the precommit hook, you might see inconsistencies in the IDE and command line. This is known issue at JetBrains so if you want this fixed, please vote for it on YouTrack.
Until the issue is resolved in the IDE, you can use the following config to work around it:
husky v1.x
{
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"post-commit": "git update-index --again"
}
}
}husky v0.x
{
"scripts": {
"precommit": "lint-staged",
"postcommit": "git update-index --again"
}
}Thanks to this comment for the fix!
How to use lint-staged in a multi-package monorepo?
Permalink: How to use lint-staged in a multi-package monorepo?
Click to expand
Install lint-staged on the monorepo root level and add separate configuration files in each package. Lint-staged will find each config file and match staged files to the closest config. The directory of each config file will be used as the working directory for those tasks, unless --cwd option is used. This is almost the same as running multiple processes of lint-staged in parallel for each config, but multiple parallel locking Git operations are avoided.
For example, in a monorepo with packages/frontend/.lintstagedrc.json and packages/backend/.lintstagedrc.json, a staged file inside packages/frontend/ will only match that configuration, and not the one in packages/backend/.
Note: lint-staged does not merge config files, so if the closest config file to a staged file doesn’t match it, the file will be ignored. For example:
// ./.lintstagedrc.json
{ "*.md": "prettier --write" }// ./packages/frontend/.lintstagedrc.json
{ "*.js": "eslint --fix" }When committing ./packages/frontend/README.md, it will not run prettier, because the configuration in the frontend/ directory is closer to the file and doesn’t include it. You should treat all lint-staged configuration files as isolated and separated from each other. You can always use JS files to “extend” configurations, for example:
import baseConfig from '../.lintstagedrc.js'
export default {
...baseConfig,
'*.js': 'eslint --fix',
}Note: If you want to run lint-staged in only one package inside a monorepo, you can simply use the --cwd option (for example lint-staged --cwd packages/frontend).
Note: It is possible to run all tasks in the monorepo root by explicitly configuring lint-staged --cwd=".".
Can I lint files outside of the current project folder?
Permalink: Can I lint files outside of the current project folder?
Click to expand
tl;dr: Yes, but the pattern should start with ../.
By default, lint-staged executes tasks only on the files present inside the project folder(where lint-staged is installed and run from).
So this question is relevant only when the project folder is a child folder inside the git repo.
In certain project setups, it might be desirable to bypass this restriction. See #425, #487 for more context.
lint-staged provides an escape hatch for the same(>= v7.3.0). For patterns that start with ../, all the staged files are allowed to match against the pattern.
Note that patterns like *.js, **/*.js will still only match the project files and not any of the files in parent or sibling directories.
Example repo: sudo-suhas/lint-staged-django-react-demo.
Can I run lint-staged in CI, or when there are no staged files?
Permalink: Can I run lint-staged in CI, or when there are no staged files?
Click to expand
Lint-staged will by default run against files staged in git, and should be run during the git pre-commit hook, for example. It’s also possible to override this default behaviour and run against files in a specific diff, for example all changed files between two different branches. If you want to run lint-staged in the CI, maybe you can set it up to compare the branch in a Pull Request/ Merge Request to the target branch.
Try out the git diff command until you are satisfied with the result, for example:
git diff --diff-filter=ACMR --name-only main...my-branchThis will print a list of added, changed, modified, and renamed files between main and my-branch.
You can then run lint-staged against the same files with:
npx lint-staged --diff="main...my-branch"Note that —diff=“main..my-branch” will have files that changed on main and are not yet caught up on my-branch be detected as changed files.
To see just that changes on the current branch, as compared to main you may wish to use:
npx lint-staged --diff="$(git merge-base main HEAD)"Can I use lint-staged with ng lint
Permalink: Can I use lint-staged with ng lint
Click to expand
You should not use ng lint through lint-staged, because it’s designed to lint an entire project. Instead, you can add ng lint to your git pre-commit hook the same way as you would run lint-staged.
See issue !951 for more details and possible workarounds.
How can I ignore files from .eslintignore?
Permalink: How can I ignore files from .eslintignore?
Click to expand
ESLint throws out warning File ignored because of a matching ignore pattern. Use "--no-ignore" to override warnings that breaks the linting process ( if you used --max-warnings=0 which is recommended ).
ESLint < 7
Click to expand
Based on the discussion from this issue, it was decided that using the outlined script is the best route to fix this.
So you can setup a .lintstagedrc.js config file to do this:
import { CLIEngine } from 'eslint'
export default {
'*.js': (files) => {
const cli = new CLIEngine({})
return 'eslint --max-warnings=0 ' + files.filter((file) => !cli.isPathIgnored(file)).join(' ')
},
}ESLint >= 7
Click to expand
In versions of ESLint > 7, isPathIgnored is an async function and now returns a promise. The code below can be used to reinstate the above functionality.
Since 10.5.3, any errors due to a bad ESLint config will come through to the console.
import { ESLint } from 'eslint'
const removeIgnoredFiles = async (files) => {
const eslint = new ESLint()
const isIgnored = await Promise.all(
files.map((file) => {
return eslint.isPathIgnored(file)
})
)
const filteredFiles = files.filter((_, i) => !isIgnored[i])
return filteredFiles.join(' ')
}
export default {
'**/*.{ts,tsx,js,jsx}': async (files) => {
const filesToLint = await removeIgnoredFiles(files)
return [`eslint --max-warnings=0 ${filesToLint}`]
},
}ESLint >= 8.51.0 && Flat ESLint config
Permalink: ESLint >= 8.51.0 && Flat ESLint config
Click to expand
ESLint v8.51.0 introduced --no-warn-ignored CLI flag. It suppresses the warning File ignored because of a matching ignore pattern. Use "--no-ignore" to override warning, so manually ignoring files via eslint.isPathIgnored is no longer necessary.
{
"*.js": "eslint --max-warnings=0 --no-warn-ignored"
}NOTE:--no-warn-ignored flag is only available when Flat ESLint config is used.
How can I resolve TypeScript (tsc) ignoring tsconfig.json when lint-staged runs via Husky hooks?
Click to expand
When running lint-staged via Husky hooks, TypeScript may ignore tsconfig.json, leading to errors like:
TS17004: Cannot use JSX unless the ‘—jsx’ flag is provided. TS1056: Accessors are only available when targeting ECMAScript 5 and higher.
See issue #825 for more details.
Root Cause
lint-stagedautomatically passes matched staged files as arguments to commands.- Certain input files can cause TypeScript to ignore
tsconfig.json. For more details, see this TypeScript issue: Allow tsconfig.json when input files are specified.
Workaround: Use a function signature for the tsc command
Permalink: Workaround: Use a function signature for the tsc command
As suggested by @antoinerousseau in #825 (comment), using a function prevents lint-staged from appending file arguments:
Before:
// package.json
"lint-staged": {
"*.{ts,tsx}":[\
"tsc --noEmit",\
"prettier --write"\
]
}After:
// lint-staged.config.js
module.exports = {
'*.{ts,tsx}': [() => 'tsc --noEmit', 'prettier --write'],
}About
🚫💩 — Run tasks like formatters and linters against staged git files
www.npmjs.com/package/lint-staged
Topics
developer-experience eslint git linter stage-files stylelint workflow
Resources
Contributing
Stars
14.7k stars
Watchers
37 watching
Forks
Releases
Sponsor this project
Used by
Contributors
Languages
You can’t perform that action at this time.
──────── [TRUNCATED] ──────── Showing 37,410 chars (head) + 12,432 chars (tail) of 68,664 total clean characters. Full text saved to: /opt/data/cache/web/github.com-68947ab54e.md To read the omitted middle: read_file path=“/opt/data/cache/web/github.com-68947ab54e.md” offset=578 limit=200 (the file is the complete page; raise/lower offset to page through it). ─────────────────────────────