git 知：提交格式

1. 前言

git 是一个分布式版本控制系统，它可以用来记录一个或若干个文件内容的变化，以便将来查阅特定版本的修订情况。

为了便于追溯，那么每次的变化就需要做好记录，不然到时候再看，可能就不明其意了。

本文所讲的提交格式，实际上就是对每次记录所做的规范说明，按照所说的格式书写，将便于以后维护。

2. 提交

有过 git 使用经历的读者应该都知道，命令git commit可以完成一次修改的提交，执行命令后，将会启动一个文本编辑器用于输入提交说明，如下所示：

可以看到，默认的提交消息包含最后一次运行 git status 的输出，放在注释行里，另外开头还有一个空行，供你输入提交说明。

那么提交说明该怎么写呢？下面将提供关于提交说明的书写格式，读者可以按需参考。

3. 格式

标题

描述

标记

每行不超过75字符（网页链接、Fixes字段例外）

3.1. 标题

参考格式：

模块：总结

要求：
1）模块：标识修改的内容所属的模块/子系统/单元等，相当于分门别类。
2）总结：用一行描述提交的作用，是对修改内容的一个简明扼要的总结。
总结中建议采用动宾结构，如：fix xxx，add yyy …

作用：
对于没有其它上下文的情况下，读者通过标题中的描述也可以了解本次修改的内容。

同时，这个标题也将成为git format-patch命令生成的补丁文件的名字。

举例：
下面是 glibc 仓库中的提交信息

3.2. 描述

详细描述本次修改，可以采用三段式描述方法，即：

• what：当前存在什么问题？描述问题现象，如有必要，可以贴上问题的现场日志/数据等。
• why：为什么会出现该问题？分析出现该问题的原因。
• how：如何解决该问题？阐述解决该问题的原理/方法等。

1）如果需要在描述引用其它提交信息，参考格式为：

Commit 12个字符或以上的commit号 ("标题")

2）如果是修复 bug 的提交，需要在描述中提供引入 bug 的提交信息，参考格式为：

Fixes: 12个字符或以上的commit号 ("标题")

3）如果是 revert 某次提交，需要在描述中保留 revert 信息，一般使用git revert命令完成。

4）如果是 cherry-pick 自其它分支的提交，需要在描述中保留 cherry-pick 字段，一般使用git cherry-pick -x命令完成。

举例：
下面是 glibc 仓库中的提交信息

3.3. 标记

标记主要是指对提交的签名信息，比如：Signed-off-by，Reviewed-by等。

其中 Signed-off-by: 字段可以通过对一些命令传递 -s 选项而自动添加，比如：

git commit -s ..
git cherry-pick -s ..
git revert -s ..
git am -s ..
...

举例：
下面是 glibc 仓库中的提交信息

4. 后语

完整的参考格式如下：

模块/子系统/单元：简明扼要的一句话总结修改内容

详细描述（包括问题现象、问题原因、解决方法等）

标记（Signed-off-by，Reviewed-by等）