返回文章

Conventional Commits:让 Git 提交记录清晰可读

从提交格式、类型和影响范围,到正文、破坏性变更与版本号,整理约定式提交的核心规则及可直接参考的示例。

翻看 Git 历史时,update、fix bug、修改代码 这样的提交信息很难告诉我们:这次变更影响了哪里,为什么要改,升级时需要注意什么。

Conventional Commits(约定式提交)为提交信息提供了一套轻量约定。统一的结构便于阅读和检索,也为自动生成变更日志(Changelog)、分析版本变化提供了依据。本文按 Conventional Commits 1.0.0 官方规范 整理,并区分规范要求与常见团队约定。

一条提交信息的结构

提交信息由标题(Header)、正文(Body)和页脚(Footer)组成。标题必填,正文与页脚按需填写。

<type>[(<scope>)][!]: <description>

<body>

<footer>

上面的方括号表示可选部分,不需要实际输入。scope 表示影响范围,! 表示破坏性变更;描述有时也称为 subject。标题中的冒号使用英文半角字符,冒号后保留一个空格。正文与标题、页脚与前面的段落之间,都用空行分隔。

最简单的提交只需要一行:

feat(user): add phone number validation on signup

它表达了三件事:新增功能,影响用户模块,具体新增注册时的手机号校验。

Header:类型、范围与简短描述

Type:这次变更属于哪一类

type 用来说明变更性质。常见类型可以按下面的方式使用:

类型用途示例
feat新增功能feat: support dark mode
fix修复缺陷fix: resolve crash on login timeout
docs仅修改文档或说明性注释docs: update API endpoints guide
style不影响运行逻辑的格式调整,如空格、缩进style: format source files with prettier
refactor不新增功能、也不修复缺陷的代码重构refactor: simplify user auth logic
perf性能优化perf: improve list rendering speed
test添加或修改测试test: add checkout service tests
build构建系统或外部依赖变更build: upgrade webpack to v5
ci持续集成配置变更ci: add automated lint workflow
chore不涉及业务源码或测试的辅助维护chore: update .gitignore
revert撤销之前的提交revert: remove dark mode support

官方规范明确规定了 feat 和 fix 的用途,但没有强制要求团队采用上表中的全部类型。 其他类型属于常见约定,应在项目中统一定义。

这里的 style 指代码格式,不等同于界面样式。新增主题切换、修复页面布局等变更,应按实际意图选择 feat 或 fix。

Scope:这次变更影响哪里

scope 是可选项,用圆括号包裹,通常填写模块或组件名:

feat(auth): add google oauth login
fix(parser): handle empty json input
docs(readme): clarify local setup steps

范围应当帮助读者定位变更。同一个模块保持同一种命名,比把范围写得很细更有用。

Description:用一句话说明具体变化

描述直接跟在冒号和空格后,简短说明本次提交的结果。

英文提交常使用祈使句,例如用 add,而不是 added 或 adds。团队也常约定描述首字母小写、结尾不加句号,并将整个标题控制在约 50~72 个字符以内。

这些是写作习惯,不是 Conventional Commits 1.0.0 的强制要求。中文提交同样可以遵守结构,例如:

fix(parser): 处理空 JSON 输入

相比 fix: fix bug,写清触发条件和变化结果,能让提交在几个月后仍然容易理解。

Body:留下改动的原因与上下文

正文适合解释标题容纳不下的信息:原来有什么问题,为什么需要这次变更,变更之后有什么不同。

fix(auth): preserve the destination after session expiry

Users previously returned to the home page after signing in again.
Keep the original destination so they can continue the interrupted task.

正文不必复述代码实现。简单变更可以只写标题;涉及复杂逻辑、行为调整或关键取舍时,再补充必要的背景。

Footer:标记破坏性变更与关联事项

破坏性变更

当变更使已有调用方式无法继续使用时,需要明确标记破坏性变更。规范允许两种写法:

  • 在类型或范围之后、冒号之前添加 !。
  • 在页脚中使用大写的 BREAKING CHANGE: ,随后说明具体变化。

两种写法可以同时使用。仅使用 ! 时,描述应说明破坏性变化;对读者需要采取迁移动作的变更,页脚适合写清旧行为、新行为及迁移方式。

feat(api)!: switch auth header from Bearer to Token

Align the authorization header with the new gateway requirements.

BREAKING CHANGE: The Authorization header now requires Token <token>
instead of Bearer <token>. Update API clients before upgrading.

Closes #204

破坏性变更可以出现在任何类型的提交中。例如,重构移除了公开接口,也需要标记为 refactor(api)!: ...。

关联 Issue

页脚还可以记录关联事项:

Closes #123
Fixes #456
Refs: #789

Refs: #789 表示引用;Closes、Fixes 常用于表达关闭 Issue 的意图。是否自动关闭,以及何时关闭,由代码托管平台和仓库配置决定。

与语义化版本的关系

约定式提交能为版本发布提供信号。按 Semantic Versioning 2.0.0 的稳定版本规则,可以这样理解常见对应关系:

变更版本变化示例
fix,且没有破坏性变更修订号 PATCH1.4.2 → 1.4.3
feat,且没有破坏性变更次版本号 MINOR1.4.2 → 1.5.0
任意类型的破坏性变更主版本号 MAJOR1.4.2 → 2.0.0

docs、chore、refactor 等类型本身不隐含固定的版本递增规则。0.y.z 属于初始开发阶段,也不能直接套用上表的稳定版本前提。

提交信息提供的是结构化依据。自动生成 Changelog、计算版本号和执行发布,还需要项目配置相应工具与流程。

提交前检查

  • 类型是否符合实际变更意图?
  • 范围是否清楚,是否沿用项目现有命名?
  • 描述是否说清具体变化,而不是只写 update 或 fix bug?
  • 复杂变更是否交代了必要的原因和上下文?
  • 破坏性变更是否明确标记,并说明迁移方式?
  • 一次提交是否聚焦同一个目的,能否独立理解和回溯?

提交信息会成为项目长期保留的一部分。写清变更性质、影响范围和关键原因,下一次排查问题、审查代码或准备发布时,就少一次重新猜测。

参考资料

  1. Conventional Commits 1.0.0 官方规范
  2. Semantic Versioning 2.0.0