Git提交信息：50/72格式化

Question

Tim Pope在他的博客文章中为一种特定的Git提交信息风格进行了辩论： http://www.tpope.net/node/106。

以下是他推荐的简要概述：

• 第一行不超过50个字符。
• 然后是一个空行。
• 剩余的文本应在72个字符处换行。

他的博客文章解释了这些建议的原因（为了简洁起见，我将其称为“50/72格式化”）：

• 实际上，一些工具将第一行视为主题行，将第二段视为正文（类似于电子邮件）。
• git log不处理换行，所以如果行太长，很难阅读。
• git format-patch --stdout将提交转换为电子邮件 - 所以如果您的提交已经很好地换行，它有助于更好地工作。

我想补充一点，我认为Tim会同意：

• 总结您的提交是任何版本控制系统中的一种良好实践。它有助于他人（或稍后的您）更快地找到相关的提交。

所以，我有几个问题的角度：

1. “思想领袖”或“经验丰富的Git用户”中有多少人采用50/72格式的风格？我问这个问题是因为有时候新用户不知道或不关心社区的惯例。

2. 对于那些不使用这种格式的人来说，是否有使用不同格式风格的原则性理由？（请注意，我寻求的是基于优点的论证，而不是“我从未听说过”或“我不在乎。”）

3. 从实证的角度来看，有多少Git仓库采用这种风格？（如果有人想对GitHub仓库进行分析的话...暗示，暗示。）

我的观点不是推荐50/72格式，也不是否定其他格式。 （坦率地说，我更喜欢它，但我也愿意接受其他想法。）我只是想了解为什么人们喜欢或反对各种Git提交消息的风格的理由。（也可以提出未提及的观点。）

- David J.

---

我刚刚注意到Github的网页界面会通过“专业提示”来警告你，如果你的第一行超过50个字符，它会说：“优秀的提交摘要应该在50个字符或更少。将额外的信息放在扩展描述中。” - David J.

这个答案提供了50/72规则的一个很好的概述，包括一些历史性的推理:https://dev59.com/L10a5IYBdhLWcg3wW3rN#50397345 - NeilG

Answer 1

关于“summary”行（在您的公式中的50），Linux内核文档有这样的说明：

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日志中摘要行长度的直方图：

（查看完整尺寸）

有一些提交的摘要行比这个图表可以容纳的更长（有些甚至非常长），这使得有趣的部分看起来像一条直线。 （也许在这里可以使用一些高级的统计技术，但是嘿... :-)

如果您想查看原始长度：

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

- mgalgs

---

你是如何生成直方图的呢，纯属好奇？ - anarchivist

在 Python 中使用 matplotlib。类似于 这个答案，但是需要输出我的答案中一个命令的结果，而不是随机数据。 - mgalgs

使用GNU AWK：git shortlog | awk '/^ / {gensub(/[[:space:]]\+\(.*\)$/, "\\1", ""); print length()}' - Dennis Williamson

Github将在第70个字符之后隐藏提交信息文本。 - Peeter Kokk

这不是很有趣吗？像 Linux 内核维护者这样的逻辑、数学人士能够写出“不超过70-75个字符”的短语。 - Fletch

Answer 2

关于“思想领袖”的问题：Linus 强烈支持对完整提交消息进行换行:

[...]我们使用72个字符的列来进行换行，除了具有特定行格式的引号文本。

这些例外主要是指“非散文”文本，即未由人类打字的文本，例如编译器错误消息。

- leonbloy

---

感谢肯定“散文”和“非散文”的区别，以及“引用具有特定行格式的材料除外”的规则。这是一个很好的经验法则。 - Alois Mahdal

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.

这是软件自动换行的阅读视图。

这是一个摘要，请尽量保持简短，并以换行符结束。

这是一种思考方式，也许是对我所做的事情的解释，以人类可读的格式呈现。它可能很复杂，由几个句子组成，以文章形式描述我的工作。在作者撰写时，我不能决定用户将如何消耗这些数据。

这两个想法之间有两个换行符。用户可能会在手机或宽屏幕显示器上阅读此内容。您是否曾经尝试阅读72个字符包装的文本，而您的设备只能显示60个字符？这是一种真正痛苦的体验。此外，本段开头的句子（假设采用文章风格格式）应该是段落的介绍，因此如果工具选择不自动换行，则可以让您仅查看每个段落的开头。同样，强制将我的特定格式强加给其他人并不取决于我（某个历史时期的随意作者），而取决于演示工具。

仅作为示例，以下是一些要点：
* 要点1。
* 要点2。
* 要点3。

我怀疑您所链接的Git提交消息建议的作者以前从未写过将被不同设备的广泛用户消耗的软件（例如网站），因为在软件/计算机的演变到现在这个阶段，众所周知使用硬编码的演示信息存储数据是一个坏主意，因为这会影响用户体验。

- Micah Zoltu

---

哇，即使在像SO这样的网页上阅读，那个提交信息也很难读。我不需要“响应式”的提交信息，但需要适用于tig、git log或gitk，并且可能也适用于GitHub的内容。 - Benjamin Bannier

信息会在任何自动换行的查看器中变得更易读。我将它放在一个不自动换行的代码块中作为示例。 - Micah Zoltu

谢谢您提供一个不同的观点。从理论上来说，您的回答听起来不错。但在实践中，我喜欢为当前的命令行工具添加换行符。 - David J.

字符序列“\n\n”是表示段落分隔符，“\n* ”则表示列表项标识符，如何渲染取决于视图。人工换行的问题在于它们除了呈现以外与任何东西都没有关联。在70个字符处插入换行符并没有传输任何与数据相关的信息。我选择“\n\n”和“\n* ”的原因与Markdown选择它们的原因相同，因为这是一种编码数据的形式，同时在纯文本视图中看起来也比较合理。 - Micah Zoltu

在小屏幕设备上（移动设备），硬换行会让阅读变得困难。无论你怎么做，这个信息在某些地方都会难以阅读。我宁愿遵循现代最佳实践，而不是迎合那些没有一些基本渲染能力的传统软件。 - Micah Zoltu

Answer 4

最大推荐标题长度真的是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”。

- Guenther Brunthaler

---

另一方面，默认高亮显示了前50个字符，这似乎是一个无意的差异。 - August Janse

不经意的差异 - NeilG

@AugustJanse 不再有“无意的差异”; 请参阅我的答案：“不超过50个字符”。 - undefined

Answer 5

我同意提出特定的工作风格很有趣。然而，除非我有机会设定风格，否则我通常会按照一贯的方式进行。

看看 Linux 内核提交记录，这个项目启用了 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 选项。

- user257111

---

参考他的说法：“正如示例所示，您应该瞄准大约50个字符（尽管这不是硬性最大值）”，但我认为你有一点道理，即你不应该为了适应工具而努力工作。 - Omni5cience

Answer 6

有人可能会争辩说，“不超过50个字符”只能意味着“不超过49个字符”。

关于Guenther Brunthaler的回答，Git 2.43（2023年第四季度）明确了“50个字符”的限制。

查看提交 c2c349a（2023年9月28日）由谢致邦（XIE Zhibang）（Red54）完成。
^{（由Junio C Hamano -- gitster --合并于提交 ba7d57b，2023年10月4日）}

doc：修正50个字符的软限制

^{签名：谢致邦（XIE Zhibang）}

提交信息的第一行软限制应为“不超过50个字符”或“50个字符或更少”，而不是“少于50个字符”。

git commit现在在其手册页面中包含以下内容：

使用一行简短的（不超过50个字符）概述变更

---

实际上，Git 2.43（2023年第四季度）通过谢致邦（XIE Zhibang）（Red54）于2023年10月8日的提交1627e6b，增加了一个精确度。
^{（由Junio C Hamano（gitster）于2023年10月18日的提交0bc6bff合并）} doc：修正50个字符的软限制（+） 已签署：谢致邦（XIE Zhibang）

提交信息的第一行的字符数应该是“不超过50个字符”或“50个字符或更少”，而不是“少于50个字符”。

这是对提交 c2c349a（“文档：修正50个字符的软限制”，2023年9月28日，Git v2.43.0 -- 合并列在批次＃15中）的补充。

gittutorial现在在其man page中包含以下内容：

提交信息应以一个简短的行（不超过50个字符）开始，概述变更，然后是一个空行，接着是更详细的描述。在提交信息中，第一个空行之前的文本被视为提交标题，并且该标题被使用。

user-manual现在在其man page中包含以下内容：

以一个简短的行（不超过50个字符）概述变更

- VonC