Conventional Commits

规范 Git 提交信息格式，便于自动化工具生成版本号、变更日志。遵循 Conventional Commits v1.0.0 与 Angular 提交规范。

何时使用

• 编写 Git 提交信息
• 创建代码提交
• 审查提交历史
• 生成提交信息模板

核心格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type 类型（必须）

其他类型允许，但不影响语义版本（除非含 BREAKING CHANGE）。

Scope 范围（可选）

放在括号内，表示影响的模块。小写，多词用连字符连接：

feat(parser): add array parsing support
fix(api-client): handle timeout errors

Description 描述（必须）

• 现在时态、祈使句：add 而非 added / adds
• 首字母小写，结尾不加句号
• ≤ 72 字符（建议 ≤ 50 更佳）
• 用动词开头，简短说明做了什么

Body 正文（可选）

• 空一行后开始
• 说明"做了什么"和"为什么"（diff 已展示 what，正文补 why）
• 每行 ≤ 72 字符，可多行，可用列表

Footer 脚注（可选）

• 空一行后开始
• 格式：<token>: <value> 或 <token> #<value>
• 每个脚注独占一行

破坏性变更

两种方式表示（对应 SemVer MAJOR）：

方式 1：! 在 type 后

feat!: remove deprecated API endpoints
feat(api)!: change authentication flow

方式 2：BREAKING CHANGE 脚注

feat: add new config format

BREAKING CHANGE: config file format changed from YAML to JSON

关联 Issue

fix: resolve login timeout

Closes #123
Refs #456

GOOD vs BAD 对比

简单提交

✅ feat: add user authentication ❌ added user authentication（过去时、无 type）

带范围

✅ feat(auth): add OAuth2 login support ❌ feat: added OAuth2 to auth（无 scope、过去时）

带正文

✅

feat: add user profile management

Add functionality for users to:
- Update profile information
- Change password
- Upload avatar image

❌ feat: add profile + 一句话流水账

破坏性变更

✅

feat!: remove deprecated API endpoints

BREAKING CHANGE: The following endpoints have been removed:
- /api/v1/users
- /api/v1/posts

Use /api/v2/* endpoints instead.

❌ feat: remove old endpoints（未标记破坏性）

关联 Issue

✅

fix: resolve authentication timeout issue

Closes #123
Refs #456

❌ fix: auth issue + #123（标题模糊、issue 未用 footer）

常见错误

最佳实践

• 一个提交一个逻辑变更——原子性优于体量
• 标题清晰具体——"add search with debouncing" 胜于 "improve search"
• 正文说"为什么"而非"做了什么"——diff 已展示 what，正文补 why
• 关联 Issue——Closes #123 让 PR 自动关闭 issue
• 不混合格式化与逻辑——style: 和 feat: 分开提交
• 不提交调试代码或临时文件

快速参考

工具推荐

• commitlint - 校验 commit 格式
• commitizen - 交互式 commit 辅助
• semantic-release - 自动版本发布

参考链接

• Conventional Commits Specification v1.0.0
• Angular Commit Guidelines

macOS 复制到剪贴板

在 macOS 系统下生成 commit message 后，使用 pbcopy 将其复制到系统剪贴板，便于直接粘贴到 git GUI 或终端。

检测系统：

[[ "$(uname)" == "Darwin" ]] && echo "macOS"

单行消息：

echo -n "feat(parser): add array parsing support" | pbcopy

多行消息（含 body / footer）：

pbcopy <<'EOF'
fix: prevent request race condition

Introduce request ID to track concurrent requests.
Reject duplicate requests with same ID.

Refs: #123
EOF

Agent 工作流建议：

生成 commit message 后，若检测到 uname 输出为 Darwin，自动通过 pbcopy 复制结果，并在回复中提示「已复制到剪贴板」。非 macOS 系统跳过此步骤。