Commitlint 使用指南

Commitlint 使用指南

什么是 Commitlint？

Commitlint 是一个 Git 提交信息检查工具，它可以帮助团队规范 Git 提交信息的格式，使提交历史更加清晰、易读。

为什么要使用 Commitlint？

  • ✅ 统一的提交格式：让团队成员遵循相同的提交规范
  • ✅ 清晰的提交历史：方便查看项目变更记录
  • ✅ 自动生成 Changelog：配合工具可自动生成版本更新日志
  • ✅ 更好的协作：让其他开发者快速理解每次提交的目的

Get start

安装依赖

# npm
npm install -D @commitlint/cli @commitlint/config-conventional

#yarn
yarn add -D @commitlint/cli @commitlint/config-conventional

#pnpm
pnpm add -D @commitlint/cli @commitlint/config-conventional

初始化Config文件

echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

配置 commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能
        'fix',      // 修复bug
        'docs',     // 文档更新
        'style',    // 代码格式调整
        'refactor', // 代码重构
        'perf',     // 性能优化
        'test',     // 测试相关
        'chore',    // 构建/工具变更
        'revert',   // 回退
        'ci',       // CI/CD 相关
        'build',    // 构建系统/依赖变更
      ],
    ],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'header-max-length': [2, 'always', 100],
  },
};

要使用 commitlint，需要设置 commit-msg 钩子.

配置 Husky

npx husky init  

echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

如果自动生成了.husky/pre-commit, 可以删除掉这个文件

提交信息格式

<type>(<scope>): <subject>

类型 (type)

提交类型必须是以下之一<这里可以自定义增减,下列表是常用的类型>：

类型 说明 示例
feat 新功能 feat: add user login feature
fix 修复 Bug fix: resolve crash on app startup
docs 文档更新 docs: update README
style 代码格式调整（不影响逻辑） style: format code with prettier
refactor 代码重构 refactor: simplify authentication flow
perf 性能优化 perf: optimize image loading
test 测试相关 test: add unit tests for utils
chore 构建/工具变更 chore: update dependencies
revert 回退之前的提交 revert: feat: remove old feature
ci CI/CD 配置变更 ci: configure github actions
build 构建系统或依赖变更 build: upgrade react native

作用域 (scope)

作用域是可选的，用于说明本次提交影响的具体模块：

feat(auth): add OAuth login support
fix(homepage): resolve image overflow issue
style(components): format button styles

描述 (subject)

  • 简洁描述本次提交的内容
  • 不超过 100 个字符
  • 不要以句号结尾
  • 使用小写字母

提交示例

✅ 正确示例

# 新功能
git commit -m "feat: add user profile page"

# 带作用域
git commit -m "feat(api): implement user authentication"

# 修复 Bug
git commit -m "fix: resolve app crash on iOS 15"

# 文档更新
git commit -m "docs: add installation guide"

# 代码重构
git commit -m "refactor: simplify navigation structure"

# 多行提交（添加详细描述）
git commit -m "feat: implement shopping cart

- Add product selection functionality
- Implement quantity adjustment
- Add price calculation feature
"

❌ 错误示例

# 类型不在允许范围内
git commit -m "add: new feature"

# 描述为空
git commit -m "feat:"

# 以句号结尾
git commit -m "feat: add new feature."

# 类型大写
git commit -m "Feat: add new feature"

# 描述超过 100 字符
git commit -m "feat: add a very very very very very very very very very very very long description"

常见错误与处理

1. 类型错误

✖ type must be one of [feat, fix, docs, style, refactor, perf, test, chore, revert, ci, build]

解决方法：使用允许的类型之一

2. 描述为空

✖ subject may not be empty

解决方法：添加提交描述

3. 类型大写

✖ type must be lower-case

解决方法：使用小写类型

4. 描述以句号结尾

✖ subject may not end with full stop

解决方法：移除结尾的句号

5. 描述过长

✖ subject may not be longer than 100 characters

解决方法：缩短描述或使用多行提交

多行提交格式

如果需要添加更详细的描述，可以使用多行格式：

git commit -m "feat: add payment feature

- Implement credit card payment
- Add payment confirmation screen
- Integrate with payment gateway API

Closes #123"

修改错误的提交信息

如果提交信息不符合规范，可以使用以下方法修改：

修改最后一次提交

git commit --amend -m "fix: correct typo in user name"

修改历史的提交

# 交互式变基
git rebase -i HEAD~n

# 将需要修改的提交标记为 edit
# 保存后修改提交信息
git commit --amend -m "new message"
git rebase --continue

配置说明

按照配置则项目已配置以下规则：

  • ✅ 类型必须是允许的类型之一
  • ✅ 类型必须小写
  • ✅ 类型不能为空
  • ✅ 描述不能为空
  • ✅ 描述不能以句号结尾
  • ✅ 描述不超过 100 字符

参考资源

posted on 2026-01-20 20:40  爱IT的小狐狸  阅读(1)  评论(0)    收藏  举报