lint-staged 16.4.0 → 17.0.0

package/MIGRATION.md

@@ -1,3 +1,23 @@
+## v17
+
+#### Node.js v20 is no longer supported.
+
+The oldest supported Node.js version is now 22.22.1, which is the latest active v22 LTS version at the time of release. You can — of course — update to v24 or v25, or later.
+
+#### The `yaml` dependency is now optional
+
+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:
+
+```shell
+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`.
+
+#### Git version needs to be at least 2.32.0
+
+_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](https://git-scm.com/install/mac) it before running _lint-staged_!
+
 ## v16
 
 #### Updated Node.js version requirement

package/README.md

@@ -23,7 +23,7 @@ $ git commit
     ❯ *.js — 2 files
       ⠼ eslint --fix
     ↓ *.{json,md} — no files [SKIPPED]
-◼ Applying modifications from tasks...
+◼ Updating Git index again...
 ◼ Cleaning up temporary files...
 ```
 
@@ -104,34 +104,32 @@ For breaking changes, see [MIGRATION.md](./MIGRATION.md).
 ❯ npx lint-staged --help
 Usage: lint-staged [options]
 
-Options:
-  -V, --version                      output the version number
-  --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
-  --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
-  --continue-on-error                run all tasks to completion even if one fails (default: false)
-  --fail-on-changes                  fail with exit code 1 when tasks modify tracked files (default: false)
-  --max-arg-length [number]          maximum length of the command-line argument string (default: 0)
-  --no-revert                        do not revert to original state in case of errors.
-  --no-stash                         disable the backup stash. Implies "--no-revert".
-  --no-hide-partially-staged         disable hiding unstaged changes from partially staged files
-  --hide-unstaged                    hide all unstaged changes, instead of just partially staged (default: false)
-  -q, --quiet                        disable lint-staged’s own console output (default: false)
-  -r, --relative                     pass relative filepaths to tasks (default: false)
-  -v, --verbose                      show task output even when tasks succeed; by default only failed output is shown
-                                     (default: false)
-  -h, --help                         display help for command
+-h, --help                         display this help message
+-V, --version                      display the current version number
+--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"
-  h0a0s0h0 On main: lint-staged automatic backup
-  > git apply --index h0a0s0h0
+  <git-hash> On main: lint-staged automatic backup
+  > git apply --index <git-hash>
 ```
 
 #### `--allow-empty`
@@ -152,7 +150,7 @@ Manually specify a path to a config file or npm package name. Note: when used, l
 
 #### `--cwd [path]`
 
-By default tasks run in the current working directory. Use the `--cwd some/directory` to override this. The path can be absolute or relative to the current working directory.
+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`
 
@@ -192,7 +190,11 @@ By default, unstaged changes from partially staged files will be hidden and appl
 
 #### `--hide-unstaged`
 
-Use this option to hide all unstaged changes to tracked files before running tasks. The changes will be applied back after running the tasks. Note that the combination of flags `--hide-unstaged --no-hide-partially-staged` isn't meaningful and behaves the same as just `--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](https://knip.dev) which check for unused code. Untracked files are included in the backup stash and restored automatically after running.
 
 #### `--quiet`
 
@@ -229,7 +231,7 @@ _Lint-staged_ can be configured in many ways:
 
 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](https://github.com/micromatch/picomatch) for glob patterns. JavaScript files can also export advanced configuration as a function. See [Using JS configuration files](#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. See ["How to use `lint-staged` in a multi-package monorepo?"](#how-to-use-lint-staged-in-a-multi-package-monorepo) for more info and an example.
+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?"](#how-to-use-lint-staged-in-a-multi-package-monorepo) for more info and an example.
 
 #### `package.json` example:
 
@@ -901,11 +903,11 @@ _Thanks to [this comment](https://youtrack.jetbrains.com/issue/IDEA-135454#comme
 <details>
   <summary>Click to expand</summary>
 
-Install _lint-staged_ on the monorepo root level, and add separate configuration files in each package. When running, _lint-staged_ will always use the configuration closest to a staged file, so having separate configuration files makes sure tasks do not "leak" into other packages.
+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_ discovers the closest configuration to each staged file, even if that configuration doesn't include any matching globs. Given these example configurations:
+**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:
 
 ```js
 // ./.lintstagedrc.json
@@ -928,7 +930,9 @@ export default {
 }
 ```
 
-To support backwards-compatibility, monorepo features require multiple _lint-staged_ configuration files present in the git repo. If you still want to run _lint-staged_ in only one of the packages in a monorepo, you can use the `--cwd` option (for example, `lint-staged --cwd packages/frontend`).
+**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="."`.
 
 </details>
 

package/bin/lint-staged.js

@@ -2,152 +2,33 @@
 
 import { userInfo } from 'node:os'
 
-import { Option, program } from 'commander'
-
+import { getVersionNumber, parseCliOptions, printHelpText } from '../lib/cli.js'
 import { createDebug, enableDebug } from '../lib/debug.js'
 import lintStaged from '../lib/index.js'
-import { CONFIG_STDIN_ERROR, restoreStashExample } from '../lib/messages.js'
+import { CONFIG_STDIN_ERROR } from '../lib/messages.js'
 import { readStdin } from '../lib/readStdin.js'
-import { getVersion } from '../lib/version.js'
 
 const debugLog = createDebug('lint-staged:bin')
 
 // Do not terminate main Listr process on SIGINT
 process.on('SIGINT', () => {})
 
-program
-  .version(await getVersion())
-
-  /**
-   * This shouldn't be necessary for lint-staged, but add migration step just in case
-   * to preserve old behavior of "commander".
-   *
-   * @todo remove this in the major version
-   * @see https://github.com/tj/commander.js/releases/tag/v13.0.0
-   * */
-  .allowExcessArguments()
-
-  .addOption(
-    new Option('--allow-empty', 'allow empty commits when tasks revert all staged changes').default(
-      false
-    )
-  )
-  .addOption(
-    new Option(
-      '-p, --concurrent <number|boolean>',
-      'the number of tasks to run concurrently, or false for serial'
-    ).default(true)
-  )
-  .addOption(
-    new Option('-c, --config [path]', 'path to configuration file, or - to read from stdin')
-  )
-  .addOption(
-    new Option('--cwd [path]', 'run all tasks in specific directory, instead of the current')
-  )
-  .addOption(new Option('-d, --debug', 'print additional debug information').default(false))
-  .addOption(
-    new Option(
-      '--diff [string]',
-      'override the default "--staged" flag of "git diff" to get list of files. Implies "--no-stash".'
-    ).implies({ stash: false })
-  )
-  .addOption(
-    new Option(
-      '--diff-filter [string]',
-      'override the default "--diff-filter=ACMR" flag of "git diff" to get list of files'
-    )
-  )
-  .addOption(
-    new Option('--continue-on-error', 'run all tasks to completion even if one fails').default(
-      false
-    )
-  )
-  .addOption(
-    new Option('--fail-on-changes', 'fail with exit code 1 when tasks modify tracked files')
-      .default(false)
-      .implies({ revert: false })
-  )
-  .addOption(
-    new Option(
-      '--max-arg-length [number]',
-      'maximum length of the command-line argument string'
-    ).default(0)
-  )
-
-  /**
-   * We don't want to show the `--revert` flag because it's on by default, and only show the
-   * negatable flag `--no-rever` instead. There seems to be a bug in Commander.js where
-   * configuring only the latter won't actually set the default value.
-   */
-  .addOption(
-    new Option('--revert', 'revert to original state in case of errors').default(true).hideHelp()
-  )
-  .addOption(
-    new Option('--no-revert', 'do not revert to original state in case of errors.').default(false)
-  )
-
-  .addOption(new Option('--stash', 'enable the backup stash').default(true).hideHelp())
-  .addOption(
-    new Option('--no-stash', 'disable the backup stash. Implies "--no-revert".')
-      .default(false)
-      .implies({ revert: false })
-  )
-
-  .addOption(
-    new Option('--hide-partially-staged', 'hide unstaged changes from partially staged files')
-      .default(true)
-      .hideHelp()
-  )
-  .addOption(
-    new Option(
-      '--no-hide-partially-staged',
-      'disable hiding unstaged changes from partially staged files'
-    ).default(false)
-  )
+const cliOptions = parseCliOptions(process.argv)
 
-  .addOption(
-    new Option('--hide-unstaged', 'hide all unstaged changes, instead of just partially staged')
-      .default(false)
-      .implies({ hidePartiallyStaged: false })
-  )
-
-  .addOption(new Option('-q, --quiet', 'disable lint-staged’s own console output').default(false))
-  .addOption(new Option('-r, --relative', 'pass relative filepaths to tasks').default(false))
-  .addOption(
-    new Option(
-      '-v, --verbose',
-      'show task output even when tasks succeed; by default only failed output is shown'
-    ).default(false)
-  )
-
-  .addHelpText('afterAll', '\n' + restoreStashExample())
+if (cliOptions.version) {
+  console.log(await getVersionNumber())
+  process.exit(0)
+}
 
-const cliOptions = program.parse(process.argv).opts()
+if (cliOptions.help) {
+  console.log(await printHelpText())
+  process.exit(0)
+}
 
 if (cliOptions.debug) {
   enableDebug()
 }
 
-const options = {
-  allowEmpty: !!cliOptions.allowEmpty,
-  concurrent: JSON.parse(cliOptions.concurrent),
-  configPath: cliOptions.config,
-  continueOnError: !!cliOptions.continueOnError,
-  cwd: cliOptions.cwd,
-  debug: !!cliOptions.debug,
-  diff: cliOptions.diff,
-  diffFilter: cliOptions.diffFilter,
-  failOnChanges: !!cliOptions.failOnChanges,
-  hidePartiallyStaged: !!cliOptions.hidePartiallyStaged, // commander inverts `no-<x>` flags to `!x`
-  hideUnstaged: !!cliOptions.hideUnstaged,
-  maxArgLength: cliOptions.maxArgLength || undefined,
-  quiet: !!cliOptions.quiet,
-  relative: !!cliOptions.relative,
-  revert: !!cliOptions.revert, // commander inverts `no-<x>` flags to `!x`
-  stash: !!cliOptions.stash, // commander inverts `no-<x>` flags to `!x`
-  verbose: !!cliOptions.verbose,
-}
-
 try {
   const { shell } = userInfo()
   debugLog('Using shell: %s', shell)
@@ -155,13 +36,13 @@ try {
   debugLog('Could not determine current shell')
 }
 
-debugLog('Options parsed from command-line: %o', options)
+debugLog('Options parsed from command-line: %o', cliOptions)
 
-if (options.configPath === '-') {
-  delete options.configPath
+if (cliOptions.configPath === '-') {
+  delete cliOptions.configPath
   try {
     debugLog('Reading config from stdin')
-    options.config = JSON.parse(await readStdin())
+    cliOptions.config = JSON.parse(await readStdin())
   } catch (error) {
     debugLog(CONFIG_STDIN_ERROR, error)
     console.error(CONFIG_STDIN_ERROR)
@@ -169,7 +50,7 @@ if (options.configPath === '-') {
   }
 }
 
-const passed = await lintStaged(options)
+const passed = await lintStaged(cliOptions)
 if (!passed) {
   process.exitCode = 1
 }

package/lib/assertGitVersion.js

@@ -0,0 +1,48 @@
+/** @see {@link https://github.com/git/git/blob/master/Documentation/RelNotes/2.32.0.adoc} */
+export const MIN_GIT_VERSION = '2.32.0'
+
+/**
+ * @param {string} gitVersionOutput the Git version command output
+ * @returns {string} the Git version number in format `<major>.<minor>.<patch>`
+ */
+const extractGitVersionNumber = (gitVersionOutput) => {
+  const match = gitVersionOutput.match(/git version\s+(\d+\.\d+\.\d+)/i)
+  return match?.[1]
+}
+
+/**
+ * @param {string} version the version number in format `<major>.<minor>.<patch>`
+ * @returns {[string, string, string]} the version number parsed as integers `[major, minor, patch]`
+ */
+const parseSemver = (version) => {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(version)
+  return match?.slice(1, 4).map(Number)
+}
+
+/**
+ *
+ * @param {string} actual the actual version number in format `<major>.<minor>.<patch>`
+ * @param {string} expected the expected version number in format `<major>.<minor>.<patch>`
+ * @returns {boolean} `true` when the actual version number is at least the expected version number
+ */
+export const satisfiesVersion = (actual, expected) => {
+  const a = parseSemver(actual)
+  const e = parseSemver(expected)
+  if (a[0] !== e[0]) return a[0] > e[0]
+  if (a[1] !== e[1]) return a[1] > e[1]
+  return a[2] >= e[2]
+}
+
+/**
+ *
+ * @param {string} gitVersionOutput the Git version command output
+ * @returns {boolean} `true` when the Git version number is supported
+ */
+export const assertGitVersion = (gitVersionOutput) => {
+  try {
+    const version = extractGitVersionNumber(gitVersionOutput)
+    return satisfiesVersion(version, MIN_GIT_VERSION)
+  } catch {
+    return false
+  }
+}

package/lib/cli.js

@@ -0,0 +1,242 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+
+import { restoreStashExample } from './messages.js'
+
+const CLI_OPTIONS = [
+  {
+    short: 'h',
+    flag: 'help',
+    type: 'boolean',
+    description: 'display this help message',
+  },
+  {
+    short: 'V',
+    flag: 'version',
+    type: 'boolean',
+    description: 'display the current version number',
+  },
+  {
+    flag: 'allow-empty',
+    type: 'boolean',
+    description: 'allow empty commits when tasks revert all staged changes (default: false)',
+  },
+  {
+    short: 'p',
+    flag: 'concurrent',
+    positional: '<number|boolean>',
+    type: 'string',
+    description: 'the number of tasks to run concurrently, or false for serial (default: true)',
+  },
+  {
+    short: 'c',
+    flag: 'config',
+    positional: '[path]',
+    type: 'string',
+    description: 'path to configuration file, or - to read from stdin',
+  },
+  {
+    flag: 'continue-on-error',
+    type: 'boolean',
+    description: 'run all tasks to completion even if one fails (default: false)',
+  },
+  {
+    flag: 'cwd',
+    positional: '[path]',
+    type: 'string',
+    description: 'run all tasks in specific directory, instead of the current',
+  },
+  {
+    short: 'd',
+    flag: 'debug',
+    type: 'boolean',
+    description: 'print additional debug information (default: false)',
+  },
+  {
+    flag: 'diff',
+    positional: '[string]',
+    type: 'string',
+    description:
+      'override the default "--staged" flag of "git diff" to get list of files. Implies "--no-stash".',
+  },
+  {
+    flag: 'diff-filter',
+    positional: '[string]',
+    type: 'string',
+    description:
+      'override the default "--diff-filter=ACMR" flag of "git diff" to get list of files',
+  },
+  {
+    flag: 'fail-on-changes',
+    type: 'boolean',
+    description: 'fail with exit code 1 when tasks modify tracked files (default: false)',
+  },
+  {
+    negative: true,
+    flag: 'hide-partially-staged',
+    type: 'boolean',
+    description: 'hide unstaged changes from partially staged files (default: true)',
+  },
+  {
+    flag: 'hide-unstaged',
+    type: 'boolean',
+    description: 'hide all unstaged changes, instead of just partially staged (default: false)',
+  },
+  {
+    flag: 'hide-all',
+    type: 'boolean',
+    description: 'hide all unstaged changes and untracked files (default: false)',
+  },
+  {
+    flag: 'max-arg-length',
+    type: 'string', // Parsed with `parseInt()` below
+    positional: '[number]',
+    description: 'maximum length of the command-line argument string (default: 0)',
+  },
+  {
+    short: 'q',
+    flag: 'quiet',
+    type: 'boolean',
+    description: "disable lint-staged's own console output (default: false)",
+  },
+  {
+    short: 'r',
+    flag: 'relative',
+    type: 'boolean',
+    description: 'pass relative filepaths to tasks (default: false)',
+  },
+  {
+    negative: true,
+    flag: 'revert',
+    type: 'boolean',
+    description: 'revert to original state in case of errors (default: true)',
+  },
+  {
+    negative: true,
+    flag: 'stash',
+    type: 'boolean',
+    description: 'enable the backup stash (default: true)',
+  },
+  {
+    short: 'v',
+    flag: 'verbose',
+    type: 'boolean',
+    description:
+      'show task output even when tasks succeed; by default only failed output is shown (default: false)',
+  },
+]
+
+/** @param {string[]} argv */
+export const parseCliOptions = (argv) => {
+  const options = CLI_OPTIONS.reduce((acc, current) => {
+    acc[current.flag] = { type: current.type }
+    if (current.short) acc[current.flag].short = current.short
+    return acc
+  }, {})
+
+  const { values } = parseArgs({
+    args: argv,
+    allowNegative: true,
+    allowPositionals: true,
+    options,
+  })
+
+  if (values.diff !== undefined && values.stash === undefined) {
+    /** Disable stashing by default when diffing specific value */
+    values.stash = false
+  }
+
+  if (values['fail-on-changes'] && values.revert === undefined) {
+    /** When using --fail-on-changes, default to not reverting on errors */
+    values.revert = false
+  }
+
+  if (values.stash === false && values.revert === undefined) {
+    /** Can't revert when using --no-stash */
+    values.revert = false
+  }
+
+  if (values['hide-unstaged'] === true) {
+    values['hide-partially-staged'] = false // becomes redundant
+  }
+
+  if (values['hide-all'] === true) {
+    values['hide-partially-staged'] = false // becomes redundant
+    values['hide-unstaged'] = false // becomes redundant
+  }
+
+  return {
+    allowEmpty: values['allow-empty'] ?? false,
+    concurrent: values.concurrent === undefined ? true : JSON.parse(values.concurrent),
+    configPath: values.config,
+    continueOnError: !!values['continue-on-error'],
+    cwd: values.cwd,
+    debug: !!values.debug,
+    diff: values.diff,
+    diffFilter: values['diff-filter'],
+    failOnChanges: !!values['fail-on-changes'],
+    help: !!values.help,
+    hidePartiallyStaged: values['hide-partially-staged'] ?? true,
+    hideUnstaged: !!values['hide-unstaged'],
+    hideAll: !!values['hide-all'],
+    maxArgLength: parseInt(values['max-arg-length'], 10),
+    quiet: !!values.quiet,
+    relative: !!values.relative,
+    revert: values.revert ?? true,
+    stash: values.stash ?? true,
+    verbose: !!values.verbose,
+    version: !!values.version,
+  }
+}
+
+export const getVersionNumber = async () => {
+  const dirname = path.dirname(fileURLToPath(import.meta.url))
+  const packageJsonFile = await readFile(path.join(dirname, '../package.json'), 'utf-8')
+  /** @type {import('../package.json')} */
+  const packageJson = JSON.parse(packageJsonFile)
+
+  return packageJson.version
+}
+
+const helpOptions = CLI_OPTIONS.map((option) => {
+  if (option.negative) {
+    /** @example `--no-stash` */
+    return [`--no-${option.flag}`, option.description]
+  }
+
+  /**
+   * @example `-V, --version
+   * or
+   * @example `--allow-empty`
+   */
+  let arg = option.short ? `-${option.short}, --${option.flag}` : `--${option.flag}`
+
+  /** @example `--cwd [path]` */
+  if (option.positional) arg += ` ${option.positional}`
+
+  return [arg, option.description]
+})
+
+const createWrap = (width) => {
+  const regExp = new RegExp(`.{1,${width}}(\\s|$)`, 'g')
+  return (text) => text.match(regExp)?.map((s) => s.trimEnd())
+}
+
+export const printHelpText = async (width = process.stdout.columns ?? 80) => {
+  const output = ['Usage: lint-staged [options]', '']
+
+  const col1Width = Math.max(...helpOptions.map(([arg]) => arg.length)) + 2
+  const wrap = createWrap(width - col1Width)
+
+  for (const [arg, description] of helpOptions) {
+    const lines = wrap(description)
+    const pad = ' '.repeat(col1Width)
+    output.push(arg.padEnd(col1Width) + lines[0], ...lines.slice(1).map((line) => pad + line))
+  }
+
+  output.push('', restoreStashExample())
+
+  return output.join('\n')
+}