CommitLint 简明使用教程

在软件开发过程中，良好的提交信息（commit message）是非常重要的。它不仅有助于代码审查，还能提供更好的历史追踪和自动化工具的支持。CommitLint 是一个帮助你规范化提交信息的工具。本教程将从原理、要解决的问题、使用说明、使用配置、插件开发等方面详细介绍如何使用 CommitLint。

原理

CommitLint 是基于 Node.js 的工具，它通过一系列的规则来检查 Git 提交信息的格式，确保它们遵循预定义的标准。它在 Git 的 commit-msg 钩子中运行，这意味着每次提交时，CommitLint 都会自动检查提交信息。如果提交信息不符合规则，CommitLint 会阻止提交并给出错误提示。

CommitLint 的核心是一个可扩展的规则引擎，它允许开发者自定义规则，或者使用社区提供的规则集。这些规则可以控制提交信息的各个方面，包括标题、正文和脚注。

要解决的问题

不规范的提交信息：开发者可能以各种格式提交信息，这使得后续的代码审查、版本控制和自动化工具使用变得困难。
自动化难度：不规范的提交信息使得自动化工具（如自动化生成 CHANGELOG）难以实现。
团队协作：在团队项目中，统一的提交信息格式有助于提高团队协作效率。

使用说明

安装

首先，你需要在项目中安装 CommitLint 及其相关依赖。以下命令使用 npm 作为包管理器，你也可以使用 yarn 或其他包管理器。

bash 复制代码

npm install --save-dev @commitlint/{config-conventional,cli}

这将安装 CommitLint 的命令行工具和一个常用的规则集 config-conventional，后者基于 Angular 团队的提交准则。

配置

安装完成后，你需要在项目根目录下创建一个名为 commitlint.config.js 的配置文件。以下是一个基本的配置示例，它使用了 @commitlint/config-conventional，这是一个遵循 Angular 团队提交准则的预设配置。

javascript 复制代码

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

这个配置文件告诉 CommitLint 使用 config-conventional 规则集，它定义了一系列常用的规则，如提交类型、范围、标题格式等。

集成 Git 钩子

为了让 CommitLint 在每次提交时自动运行，我们推荐使用 Husky 来管理 Git 钩子。首先安装 Husky：

bash 复制代码

npm install husky --save-dev

然后在 package.json 中配置 Husky：

json 复制代码

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

这样，每次提交时，CommitLint 就会自动检查提交信息。Husky 是一个流行的 Git 钩子工具，它可以轻松地将脚本集成到 Git 事件中。

使用配置

CommitLint 允许你自定义规则来满足特定的项目需求。以下是一些常见的配置项：

rules：定义一组规则，每个规则可以设置为数组，包含级别、适用条件和值。
extends：继承其他配置文件的规则。
plugins：添加插件以扩展 CommitLint 的功能。

例如，如果你想要自定义提交类型，可以在 commitlint.config.js 中添加如下配置：

javascript 复制代码

module.exports = {
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
  }
};

在这个例子中，type-enum 规则被设置为错误级别（2），并且总是应用（'always'），允许的提交类型包括 feat, fix, docs, style, refactor, test, chore。

插件开发

如果你的项目有特殊需求，CommitLint 也支持通过插件来扩展。一个插件是一个 Node.js 模块，它可以添加新的规则或覆盖现有规则。

以下是一个简单的插件示例：

javascript 复制代码

// commitlint-plugin-example.js
module.exports = {
  rules: {
    'example-rule': ({subject}) => {
      return [subject.includes('example'), 'Your commit message must contain the word "example"'];
    }
  }
};

然后在 commitlint.config.js 中使用这个插件：

javascript 复制代码

module.exports = {
  plugins: ['commitlint-plugin-example'],
  rules: {
    'example-rule': [2, 'always']
  }
};

在这个插件中，我们定义了一个名为 example-rule 的规则，它检查提交信息的主题是否包含单词 "example"。如果不包含，提交将被拒绝，并显示一条错误消息。

结语

CommitLint 是一个强大的工具，可以帮助你和你的团队规范化提交信息。通过本教程，你应该已经了解了 CommitLint 的基本使用方法，包括安装、配置、自定义规则和插件开发。希望这能帮助你提高项目的质量和团队的协作效率。记住，良好的提交习惯是高效团队协作的基石。