更多互联网精彩资讯、工作效率提升关注【飞鱼在浪屿】（日更新）

提交消息很重要。以下是如何写好它们

简介：为什么提交信息很重要

浏览Git 存储库的日志，你可能会发现提交消息或多或少是一团糟。

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing

与来自同一存储库的这些更新的提交进行比较，你更愿意读哪个？

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage

前者的长度和形式各不相同；后者简洁一致。

虽然许多存储库的日志看起来像前者，但也有例外。Linux 内核和Git 本身就是很好的例子。查看Spring Boot或Tim Pope管理的任何存储库。

这些存储库的贡献者知道，精心设计的 Git 提交消息是向其他开发人员（以及他们未来的自己）传达有关更改的上下文的最佳方式。差异会告诉发生了什么变化，但只有提交消息才能正确地告诉原因。Peter Hutterer很好地说明了这一点：

重新建立一段代码的上下文是一种浪费。我们不能完全避免它，所以我们应该努力[尽可能地]减少它。提交消息可以做到这一点，因此，提交消息显示开发人员是否是一个好的合作者。

如果没有过多考虑什么是出色的 Git 提交消息，那么可能没有花太多时间使用git log相关工具。这里有一个恶性循环：因为提交历史是非结构化的和不一致的，人们不会花太多时间使用或照顾它。而且因为它没有被使用，它仍然是非结构化和不一致的。

git blame, revert, rebase, log,shortlog和其他子命令审查其他人的提交和拉取请求成为值得做的事情，一个项目的长期成功取决于它的可维护性。

这篇文章将讨论提交的最基本要素：如何编写单独的提交消息。

大多数编程语言对于什么构成惯用风格（即命名、格式等）都有完善的约定。团队处理提交日志的方法没有什么不同。创建有用的修订历史记录，团队应首先就提交消息约定达成一致，该约定至少定义以下三件事：

风格。标记语法、换行边距、语法、大写、标点符号。

内容。提交消息的正文应该包含什么样的信息？它不应该包含什么？

元数据。应该如何引用问题跟踪 ID、拉取请求编号等？

幸运的是，Git 提交消息有一些成熟的约定。许多都是以某些 Git 命令的功能假设的。无需重新发明任何东西。只需遵循以下七条规则，就可以像专业人士一样。

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

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

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

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

git commit 手册页这样写道：

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

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

Fix typo in introduction to user guide

如果读者想知道错字是什么，简单地看一下更改本身，即使用git showorgit 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 <[email protected]>
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 个字符的限制，它会警告您：

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

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

以这种方式编写一开始可能会有些尴尬。我们更习惯于用指示性语气说话，这都是关于报告事实的。这就是为什么提交消息通常最终会变成这样：

• Fixed bug with Y
• Changing behavior of X

有时提交消息会被写成对其内容的描述：

• More fixes for broken stuff
• Sweet new API methods

为了消除任何混淆，这里有一个简单的规则，每次都能正确处理。

格式正确的 Git 提交主题行应该始终能够完成以下句子：

• 如果应用，此提交将在此处显示您的主题行

例如：

• 如果应用，此提交将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

请注意，这对于其他非命令形式如何不起作用：

• 如果应用，此提交将fixed bug with Y、使用 Y 修复错误
• 如果应用，此提交将changing behavior of X、改变 X 的行为
• 如果应用，此提交将对more fixes for broken stuff、损坏的内容进行更多修复
• 如果应用，此提交将提供sweet new API methods、新的 API 方法

请记住：祈使句的使用仅在主题行中。在写body的时候可以放宽这个限制。

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

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

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

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

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

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

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <[email protected]>
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.

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

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

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