Git 提交消息：50/72 格式答案

【问题标题】：Git Commit Messages: 50/72 FormattingGit 提交消息：50/72 格式
【发布时间】：2011-01-18 09:38:09
【问题描述】：

Tim Pope 在他的博文中主张使用特定的 Git 提交消息样式： 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 提交消息样式的理由。（也可以提出未提及的观点。）

【问题讨论】：

我刚刚注意到，如果您的第一行超过 50 个字符，Github 的 Web 界面会通过说“ProTip：伟大的提交摘要不超过 50 个字符。在扩展描述中添加额外信息”来警告您。

标签： git

【解决方案1】：

我同意提出一种特定的工作方式很有趣。但是，除非我有机会设置样式，否则我通常会遵循已完成的操作以保持一致性。

看看 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 的选项。

【讨论】：

作为参考，他说“如示例所示，你应该拍摄大约 50 个字符（尽管这不是一个硬性最大值）”，但我想你有一个观点，你不应该必须解决您的工具问题。

【解决方案2】：

关于“摘要”行（公式中的 50），Linux 内核文档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

【讨论】：

出于好奇，您是如何生成直方图的？
matplotlib 在 python 中。类似于 this 的东西，但输出来自我的答案中的一个命令，而不是随机数据。
使用 GNU AWK：git shortlog | awk '/^ / {gensub(/[[:space:]]\+$.*$$/, "\\1", ""); print length()}'
Github 将在第 70 个字符之后隐藏提交消息文本。
关于“花式统计技术”，您可以简单地制作最后一个 bin，例如“≥100”

【解决方案3】：

关于“思想领袖”：Linus 强烈主张为完整的提交信息换行：

[...] 我们使用 72 个字符的列进行自动换行，除了带引号的具有特定线条格式的材料。

异常主要是指“非散文”文本，即不是人工为提交而输入的文本 — 例如编译器错误消息。

【讨论】：

+1 用于区分“散文”和“非散文”。以及“具有特定行格式的引用材料除外”。优秀的经验法则。

【解决方案4】：

展示和数据的分离推动了我的提交信息。

您的提交信息不应以任何个字符数硬包装，而应使用换行符来分隔思想、段落等，作为数据的一部分，而不是演示文稿。在这种情况下，“数据”是您试图传达的信息，而“展示”是用户看到的方式。

我在顶部使用单个摘要行，并尽量保持简短，但我不会将自己限制为任意数字。如果 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 提交消息推荐的作者之前从未编写过将由不同设备（即网站）上的大量最终用户使用的软件，因为在这一点上的演变软件/计算众所周知，就用户体验而言，使用硬编码的演示信息存储数据是一个坏主意。

【讨论】：

哇，即使在像 SO 这样的网页上阅读提交消息也很痛苦。我不需要 responsive 提交消息，但可以与 tig、git log 或 gitk 配合使用，也许还有 github。
任何换行的查看器都可以轻松阅读该消息。我把它放在一个非包装代码块中作为例子。
感谢您提供不同的视角。从理论上讲，您的答案听起来不错。在实践中，我喜欢当前命令行工具的换行符。
字符序列\n\n是一个思想分隔符。 \n* 是一个列表项指示器。如何呈现这些取决于视图。人工换行符的问题在于它们与除了演示文稿无关。通过在 70 个字符处放置换行符，不会传输任何与数据相关的信息。我对\n\n 和\n* 的选择与markdown 选择它的原因相同，因为它是一种编码数据的形式，在纯文本视图中也恰好看起来有些合理。
硬包装很难在小屏幕设备（移动设备）上阅读。无论您做什么，都很难在某处阅读该消息。我宁愿遵循现代最佳实践，也不愿迎合没有一些最基本渲染功能的遗留软件。

【解决方案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”。

【讨论】：

另一方面，默认突出显示前 50 个字符。这似乎是一种无意的差异。