git-commit-message- 如何写好

commit message

git commit message 是我们经常要用到的东西,但是大部分人都写得很随便,翻 git log 看到的信息也是不明觉厉,这里结合其他资料阐述一下如何写好一个 commit message。

其实 git commit message 对于不同的项目有不同的要求。 比如 Angular 的 commit message
标题要加分类,比如是属于 refactor 还是 docs , 还有影响范围(例如 属于全部、*, 还是编译器 $compiler),但是在 Linux Kernel 和类似的 GNU style 的项目里面是类似这样的 commit header。

“mm, tracing: unify mm flags handling in tracepoints and printk”

如果没有子系统要求开头大写,如果有涉及的子系统就说明涉及的子系统并且跟上冒号做解释,冒号后的小写。这个根据具体的场景有不同的要求,但是核心就是简洁明了,另外要使用祈使句。

这样的好处,就能通过git log --pretty=format:%s来遍历所有的 log message,对于修改一目了然。

commit header

第一条规则因项目而异。
比如 Angular 的规则是:<type>(<scope>): <subject>

type(必需),scope(可选)和 subject(必需)

angular 要求的 type 有几种

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

scope 表示影响的范围,subject 开头小写,使用祈使句,结尾不用。号。

但是在 runc 里面要求比较简单,使用祈使句,并且开头大写就可以,结尾不带。号。

kernel 的 subject 如果带上子系统比如 (mm),就要 mm: 开头,然后不用大写。
不然也要开头大写。总之 subject 的部分要求根据项目不同有一些不同,但是 body 部分要求是类似的。

commit body

body 要和 header 空格一行,每行不要超过 72 个字符,并且对改动进行解释。

例如:

1
2
3
4
5
6
7
8
9
在 50 个字符内概括你的改动标题

更详细的解释,限制到 72 个字符,和标题隔开一行。
有什么副作用或者后遗症也要指出。

如果有任务管理器,可以在结尾指定。

Resolves: #123
See also: #456, #789

例子

Angular

1
2
3
4
5
6
7
8
fix($compile): couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #392
Breaks foo.bar api, foo.baz should be used instead

GNU style

1
2
3
4
5
6
7
8
9
10
Author: Aleksa Sarai <asarai@suse.de>
Date: Sun Mar 13 04:53:20 2016 +1100

libcontainer: add pids.max to PidsStats

In order to allow nice usage statistics (in terms of percentages and
other such data), add the value of pids.max to the PidsStats struct
returned from the pids cgroup controller.

Signed-off-by: Aleksa Sarai <asarai@suse.de>

或者

1
2
3
4
5
6
7
8
9
10
11
12
13
Author: Alexander Morozov <lk4d4@docker.com>
Date: Fri Mar 27 10:50:32 2015 -0700

Use syscall.Kill instead of p.cmd.Process.Kill

We need this to unmask syscall.ESRCH error, which handled in docker and
can be handled by other clients.

Closes #457

Signed-off-by: Alexander Morozov <lk4d4@docker.com>
Acked-by: Hugh Dickins <hughd@google.com>
Reviewed-by: Michal Hocko <mhocko@suse.com>

在进行 code review 的时候,一般会带上签名 Signed-off-by 表示自己对这段改动负责,matainer 也会查看这段代码如果理解这段代码并且进行了测试同样对这段代码负责也要签名,如果只是保证自己觉得代码无误要使用 Reviewed-by,如果表示只是知道这个带动就带上Acked-bygit commit -s 可以自动带上 Signed-off-by

总之,一个好的 commit message 是一个好习惯,如果项目从一开始打 commit message 就很随便,那 commit log 的意义就没有了,导致根本没人会看。如果有意义整个代码就有据可查了,看起来也很漂亮。

参考:

  1. Commit message 和 Change log 编写指南
  2. Submitting patches: the essential guide to getting your code into the kernel