人们应该拿内核的 Git 日志质量和其他项目比一比，然后哭着入睡。

—— Linus Torvalds

我永远记不住你们项目的提交规范。

每个项目的要求都不一样：

• 约定式提交
• 问题/解决方案格式
• Gitmoji
• 错综复杂的 Linux 内核中的 trailers

不过，Git 提交模板能帮上忙。提交模板为提交信息提供了脚手架，把说明文档放在你最需要的地方——在你编写提交信息的编辑器里。

什么是 Git 提交模板？

当你输入 git commit 时，Git 会打开你的文本编辑器¹。Git 可以用提交模板预先填充编辑器——就像一份待填写的表单。

创建提交模板很简单。

• 创建一个纯文本文件——我的文件放在 ~/.config/git/message.txt
• 告诉 Git 使用它：

git config --global \
    commit.template '~/.config/git/message.txt'

我的默认模板汇集了我对编写提交信息的所有心得。

用 IncludeIf 实现按项目区分的模板

提交模板真正的妙处在于，你可以为每个项目使用不同的模板。

通过 Git 的 includeIf 配置项，不同的项目就可以使用不同的模板。²

像 Linux 内核、Git 和 MediaWiki 这样的大型项目，都有各自的提交规范。

为了处理 Wikimedia 相关的工作，我把 Git 仓库放在 ~/Projects/Wikimedia 目录下，并在全局 Git 配置文件（~/.config/git/config）的末尾添加了如下配置：

[includeIf "gitdir:~/Projects/Wikimedia/**"]
    path = ~/.config/git/config.wikimedia

在 config.wikimedia 中，我指向了 Wikimedia 专用的提交模板。我还在其中覆盖了其他 Git 配置，例如 user.email 或 core.hooksPath。

示例：我的全局模板

我的默认提交模板包含三个部分：

1. 标题——50 个字符以内，首字母大写，末尾不加标点。
2. 正文——每行在 72 个字符处换行，与标题之间用空行分隔。
3. Trailers——采用标准格式，与正文之间用空行分隔。

在每个部分，我都为格式和内容添加了提示。³

对于标题部分，提示很简洁：

# 50ch. wide ----------------------------- SUBJECT
#                                                |
#     "If applied, this commit will..."          |
#                                                |
#     Change / Add / Fix                         |
#     Remove / Update / Document                 |
#                                                |
# ------- ↓ LEAVE BLANK LINE ↓ ---------- /SUBJECT

对于正文部分，我提醒自己回答几个基本问题：

# 72ch. wide ------------------------------------------------------ BODY
#                                                                      |
#     - Why should this change be made?                                |
#       - What problem are you solving?                                |
#       - Why this solution?                                           |
#     - What's wrong with the current code?                            |
#     - Are there other ways to do it?                                 |
#     - How can the reviewer confirm it works?                         |
#                                                                      |

就这些了，除去 Git trailers 部分。

Git trailers 的曲折迷宫

我的模板中有一节是为我参与的项目所使用的 trailers 准备的。

#     TRAILERS                                                         |
#     --------                                                         |
#     (optional) Uncomment as needed.                                  |
#     Leave a blank line before the trailers.                          |
#                                                                      |
# Bug: #xxxx
# Acked-by: Example User <[email protected]>
# Cc: Example User <[email protected]>
# Co-Authored-by: Example User <[email protected]>
# Requested-by: Example User <[email protected]>
# Reported-by: Example User <[email protected]>
# Reviewed-by: Example User <[email protected]>
# Suggested-by: Example User <[email protected]>
# Tested-by: Example User <[email protected]>
# Thanks: Example User <[email protected]>

这些 trailers 是有用的文档线索，Git 可以通过标准命令来解析它们。

例如，如果我想得到一份以制表符分隔的提交及其关联任务的列表，就可以用 git log 来查找 Bug trailers：

$ TAB=%x09
$ BUG_TRAILER='%(trailers:key=Bug,valueonly=true,separator=%x2C )'
$ SHORT_HASH=%h
$ SUBJ=%s
$ FORMAT="${SHORT_HASH}${TAB}${BUG_TRAILER}${TAB}${SUBJ}"
$ git log --topo-order --no-merges \
      --format="$FORMAT"
d2b09deb12f     T359762 Rewrite Kurdish (ku) Latin to Arabic converter
28123a6a262     T332865 tests: Remove non-static fallback in HookRunnerTestBase
4e919a307a4     T328919 tests: Remove unused argument from data provider in PageUpdaterTest
bedd0f685f9             objectcache: Improve `RESTBagOStuff::handleError()`
2182a0c4490     T393219 tests: Remove two data provider in RestStructureTest

别再死记提交信息规范了

Git 提交模板让你无需再记忆该写什么，从而可以专注于讲述你需要传达的故事。

把脑力留给它更擅长的事情吧。