Git提交消息:50/72格式

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

以下是他建议的一个简短摘要:

  • 第一行是50个字符或更少
  • 然后是一个空白行
  • 剩余的文字应该包裹72个字符
  • 他的博客文章提供了这些建议的基本原理(为简洁起见,我将其称为“50/72格式化”):

  • 实际上,一些工具将第一行视为主题行,第二段视为主体(类似于电子邮件)
  • git log不处理包装,所以如果行太长,很难阅读。
  • git format-patch --stdout将提交转换为电子邮件 - 因此,如果你的提交已经很好地包装好了,就可以发挥它的作用。
  • 我想补充的一点是,我认为蒂姆会同意这一观点:在任何版本控制系统中,总结你的提交行为本身就是一种很好的做法。 它可以帮助其他人(或稍后您)更快地找到相关的提交。
  • 所以,我对我的问题有几个部分:

  • git的“思想领袖”或“有经验的用户”大概包含50/72格式化风格? 我问这个问题是因为有时新的用户不知道或不关心社区实践。
  • 对于那些不使用此格式的用户,是否有使用不同格式样式的原则性原因? (请注意,我正在寻找关于优点的争论,而不是“我从未听说过”或“我不在乎”。)
  • 从经验上讲,git存储库拥有这种风格的百分比是多少? (如果有人想对GitHub存储库进行分析......提示,提示。)
  • 我的意思是,不要推荐50/72风格或者击倒其他风格。 (为了开放,我更喜欢它,但我愿意接受其他想法。)我只想得到为什么人们喜欢或反对各种git commit消息风格的基本原理。 (随意提出未提及的要点。)


    关于“总结”一行(公式中的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日志中总结行长度的直方图:

    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
    

    关于“思想领袖”:Linus着重提倡对完整提交信息进行换行:

    除了具有特定行格式的引用材料之外,我们使用72个字符的列进行换行

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


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

    您的提交信息不应该在任何字符数上被硬包装,而应该使用换行符作为数据的一部分,而不是演示文稿来分隔想法,段落等。 在这种情况下,“数据”就是你想要传递的信息,而“演示”就是用户看到的信息。

    我在顶部使用了一个摘要行,并尽量保持简短,但我不会将自己限制为任意数字。 如果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 commit消息推荐的作者从来没有编写过软件,这些软件会在不同设备上的大量终端用户使用之前(即网站),因为此时软件/计算的发展众所周知,就用户体验而言,将数据与硬编码的演示信息一起存储是一个坏主意。

    链接地址: http://www.djcxy.com/p/35483.html

    上一篇: Git Commit Messages : 50/72 Formatting

    下一篇: Is there a quick git command to see an old version of a file?