5.2 KiB
5.2 KiB
Git 提交规范指南
本项目使用 Conventional Commits 规范,通过 commitizen + cz-git 提供交互式提交体验。
快速开始
使用交互式提交(推荐)
# 1. 暂存你的更改
git add .
# 2. 使用交互式提交
pnpm commit
交互式提交会引导你完成:
- 选择提交类型(feat/fix/docs 等)
- 选择影响范围(common/vue3/uni-app 等,可跳过)
- 输入简短描述(必填,4-100 字符)
- 输入详细描述(可选)
- 是否有破坏性变更(可选)
- 关联 Issue(可选)
手动提交
如果你熟悉规范,也可以手动提交:
git commit -m "feat(common): 添加 debounce 防抖函数"
提交信息格式
<type>(<scope>): <subject>
<body>
<footer>
Type(必填)
| 类型 | Emoji | 说明 | 示例 |
|---|---|---|---|
feat |
✨ | 新功能 | feat(common): 添加 throttle 节流函数 |
fix |
🐛 | Bug 修复 | fix(uni-app): 修复蓝牙连接超时问题 |
docs |
📚 | 文档更新 | docs: 更新 README 安装说明 |
style |
💎 | 代码格式(不影响逻辑) | style(vue3): 格式化代码缩进 |
refactor |
📦 | 重构(不是新功能也不是修复) | refactor(common): 优化 Permission 类实现 |
perf |
🚀 | 性能优化 | perf(vue3): 优化 mergeClass 性能 |
test |
🚨 | 测试相关 | test(common): 添加 timer 单元测试 |
build |
🛠 | 构建系统或依赖更新 | build: 升级 webpack 到 5.80 |
ci |
⚙️ | CI 配置更新 | ci: 添加 GitHub Actions 配置 |
chore |
♻️ | 其他杂项 | chore: 更新 .gitignore |
revert |
🗑 | 回滚之前的提交 | revert: 回滚 feat(common): xxx |
Scope(可选)
影响范围,必须是以下之一:
common- @r-utils/common 包vue3- @r-utils/vue3 包vue2- @r-utils/vue2 包uni-app- @r-utils/uni-app 包deps- 依赖更新release- 版本发布
如果改动影响多个包或不属于特定包,可以省略 scope。
Subject(必填)
简短描述,要求:
- 长度: 4-100 字符
- 使用祈使句,如"添加"而不是"添加了"
- 首字母小写
- 结尾不加句号
Body(可选)
详细描述,说明:
- 改动的原因
- 与之前行为的对比
- 实现细节
每行不超过 200 字符。
Footer(可选)
用于:
- 关联 Issue:
fix #123或close #456 - 说明破坏性变更:
BREAKING CHANGE: xxx
提交示例
基础示例
# 新功能
feat(common): 添加 debounce 防抖函数
# Bug 修复
fix(uni-app): 修复蓝牙连接超时问题
# 文档更新
docs: 更新安装说明
# 重构
refactor(vue3): 优化 mergeClass 实现逻辑
带 Body 的示例
feat(common): 添加 throttle 节流函数
实现了一个通用的节流函数,支持:
- 自定义延迟时间
- leading 和 trailing 选项
- 取消功能
关联 Issue 的示例
fix(uni-app): 修复蓝牙连接超时问题
修复了在某些 Android 设备上蓝牙连接超时的问题,
通过增加重试机制和优化超时时间来提高连接成功率。
fix #123
破坏性变更示例
feat(common)!: 重构 Permission 类 API
BREAKING CHANGE: Permission 类的构造函数参数已更改
之前:
new Permission('module:action')
现在:
new Permission({ module: 'module', action: 'action' })
迁移指南请参考文档。
提交规则
项目通过 commitlint 强制执行以下规则:
- type 必须是允许的类型之一
- scope 如果提供,必须是允许的范围之一
- subject 不能为空,长度 4-100 字符
- subject 不能以句号结尾
- type 和 scope 必须小写
- header 总长度不超过 120 字符
- body 和 footer 每行不超过 200 字符
如果提交信息不符合规范,commit-msg hook 会阻止提交并提示错误。
Git Hooks
项目配置了以下 Git Hooks:
pre-commit
运行 lint-staged,自动检查和修复:
- ESLint 代码检查
- Prettier 代码格式化
- Jest 单元测试
commit-msg
使用 commitlint 校验提交信息格式。
常见问题
Q: 提交被拒绝怎么办?
A: 检查以下几点:
- 提交信息格式是否正确
- 代码是否通过 ESLint 检查
- 测试是否全部通过
Q: 如何跳过 hooks?
A: 不建议跳过 hooks,但如果确实需要:
git commit --no-verify -m "your message"
Q: 如何修改上一次提交?
A: 使用 git commit --amend:
# 修改提交信息
git commit --amend
# 添加遗漏的文件
git add forgotten-file.js
git commit --amend --no-edit
Q: 提交信息写错了怎么办?
A: 如果还没有 push,可以修改:
# 修改最后一次提交
git commit --amend
# 修改更早的提交(交互式 rebase)
git rebase -i HEAD~3
如果已经 push,不建议修改,可以创建新的提交来修正。