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 中还有许多其他上下文,其中主题行和正文之间的区别从中间的空白行引入,如果没有空白行,它们都不能正常工作。
50 个字符不是硬性限制,只是一个经验法则。将主题行保持在这个长度可确保它们可读,并迫使作者思考片刻以最简洁的方式来解释正在发生的事情。
提示:如果难以总结,你可能一次提交了太多更改。争取原子提交(一个单独的帖子的主题)。
GitHub 的 UI 完全了解这些约定。如果超过 50 个字符的限制,它会警告您:
并且会用省略号截断任何超过 72 个字符的主题行:
所有主题行都以大写字母开头。
例如:
代替:
主题行中不需要尾随标点符号。此外,保持在50 个字符或更少
例子:
代替:
祈使语气的意思是“像发出命令或指示一样的口头或书面”。几个例子:
命令听起来有点粗鲁。但它非常适合 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 自己的内置约定。例如:
Git 从不自动换行。当提交消息的正文时,必须注意其右边距,并手动换行。
建议以 72 个字符执行此操作,以便 Git 有足够的空间来缩进文本,同时仍将所有内容保持在 80 个字符以下。
配置一个好的文本编辑器比如 Vim 很重要,例如,在编写 Git 提交时将文本换行为 72 个字符。然而,传统上,IDE 在为提交消息中的文本换行提供智能支持方面一直很糟糕。
来自 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.
看看完整的差异,想想作者花时间在此时此地提供这个上下文,为其他和未来的提交者节省了多少时间。如果他不这样做,它可能会永远丢失。
在大多数情况下,可以省略有关如何进行更改的详细信息。在这方面,代码通常是不言自明的(如果代码太复杂以至于需要用散文来解释,这就是源注释的用途)。只需专注于首先弄清楚进行更改的原因 - 更改之前的工作方式(以及其中的问题),它们现在的工作方式,以及为什么决定以你的方式解决它.
感谢你的未来维护者可能就是你自己!
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。