Git Commit Messages：50/72格式化

Question

Tim Pope在他的博客文章中争论了一个特定的git commit消息风格： http://www.tpope.net/node/106

以下是他推荐的内容的快速摘要：

• 第一行不超过50个字符
• 然后是一个空行
• 剩余文字应包含72个字符

他的博客文章给出了这些建议的基本原理（为简洁起见，我称之为“50/72格式化”）：

• 在实践中，有些工具会将第一行视为主题行，将第二段视为正文（类似于电子邮件）
• git log不处理包装，因此如果行太长则很难读取。
• git format-patch --stdout将提交转换为电子邮件 - 所以如果您的提交已经很好地包装，那么它就会很有用。
• 我想补充一点，我认为Tim会同意：总结你的提交的行为在任何版本控制系统中都是一个很好的做法。它可以帮助其他人（或稍后的人）更快地找到相关提交。

所以，我的问题有几个部分：

• git的'思想领袖'或'有经验的用户'有多少（大致）拥抱50/72格式化风格？我问这个问题是因为有时候新用户不知道或者不关心社区实践。
• 对于那些不使用此格式的用户，是否有使用不同格式样式的原因？ （请注意，我正在寻找关于优点的论据，而不是“我从未听说过”或“我不在乎。”）
• 从经验上讲，git存储库中有多少百分比采用这种风格？ （如果有人想对GitHub存储库进行分析......提示，提示。）

我的观点是不推荐50/72风格或拍摄其他风格。 （关于它，我更喜欢它，但我对其他想法持开放态度。）我只是想了解为什么人们喜欢或反对各种git提交消息样式的理由。 （请随意提出尚未提及的要点。）

Answer 1

关于“摘要”行（公式中的50），the Linux kernel documentation has this to say：

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

也就是说，内核维护者确实试图将事物保持在50左右。这是内核git日志中汇总行长度的直方图：

（view full-sized）

有一些提交的提交行比这个绘图更长（有些长得多），而不会使有趣的部分看起来像一行。 （可能有一些花哨的统计技术可以将这些数据合并到这里但是很好...... :)）。

如果您想查看原始长度：

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

或基于文本的直方图：

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Answer 2

关于“思想领袖”：Linus着重提倡完整提交消息的换行：

  

我们使用72个字符的列进行自动换行，但引用除外   具有特定行格式的材料

例外主要是指“非散文”文本，即人类没有为提交键入的文本 - 例如，编译器错误消息。

Answer 3

表示和数据的分离在这里驱动我的提交消息。

您的提交消息不应该包含在任何字符数中，而应使用换行符将思想，段落等分开作为数据的一部分，而不是表示。在这种情况下，“数据”是您尝试通过的消息，“演示”是用户看到的消息。

我在顶部使用了一个摘要行，我尽量保持简短，但我不限于任意数字。如果Git实际上提供了一种将摘要消息作为一个单独的实体存储在消息中的方法会好得多，但因为它不是我必须破解其中一个并且我使用第一个换行符作为分隔符（幸运的是，许多工具支持这意味着分解数据。）

对于消息本身，换行符表示数据中有意义的内容。单个换行符表示列表中的开始/中断，双换行符表示新的想法/想法。

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

这是在软包装文本的查看器中的样子。

  

这是一个摘要行，尝试保持简短并以换行符结束。

     

这是一个想法，也许是我用人类可读格式所做的解释。它可能很复杂，很长，由几个句子组成，用于描述我在论文格式中的工作。我现在（在作者时间）决定用户将如何使用这些数据。

     

两个换行符将这两个想法分开。用户可能正在手机或宽屏显示器上阅读。您是否尝试在仅显示60个字符的设备上阅读72个字符包装文本？这是一次真正痛苦的经历。此外，本段的开头句（假设论文风格格式）应该是段落的介绍，因此如果工具选择它可能不想自动换行，让你只看到每个段落的开头。同样，由演示工具而不是我（历史上某个时候的随机作者）试图强迫我的特定格式压低其他人的喉咙。

     

举个例子，这是一个点列表：
    *点1.
    *点2.
    *第3点。

我怀疑，你链接的Git提交消息推荐的作者从来没有编写过软件，这些软件将在不同的设备之前被广泛的终端用户使用（即网站），因为此时在演变中软件/计算众所周知，就用户体验而言，使用硬编码的演示信息存储数据是一个坏主意。

Answer 4

我同意提出一种特定的工作方式很有意思。但是，除非我有机会设置风格，否则我通常会遵循为保持一致性而采取的措施。

看看Linux Kernel Commits，如果你愿意，启动git的项目http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bca476139d2ded86be146dae09b06e22548b67f3，他们不遵循50/72规则。第一行是54个字符。

我认为一致性很重要。设置正确的方法来识别已提交的用户（user.name，user.email - 尤其是在内部网络上.User @ OFFICE-1-PC-10293982811111不是有用的联系地址）。根据项目，在提交中提供适当的详细信息。很难说应该是什么;它可能是在开发过程中完成的任务，然后是更改内容的详细信息。

我不相信用户应该以一种方式使用git，因为git的某些接口以某种方式处理提交。

我还应该注意还有其他方法可以找到提交。首先，git diff会告诉您更改的内容。您还可以执行git log --pretty=format:'%T %cN %ce'之类的操作来格式化git log的选项。

Answer 5

建议的最大标题长度真的是50吗？

我已经相信了很多年，但是正如我刚刚注意到的“ git commit”文档实际上指出的那样

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

有人可能会说，“少于50”只能表示“不超过49”。