Git提交规范

delphidoc
72 阅读8分钟

Git提交规范

标准化、可落地、行业通用的Git提交规范，是团队协作的核心规范之一，能大幅提升日志可读性、版本追溯效率，还能无缝对接Changelog自动生成、语义化版本号等工程化能力。

✅ 1. 为什么必须遵守Git提交规范？

  • 不规范的提交（比如 git commit -m "改了点东西"/"修复bug"/"更新代码"）会带来严重问题：
      1. 项目迭代后，无法通过提交日志快速定位哪个提交修复了哪个bug、哪个提交加了哪个功能；
      1. 多人协作时，团队成员看不懂彼此的提交意图，沟通成本飙升；
      1. 无法自动化生成项目更新日志（CHANGELOG.md），发布版本时手动整理繁琐易出错；
      1. 无法基于提交记录自动生成语义化版本号（major/minor/patch）；
      1. 提交历史混乱，项目维护难度指数级增加。
  • 规范的核心价值：统一标准、提升可读性、降低协作成本、赋能工程化自动化。

一、完整标准格式

目前业内事实标准是 Angular 团队制定的 Git Commit Message 规范，规范要求提交信息必须结构化，格式统一、语义明确，强制要求 ：提交信息分为 「标题」、「正文」 和 [页脚]，标题是必填，格式固定，正文、页脚可选，所有内容需遵循固定规则，具体格式和细节如下：

<type>(<scope>): <subject>

<body>

<footer>

核心规则

  1. 标题是唯一必填项，正文和页脚可选；
  2. 标题、正文、页脚之间必须空一行分隔；
  3. 任意一行内容长度不超过 100 字符，保证在 Git 工具和代码平台的可读性。

二、各部分详细规则

1. 标题：<type>(<scope>): <subject>(必填)

标题是提交信息的核心，需简洁明了地概括提交内容，三个组成部分规则如下：

（1）<type>：提交类型（必填，不可自定义）

用于说明提交的性质，只能从以下官方指定值中选择：

类型说明
feat新增功能
fix修复 bug
docs仅修改文档（如 README、注释，无代码改动）
style仅调整代码格式（如空格、缩进、分号，不影响代码逻辑）
refactor代码重构（既不新增功能，也不修复 bug）
perf性能优化（如算法优化、减少请求）
test新增/修改测试用例（无业务代码改动）
build构建系统或外部依赖变更（如 npm 包升级、webpack 配置修改）
ciCI 配置文件或脚本变更（如 Travis、CircleCI 配置）
chore其他不修改 src 或 test 的变更（如修改 .gitignore）
revert回滚某次提交（格式特殊，见下文补充）

（2）<scope>：影响范围（可选）

用于说明提交影响的模块、组件或功能范围，可自定义，需贴合项目实际结构。

  • 示例：前端项目可用 home（首页）、user（用户模块）；后端项目可用 order-api（订单接口）、mysql（数据库配置）；
  • 省略规则：若影响范围全局或不明确，可直接省略 scope，格式变为 <type>: <subject>。

（3）<subject>：简短描述（必填）

对提交内容的精准概括，需严格遵守 4 条规则：

  1. 采用祈使句（命令式语气，如 add「添加」、fix「修复」、update「更新」）；
  2. 首字母小写；
  3. 结尾不加句号；
  4. 长度控制在 50 字符以内。
  • ✅ 正确示例：add home page banner component
  • ❌ 错误示例：Added Home Page Banner Component.

2. 正文（body）：详细描述（可选）

对提交内容的补充说明，需清晰回答 「为什么改？改了什么？变更前后的差异？」，规则如下：

  1. 同样采用祈使句；
  2. 可分点阐述（建议用 - 开头），每一行尽量简短；
  3. 适用于功能新增、复杂 bug 修复、代码重构等场景。

示例：

feat(home): add recommend product list

- Implement lazy loading of product list to optimize page loading speed
- Add product click jump logic to detail page
- Adapt the style of the list to mobile and desktop terminals

3. 页脚（footer）：特殊备注（可选）

仅用于 Angular 官方指定的 2 种场景，不可写入无关备注（如作者、日期），规则如下：

（1）场景1：关联并关闭 Issue/需求单

用于绑定提交与项目工单，支持自动关闭工单，格式为 关键字 #工单号，关键字需首字母大写：

关键字语义适用场景
Closes彻底解决，提交后自动关闭工单功能开发完成、需求收尾
Fixes彻底修复，提交后自动关闭 bug 单bug 修复类提交（搭配 fix 类型）
Resolves与 Closes 语义等价，可任选其一功能开发完成、需求收尾
Related to仅关联工单，不触发关闭需求拆分开发、辅助性修改
  • 多工单格式：用英文逗号分隔，如 Closes #123, Fixes #456。

（2）场景2：标记破坏性变更（BREAKING CHANGE）

用于说明不兼容的代码变更（如删除核心接口、修改参数格式），是强制必写的页脚，格式为：

BREAKING CHANGE: <变更描述 + 影响范围 + 适配方案>
  • 判定标准：其他开发者拉取代码后，若不修改自身代码，项目会无法正常运行。

页脚组合示例

refactor(api): reconstruct user info query interface

- Remove the old getUserInfo interface and replace it with getUserProfile
- Adjust the return parameter structure and add field verification

BREAKING CHANGE: the old getUserInfo interface is removed, all business modules need to replace it with getUserProfile
Closes #789

三、特殊类型：回滚提交（revert）

当执行 git revert 回滚某次提交时，提交信息需遵循固定格式：

revert: <被回滚提交的完整标题>

This reverts commit <被回滚提交的 SHA 校验值>.

Reverts: <SHA 校验值> (<被回滚提交的完整标题>)
  • 示例：
revert: feat(home): add recommend product list

This reverts commit a1b2c3d4e5f67890abcdef1234567890abcdefab.

Reverts: a1b2c3d (feat(home): add recommend product list)

四、合规提交完整示例

✅ 示例1：feat + Closes 需求工单（最常用）

feat(home): 新增首页商品推荐卡片功能

- 实现商品推荐列表的懒加载渲染
- 对接推荐算法接口，支持个性化展示
- 适配移动端和桌面端的样式布局

Closes #10086

✅ 示例2：fix + Fixes Bug工单（黄金组合）

fix(pay): 修复支付宝支付回调后订单状态未更新的问题

- 问题根因：回调接口签名验证失败，导致业务逻辑未执行
- 修复方案：修正签名校验的加密规则，增加异常日志打印
- 测试验证：支付宝沙箱环境全流程测试通过

Fixes #10099

✅ 示例3：refactor + BREAKING CHANGE + Closes（组合最全，大厂高频）

refactor(user): 重构用户信息查询核心接口

- 移除旧的 getUserBasicInfo 接口，合并为 getUserAllInfo
- 修改返回参数结构，统一用户信息字段命名规范
- 删除冗余的接口入参校验逻辑

BREAKING CHANGE: 原用户基础信息接口已移除，所有业务模块需替换为新的全量信息接口，返回字段结构变更
Closes #10100, Fixes #10101

✅ 示例4：feat + Related to 关联需求（拆分开发，不闭环）

feat(cart): 开发购物车商品选中状态存储功能

- 实现商品选中状态的本地缓存逻辑
- 新增选中状态的增删改查工具函数
- 适配购物车列表的选中样式展示

Related to #10102

五、Git提交的「补充最佳实践」（规范的延伸，同样重要）

✅ 5.1 提交粒度：「小而频」，拒绝「大而全」

这是Git使用的黄金原则，比提交规范更重要，核心：一个提交只做一件事！

  • ❌ 错误示范：一次提交改了「新增功能+修复3个bug+优化样式+重构代码」，日志混乱，回滚时会连带其他改动；
  • ✅ 正确示范：新增功能单独提交、修复bug单独提交、样式优化单独提交，哪怕一天提交10次，也比一次提交10个改动好。

好处：日志清晰、定位问题精准、回滚风险低、多人协作冲突少。

✅ 5.2 提交前必做：先拉取再提交，解决冲突

# 提交前一定要拉取最新代码，避免冲突
git pull origin 分支名
# 解决冲突后，再添加、提交、推送
git add .
git commit -m "规范的提交信息"
git push origin 分支名

✅ 5.3 分支命名规范（和提交规范配套，团队必统一）

提交规范是「内容规范」，分支规范是「载体规范」，推荐统一格式（自定义scope即可）：

# 功能开发分支
feature/模块名-功能描述  例：feature/home-banner、feature/user-login
# bug修复分支
bugfix/模块名-问题描述   例：bugfix/pay-callback、bugfix/cart-empty
# 线上紧急修复分支
hotfix/模块名-问题描述   例：hotfix/order-pay-fail
# 重构分支
refactor/模块名-描述     例：refactor/utils-optimize

✅ 六、总结

  1. Git提交规范的行业事实标准是 Angular规范，核心是「结构化、语义化、可读性」；
  2. 提交信息核心必填格式：type(scope): subject，英文书写，祈使句，首字母小写，无句号；
  3. 核心type关键字：feat(新增)、fix(修复)、docs(文档)、style(格式)、refactor(重构)、test(测试)、chore(配置)；
  4. 提交粒度：一个提交只做一件事，小而频，拒绝大而全；
  5. 落地保障：小团队手动遵守，中大型团队用 commitlint+husky 强制校验，新手用 git cz 交互式生成；
  6. 规范价值：日志清晰、协作高效、自动化生成Changelog、自动升级语义化版本号。

遵守以上规范，你的Git提交历史会非常整洁，团队协作效率会大幅提升，这也是开发人员的必备工程化规范之一，养成习惯后收益终身！

avatar
文章
阅读
粉丝