28 - lint-staged - Lint Git Commit 的档案

做 lint 、 format 或是通过测试，对於程序码的品质维护有很大的帮助，因此在提交代码时，我们会使用 Git hooks 确保这些优化程序有被执行。

但是在 Git hooks 执行这些优化时，程序处理的范围会包含整个专案的程序码，就算是未提交的档案，依然会被作为优化对象，这样一来会浪费许多时间。

只 Lint 修改的档案 - lint-staged

lint-staged 是个 npm 套件，它会依照配置将符合规则（ glob ）的 Git 暂存档案路径带入设定的程序中并执行。

lint-staged 的目的就是让这些优化程序只作用於提交的程序码上，进而减少花费的时间。

安装 lint-staged

用 npm 安装 lint-staged ：

npm install lint-staged --save-dev

使用 lint-staged

使用前需要建立配置档 lint-staged.config.js ：

module.exports = {
  '*': ['echo'],
};

为了解说 lint-staged 的功能，这里将所有提交的档案都以 echo 输出参数资讯。

接着将档案加入暂存区中：

git add package.json package-lock.json

然後执行 lint-staged 指令：

npx lint-staged -v

lint-staged 预设不输出程序的讯息，为了观看 lint-staged 的功能，要加上参数 -v ，它会显示程序所输出的讯息。

执行的结果如下：

> lint-staged -v

✔ Preparing...
✔ Running tasks...
✔ Applying modifications...
✔ Cleaning up...

ℹ echo:
/Users/PeterChen/Documents/code/build-a-super-comfortable-web-dev-env/days/11-lint-staged/examples/example-lint-staged/package-lock.json /Users/PeterChen/Documents/code/build-a-super-comfortable-web-dev-env/days/11-lint-staged/examples/example-lint-staged/package.json

进入暂存的的档案 package.json 与 package-lock.json 被作为参数传入程序中，并被 echo 输出。

不同档案执行不同程序

lint-staged 设定的每个规则的键值为 glob 的字串， lint-staged 会将包含在内的档案转为绝对路径（ absolute path ）并作为参数传入各个指令内。

例如下面这个例子：

module.exports = {
  '*.js': ['echo'],
};

这样的配置会只让 JS 档案被 echo 输出路径，例如 lint-staged.config.js 就会被包含，但是 package.json 因为不是 .js 的档案，所以就算提交了还是不会被 echo 输出。

复数指令

有时在同个档案上，我们不只要使用 linter 检查语法的问题，还要使用 formatter 格式化，甚至执行测试确认通过。

lint-staged 可以设置阵列，让复数指令作用於相同的档案上。

以下面的例子来说：

module.exports = {
  '*': ['echo', 'cat'],
};

它会对所有的提交的档案执行 echo 与 cat 。

与 Husky 整合

藉由与 Husky 的整合，在提交前确保程序码的品质，让开发者可以：

• 依提交的程序码种类，对其做对应的 lint 、 format 与测试。
• 只针对提交的程序码做相关的 lint 、 format 与测试，避免全局的执行处理。
• 在 git commit 时自动启用 lint 、 format 与测试。

在 Husky 中设置 lint-staged

为了在提交代码时可以触发各种检查工具，我们需要将 lint-staged 藉由 Husky 配置到 Git hook 上：

npx husky add .husky/pre-commit 'npx lint-staged'

然後重新注册 Git hooks ：

npm install

npm install 会触发在执行 husky-init 时建立的 prepare script ，去做相关的初始化工作。

如果需要 Husky 相关的使用说明，请看「 20 - Husky - Git Hooks 工具」的介绍。

这样一来，每当我们提交代码时，就会叫用 npx lint-staged 把提交的档案路径送去给 lint-staged 中设定指令做处理。

在 lint-staged 中依照档案类型设置对应的工具

为了让 lint-staged 可以对於各类型的档案提供合适的工具做处理，我们需要设定 lint-staged.config.js ：

module.exports = {
  'package.json': ['prettier --write'],
  '*.js': ['npx eslint --fix', 'prettier --write'],
  '*.css': ['stylelint --fix', 'prettier --write'],
  '*.md': ['markdownlint', 'prettier --write'],
};

藉由 glob 设定各个档案类型应该被哪些工具检查，藉以避免不必要的花费与冲突产生。

本文重点整理

• 在每次提交时，对专案中所有档案做优化的处理是没必要的，只会浪费更多的资源。
• lint-staged 让优化的程序可以聚焦於暂存档案上，只有那些这次提交的档案会作用这些优化程序，并且可以利用 glob 指示要使用不同指令。
• 藉由 lint-staged 与 Husky 的搭配，我们可以在 git commit 的时候叫用 lint-staged ，接着在 lint-staged 中针对各种不同的档案类型设置对应的处理工具，如此一来，可以减少工具因不符合的档案而进行无用的处理，也可以降低冲突的产生。

参考资料

• GitHub: okonet/lint-staged