committing-with-commitlint

在使用 commitlint 的仓库中提交

commitlint 会根据仓库配置的约定验证提交消息（通常是 Conventional Commits）。配置就是约定：编写提交消息前先阅读配置；提交被拒绝时，以错误输出为准。

1. 检查仓库是否使用 commitlint

以下任一情况都表示仓库启用了 commitlint：

• 仓库根目录中的配置文件： .commitlintrc、.commitlintrc.{json,yaml,yml,js,cjs,mjs,ts,cts,mts}， 或 commitlint.config.{js,cjs,mjs,ts,cts,mts}
• package.json 中有 "commitlint" 字段
• 会运行 commitlint 的 commit-msg 钩子（检查 .husky/commit-msg、lefthook.yml， 或 .git/hooks/commit-msg）

2. 查看强制执行的规则

npx commitlint --print-config json

如果此命令以非零状态码退出，说明配置本身有问题（例如 extends 无法解析）——请查看 stderr 中的错误，不要猜测。

查看 rules 对象。每条规则的格式为 [severity, applicability, value]：

• severity — 0 = 禁用，1 = 警告，2 = 错误（只有错误会阻止提交）
• applicability — "always" = 必须满足条件，"never" = 不得满足条件
• value — 规则参数（列表、数字或字符串）

编写消息时最重要的规则：

规则	控制内容
type-enum	允许的类型（例如 feat、fix、chore 等）
scope-enum	允许的范围（空列表 = 允许任何范围）
scope-empty	[2, "never"] = 必须填写范围；[2, "always"] = 禁止填写范围
subject-case	使用 "never" 时：主题不得采用的大小写格式
subject-full-stop	使用 "never" 和 "." 时：主题末尾不得加句号
header-max-length	第一行的最大长度
body-leading-blank	主题与正文之间必须有空行
body-max-line-length	正文每行的最大长度

未列出或已禁用（severity 为 0）的规则不会强制执行。不确定时，请采用能通过常见预设的保守基准：类型使用小写，不加句末标点，标题不超过 72 个字符（config-conventional 允许最多 100 个字符）。请注意，如果完全没有配置，运行 commitlint 会报 empty-rules 错误，而不是回退到任何默认约定。

3. 编写消息

格式：type(scope): subject —— 除非 scope-empty 为 [2, "never"]，否则范围可省略。

以下示例符合 @commitlint/config-conventional 的要求：

feat(parser): add support for inline issue references

Explain what changed and why. Separate the body from the subject with a blank
line (body-leading-blank) and keep lines within body-max-line-length.

Closes #123

4. 提交前验证

printf '%s' "feat(parser): add support for inline issue references

Explain what changed and why.

Closes #123" | npx commitlint

退出码为 0 且没有输出，表示消息通过验证。请验证完整消息（标题和正文），而不只是第一行——正文规则也会检查。提交前先验证，比提交失败后再处理更省事。

5. commit-msg 钩子拒绝提交时自行修正

拒绝输出会在方括号中列出每条违反的规则：

⧗   --- input ---
Feat: Added new parser.
✖   subject must not be sentence-case, start-case, pascal-case, upper-case [subject-case]
✖   subject may not end with full stop [subject-full-stop]
✖   type must be lower-case [type-case]
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 4 problems, 0 warnings

• 仅修复方括号中列出的规则；其他内容保持完全不变。
• 通过标准输入重新验证（第 4 步），然后重试提交。
• 绝不要使用 git commit --no-verify 绕过钩子——正确做法始终是修正消息。