Git Commit Message Style Guide

2019-04-20 Engineering

在 Git 中，我们使用 git commit -m "xxx" 来提交代码，参数 -m 用来指定 Commit Message（提交说明），直接执行 git commit 会进入编辑器模式，可提交多行说明。Commit Message 应规范化，规范化的 Commit Message 能带来很多好处：

1
2
* 提交说明明确，方便快速浏览和查找，比如 git log --pretty=format:%s, git log HEAD --grep feature
* 可以直接从 Commit Message 生成 Change Log

目前，社区中有很多 Commit Message 规范，本文介绍 Conventional Commits 规范，因其合理、系统，且有配套工具，在社区中得到来广泛的应用。

Conventional Commits 提交规范

Conventional Commits 中将 Commit message 分为三个部分：Header，Body 和 Footer。

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

其中，Header 是必需的，Body 和 Footer 可选。<BLANK LINE> 指空行，各个部分必须由空行分割。为了避免自动换行影响美观，不管是哪一个部分，任何一行都不得超过 72 个字符（或 100 个字符）。

1
docs(changelog): update changelog to beta.5
1
2
3
4
5
6
7
fix(ivy): prevent templateOverrides from causing infinite loop (#29402)

Previously, the transitive scope calculation could lead into re-compiling
the same module multiple times. This fix ensures we cannot get into this loop.
It should be fixed more completely (e.g. more cases) once FW-1178 is resolved.

PR Close #29402

注：Angular commit message guidelines 采用同样的提交规范。

Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和 subject（必需）。

  • type

type 用于说明 Commit 的类别，只允许使用下面 9 个标识。

1
2
3
4
5
6
7
8
9
10
11
* feat       # 新功能（Feature）
* fix        # 修复 Bug
* perf      # 性能（提高性能的代码更改，比如，提升性能、体验）
* refactor   # 重构（即不是新增功能，也不是修改 bug 的代码变动）
* style      # 格式（不影响代码运行的变动，比如：空白、换行、分号等）
* build      # 构建过程或辅助工具的变动。影响构建系统或外部依赖关系的更改（比如：Gulp、Broccoli、NPM）
* chore      # 其他修改，比如改变构建流程，或增加依赖库、工具等
* ci         # 持续集成相关修改（对 CI 配置文件和脚本的更改，比如：k8s、docker）
* docs       # 文档（Documentation，比如 Readme、Changelog、Contribute 等等）
* test       # 测试（增加测试或更正现有测试）
* revert     # 回滚（回滚到某一个版本，带上版本号）

如果 type 为 feat 和 fix，则该 Commit 将肯定出现在 Change Log 之中。其他情况（docs、chore、style、refactor、test）建议不要放入 Change Log。

  • scope

scope 用于说明 Commit 影响的范围，比如框架中的数据层、控制层、视图层，或业务中某个业务模块，视具体项目的不同而不同，比如：user 用户、pay 支付、product 产品、article 文章、core 核心、router 路由、api 接口、doc 文档…

  • subject

subject 是 Commit 目的的简短描述，不超过 50 个字符。

1
2
3
* 以动词开头，使用第一人称现在时，比如 change，而不是 changed 或 changes
* 第一个字母小写
* 结尾不加句号（.）

常用表述语有：add、change、update、remove、delete。

Body

Body 部分是对本次 Commit 的详细描述，可以分成多行。有两个注意点：

1
2
* 使用第一人称现在时，比如使用 change 而不是 changed 或 changes
* 应该说明代码变动的动机，以及与以前行为的对比

Footer 部分只用于两种情况。

  • 不兼容变动

如果当前代码与上一个版本不兼容，则 Footer 部分以 BREAKING CHANGE 开头，后面是对变动的描述、以及变动理由和迁移方法。

1
2
BREAKING CHANGE: isolate scope bindings definition has changed.
...
  • 关闭 Issue 或 Pull requests

在开源的项目中，如果当前 commit 针对某个 issue 或 pr，那么可以在 Footer 部分关闭这个 issue 或 pr。例如：

1
2
Fixes #21388
PR Closes #234

常用的表述语有 sclose、fix、resolve。

Revert

还有一种特殊情况，如果当前 Commit 用于撤销以前的 Commit，则必须以 revert: 开头，后面跟着被撤销 Commit 的 Header。

1
2
3
revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body 部分的格式是固定的，必须写成 This reverts commit .，其中的 Hash 是被撤销 Commit 的 SHA 标识符。

如果当前 Commit 与被撤销的 Commit 在同一个发布（Release）里面，那么它们都不会出现在 Change Log 里面。如果两者在不同的发布，那么当前 Commit，会出现在 Change Log 的 Reverts 小标题下面。

为 git commit 添加表情

为 commit message 添加 Emoji 不仅有趣，也可表达当前提交的类型。Emoji CLDR Short Name 被 GitHub (emoji-cheat-sheet github-emoji-api)、Gitlab、GitBucket 所支持，提交信息中可通过短名的方式使用。

1
git commit -m ':apple: i have a apple'

Git 中常用的 Emoji CLDR Short Name 列表如下：

Emoji Emoji 代码 Commit 说明
:tada: (庆祝) :tada: 初次提交
:sparkles: (火花) :sparkles: 引入新功能
:bug: (虫子) :bug: 修复 bug
:lipstick: (口红) :lipstick: 更新 UI 和样式文件
:art: (调色板) :art: 改进代码结构/代码格式
:hammer: (锤子) :hammer: 重大重构
:zap: (闪电)
:racehorse: (赛马)		 :zap:
:racehorse:		 提升性能
:fire: (火焰) :fire: 移除代码或文件
:wrench: (扳手) :wrench: 修改配置文件
:construction_worker: (工人) :construction_worker: 添加 CI 构建系统
:green_heart: (绿心) :green_heart: 修复 CI 构建问题
:heavy_minus_sign: (减号) :heavy_minus_sign: 减少一个依赖
:heavy_plus_sign: (加号) :heavy_plus_sign: 增加一个依赖
:ambulance: (急救车) :ambulance: 重要补丁
:rotating_light: (警车灯) :rotating_light: 移除 linter 警告
:memo: (备忘录) :memo: 撰写文档
:rocket: (火箭) :rocket: 部署功能
:white_check_mark: (白色复选框) :white_check_mark: 增加测试
:lock: (锁) :lock: 修复安全问题
:globe_with_meridians: (地球) :globe_with_meridians: 国际化与本地化
:apple: (苹果) :apple: 修复 macOS 下的问题
:penguin: (企鹅) :penguin: 修复 Linux 下的问题
:checkered_flag: (旗帜) :checked_flag: 修复 Windows 下的问题
:bookmark: (书签) :bookmark: 发行/版本标签
:construction: (施工) :construction: 工作进行中
:arrow_down: (下降箭头) :arrow_down: 降级依赖
:arrow_up: (上升箭头) :arrow_up: 升级依赖
:chart_with_upwards_trend: (上升趋势图) :chart_with_upwards_trend: 添加分析或跟踪代码
:whale: (鲸鱼) :whale: Docker 相关工作
:pencil2: (铅笔) :pencil2: 修复 typo

Emoji 还可对单个 commit type 再次进行细分，比如 feat 下 :tada: feat 表示初始化项目，:sparkles: feat 引入新功能（默认），:lipstick: feat 修改样式。

这套 Emoji 规范的使用，需要配合编辑器插件、Git Commit 交互式工具（比如 gitmoji）或着 Git Commit Template，否则一个个查找难以使用。

注：除了使用 Emoji 短名，也可以直接在 commit message 中使用 Emoji code，VSCode 中可通过 git-commit-plugin 插件（但是这个插件所使用的 Emoji 语义与上面通用的不一致）。

设置 Commit Message Template

通过设置全局 .gitconfig 来指定 Commit Message 模板。

1
git config --global commit.template C:/Users/CCH/commit-template
1
2
3
4
5
<:tada: :sparkles: :lipstick: feat | :bug: :ambulance: fix | :hammer: refactor | :zap: :racehorse: perf | :art: style | :memo: docs | :wrench: ci | :wrench: :heavy_plus_sign: :heavy_minus_sign: chore>: <subject>

<body>

<footer>

TortoiseGit 中可通过依次点击 settings -> Git -> Edit global .gitconfig，然后编辑这个全局 .gitconfig 文件，在其末尾加入 commit 字段配置。

1
2
3
4
5
6
7
8
9
[user]
    email = xxxxxx@qq.com
    name = Tracy
[winUpdater]
    recentlySeenVersion = 2.17.0.windows.1
[credential]
    helper = manager
[commit]
  template = d:/commit-template