快速入门 | 网站

检查提交信息

演示由 svg-term-cli

cat docs/assets/commitlint.json | svg-term --out docs/public/assets/commitlint.svg --frame --profile=Seti --height=20 --width=80

• 🚓 做一个好的 commitizen
• 📦 通过 npm 共享配置
• 🤖 利用 conventional-changelog

目录

• 快速开始 | 网站
  • 目录
  • 什么是 commitlint
    • 使用 commitlint 的好处
  • 入门指南
  • CLI
  • 配置
  • 共享配置
  • 文档
  • API
  • 工具
  • 路线图
  • 版本支持与发布
    • 发布
  • 相关项目
  • 许可证
  • 开发
    • 安装和运行

---

什么是 commitlint

commitlint 检查你的提交信息是否符合 conventional commit 格式。

通常，该模式大致如下：

type(scope?): subject  #scope is optional; multiple scopes are supported (current delimiter options: "/", "\" and ",")

现实中的示例可能如下所示：

chore: run tests on travis ci

fix(server): send cors headers

feat(blog): add comment section

根据 commitlint-config-conventional（基于 Angular 约定），常见的类型包括：

• build
• chore
• ci
• docs
• feat
• fix
• perf
• refactor
• revert
• style
• test

这些可以通过 你自己的配置 进行修改。

使用 commitlint 的好处

• 为什么要使用 Conventional Commits？
• “遵循约定提交的好处”（演讲幻灯片）

入门指南

• 本地设置 - 使用 husky 在提交时检查消息
• CI 设置 - 在 CI 构建期间检查消息

CLI

• 与 commitlint 交互的主要方式。
• npm install --save-dev @commitlint/cli
• 包：cli

配置

• 配置从以下位置读取：
  • .commitlintrc
  • .commitlintrc.json
  • .commitlintrc.yaml
  • .commitlintrc.yml
  • .commitlintrc.js
  • .commitlintrc.cjs
  • .commitlintrc.mjs
  • .commitlintrc.ts
  • .commitlintrc.cts
  • .commitlintrc.mts
  • commitlint.config.js
  • commitlint.config.cjs
  • commitlint.config.mjs
  • commitlint.config.ts
  • commitlint.config.cts
  • commitlint.config.mts
  • commitlint 字段位于 package.json 中
  • commitlint 字段位于 package.yaml 中
• 包：cli, core
• 请参阅 规则 以获取所有可能规则的完整列表
• 示例配置可在 @commitlint/config-conventional 中找到

关于 Node 24+ 的重要说明

Node v24 更改了模块加载方式，这包括 commitlint 配置文件。如果你的项目中不包含 package.json，commitlint 可能无法加载配置，从而导致 Please add rules to your commitlint.config.js 错误消息。可以通过执行以下任一操作来修复：

• 添加一个 package.json 文件，将你的项目声明为 ES6 模块。可以通过运行 npm init es6 轻松完成此操作。
• 将配置文件从 commitlint.config.js 重命名为 commitlint.config.mjs。

共享配置

commitlint 提供了一些可供安装和使用的共享配置：

• @commitlint/config-angular
• @commitlint/config-conventional
• @commitlint/config-lerna-scopes
• @commitlint/config-nx-scopes
• @commitlint/config-patternplate
• @commitlint/config-workspace-scopes
• conventional-changelog-lint-config-atom
• conventional-changelog-lint-config-canonical

⚠️ 如果您想发布自己的可共享配置，请确保其名称符合模式 commitlint-config-emoji-log 或 commitlint-config-your-config-name — 然后在 extend 中您只需编写 emoji-log 或 your-config-name。

文档

请查阅主网站。

API

• 与 commitlint 交互的替代编程方式
• 包：
  • format - 格式化 commitlint 报告
  • lint - 根据 commitlint 规则检查字符串
  • load - 加载共享的 commitlint 配置
  • read - 从指定范围或最后一次编辑中读取提交信息
• 请参阅 API 获取完整的方法列表和示例

工具

• commitizen 适配器
• prompt

路线图

commitlint 被视为稳定版本，并作为开发工具用于各种项目中。

想法：conventional-changelog/commitlint#94

版本支持与发布

• Node.js LTS >= 22.12.0
• git >= 2.13.2

发布

我们不是一个受赞助的 OSS 项目。因此，我们无法保证及时为旧版本发布补丁版本。
如果您被困在旧版本中并且需要安全补丁，我们很乐意接受您提供的 PR。

相关项目

• conventional-changelog 从 conventional commit 历史生成 changelog
• commitizen 面向互联网公民的简单 commit 规范
• create-semantic-module 用于在新项目或现有项目中快速集成 commitizen 和 commitlint 的 CLI

许可证

版权所有 @marionebl。所有 commitlint 个包均根据 MIT 许可证发布。

开发

commitlint 在一个 mono repository 中开发。

安装和运行

git clone git@github.com:conventional-changelog/commitlint.git
cd commitlint
pnpm install
pnpm build # run build tasks
pnpm start # rebuild on change (tsc -b --watch)
node @commitlint/cli/cli.js # run CLI

有关如何贡献的更多信息，请参阅我们的贡献指南。