Git 提交规范¶

怎么写 commit message 才清晰、可检索、方便协作。命令见 Git 命令集；本地校验见 Gitignore 与 Hooks。

相关文档：Git 命令集 · Gitignore 与 Hooks · 协作流程

阅读指引¶

1. 概念：提交说明由哪几部分组成、为什么要约定
2. 总览：常见格式、type 表、相关命令
3. 场景：按实际写法与踩坑展开，含正反例
4. 文末速查：现象 → 建议

提交说明是什么¶

每次 git commit 都会留下一条 提交说明（commit message），包含 标题（subject，通常第一行）和可选的 正文（body）、页脚（footer / trailer）。

一句话：「给这次改动贴标签，让未来的自己和队友能看懂 改了什么、为什么改。」

效果：说明随 commit 永久保存在 Git 历史里；git log、PR、changelog、自动化发版都会读到它。写得好不好，直接影响 code review 和排障效率。

总览¶

常见格式一览¶

Conventional Commits 规范 被 Angular、Semantic Release 等广泛采用；团队可以裁剪（例如只要 type: 不要 scope），但结构清晰比死记标准更重要。

Conventional Commits：type 速查¶

可选 scope（括号内模块名）：feat(api): ...、fix(ui): ...。
表示 不兼容变更 时在 type 后加 !：feat(api)!: remove v1 endpoints。

本篇相关 Git 命令¶

写好标题的通用原则¶

场景：团队没定规范时的最低要求¶

常见场景：个人仓库、小团队尚未写 CONTRIBUTING。

一句话：「首行让人 5 秒内看懂这次改动目的。」

# 可以：动词开头、具体
git commit -m "Fix crash when profile avatar is missing"

# 可以：中文项目
git commit -m "修复头像为空时个人页崩溃"

# 避免：太泛
git commit -m "update"
git commit -m "fix bug"
git commit -m "WIP"

# 避免：把 issue 号当唯一说明
git commit -m "#123"

场景：Conventional Commits 怎么写¶

常见场景：开源项目、需要自动生成 changelog、PR 标题与 commit 对齐。

# 新功能 + scope
git commit -m "feat(billing): support annual subscription"

# 修 bug
git commit -m "fix: prevent double submit on checkout"

# 文档-only
git commit -m "docs: add API rate limit section"

# 依赖升级（别和功能混在一起）
git commit -m "build: upgrade eslint to 9.x"

效果：工具可按 feat / fix 分类发版；reviewer 从 git log 快速过滤类型。

场景：多行说明 — 标题 + 正文¶

常见场景：重构、行为变更、需要交代 为什么 而不是 改了哪些文件。

一句话：「首行摘要，空一行，正文写动机、取舍、风险。」

git commit -m "$(cat <<'EOF'
fix(auth): reject expired refresh tokens

Previously expired tokens still passed middleware when
clock skew was under 30s. Align with OAuth spec and
return 401 with clear error code.

Refs #8842
EOF
)"

或用编辑器（不设 -m）：

git commit
# 编辑器中：
# fix(auth): reject expired refresh tokens
#
# Previously expired tokens still passed...

效果：git log 默认只显示首行；git log -p 或 git show 能看到正文。

场景：改最近一次说明（还没 push）¶

常见场景：commit 完发现 typo、漏 git add 某个文件。

# 只改说明
git commit --amend

# 说明写在一行
git commit --amend -m "feat: add password reset email"

# 补文件进上一次 commit，说明不变
git add forgotten.ts
git commit --amend --no-edit

一句话：「最后一笔账还没 push，可以涂改。」

效果：commit hash 会变；仅适用于尚未 push 或仅你使用的分支。

场景：已经 push 到远程了¶

常见场景：说明写错、功能要撤回，但 commit 已在 origin/main 上。

# 推荐：用 revert 生成「反向」commit
git revert HEAD
git commit  # 编辑器里默认有 revert 说明，可改

# 不推荐在 shared main 上：
# git reset --hard HEAD~1 && git push --force

一句话：「公共历史已发布，优先 追加 新 commit，而不是改旧账。」

场景：破坏性变更（Breaking Change）¶

常见场景：删 API、改配置项默认值、主版本号升级。

# 方式 1：type 后加 !
git commit -m "$(cat <<'EOF'
feat(api)!: remove legacy /v1 users endpoint

BREAKING CHANGE: clients must use /v2/users. v1 removed
after deprecation period noted in 2025-Q4 changelog.
EOF
)"

# 方式 2：footer 里写 BREAKING CHANGE:
git commit -m "feat: switch default TLS to 1.3

BREAKING CHANGE: TLS 1.0/1.1 no longer supported."

效果：发版工具可据此 bump 主版本号；使用者能在 log 里搜 BREAKING CHANGE。

场景：Trailer 与 Issue 关联¶

Trailer 是 message 末尾 的标准化行（Key: Value），常见于开源与 GitHub/GitLab 集成。

git commit -m "$(cat <<'EOF'
fix: validate upload MIME type

Co-authored-by: Alex Chen <alex@example.com>
Closes #456
EOF
)"

常见场景：

• PR Squash merge 时把多位作者的 Co-authored-by 写进最终 commit
• IDE / AI 工具 自动插入 trailer — 提交前看一眼，去掉不需要或违反项目政策的行

场景：PR 合并后 commit 长什么样¶

常见场景：在 GitHub/GitLab 上 merge PR，本地 history 出现 merge commit 或 squash commit。

一句话：「在平台上 merge 时，PR 标题 ≈ 未来的 commit 标题（尤其 squash）。」

场景：与 commit-msg hook 配合¶

团队可在 commit-msg hook 里校验格式（例如必须 feat: 开头、首行非空）。示例与安装见 Gitignore 与 Hooks — commit-msg。

效果：不合规时在本地 commit 失败，比 push 后 CI 打回更早。

场景：好 vs 差 — 对照示例¶

速查：现象 → 建议¶

更多命令：Git 命令集 — git commit。