如何编写 Git 提交消息

如何编写 Git 提交消息

优秀 Git 提交消息的七个规则

1. 用空行将主体与主体分开
2. 将主题行限制为 50 个字符
3. 将主题行大写
4. 不要以句点结束主题行
5. 在主题行中使用祈使语气
6. 将正文限制在 72 个字符
7. 用正文来解释what，why，how

1. 用空行分隔主体和主体

git commit 手册页这样写道：

虽然不是必需的，但最好以一个简短（少于 50 个字符）行开始提交消息，总结更改，然后是一个空行，然后是更全面的描述。提交消息中直到第一个空白行的文本被视为提交标题，并且该标题在整个 Git 中使用。例如，Git-format-patch(1) 将提交转换为电子邮件，包括主题行中的标题和正文中的其余提交。

首先，并不是每个提交都需要一个主题和一个主体。有时单行就可以了，尤其是当更改非常简单以至于不需要进一步的上下文时。例如：

Fix typo in introduction to user guide

如果读者想知道错字是什么，简单地看一下更改本身，即使用git show或者git diff或git log -p。

如果提交类似这样的内容，则可以使用以下-m选项git commit：

$ git commit -m"Fix typo in introduction to user guide"

但是，当提交需要一些解释和上下文时，那么需要编写一个正文。例如：

Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

-m使用该选项编写带有正文的提交消息并不容易。最好在适当的文本编辑器中编写消息。如果还没有在命令行中设置与 Git 一起使用的编辑器，请阅读Pro Git 的这一部分。

https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration

在浏览日志时，看到主体与主体的分离是有意义的。这是完整的日志条目：

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

现在git log --oneline，它只打印出主题行：

$ git log --oneline
42e769 Derezz the master control program

或者，git shortlog按用户提交的分组，再次显示简洁的主题行：

$ git shortlog
Kevin Flynn (1):
      Derezz the master control program

Alan Bradley (1):
      Introduce security program "Tron"

Ed Dillinger (3):
      Rename chess program to "MCP"
      Modify chess program
      Upgrade chess program

Walter Gibbs (1):
      Introduce protoype chess program

Git 中还有许多其他上下文，其中主题行和正文之间的区别从中间的空白行引入，如果没有空白行，它们都不能正常工作。

2. 主题行限制为 50 个字符

50 个字符不是硬性限制，只是一个经验法则。将主题行保持在这个长度可确保它们可读，并迫使作者思考片刻以最简洁的方式来解释正在发生的事情。

提示：如果难以总结，你可能一次提交了太多更改。争取原子提交（一个单独的帖子的主题）。

GitHub 的 UI 完全了解这些约定。如果超过 50 个字符的限制，它会警告您：

如何编写 Git 提交消息

并且会用省略号截断任何超过 72 个字符的主题行：

如何编写 Git 提交消息

3. 主题行大写

所有主题行都以大写字母开头。

例如：

• Accelerate to 88 miles per hour

代替：

• accelerate to 88 miles per hour

4. 不要以句号结束主题行

主题行中不需要尾随标点符号。此外，保持在50 个字符或更少

例子：

• Open the pod bay doors

代替：

• Open the pod bay doors.

5. 在主题行中使用祈使语气

祈使语气的意思是“像发出命令或指示一样的口头或书面”。几个例子：

• Clean your room
• Close the door
• Take out the trash

命令听起来有点粗鲁。但它非常适合 Git 提交主题行。原因之一是Git 本身在代表您创建提交时使用命令式。

例如，使用时创建的默认消息git merge为：

Merge branch 'myfeature'

使用时git revert：

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

或者在 GitHub 拉取请求上单击“合并”按钮时：

Merge pull request #123 from someuser/somebranch

因此，当以命令式编写提交消息时，你遵循的是 Git 自己的内置约定。例如：

• Refactor subsystem X for readability
• Update getting started documentation
• Remove deprecated methods
• Release version 1.0.0

• 此提交将refactor subsystem X for readability、重构子系统 X 以提高可读性
• 此提交将update getting started documentation、更新入门文档
• 此提交将remove deprecated methods、删除不推荐使用的方法
• 此提交将release version 1.0.0、发布版本 1.0.0
• 此提交将merge pull request #123 from user/branch、合并来自用户/分支的拉取请求 #123

6. 将正文包裹在 72 个字符处

Git 从不自动换行。当提交消息的正文时，必须注意其右边距，并手动换行。

建议以 72 个字符执行此操作，以便 Git 有足够的空间来缩进文本，同时仍将所有内容保持在 80 个字符以下。

配置一个好的文本编辑器比如 Vim 很重要，例如，在编写 Git 提交时将文本换行为 72 个字符。然而，传统上，IDE 在为提交消息中的文本换行提供智能支持方面一直很糟糕。

7. 用正文来解释什么和为什么与如何

来自 Bitcoin Core的这个提交是一个很好的例子，可以解释发生了什么变化以及为什么：

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

看看完整的差异，想想作者花时间在此时此地提供这个上下文，为其他和未来的提交者节省了多少时间。如果他不这样做，它可能会永远丢失。

在大多数情况下，可以省略有关如何进行更改的详细信息。在这方面，代码通常是不言自明的（如果代码太复杂以至于需要用散文来解释，这就是源注释的用途）。只需专注于首先弄清楚进行更改的原因 - 更改之前的工作方式（以及其中的问题），它们现在的工作方式，以及为什么决定以你的方式解决它.

感谢你的未来维护者可能就是你自己！