Git 提交消息：50/72 格式

Git Commit Messages: 50/72 Formatting

提问by David J.

Tim Pope argues for a particular Git commit message style in his blog post: http://www.tpope.net/node/106.

Tim Pope 在他的博客文章中主张使用特定的 Git 提交消息样式：http: //www.tpope.net/node/106。

Here is a quick summary of what he recommends:

以下是他建议的快速摘要：

• First line is 50 characters or less.
• Then a blank line.
• Remaining text should be wrapped at 72 characters.

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

His blog post gives the rationale for these recommendations (which I will call “50/72 formatting” for brevity):

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

• In practice, some tools treat the first line as a subject line and the second paragraph as a body (similar to email).
• git logdoes not handle wrapping, so it is hard to read if lines are too long.
• git format-patch --stdoutconverts commits to email?—?so to play nice it helps if your commits are already wrapped nicely.

• 在实践中，一些工具将第一行视为主题行，将第二段视为正文（类似于电子邮件）。
• git log不处理换行，所以如果行太长很难阅读。
• git format-patch --stdout将提交转换为电子邮件？-？所以如果你的提交已经很好地包装，那么玩得好会有所帮助。

A point I would like to add that I think Tim would agree with:

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

• The act of summarizing your commit is a good practice inherently in any version control system. It helps others (or a later you) find relevant commits more quickly.

• 总结提交的行为在任何版本控制系统中都是一种固有的好习惯。它可以帮助其他人（或后来的您）更快地找到相关的提交。

So, I have a couple of angles to my question:

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

• What chunk (roughly) of the “thought leaders” or “experienced users” of Git embrace the 50/72 formatting style? I ask this because sometime newer users don't know or don't care about community practices.
• For those that don't use this formatting, is there a principled reason for using a different formatting style? (Please note that I'm looking for an argument on the merits, not “I've never heard of it” or “I don't care.”)
• Empirically speaking, what percentage of Git repositories embrace this style? (In case someone wants to do an analysis on GitHub repositories… hint, hint.)

• Git 的“思想领袖”或“经验丰富的用户”中有哪些（大致）接受 50/72 格式样式？我问这个是因为有时新用户不知道或不关心社区实践。
• 对于那些不使用这种格式的人，是否有使用不同格式样式的原则性原因？（请注意，我正在寻找关于案情的论据，而不是“我从未听说过”或“我不在乎”。）
• 从经验上讲，有多少 Git 存储库采用这种风格？（如果有人想对 GitHub 存储库进行分析……提示，提示。）

My point here is not to recommend the 50/72 style or shoot down other styles. (To be open about it, I do prefer it, but I am open to other ideas.) I just want to get the rationale for why people like or oppose various Git commit message styles. (Feel free to bring up points that haven't been mentioned, too.)

我的观点不是推荐 50/72 款式或否定其他款式。（坦率地说，我确实更喜欢它，但我对其他想法持开放态度。）我只是想了解人们为什么喜欢或反对各种 Git 提交消息样式的理由。（也可以随意提出尚未提及的要点。）

采纳答案by mgalgs

Regarding the “summary” line (the 50?in your formula), the Linux kernel documentation has this to say:

关于“摘要”行（公式中的 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.

That said, it seems like kernel maintainers do indeed try to keep things around?50. Here's a histogram of the lengths of the summary lines in the git log for the kernel:

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

(view full-sized)

（查看全尺寸）

There is a smattering of commits that have summary lines that are longer (some much longer) than this plot can hold without making the interesting part look like one single line. (There's probably some fancy statistical technique for incorporating that data here but oh well… :-)

有少量提交的摘要行比该图可以容纳的要长（有些要长得多），而不会使有趣的部分看起来像一行。（这里可能有一些花哨的统计技术来合并这些数据，但哦…… :-)

If you want to see the raw lengths:

如果您想查看原始长度：

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

or a text-based histogram:

或基于文本的直方图：

$ 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

回答by leonbloy

Regarding “thought leaders”: Linusemphatically advocates line wrapping for the full commit message:

关于“思想领袖”：Linus强烈主张对完整提交消息进行换行：

[…] we use 72-character columns for word-wrapping, except for quoted material that has a specific line format.

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

The exceptions refers mainly to “non-prose” text, that is, text that was not typed by a human for the commit?—?for example, compiler error messages.

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

回答by Micah Zoltu

Separation of presentation and data drives my commit messages here.

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

Your commit message should not be hard-wrapped at anycharacter count and instead line breaks should be used to separate thoughts, paragraphs, etc. as part of the data, not the presentation. In this case, the "data" is the message you are trying to get across and the "presentation" is how the user sees that.

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

I use a single summary line at the top and I try to keep it short but I don't limit myself to an arbitrary number. It would be far better if Git actually provided a way to store summary messages as a separate entity from the message but since it doesn't I have to hack one in and I use the first line break as the delimiter (luckily, many tools support this means of breaking apart the data).

我在顶部使用了一个摘要行，并尽量保持简短，但我不会将自己限制为任意数字。如果 Git 实际上提供了一种将摘要消息作为与消息分开的实体来存储的方法，那会好得多，但由于它不必我修改一个，我使用第一个换行符作为分隔符（幸运的是，许多工具支持这种分解数据的方法）。

For the message itself newlines indicate something meaningful in the data. A single newline indicates a start/break in a list and a double newline indicates a new thought/idea.

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

##代码##

Here's what it looks like in a viewer that soft wraps the text.

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

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。

My suspicion is that the author of Git commit message recommendation you linked has never written software that will be consumed by a wide array of end-users on different devices before (i.e., a website) since at this point in the evolution of software/computing it is well known that storing your data with hard-coded presentation information is a bad idea as far as user experience goes.

我怀疑您链接的 Git 提交消息推荐的作者从未编写过软件，这些软件将被不同设备（即网站）上的大量最终用户使用，因为此时软件/计算的发展众所周知，就用户体验而言，将数据与硬编码的演示信息一起存储是一个坏主意。

回答by Micah Zoltu

I'd agree it is interesting to propose a particular style of working. However, unless I have the chance to set the style, I usually follow what's been done for consistency.

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

Taking a look at the Linux Kernel Commits, the project that started git if you like, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bca476139d2ded86be146dae09b06e22548b67f3, they don't follow the 50/72 rule. The first line is 54 characters.

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

I would say consistency matters. Set up proper means of identifying users who've made commits (user.name, user.email - especially on internal networks. User@OFFICE-1-PC-10293982811111 isn't a useful contact address). Depending on the project, make the appropriate detail available in the commit. It's hard to say what that should be; it might be tasks completed in a development process, then details of what's changed.

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

I don't believe users should use git one way because certain interfaces to git treat the commits in certain ways.

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

I should also note there are other ways to find commits. For a start, git diffwill tell you what's changed. You can also do things like git log --pretty=format:'%T %cN %ce'to format the options of git log.

我还应该注意到还有其他方法可以找到提交。首先，git diff会告诉你发生了什么变化。您还可以执行诸如git log --pretty=format:'%T %cN %ce'格式化git log.

回答by Guenther Brunthaler

Is the maximum recommended title length really 50?

最大推荐标题长度真的是50吗？

I have believed this for years, but as I just noticed the documentation of "git commit" actually states

多年来我一直相信这一点，但正如我刚刚注意到“git commit”的文档实际上指出

##代码##

One could argue that "less then 50" can only mean "no longer than 49".

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