lint-staged

Task functions like { title, task } can now use a logger function log() to emit output while the task runs. By default, the output will only be visible if the task fails, unless the --verbose option was used. Additionally, when the task rejects, the error will be shown in the output.

import { defineConfig } from 'lint-staged/config'

export default defineConfig({
  '*': {
    title: 'Fail if PDF files are committed',
    task: async (filepaths, { log }) => {
      const pdfFiles = filepaths.filter((f) => f.toLowerCase().endsWith('.pdf'))
      if (pdfFiles.length > 0) {
        log('PDF files should not be committed: %s', pdfFiles)
        throw new Error('Failed')
      }
    },
  },
})

lint-staged now stages changes to all tracked files modified by tasks, including files that weren’t originally staged or didn’t match the configured globs. This can happen when your task has side-effects, or it's a function that ignores the staged files like () => "prettier --write .".

If you have unstaged changes in a file and the task also edits that file, your unstaged changes will be staged too. Use --hide-unstaged to hide your changes while tasks run.

The assignment of staged files to lint-staged configuration files (when using multiple, for example in a monorepo) has been rewritten to be more efficient. As a reminder, each staged file is assigned to exactly one configuration (the closest one), even if that config doesn't match the file in its globs.

Fix TypeScript issue TS1254 from defineConfig() by changing the signature from const to a function:

A 'const' initializer in an ambient context must be a string or numeric literal or literal enum reference.

Lint-staged now refuses to run when files were staged with --intent-to-add, because Git stash doesn't support them. Previously this was an unhandled error.

Lint-staged now handles color support better in non-TTY streams, and honors the FORCE_COLOR environment variable.

Update tinyexec@1.3.1 so that local binaries from node_modules/.bin are resolved starting from the directory of each lint-staged configuration file (in monorepo setups). This behavior was broken in lint-staged@16.3.0 where they were only resolved from the current working directory and up.

This is a version-bump-only release because the previous version 17.4.0 was not published to npmjs.com due to problems with GitHub Actions and Changesets.

It is now possible to run multiple tasks in parallel for a single glob by configuring it with an array of tasks (which run sequentially), and then placing another array inside it (where the tasks will run in parallel). The following demonstrates the order tasks will start in:

{
  "*.ts": ["first", "second", ["third", "third"], "fourth"]
}

As a concrete example, lint-staged's own configuration is:

/** @type {import('./lib/index.js').Configuration} */
export default {
  '*': [
    ['oxfmt --check --no-error-on-unmatched-pattern', 'oxlint --no-error-on-unmatched-pattern'],
  ],
  '*.ts': () => 'tsc',
}

which means:

During an in-progress merge, files that are unchanged from the branch being merged are now skipped. Technically, files are only included if there are staged changes against both HEAD and MERGE_HEAD.

The chunking of tasks based on maximum command line argument length has been re-implemented to be more precise. Now the chunking happens based on the final generated command string, instead of just the list of staged files like previously. This benefits mainly Windows platforms and function commands like:

/** @type {import('lint-staged').Configuration} */
export default {
  '*.ts': () => 'tsc', // Run "tsc" when any TS file is changed (for entire project)
}

Where the spawned command is literally "tsc" without any extra arguments. Previously, this was still chunked when a lot of files were staged. Now, it probably won't be chunked because the length of the command is just three letters.

Also, native JavaScript/Node.js function tasks won't be chunked at all, when previously they were run multiple times when chunked:

/** @type {import('lint-staged').Configuration} */
export default {
  '*.js': {
    title: 'Log staged JS files to console',
    task: async (files) => {
      console.log('Staged JS files:', files)
    },
  },
}

It's now possible to set --max-arg-length=Infinity to effectively disable chunking of tasks based on the number of staged files. The parsing and validation of the numeric CLI options --max-arg-length and --concurrency has been improved.

The console output of lint-staged has been simplified so that there's less interactive spinners and more explicit messages like "Started…" -> "Done!". The primary purpose of this was to remove Listr2, a very large dependency.

Before:

Size of node_modules/ after installing: 1561.7 kB with 29 packages.

Fancy interactive spinners, but output dynamically changes:

✔ Backed up original state in git stash (0b191303)
✔ Running tasks for staged files...
✔ Staging changes from tasks...
✔ Cleaning up temporary files...

After:

Size of node_modules/ after installing: 974.0 kB with 5 packages (37.6 % smaller, 82.7 % less transitive dependencies).

Simpler but more explicit output:

⋯ Backing up original state…
✔ Done backing up original state (35b38ed1)!
⋯ Running tasks for staged files…
    *.js — 1 file
      ⋯ oxlint --fix
    *.{json,md} — 1 file
      ⋯ oxfmt --write

✔ oxfmt --write
✔ oxlint --fix

✔ Done running tasks for staged files!
⋯ Staging changes from tasks…
✔ Done staging changes from tasks!
⋯ Cleaning up temporary files…
✔ Done cleaning up temporary files!

Try to restore hidden unstaged changes when using --no-revert.

Console output colors are enabled/disabled more consistently.

Fix lint-staged discarding the ongoing merge conflict status (.git/MERGE_HEAD) when using the --hide-unstaged or --hide-all options.

Fix issues with Git commands that are successful but also emit warnings to stderr, by ignoring the stderr output completely when the process exits with code 0. This was the behavior when using nano-spawn and execa, but when switching to tinyexec in 16.3.0 both stdout and stderr were used as interleaved output.

Run all tests with Deno, in addition to Node.js and Bun.

Fix performance regression of lint-staged v17 by going back to using git add to stage task modifications. This was changed to git update-index --again in v17 for less manual work, but unfortunately the update-index command gets slower in very large Git repos.

This version of lint-staged uses the new staged publishing for npm packages feature. Releases are already published from GitHub Actions with trusted publishing, but now an additional approval with two-factor authentication is also required.

Correctly set the --max-arg-length default value based on the running platform. This controls how very long lists of staged files are split into multiple chunks.

Another fix for making sure lint-staged adds task modifications correctly to the commit in the following cases:

There's new test cases which actually setup the Git pre_commit hook to run lint-staged and verify them. These issues started in v17.0.0 when trying to improve support for committig without having explicitly staged files.

Fix lint-staged behavior when implicitly committing files without using git add by either:

Enable immutable GitHub releases

Adjust GitHub Actions workflow so that automatic publishing works with signed commits.

Node.js v20 is no longer supported, and the oldest supported version is now 22.22.1, which is an active LTS version at the time of this release. Node.js 20 will be EOL after April 2026. Please upgrade your Node.js version!

Lint-staged now tries to verify the installed Git version is at least 2.32.0, released in 2021. If you're using an even older Git version, you need to upgrade it before running lint-staged!

The dependency yaml is now marked as optional and probably won't be installed by default. If you're using a YAML configuration file you should install the package separately:

npm install --development yaml

If you're using .lintstagedrc as the config file name (without a file extension), it will be treated as a YAML file. If the content is JSON, consider renaming it to .lintstagedrc.json to avoid needing to install yaml.