按 Enter 键跳转到正文

Git提交日志规范指南

发布于 2023年4月2日，作者 Leanku

在软件开发流程中，Git已经成为版本控制的事实标准。每次提交代码都需要填写commit message，否则不允许提交。然而，在日常开发中，我们经常会看到各种各样模糊不清的提交信息，如“fix bug”、“更新代码”、“修改问题”等。这些不规范的commit message充斥在git history中，导致后续维护人员无法快速定位问题，有时甚至连提交者自己都不记得某次提交的目的。因此，我们需要一套统一的规范来管理和约束commit message。

规范概述

目前业界最知名的规范是Angular团队的commit message规范，它结构清晰、易于实施，已被广泛应用于开源项目和商业项目中。同时，许多IDE（如IntelliJ IDEA）也提供了相应的插件（如Git Commit Template）来辅助开发者遵循这一规范。

本文将以Angular规范为基础，详细介绍一套通用的Git commit message规范，并提供具体的操作示例。

Commit Message整体结构

规范的commit message包含三个部分：Header、Body和Footer。其格式如下：

<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

重要说明：

  • Header是必需的，包含type、scope和summary三个子元素
  • Body是必需的，用于详细描述提交内容
  • Footer是可选的，用于记录不兼容变更或关闭issue

关键规则：Header和Body之间必须有一个空行分隔，这是许多Git工具正确解析提交信息的前提。

整体结构示例

feat(用户认证): 增加短信验证码登录功能

为了提升用户登录体验，增加了通过手机号接收验证码进行登录的方式。
- 集成阿里云短信服务
- 新增验证码生成与校验逻辑
- 更新登录页面UI

Closes #245

Header详解

Header是commit message的“标题”，格式为：

<type>(<scope>): <summary>

其中，type和summary为必填项，scope为可选项。

Type：提交类别

Type用于说明本次提交的类别，必须使用以下标准化标识之一：

Type说明使用场景
feat新功能新增用户可见的功能特性
fix修复bug修复线上或测试环境发现的缺陷
docs文档更新仅修改文档，不涉及代码变更
style代码格式不影响代码运行的格式调整（空格、缩进、分号等）
refactor代码重构既不是新增功能，也不是修复bug的代码结构调整
perf性能优化提升系统性能或用户体验的代码变更
test测试相关新增或修改测试用例
chore构建/工具变动构建流程、依赖管理、辅助工具等变更
revert回滚提交撤销之前的某次提交

Type使用示例：

 1# 新增功能
 2git commit -m "feat: 新增用户积分排行榜功能"
 3
 4# 修复bug
 5git commit -m "fix: 修复登录接口在并发场景下的空指针异常"
 6
 7# 文档更新
 8git commit -m "docs: 更新API接口文档中的参数说明"
 9
10# 代码重构
11git commit -m "refactor: 优化订单处理模块的代码结构"
12
13# 性能优化
14git commit -m "perf: 优化图片加载策略，减少首屏加载时间"

Scope：影响范围

Scope用于说明本次提交影响的功能模块或代码范围，如Controller、Service、DAO、View等。具体值视项目架构而定。

在大型项目中，Scope可以帮助团队成员快速定位变更的模块。例如在Angular项目中，常见的Scope包括：

animations, bazel, benchpress, common, compiler, compiler-cli, core, elements, forms, http, platform-browser, router, service-worker

Scope使用示例：

1# 指定影响范围
2git commit -m "feat(用户模块): 增加手机号快捷登录功能"
3
4git commit -m "fix(支付服务): 修复支付宝回调签名验证失败问题"
5
6# 影响多个范围
7git commit -m "feat(用户模块,订单模块): 增加统一的消息通知组件"

Summary：简短描述

Summary是对本次提交内容的一句话概括，需要遵循以下原则：

  • 长度限制：不超过50个字符，确保在Git日志中完整显示
  • 使用祈使句：英文使用现在时第一人称（如change而非changed或changes），中文使用“修复”、“新增”、“优化”等动词开头
  • 首字母无需大写（英文）
  • 结尾不加标点符号

Summary正确示例：

1# ✅ 正确的Summary
2git commit -m "feat: 新增用户积分排行榜功能"
3git commit -m "fix: 修复登录接口空指针异常"
4git commit -m "docs: 更新API接口文档参数说明"
5
6# ❌ 错误的Summary（超过50字符、使用过去时、结尾加句号）
7git commit -m "feat: 新增用户积分排行榜功能，包括积分计算规则和排名展示逻辑。"
8git commit -m "fix: Fixed login null pointer issue."

Body详解

Body是commit message的“正文”，用于详细描述本次提交的动机、内容和影响。它可以帮助团队成员和未来的维护者理解代码变更的背景。

Body的核心内容

Body应当清晰地回答以下三个核心问题：

  1. WHY（为什么）：本次提交要解决什么问题？这个问题的背景和影响是什么？
  2. HOW（怎么做）：采用了什么方法或策略来解决问题？
  3. OTHERS（其他影响）：本次提交是否包含其他变更？是否有副作用或需要注意的事项？

Body的格式规范

  • 每行长度控制在72个字符以内，保证在标准终端中阅读舒适
  • 不同段落之间使用空行分隔，提升可读性
  • 可以使用项目符号（-或*） 列出要点，与Markdown语法一致

Body使用示例：

 1git commit -m "fix(支付回调): 修复支付宝异步回调验签失败问题
 2
 3问题描述：
 4- 支付宝异步回调参数中包含特殊字符，导致签名验证失败
 5- 影响所有使用支付宝支付的订单，造成订单状态无法及时更新
 6
 7解决方案：
 8- 将参数解码方式从URLEncoder调整为RFC 3986标准
 9- 增加详细的验签日志，便于后续问题排查
10
11影响范围：
12- 仅影响支付宝支付回调处理逻辑，不涉及其他支付渠道
13- 已添加对应的单元测试用例覆盖该场景"

Footer详解

Footer是可选的提交信息部分，主要用于以下两种场景：

1. 不兼容变更（BREAKING CHANGE）

当提交包含破坏性变更时，需要使用BREAKING CHANGE标记，并说明变更内容、理由和迁移方法。

BREAKING CHANGE: <变更概述>
<空行>
<详细描述和迁移指南>

BREAKING CHANGE示例：

 1git commit -m "refactor(API): 重构用户认证接口
 2
 3将用户认证接口从Session方式迁移到JWT方式，提升系统可扩展性。
 4
 5BREAKING CHANGE: 
 6用户认证接口的请求和响应格式已变更
 7- 移除 /api/login 的session返回
 8- 新增 /api/auth/token 接口返回JWT令牌
 9- 所有需要认证的接口现在需要在Header中携带 Authorization: Bearer <token>
10
11迁移指南：
121. 前端应用需要修改登录逻辑，存储并管理JWT令牌
132. 所有API请求需要添加Authorization请求头
143. 旧版客户端需升级至v2.0.0及以上版本"

2. 关闭Issue

如果本次提交与某个issue或工单相关，可以在Footer中使用Closes或Fixes关键字自动关闭它。

Closes #123, #456
Fixes #789

关闭Issue示例：

1git commit -m "fix(订单): 修复订单金额计算精度丢失问题
2
3使用BigDecimal替代double进行金额计算，避免浮点数精度问题。
4
5Closes #1289"

Revert：回滚提交

当需要撤销某次提交时，使用revert类型的提交，并遵循特定格式：

revert: <被撤销提交的header>

This reverts commit <被撤销提交的完整hash值>.

Revert示例：

1git commit -m "revert: feat(用户): 新增用户积分功能
2
3This reverts commit 667ecc1654a317a13331b17617d973392f415f02."

规范的实践价值

1. 提升Git History可读性

规范的commit message让Git历史变得清晰有序。在GitHub或GitLab的提交列表页面，只需浏览每个提交的Header，就能快速了解项目演进脉络。

1# 查看简洁的提交历史
2git log --oneline
3
4# 输出示例：
5# abc1234 feat(用户): 增加手机号快捷登录
6# def5678 fix(支付): 修复支付宝回调验签失败
7# ghi9012 docs(API): 更新订单接口文档
8# jkl3456 perf(图片): 优化图片加载策略

2. 快速检索和过滤

通过git log --grep命令，可以快速筛选特定类型的提交：

1# 查找所有性能优化相关的提交
2git log HEAD --grep perf
3
4# 查找所有修复bug的提交
5git log HEAD --grep fix
6
7# 查找影响用户模块的所有提交
8git log HEAD --grep "feat(用户)"

3. 自动化生成Change Log

结合工具（如standard-version），可以根据规范的commit message自动生成版本发布日志：

 1## [1.2.0] - 2026-08-27
 2### Features
 3- 新增用户积分排行榜功能 (abc1234)
 4- 增加手机号快捷登录 (def5678)
 5
 6### Bug Fixes
 7- 修复支付宝回调验签失败问题 (ghi9012)
 8- 修复订单金额计算精度丢失 (jkl3456)
 9
10### Performance Improvements
11- 优化图片加载策略 (mno3456)

自动化辅助工具

Commitizen：交互式提交工具

Commitizen通过交互式问答引导开发者生成规范的commit message，降低学习成本。

安装：

1npm install -g commitizen

初始化项目：

1# 在项目根目录执行
2commitizen init cz-conventional-changelog --save --save-exact

使用：

1# 用 git cz 替代 git commit
2git cz

执行后，工具会依次提示选择type、填写scope、编写summary和body，最终生成符合规范的提交信息。

validate-commit-msg：自动校验工具

通过Git Hooks在提交时自动校验commit message格式，不符合规范的提交将被拒绝。

实施步骤：

  1. 在项目根目录创建validate-commit-msg.js文件，编写校验逻辑
  2. 在package.json中配置Git Hooks：
1{
2  "config": {
3    "ghooks": {
4      "commit-msg": "./validate-commit-msg.js"
5    }
6  }
7}
  1. 每次执行git commit时，脚本会自动检查commit message格式，不合格则报错并阻止提交。

最佳实践总结

  1. 坚持原子提交：每次提交只解决一个问题，只涉及一个功能模块
  2. Header必填且精简：type准确、scope明确、summary不超过50字符
  3. Body详细但有重点：回答WHY和HOW，控制每行72字符以内
  4. Footer按需使用：破坏性变更必须说明，关联issue及时关闭
  5. 善用自动化工具：通过Commitizen降低规范门槛，通过validate-commit-msg保证规范执行

完整示例：一次规范提交的全流程

场景描述

开发人员完成了一个新功能：在用户中心增加头像上传功能，支持裁剪和预览。

1. 编写规范的commit message

 1git commit -m "feat(用户中心): 新增头像上传及裁剪功能
 2
 3需求背景：
 4- 用户在个人设置页面需要上传自定义头像
 5- 要求支持图片裁剪和实时预览
 6
 7实现方案：
 8- 集成vue-cropper组件实现图片裁剪
 9- 使用HTML5 File API处理文件读取
10- 通过Canvas实现图片压缩，限制上传大小在2MB以内
11- 添加上传进度提示和错误处理
12
13技术细节：
14- 前端：Vue3 + Element Plus
15- 图片处理：cropper.js + canvas
16- 接口：POST /api/user/avatar
17
18测试情况：
19- 已测试jpg/png/webp格式图片上传
20- 已测试图片裁剪拖拽交互
21- 已测试网络异常时的错误提示
22
23Closes #567"

2. 查看提交历史

1git log --oneline -1
2
3# 输出：
4# a1b2c3d feat(用户中心): 新增头像上传及裁剪功能

3. 查看详细提交信息

1git log -1
2
3# 输出完整的提交信息，包含Header、空行、Body和Footer

结语

规范的Git提交信息是专业软件开发团队的基础设施之一。它不仅提升了代码历史的可读性和可维护性，还通过自动化工具的支持，为版本管理、发布流程和团队协作带来了实实在在的效率提升。

建议团队从今天开始逐步引入这些规范，借助Commitizen等工具降低实施成本，最终培养起良好的提交习惯。记住：规范的commit message不是负担，而是让团队协作更高效、项目维护更轻松的加速器。

发布在 ProjectManagement

发表评论