commitlint

提交信息规范检查

补充说明

commitlint 按配置校验 commit message，常配合 Conventional Commits 和 commit-msg 钩子使用。它只检查信息格式，不检查代码内容。

常用示例

npx commitlint --edit
npx commitlint --from HEAD~1 --to HEAD
npx commitlint --from origin/main --to HEAD
echo "feat: add search" | npx commitlint --stdin
npx commitlint --print-config

commitlint.config.js：

export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'refactor', 'test', 'chore', 'ci']],
    'header-max-length': [2, 'always', 100],
    'scope-empty': [0]
  }
};

易错点与排错

• --edit 读取 .git/COMMIT_EDITMSG；在 commit-msg 钩子里用它才能校验当前提交。
• --from/--to 的范围在浅克隆或合并提交上可能不完整；CI 要 fetch 足够历史。
• 配置是 ESM 还是 CommonJS 取决于项目 type；格式不对会直接加载失败。
• 合并提交和 revert 提交通常需要豁免；用 defaultIgnores 或自定义规则。
• 规则严重级别 0/1/2 分别代表关闭/警告/错误；写成字符串不会生效。
• 钩子安装顺序要在 commit-msg 阶段；只装 pre-commit 不会检查信息。
• 只校验最近提交不够；CI 里应对 PR 的全部提交做范围检查。
• Conventional Commits 只是约定；团队要同步 type 和 scope 的含义。

相关命令

• pre-commit / lefthook — 安装 commit-msg 钩子
• git — 提交与历史范围
• semantic-release — 消费提交信息发版