提交技能
按照约定式提交风格和原子提交原则,暂存并提交更改。
提交信息格式
<类型>(<可选作用域>): <简短摘要>
- 全部小写 — 类型、作用域和摘要均小写
- 摘要末尾不加句号
- 祈使语气 — 使用"添加功能"而非"添加了功能"或"添加功能"
- 摘要行最多 50 个字符(软限制,硬限制 72 个字符)
- 摘要描述原因,而非内容(差异显示内容)
类型
| 类型 | 使用场景 | 示例 |
|---|---|---|
feat | 新功能或能力 | feat: add user authentication flow |
fix | 错误修复 | fix: resolve null pointer on empty input |
refactor | 既非修复错误也非添加功能的代码更改 | refactor: extract parser into standalone module |
style | 格式、空白、分号 — 无逻辑更改 | style: apply formatter to config files |
docs | 仅文档更改 | docs: add API usage examples to readme |
test | 添加或更新测试 | test: add edge case coverage for validator |
chore | 构建过程、工具、依赖、配置 | chore: update dependency lockfile |
perf | 性能改进 | perf: cache repeated database lookups |
ci | CI/CD 流水线更改 | ci: add lint step to PR workflow |
作用域(可选)
当类型本身不明确时,使用作用域缩小上下文。从项目的目录结构或领域区域派生作用域:
feat(auth): add OAuth2 token refresh
fix(api): handle timeout on large payloads
docs(contributing): add setup instructions
工作流程
- 审查更改 — 运行
git status和git diff(暂存 + 未暂存)了解发生了什么更改 - 检查近期历史 — 运行
git log --oneline -10以匹配项目现有的提交风格 - 验证意图 — 确认更改构成单个逻辑单元;如果不是,建议拆分为多个提交
- 运行 CI 检查 — 在暂存之前,运行项目的 linter、格式化程序和测试套件以尽早发现问题。检查
package.json中的脚本、Makefile或 CI 配置以获取可用命令。先修复任何失败再继续。 - 暂存文件 — 按文件名添加特定文件(
git add file1 file2),切勿使用git add -A或git add . - 编写信息 — 选择正确的类型,如有帮助则添加作用域,编写祈使语气的摘要
- 提交 — 使用 heredoc 作为提交信息以确保格式整洁
- 验证 — 提交后运行
git status确认提交成功
多行提交
对于需要正文的提交(很少见 — 优先选择简洁的单行信息):
<类型>(<作用域>): <摘要>
<正文解释原因,而非内容>
- 摘要和正文之间留空行
- 正文每行 72 个字符换行
- 仅在摘要本身无法传达原因时使用正文
规则
- 原子提交 — 每个提交一个逻辑更改。一个功能及其测试可以是一个提交。不相关的格式修复应单独提交。
- 无密钥 — 切勿提交
.env、凭据、API 密钥或令牌。如果这些被暂存,请警告用户。 - 无生成产物 — 不要提交构建输出、依赖目录或编译后的文件。在暂存前检查
.gitignore的覆盖范围。 - 仅新建提交 — 始终创建新提交。除非用户明确要求,否则绝不修改。
- 不跳过钩子 — 绝不使用
--no-verify。如果钩子失败,修复根本问题。 - 合作者署名 — 当 Claude 编写或共同编写了更改时,附加合作作者尾注:
Co-Authored-By: Claude <[email protected]>
示例
# 功能 — 新能力
feat: add webhook notification system
# 带作用域的功能
feat(api): add rate limiting middleware
# 修复 — 错误修正
fix: prevent crash on malformed JSON input
# 样式 — 仅格式
style: apply consistent indentation across modules
# 文档 — 文档
docs: add architecture decision records
# 杂务 — 工具/配置
chore: broaden gitignore to cover build artifacts
# 带作用域的测试
test(auth): add integration tests for token refresh
# 带作用域的重构
refactor(db): replace raw queries with query builder
参考文档
- conventional-commits.md — 类型选择指南、破坏性变更、作用域策略、多文件提交决策、正文格式、尾注和常见错误