公认的 Git 提交规范是怎样的?

2026-11-15 18:35:00
丁国栋
AI生成 20
摘要:本文记录和整理公认的Git提交规范。

“公认”的 Git 提交规范,业界最主流的是 ​Conventional Commits(约定式提交)​,它脱胎于 Angular 提交规范,并被 commitlint、semantic-release、standard-version 等工具广泛采用。

一、标准格式

<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>
  • type:必填,变更类型
  • scope:可选,影响模块/范围,如 (auth)、(api)
  • subject:必填,简短描述(祈使句)
  • body:可选,解释「为什么改」
  • footer:可选,关联 Issue、破坏性变更等

二、type 类型对照

type 含义 版本影响(SemVer)
feat 新功能 minor
fix 修 bug patch
docs 文档变更 —
style 格式调整(空格/缩进,不改逻辑) —
refactor 重构(不改对外行为) —
perf 性能优化 通常 patch
test 测试相关 —
build 构建系统/依赖变更 —
ci CI 配置变更 —
chore 其他杂项维护 —
revert 回滚提交 —

规范本身只强制 feat/fix,其余类型来自社区约定。

三、破坏性变更(Breaking Change)

两种方式,可同时使用:

feat(api)!: remove v1 endpoints
BREAKING CHANGE: 客户端需迁移到 /v2 接口
  • 在 type(scope) 后加 !
  • 或在 footer 写 BREAKING CHANGE: <说明>(大写)

对应 SemVer 的 major 版本递增。

四、写法的几条铁律

  1. ​subject 用祈使句​:add 而不是 added / adds
  2. ​首字母小写、结尾不加句号​(社区常见约定)
  3. ​subject 尽量短​:50 字符左右,工具默认常限 100 字符
  4. ​body 与 subject 空一行​,解释 why 而不是罗列 diff(what 看代码就行)
  5. body 每行约 72 字符换行
  6. footer 用 Key: value 或 Key #123 形式:
    • Closes #123
    • Refs: #456
    • Reviewed-by: XXX

五、好例子 vs 坏例子

❌

修复了一下登录的bug
update
WIP

✅

fix(auth): prevent session leak on logout
释放未注销的监听器,避免退出登录后仍能收到推送。
Closes #142
feat(order): support partial refund
新增部分退款接口,允许按商品行退款。
BREAKING CHANGE: 原 refund() 全单退款改为 refundAll()

六、工程化落地

  • 校验:@commitlint/config-conventional + husky
  • 交互式生成:commitizen / git cz
  • 自动生成 CHANGELOG 和打版本:standard-version、semantic-release

七、一个容易忽略的点

如果改动“又加功能又顺手重构”,​按主要意图选一个 type​,不要把无关模块塞进同一个 commit。

一个 commit 只讲一件事,比“格式漂亮但内容混杂”更重要。

还没有评论,来做第一个吧!

称呼
邮箱
博客分类