npm 包 @commitlint/top-level 使用教程-JavaScript中文网-JavaScript教程资源分享门户

前言

在开发中，我们会写很多的 git commit，可以说是我们的开发日志。git commit 的信息就极其重要了。也许它能再一次让我们找到问题的根源或者追踪 bug。为了让 commit 的信息更有规范和明确，我们就需要使用 commitlint 来进行规范化操作。

commitlint 是一个专门用于 git commit message 验证的工具，可以用来规范化我们的 commit message，使其更加语义化，更易于理解，而不是像过去那些没有规则的 message。

在此，我将介绍一下如何使用 @commitlint/top-level 这个 npm 包。

什么是 @commitlint/top-level

@commitlint/top-level 是一个在项目中快速启用 commitlint 的 npm 包。当你在项目中使用时，这个包将准确地检查你的 commit message，并提供有关提交的详细信息。

通过使用这个包，您可以确保每个 commit message 都包含有效的功能，而且这些功能符合您团队的规范。

如何安装

使用 npm 进行全局安装 @commitlint/top-level 包

npm install --global @commitlint/top-level

如何使用

初始化配置文件

在项目根目录执行下面的命令初始化配置文件 .commitlintrc.js

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > .commitlintrc.js

安装相关 packages

执行以下命令安装相关 packages

npm install --save-dev @commitlint/cli husky

配置 git hooks

配置 git hooks 在每次 commit 时进行校验，添加以下内容到 package.json

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -e $HUSKY_GIT_PARAMS"
    }
  }
}

检查样式

在项目中编写一些 commit messages，然后运行 commitlint 检查样式，以确保一切设置正确。你可以在任何时候运行该命令以检查某个提交。在终端中执行以下命令：

echo "feat: add new feature" | commitlint

配置文件详解

在上一步中，我们使用以下命令 echo "module.exports = {extends: ['@commitlint/config-conventional']}" > .commitlintrc.js 来生成 .commitlintrc.js 文件。这个配置文件是规范 git commit message 的样式。

在这个 commitlint 的规范中，建议使用以下格式的 commit 信息：

<type>: <subject>

其中，<type> 表示我们这个 commit 的类型，而 <subject> 则是对这个 commit 的简单描述。

针对这种格式，commitlint 提供了默认的配置项作为规范，我们只需要在 .commitlintrc.js 文件中进行配置即可。

默认的配置项文件

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

我们使用了 extends 字段，来表示我们是继承 @commitlint/config-conventional 这个配置项的。

规则说明

在 .commitlintrc.js 中，rules 字段是非常重要的，它允许我们通过规则来自定义 commit message 的形式。以下是部分常用的规则：

type-enum 要求类型必须是预定义枚举之一。
type-case 要求类型必须为指定的 case，可能是 lowercase, uppercase, camel-case, kebab-case, pascal-case, snake-case
type-empty 要求 type 不允许为空
type-min-length 要求 type 的长度不小于指定值
type-max-length 要求 type 的长度不大于指定值
body-leading-blank 要求 body 之前必须有一个空行
body-max-length 要求 body 的长度不得超过指定值
footer-leading-blank 要求 footer 之前必须有一个空行

在 .commitlintrc.js 中，我们要添加的规则（如果有）必须放在 rules 对象中，规则被定义为键值对，其中键是规则名称，值是带有错误级别和配置的数组。

下面是一个例子，它规定了commit信息的类型必须为小写字母：

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-case': [2, 'always', 'lower-case']
  }
}

在规则定义中的第 1 个参数是错误级别：

0 表示禁用规则。
1 表示警告级别。在终端中运行 commit 时，将显示一个警告。
2 表示错误级别。在终端中运行 commit 时，将显示一个错误。

第 2 个参数是一个用于指定规则是否应该被应用的字符串值。例如，如果我们想要规定一个字段必须始终为目标值，我们将使用 always。如果我们要求某个字段永远不应该是目标值，我们将使用 never。

请注意，某些规则在指定 yes 或 no 时可以使用 off 和 on 来表示。

第 3 个参数是需要检查的值。使用小写字母来规范 commit message 的类型。

示例代码

$ git commit -m "New feature (#0000)

feat: added new feature
body: added new routes for user authentication
footer: added changelog"

$ echo $? # commitlint will exit with 1, since the commit message does not follow the configured rules

总结

正如 commitlint 官网所说，只需花费几分钟的时间进行设置，便可以实现更好、更一致的 git 信息规范。使用 @commitlint/top-level，可以轻松地进行设置和配置，从而确保代码库的顺畅协作。希望上述介绍的 @commitlint/top-level 使用教程可以对你有所帮助！

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/110717