编写良好的提交信息：实用指南

要创建有用的修订历史记录&＃xff0c;团队应该首先就要使用的提交消息约定达成一致&＃xff0c;这也适用于个人项目。

最近&＃xff0c;我在Hashnode上问了一个问题&＃xff0c;询问用户“ 他们在工作中使用哪种提交消息约定&＃xff1f; ”&＃xff0c;当用户解释他们在工作中以及用于个人项目的约定时&＃xff0c;我得到了相当多的反响。

在本文中&＃xff0c;我将介绍为什么您应该编写良好的提交消息以及如何编写良好的提交消息。

Git版本控制简介

版本控制软件是每天现代软件开发人员实践中必不可少的部分。

到目前为止&＃xff0c; Git是当今世界上使用最广泛的现代版本控制系统。 它是一个分布式且积极维护的开源项目&＃xff0c;最初由Linux操作系统内核的著名创建者Linus Torvalds于2005年开发。

刚接触Git&＃xff1f; 查看官方的入门指南或我过去的演讲中的这张幻灯片 。

什么是提交消息&＃xff1f;

在Git中暂存后&＃xff0c;使用commit命令将更改保存到本地存储库。 但是&＃xff0c;在保存Git更改之前&＃xff0c;您必须告诉Git您要保存哪些更改&＃xff0c;因为您可能已经进行了大量更改。 做到这一点的一种好方法是添加一个提交消息以标识您的更改。

提交选项

• -m <消息>

此选项设置提交的消息。

• -a或--all

此选项自动提交所有&＃xff08;包括新的&＃xff09;跟踪&＃xff0c;修改或删除的文件。

• - 修改

此选项将使用当前已暂存的任何更改或新的提交消息重写最后的提交&＃xff0c;并且仅应在尚未推送到远程存储库的提交上执行。

为什么要编写良好的提交消息&＃xff1f;

您可能会说“这只是一个个人项目”&＃xff0c;但是是的&＃xff0c;您现在一个人工作&＃xff0c;但是当您与团队合作或为开源做贡献时会发生什么&＃xff1f;

精心设计的Git提交消息是与从事该项目的其他开发人员以及您未来的自我沟通有关变更的上下文的最佳方法。 您是否尝试过运行旧项目之一的&＃96;git log&＃96;来查看自开始以来就使用过的“怪异”提交消息&＃xff1f; 您很难解释过去为什么要进行一些更改&＃xff0c;并且希望您现在之前已经阅读过本文&＃xff1a;)。

提交消息可以充分告诉您为什么进行了更改&＃xff0c;并且了解为什么进行了更改可以使开发和协作更加高效。

如何使用Git编写提交消息

在此之前&＃xff0c;我只在个人项目上使用了git commit -m "Fix X to allow Y to use Z" &＃xff0c;并且仅提供了一个主题&＃xff0c;没有附加描述。 这非常适合进行小而清晰的修复&＃xff0c;例如git commit -m "Fix typo in README.md中的git commit -m "Fix typo in README.md但是在更广泛的更改的情况下&＃xff0c;您需要添加一些额外的细节。

编辑器方法

运行没有消息或选项的git commit &＃xff0c;它将打开您的默认文本编辑器以编写提交消息。

>要配置“默认”编辑器&＃xff1a;

这会将git配置为使用nano作为默认编辑器。 将“ nano”替换为“ emacs”&＃xff0c;“ vim”或您的偏好。

在打开的编辑器中&＃xff0c;第一行是主题&＃xff08;简短描述&＃xff09;&＃xff0c;其后留空行&＃xff0c;其他所有内容都是扩展描述&＃xff08;正文&＃xff09;。

命令行方式

第一个-m选项是主题&＃xff08;简短描述&＃xff09;&＃xff0c;第二个是扩展描述&＃xff08;正文&＃xff09;。

如何编写良好的提交消息

一些团队和开发人员使用多种约定来编写良好的提交消息。 我只概述一些用于编写提交消息的一般规则和技巧&＃xff0c;您将不得不决定要遵循的约定&＃xff0c;并且如果您在公司工作或为开源做贡献&＃xff0c;则必须适应它们的约定&＃xff1a;)。

为了保持一致性&＃xff0c;您可以在工作中使用一种约定&＃xff0c;而在个人项目中使用另一种约定&＃xff0c;因为您有时可能会更改工作&＃xff0c;并且约定可能会更改。

确保检查此线程以了解一些惊人的提交消息约定&＃xff0c;或添加您的约定以帮助某人做出决定。

这是Tim Pope最初编写的良好提交消息的一个很好的模板

大写的简短&＃xff08;不超过50个字符&＃xff09;摘要

如有必要&＃xff0c;提供更详细的说明文字。 将其包装到大约72个字符左右。 在某些情况下&＃xff0c;第一行被视为电子邮件的主题&＃xff0c;其余文本被视为正文。 将摘要与正文分开的空白行很重要&＃xff08;除非您完全省略正文&＃xff09;&＃xff1b; 如果将两者一起运行&＃xff0c;诸如rebase之类的工具可能会感到困惑。

请务必将提交消息写在“修复错误”而不是“修复错误”或“修复错误”中。 该约定与git merge和git revert等命令生成的提交消息匹配。

空白段之后是其他段落。

-子弹点也可以

-通常在项目符号上使用连字符或星号&＃xff0c;后跟一个空格&＃xff0c;中间留有空白行&＃xff0c;但约定在此处有所不同

-使用悬挂式缩进

如果您使用问题跟踪器&＃xff0c;请在其底部添加一个引用&＃xff0c;如下所示&＃xff1a;解决&＃xff1a;&＃xff03;123

看起来不错吧&＃xff1f; 您也可以通过以下方法使自己的实力变得出色&＃xff1a;

1. 1.指定提交类型&＃xff1a;

• 壮举 &＃xff1a;您要添加到特定应用程序的新功能
• fix &＃xff1a;一个错误修复
• 样式 &＃xff1a;与样式相关的功能和更新
• 重构 &＃xff1a;重构代码库的特定部分
• 测试 &＃xff1a;与测试相关的所有内容
• docs &＃xff1a;与文档相关的所有内容
• 杂务 &＃xff1a;常规代码维护。

1. [您也可以使用表情符号来代表提交类型]

   2.用空白行将主体与身体分开

   3.您的提交消息不应包含任何空格错误

   4.删除不必要的标点符号

   5.不要以句号结尾主题行

   6.大写主题行和每个段落

   7.在主题行中使用祈使语气

   8.用正文解释您进行了哪些更改以及进行更改的原因。

   9.不要以为审阅者了解原始问题是什么&＃xff0c;请确保将其添加。

   10.不要认为您的代码是不言自明的

   11.遵循团队定义的提交约定

结论

提交消息最​​重要的部分是它应该清晰且有意义。 从长远来看&＃xff0c;编写良好的提交消息可以表明您有多大协作者&＃xff0c;而编写良好的提交消息所带来的好处不仅限于您的团队&＃xff0c;而且还不仅限于您自己&＃xff0c;还包括未来的贡献者。

想要了解有关Git的更多信息并成为专业的“版本控制器”&＃xff0c;请查看以下优秀资源&＃xff1a;

• https://try.github.io/
• https://git-scm.com/book/zh/v2
• https://www.git-tower.com/learn/
• https://learngitbranching.js.org/xxxx

先前发布在https://bolajiayodeji.com/writing-good-commit-messages-a-practical-guide-ck3izs56t00sed0s11z515m1j

From: https://hackernoon.com/writing-good-commit-messages-a-practical-guide-1j11i3y4c