人们应该试着把内核的 Git 提交日志和其他一些项目比较一下，然后哭着入睡。

– Linus Torvalds（林纳斯·托瓦兹）

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

每个项目都坚持用一套不同的东西：

• 约定式提交（Conventional Commits）
• 问题/解决方案格式
• Gitmoji
• Linux 内核中错综复杂的 trailer（提交尾注）

但 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. Trailer（提交尾注）——标准格式，与正文之间空一行。

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

对于主题行，指导很简单：

# 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 trailer。

错综复杂的 Git trailer

我的模板中有一个部分，存放我所参与的项目使用的 trailer。

#     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]>

这些 trailer 是很有用的文档线索。Git 可以用标准命令解析它们。

例如，如果我想要一个以制表符分隔的提交及其相关任务列表，我可以用 git log 查找 Bug trailer：

$ 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 提交模板让你不必再费脑子记住该写什么，从而专注于你需要讲述的故事。

把大脑留给它真正擅长的事情吧。