作为代码狗程序员,每天肯定离不开各种 pull / push/ commit / add,离不开填写 Commit message。

对于如何写 Commit message 我也一度十分纠结。

  • 今天新增了好几个功能,是要下班时候一起提交还是每开发完一个功能做一次提交呢?一起提交的话 message 要怎么写呢?
  • 直接用中文来写吗?好像怪傻*的。用英文又怕词不达意
  • 大家写的 message 乱七八糟的看起来好丑……

于是经历了十分漫长的乱写历程,最近因为团队对 Commit message 的规范化,我也终于规范了自己的书写格式。

下面这篇文章就来聊一聊曾经我写的奇怪 Commit message、Commit message 的规范写法以及为何需要规范化。

好了,开始吧,从纪念奇奇怪怪的 Commit message 开始。

奇怪的写法

没有写法

最奇怪的写法就是没有写法(认真脸)。

提交的时候想到什么就写什么,曾经甚至为了装逼狂甩英文,当然甩了一段时间后就甩不下去了……

这种没有写法的最大缺点就是:整个团队的 Commit message 记录真的很丑……

我曾经看到有(前)同事在 Commit Message 里面直接填写一个句号或逗号提交。

如果没有明确的规范,大家为了省事真的什么 message 都写得出来。

寻找规范

开始写自己的项目后充分认识到了自己强迫症的本质。为了满足自己 Commit message 强迫症,开始寻找规范。

下面是我找到的其中一种规范:

[scope]message

scope 如下:

  • feat(feature)
  • fix(bug fix)
  • hotfix(workaround)
  • docs(documentation)
  • style(formatting)
  • refactor
  • test(when adding missing tests)
  • chore(maintain)
  • improve(improvement, e.g. enhanced feature)

当时也践行了一段时间,我上个月应该还是这样写的。

规范化后确实好看了很多,缺点的话我们一起看看 Angular 规范后就知道了。

该怎么写

这里以 Angular 规范 举例,也是我现在团队在用的规范。

格式

共包含三个部分:

  • Header(必须)
  • Body(可省略)
  • Footer(可省略)
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

Header 仅有一行,包含三个字段:

  • type(必需):用于说明 commit 的类别
  • scope(可选):用于说明 commit 影响的范围
  • subject(必需):commit 目的的简短描述

其中 type 只允许使用下面 7 个标识:

  • feat:新功能(feature)
  • fix:修补bug
  • docs:文档(documentation)
  • style: 格式(不影响代码运行的变动)
  • refactor:重构(即不是新增功能,也不是修改bug的代码变动)
  • test:增加测试
  • chore:构建过程或辅助工具的变动

Body

Body 是对本次 commit 的详细描述,可分成多行。

要注意:应该说明代码变动的动机,以及与以前行为的对比。

该部分用于两种情况:

  1. 不兼容的变动:与上一个版本不兼容,则 Footer 部分以 BREAKING CHANGE 开头
  2. 关闭 Issue:commit 针对某个 issue,在 Footer 中可以写上 Closes #123

特殊情况 Revert

有一种特殊情况,如果当前 commit 用于撤销以前的 commit:

  • 必须以 revert: 开头,后面跟着被撤销 Commit 的 Header
  • Body部分的格式是固定的,必须写成 This reverts commit &lt;hash>.
    • hash 为被撤销 commit 的 SHA 标识符

例如:

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

使用新规范后我的 commit 如下:

为什么这么写

看完上述规范后你可能觉得太麻烦了,commit 的时候随随便便提交一条信息不就好了,为什么要这么麻烦呢?格式化、规范化的 Commit message 究竟有什么用呢?

方便浏览

当然是为了好看了。

只看标识符就可以明白提交的目的相当舒服。

$ git log HEAD --pretty=format:%s

doc(README):更新图标,整理格式
refactor(auth):修改签名算法为 hmac-sh1
feat(auth):签名算法
refactor(account):修改变量获取方法
refactor(auth):改为从数据库获取鉴权信息
feat(config):增加 auth 加密信息配置
doc(auth):修改鉴权算法说明
doc(auth):鉴权算法定义
feat(account):发送邮件验证码

便于快速查找

例如只想找新增功能,可以这样:

$ git log HEAD --grep feat

commit 164b5f8245dff63a18360aa8434aa7066e305eb8
Author: JalanJiang <448300947@qq.com>
Date: Sat Apr 20 22:40:17 2019 +0800

feat(auth):签名算法

commit 96e3059f1f76bdd6e756786677412d06473ecdd7
Author: JalanJiang <448300947@qq.com>
Date: Fri Apr 19 23:13:01 2019 +0800

feat(config):增加 auth 加密信息配置

commit 19ca524ac438742e0c327a3b0586670db587979a
Author: JalanJiang <448300947@qq.com>
Date: Wed Apr 17 21:58:40 2019 +0800

feat(account):发送邮件验证码

生成 Change log

可以借助 conventional-changelog 来完成,在这里不多做赘述了。

总结

  • 规范没有绝对的好坏,只要适合团队和个人就行
  • 好的习惯尽早养成,受益终身

参考资料