我最喜欢的git commit

注意事项 佩雷夫 ：这本英国程序员的出版物已在英语互联网上大受欢迎，它指的是6年前的Git承诺。 它被记录在一个政府数字服务开放存储库中-该服务专用于在英国开发数字服务并支持GOV.UK项目。 提交本身很有趣，与其说是代码更改，不如说是伴随它们的描述。


图片来自xkcd＃1296

我喜欢在Git中提交描述。 如果使用得当，它们可以被称为最强大的工具，用于记录代码库在其存在期间的演变。 我想用我最喜欢的描述的例子来说明我的观点。

这项工作可以追溯到我在政府数字服务部门工作时。 它的作者是一个名为Dan Carley的开发人员，它的标题不太明显：“ 将模板转换为US-ASCII以解决错误 。”

“我已经在功能分支中实现了一些测试，以匹配/ etc / nginx / router_routes.conf`的内容。 如果与命令“ bundle exec rake spec”或“ bundle exec rspec modules / router / spec”一起运行，它们可以很好地工作。 但是当运行`bundle exec rake`时，每个应该阻止的块都会失败：

ArgumentError: invalid byte sequence in US-ASCII 

最后，我发现在表达式`.with_content（//）`例外之后，所有错误都消失了。 规范文件中没有奇怪的字符。 而且可以通过在同一个解释器中调用Puppet来播放它：

  rake -E 'require "puppet"' spec 

该模板似乎是我们代码库中唯一以'utf-8'编码的文件。 “ us-ascii”中的所有其他文件：

  dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 

尝试将其转码为US-ASCII失败，因为单个字符看起来像空格：

  dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert 

手动替换之后，文件再次变为“ US-ASCII”：

  dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii 

现在测试工作了！ 我一生的一小时都无法归还...”

一个小的题外话：GDS中实践的开源开发的好处之一是，您可以在创建它们的组织之外共享这样的示例。 我不知道是谁首先向GDS提出了这个概念-在我加入该组织时，它已经被广泛使用-但我无限感激此人。

为什么我喜欢这个提交

我无数次引用它作为提交描述功能的示例。 由于代码的更改比例和说明的大小，这有点有趣，但我一点都不喜欢。

在另一家公司中，与另一名开发人员一起，提交的全部信息可以简化为“替换差距”，“修复错误”或（取决于团队的文化）攻击不可分割的空间的发明者。 相反，Dan花时间创建了对其他人有用的详细描述。 我想详细说明为什么我认为此承诺是一个很好的例子。

披露更改的原因

对提交的最佳描述不仅可以告诉我们发生了什么变化，而且还可以解释原因 。 在我们的情况下：

我已经在功能分支中实现了一些测试，以匹配`/ etc / nginx / router_routes.conf`的内容。 如果与命令“ bundle exec rake spec”或“ bundle exec rspec modules / router / spec”一起运行，它们可以很好地工作。 但是当运行`bundle exec rake`时，每个应该阻止都失败了：

  ArgumentError: invalid byte sequence in US-ASCII 

没有如此详细的说明，我们可以假设提交已纠正了特定工具中的解析错误。 通过提交的描述，我们知道了它是哪种工具。

这种信息可能真的很有价值，而且很容易丢失，因为人们往往会忘记工作的复杂性，转移到其他团队并最终离开公司。

适合搜寻

此描述的关键要素之一是错误本身，并由此开始进一步搜索：

ArgumentError：
US-ASCII中的无效字节序列

遇到此错误的任何人都可以通过运行git log --grep "invalid byte sequence"或使用GitHub commits搜索来搜索代码库。 实际上，从搜索结果来看，许多人已经这样做了，并且找出了何时何人面临该问题以及如何最终解决该问题。

提供完整的图片

提交消息详细说明了问题的外观，如何进行调查和解决。 例如：

最后，我发现在表达式`.with_content（//）`例外之后，所有错误都消失了。 规范文件中没有奇怪的字符。 而且它可以通过在同一个解释器中调用Puppet来播放。

这是提交时消息真正能够显示的区域之一，因为它们描述更改本身，而不是某些文件，函数或代码行。 这使它们成为存储此类附加代码库冒险信息的好地方。

使每个人都变得更聪明

Dan在这里做了一件事，我真的很感激：带来了我在每个阶段执行的所有团队。 这是在团队中共享知识的一种很棒且价格合理的方法。 阅读他对提交的描述，您可以学到很多有关Unix工具的知识：

• 您可以传递-exec参数来find以对find每个文件执行命令；
• 在命令末尾添加\+会产生非常有趣的效果（将多个文件名传递给file命令，并且不会为每个文件执行一次命令）；
• file --mime可以让file --mime找出文件的MIME类型；
• 有一个实用程序iconv 。

查看说明的人可以了解所有这些内容。 稍后偶然发现此提交的任何人也将了解这些内容。 如果将这种方法长时间用于承诺并且数量足够多，那么它可以成为团队的有力激励工具。

发展同理心和信任

现在测试工作了！ 我一生的一小时无法归还...

最后一段增加了一点人性。 读了这些话，很难不感到Dan的失望，他不得不花整整一个小时的时间来寻找隐藏的错误，并且对纠正错误感到满意。

现在想象一下，类似的消息附加到临时的hack或进入生产并“扎根”的原型代码片段中（这种片段通常是这种情况）。 对提交的描述提醒每个人，在每次更改的背后，都有一个可以做出最佳决策的人，因为当时可以提供信息。

好的承诺很重要

我承认这是一个极端的例子，我不希望所有提交（尤其是这种范围的提交）都具有相同的详细程度。 但是，我仍然认为这是一个很好的例子，可以说明更改的原因，帮助其他人学习新事物，并为与代码库关联的集体思维模型做出贡献。

如果您想进一步了解提交的良好描述的优点以及一些易于进行编辑的工具，我可以推荐以下材料：

• Joel Chippindale的“ 通过您的承诺讲故事 ”；
• TekinSüleyman撰写的《 时间的分支 》。

译者的PS

另请参阅我们的博客：

• ” Git发生了！ 6个典型的Git错误以及如何解决 ”
• “ 使一天成为开源项目维护者的绝妙技巧 ”；
• “ 成功的大型开源项目有什么共同点？ ”。