1. 前言

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

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

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

2. 提交

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

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

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

3. 格式

标题

描述

标记
1
2
3
4
5

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

3.1. 标题

参考格式：

模块：总结
1

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

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

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

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

3.2. 描述

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

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

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

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

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

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

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 ..
...
1
2
3
4
5

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

4. 后语

完整的参考格式如下：

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

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

标记（Signed-off-by，Reviewed-by等）
1
2
3
4
5