lint-staged 使用教程

lint-staged 是一个在 git 暂存文件上运行 linters 的工具，当然如果你觉得每次修改一个文件就给所有文件执行一次 lint 检查不恶心的话，这个工具对你来说就没有什么意义了，请直接关闭即可。

npx mrm lint-staged

它将根据package.json依赖项中的代码质量工具来安装和配置 husky 和 lint-staged，因此请确保在此之前安装（npm install --save-dev）并配置所有代码质量工具，如Prettier和ESlint。

不要忘记提交对package.json的更改以与您的团队共享此设置！

现在更改一些文件，git add或git add --patch将其中一些文件修补到您的提交中，并尝试 git 提交它们。

命令行标志

npx lint-staged --help
用法: lint-staged [options]

Options:
-V, --version 输出版本号
–allow-empty 当任务撤消所有分阶段的更改时允许空提交（默认值：false）
-c, --config [path] 配置文件的路径
-d, --debug 打印其他调试信息（默认值：false）
-p, --concurrent 要同时运行的任务数，或者为 false 则要连续运行任务（默认值：true）
-q, --quiet 自己的控制台输出（默认值：false）
-r, --relative 将相对文件路径传递给任务（默认值：false）
-x, --shell 跳过任务解析以更好地支持 shell（默认值：false）
-h, --help 输出用法信息
–allow-empty: 默认情况下，当 LITER 任务撤消所有阶段性的更改时，LITET 阶段将退出一个错误，并中止提交。使用此标志允许创建空 git 提交。
–config [path] : 手动指定配置文件或 npm 包名称的路径。注意：使用时，lint-staged 不会执行配置文件搜索，如果找不到指定的文件，则会打印错误。
–debug :在调试模式下运行。设置后，它将执行以下操作
在内部使用 debug 记录有关暂存文件、正在执行的命令、二进制文件的位置等的其他信息。通过传递标志自动启用的调试日志也可以通过将环境变量$DEBUG 设置为 lint-staged*启用。
使用 verbose 渲染程序的 listr; 这将导致串行无色输出到终端，而不是默认（美化，动态）输出。
–concurrent [number | (true/false)]: 控制由 lint-staged 运行的任务的并发性。注意：这不会影响子任务的并发性（它们将始终按顺序运行）。可能的值为：
false:依次运行所有任务
true（默认）：无限并发。并行运行尽可能多的任务
{number}：并行运行指定数量的任务，其中 1 等效于 false。
–quiet:禁止所有 CLI 输出，但任务中除外。
–relative: 将与 process.cwd()（lint-staged 运行）相关的文件路径传递给任务。默认值为 false。
–shell:默认情况下，将分析 linter 命令以提高速度和安全性。这具有常规 shell 脚本可能无法按预期工作的副作用。您可以使用此选项跳过命令解析。

配置

从 v3.1 开始，您现在可以使用不同的方式进行配置：

lint-staged 在你的对象 package.json,.lintstagedrc JSON 或 YML 格式的文件,lint-staged.config.js JS 格式的文件
使用--config 或-c 标志传递配置文件
配置应该是一个对象，其中每个值都是要运行的命令，其键是要用于此命令的 glob 模式。
这个软件包使用 micromatch 进行全局模式匹配。

package.json 例:

{
  "lint-staged": {
    "*": "your-cmd"
  }
}

.lintstagedrc 例：

{
  "*": "your-cmd"
}

该配置将 your-cmd 使用作为参数传递的当前暂存文件的列表执行。

因此，考虑到您做了 git add file1.ext file2.ext，lint-staged 将运行以下命令：
your-cmd file1.ext file2.ext

过滤文件

Linter 命令处理由 glob 模式定义的所有暂存文件的子集。lint staged 使用 micromatch 将文件与以下规则匹配：

如果全局模式不包含斜杠（/），matchBase 则将启用 micromatch 的选项，因此无论目录如何，全局匹配文件的基本名称：
“*.js"将匹配所有 JS 文件，例如/test.js 和/foo/bar/test.js
2.”!(*test).js"。将匹配所有以结尾的 JS 文件 test.js，因此 foo.js 但不匹配 foo.test.js
如果全局模式确实包含斜杠（/），则它也将与路径匹配：
"./*.js"将匹配 git repo 根目录中的所有 JS 文件，因此/test.js 但不匹配/foo/bar/test.js
2."foo/**/*.js"将匹配/foo 目录中的所有 JS 文件，所以/foo/bar/test.js 但不匹配/test.js
匹配时，lint-staged 将执行以下操作

自动解决 git root，无需配置。
选择项目目录中存在的暂存文件。
使用指定的 glob 模式过滤它们。
将绝对路径传递给 linters 作为参数。
注意： lint-staged 将绝对路径传递给 linter，以免在其他工作目录（例如，您的.git 目录与您的 package.json 目录不同）中执行时产生混淆。

忽略文件

lint-staged 的概念是在 git 中暂存的文件上运行已配置的 linter（或其他）任务。lint-staged 总是将所有暂存文件的列表传递给任务，忽略任何文件都应该在任务本身中配置。

考虑一个 prettier 用于使代码格式在所有文件中保持一致的项目。 项目还将缩小的第三方供应商库存储在 vendor/目录中。为了防止 prettier 在这些文件上抛出错误，应该将供应商目录添加到 prettier 的忽略配置.prettierignore 文件中。运行 npx prettier .。将忽略整个供应商目录，不会引发错误。当 lint-staged 被添加到项目并配置为运行 prettier 时，prettier 将忽略供应商目录中所有修改的和暂存的文件，即使它将它们作为输入接收。

在高级方案中，如果无法将 linter 任务本身配置为忽略文件，但 lint-staged 仍应忽略某些暂存文件，则可以在使用函数语法将文件路径传递给任务之前对其进行筛选。请参见示例：忽略 match 中的文件。

支持哪些命令？

支持通过本地或全局安装的任何可执行文件 npm，以及$PATH 中的任何可执行文件。

不建议使用全局安装的脚本，因为对于没有安装脚本的人，lint-staged 可能不起作用。

lint-staged 使用 execa 查找本地安装的脚本。因此，您.lintstagedrc 可以编写：

{
  "*.js": "eslint --fix"
}

依次运行多个命令

可以在每个 glob 上按顺序运行多个命令。为此，请传递一个命令数组而不是单个命令。这对于运行诸如 eslint --fix 或 stylefmt 之类的自动格式化工具很有用，但可以用于任何任意序列。

例如：

{
  "*.js": ["eslint", "prettier --write"]
}

要执行 esLIt，如果它用 0 个代码退出，它将执行 prettier --write 所有暂存的*.js 文件。

使用 JS 函数自定义任务

当以 JS 格式提供配置时，可以将任务定义为一个函数，该函数将接收一个分段文件名/路径数组，并应以字符串形式返回完整的命令。也可以返回一个完整的命令字符串数组，例如当任务只支持单个文件输入时。函数可以是 sync 或 async。

type TaskFn = (filenames: string[]) => string | string[] | Promise<string | string[]>
示例：将文件名用单引号引起来，并在每个文件中运行一次

// .lintstagedrc.js
module.exports = {
  "**/*.js?(x)": (filenames) =>
    filenames.map((filename) => `prettier --write '${filename}'`),
};

示例：运行 tsc 对 TypeScript 文件的更改，但不传递任何文件名参数

// lint-staged.config.js
module.exports = {
  "**/*.ts?(x)": () => "tsc -p tsconfig.json --noEmit",
};

示例：如果超过 10 个暂存文件，则在整个存储库上运行 eslint

// .lintstagedrc.js
module.exports = {
  "**/*.js?(x)": (filenames) =>
    filenames.length > 10 ? "eslint ." : `eslint ${filenames.join(" ")}`,
};

示例：使用自己的全局

// lint-staged.config.js
const micromatch = require("micromatch");

module.exports = {
  "*": (allFiles) => {
    const match = micromatch(allFiles, ["*.js", "*.ts"]);
    return `eslint ${match.join(" ")}`;
  },
};

示例：忽略匹配文件
如果出于某种原因要忽略全局匹配中的文件，则可以使用 micromatch.not()：

// lint-staged.config.js
const micromatch = require("micromatch");

module.exports = {
  "*.js": (files) => {
    // from `files` filter those _NOT_ matching `*test.js`
    const match = micromatch.not(files, "*test.js");
    return `eslint ${match.join(" ")}`;
  },
};

请注意，在大多数情况下，全局效果可以达到相同的效果。对于上面的示例，匹配的glob为!(*test).js。

** 示例：对命令使用相对路径 **

const path = require("path");

module.exports = {
  "*.ts": (absolutePaths) => {
    const cwd = process.cwd();
    const relativePaths = absolutePaths.map((file) => path.relative(cwd, file));
    return `ng lint myProjectName --files ${relativePaths.join(" ")}`;
  },
};

重新格式化代码

像 Prettier、ESLint/TSLint 或 stylelint 这样的工具可以根据适当的配置重新格式化代码，方法是运行 Prettier–write / ESLint --fix / TSLint --fix / stylelint --fix。只要没有错误,lint-staged 将自动向提交添加任何修改。

{
  "*.js": "prettier --write"
}

在版本 10 之前，git add 作为最后一步，必须手动包含任务。此行为已集成到 lint 阶段本身中，以防止多个任务编辑同一文件时出现争用情况。如果 lint-staged git add 在任务配置中检测到，它将在控制台中显示警告。git add 升级后，请从您的配置中删除。

例子
假设您已经在中设置了 lint-staged 和 husky 的所有示例 package.json。

{
  "name": "My project",
  "version": "0.1.0",
  "scripts": {
    "my-custom-script": "linter --arg1 --arg2"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js}": [
      "eslint --cache --fix",
      "prettier --write"
    ],
    "*.css": [
      "stylelint --cache --fix",
      "prettier --write"
    ]
  }
}

注意，我们不将路径作为命令调用时的参数传递。这一点很重要，因为 lint-stage 将为您完成这一点。

具有默认参数的 ESLint .js 并.jsx 作为预提交挂钩运行

{
  "*.{js,jsx}": "eslint"
}

自动修复代码样式–fix 并添加提交

{
  "*.js": "eslint --fix"
}

这将运行 eslint --fix 并自动向提交添加更改。

重用 npm 脚本

如果您想重用 package.json 中定义的 npm 脚本：

{
  "*.js": "npm run my-custom-script --"
}

以下是等效的：

{
  "*.js": "linter --arg1 --arg2"
}

在 linting 命令中使用环境变量
Linting 命令不支持扩展环境变量的 Shell 约定。要自己启用该约定，请使用诸如之类的工具 cross-env。

例如，此处 jest 正在.js 将 NODE_ENV 变量设置为的所有文件上运行"test"：

{
  "*.js": ["cross-env NODE_ENV=test jest --bail --findRelatedTests"]
}

使用 prettier 自动修复 javascript、typescript、markdown、HTML 或 CSS 的代码样式

{
  "*.{js,jsx,ts,tsx,md,html,css}": "prettier --write"
}

Stylelint 用于具有默认值的 CSS 和具有 SCSS 语法的 SCSS

{
  "*.css": "stylelint",
  "*.scss": "stylelint --syntax=scss"
}

运行 PostCSS 排序和 Stylelint 进行检查

{
  "*.scss": ["postcss --config path/to/your/config --replace", "stylelint"]
}

缩小图像

{
  "*.{png,jpeg,jpg,gif,svg}": "imagemin-lint-staged"
}

imagemin-lint-staged 是一个 CLI 工具，专门用于具有合理默认值的 lint-staged 使用。

使用流对您的暂存文件进行类型检查

{
  "*.{js,jsx}": "flow focus-check"
}