21 - Commitlint - Lint Commit 讯息

git 的 commit 讯息是个随意格式的纯文字文件，使用者可以使用 commit 的讯息快速理解各个 commit 的用途。

但由於 commit 讯息本身并没有限制相关的写法，因此常会造成不同人对於 commit 讯息编辑方式有所差异，这样随意的讯息所提供的资讯有些多、有些少，使得其几乎没有参考的价值。

Commit 讯息的 Linter - Commitlint

Commitlint 是个 npm 套件，它使用 commit conventions 规范来检查 commit 的讯息是否符合使用者所设定之规则。

透过配置档 commitlint.config.js 的设定， Commitlint 可以知道要使用哪些规则规范 commit 讯息，并输出相对的提示供使用者作为修改的依据。

使用 Commitlint 规范专案的 commit 讯息，可以让所有人的讯息保持一致的格式，这样做会有下列好处：

容易检索：利用定义的关键字及模组名称可以轻松地找到想要找的 commit
自动输出 Changelog ：固定的讯息格式可以藉由工具的帮助输出 Changelog

安装 Commitlint

首先使用 npm 安装 Commitlint ：

npm install @commitlint/cli --save-dev

使用 Commitlint

安装完成後，由於 Commitlint 的配置档是必要的，因此要建立配置档 commitlint.config.js ：

module.exports = {
  rules: {
    'header-min-length': [2, 'always', 10],
  },
};

配置档中的属性 rules 可以设定各式的规则，规则列表请参考 Commitlint 的官方页面。

范例中设定讯息标头的最小长度要大於 10 。

接着执行 commitlint ：

> echo 'foo' | npx commitlint
⧗   input: foo
✖   header must not be shorter than 10 characters, current length is 3 [header-min-length]

✖   found 1 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

当讯息为 foo 时，由於长度只有 3 ，因此 Commitlint 会视为违规而输出错误讯息。

预设规则包

为了节省使用者配置规则的时间， Commitlint 可以使用预先配置的规则包来设定多项规则。

在使用前须要先安装：

npm install @commitlint/config-conventional --save-dev

这里使用 @commitlint/config-conventional 是 Commitlint 提供的规则包。

安装完成後，要在配置档中设定使用规则包：

module.exports = {
  extends: ['@commitlint/config-conventional'],
  // ...
};

这样一来 Commitlint 就会将 @commitlint/config-conventional 所配置的规则都纳入并对讯息做相应的检查。

使用 Husky 为 Commitlint 注册 Git Hooks

到目前为止，我们都必须自己去叫用 Commitlint 才能作用，使用起来的步骤较原本多，也更不直觉，容易被忽略。

接下来我们藉由 Husky 的帮助，将 Commitlint 融入 Git flow 中，让其更加的易用。

使用 husky add 将指令加入 Git hooks ：

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

修改完後，要重新注册 Git hooks ：

npm install

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

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

完成设定後，当你输入指令 git commit ，在完成编辑讯息後会启动 Commitlint 检查讯息。

本文重点整理

commit 讯息是开发者识别 commit 内容的重要资讯，如果 commit 讯息不能清楚表示 commit 的用途时，开发者就必须直接看程序码修改的内容来确认 commit ，会造成时间上的花费。
好的 commit 讯息不仅能增加查找的速度，在发布时还可以藉由订定的结构自动产生 Changelog ，就不需要每次发布时还要人工编辑 Changelog 。
以自动化发布为目标的专案来说， Commitlint 是不可或缺的工具。
在使用 Commitlint 前，需要设定配置档才能使 Linter 产生效用。
可以使用预设的规则包来减少配置时所需的时间。
与 Husky 一起使用，可以在提交讯息时启动 Commitlint 检查。