我在Git提交信息中应该使用过去时还是现在时?

693

我曾经读过一篇文章,说git提交信息应该使用现在时的祈使语态,例如"Add tests for x"。然而,我总是使用过去时,例如"Added tests for x",这对我来说感觉更自然。

以下是最近John Resig的一次提交记录,其中包含两种不同的提交信息:

Tweak some more jQuery set results in the manipulation tests. Also fixed the order of the expected test results.

这有关紧要吗?我应该使用哪个?


1
请参阅以下链接:http://www.exquisitetweets.com/collection/hugovk/1258 http://english.stackexchange.com/q/6602/9001 http://programmers.stackexchange.com/q/56031/25708 http://programmers.stackexchange.com/q/157590/25708 https://dev59.com/23I-5IYBdhLWcg3woJ9J - Hugo
请参考 https://github.com/agis-/git-style-guide。 - Agis
3
如果这个问题因为基于个人观点而被关闭,那么在其他地方也会因为基于个人观点而被关闭。 - ratchet freak
@Eonil,而且,超过60天的问题即使由版主也无法迁移。 - yannis
1
我不确定它是否必须是“基于观点的”。例如,如果提交消息用于创建自动发布说明,则几乎100%的时间以后者格式(即“添加了xyz功能”)呈现是有意义的。如果没有,则并不那么重要,这是一种基于观点的偏好。 - developerinlondon
显示剩余8条评论
7个回答

825
喜欢使用现在时和祈使句风格的提交信息偏好来自于 Git 本身。来自 Git 存储库中的 Documentation/SubmittingPatches
描述您的更改时请使用祈使语气,例如“让 xyzzy 做 frotz”,而不是“[此补丁] 使 xyzzy 做 frotz”或“[我] 改变了 xyzzy 的行为”,就像您正在命令代码库更改其行为一样。
因此,你会看到很多 Git 提交消息都是以这种方式书写的。如果你在团队或开源软件上工作,每个人都坚持这种风格有助于保持一致性。即使你在一个私人项目上工作,并且只有你自己会看到你的 Git 历史记录,使用祈使语气也是有帮助的,因为它可以建立良好的习惯,在与他人合作时会受到赞赏。

112
我认为这是一个很好的选择。考虑一下提交(commit)在差异形式下的含义:它是一组指示,告诉你如何从之前的状态转换到新的状态。正如差异(diff)会说“在这里添加这一行,在这里删除这一行”,提交消息则是以定性术语表达“进行此更改”。(是的,Git将提交简单地存储为带有元数据的树形结构,但对于人来说,提交最重要的部分是差异。) - Cascabel
177
你可能将提交视为一组指令,告诉你如何从先前的状态转换到新状态;但我更认为它是代码演变中的一个检查点。对我来说,提交消息是自上次提交以来对代码进行的更改的日志记录;对于日志记录,使用过去时态更合理。如果你真的认为提交消息应该是一组指令,那么祈使语气是正确的方式。我只是不会这样想。 - karadoc
11
文件的更新版本给出了原因:“用祈使语气描述您的更改,例如 '让 xyzzy 做 frotz',而不是 '[此补丁] 让 xyzzy 做 frotz' 或 '[我] 改变了 xyzzy 的行为,使其做 frotz',好像您正在向代码库下达命令,要求它改变自己的行为。” - mipadi
70
Git提交信息应使用祈使语气和现在时态,因为在Git中,您或其他人可能会执行“rebase”或“cherry-pick”,在这种情况下,提交信息可能会被用于其原始上下文之外。因此,提交信息应独立编写,不要期望读者查看任何周围的提交信息。当您挑选补丁时,适用于“修复快速排序算法”或“排序:提高性能”的提交信息,而不是“修复错误#124”或“修改排序以提高性能”。 - Mikko Rantalainen
11
我对此的想法是,这个信息应该告诉我如果我选择将这个提交应用到我的分支会发生什么变化。我认为它不是一个日志,而是我可以移动到的状态,我需要知道当我选择一个特定的状态时会发生什么事情。 - steinybot
显示剩余18条评论

433

你的项目应该 几乎总是 使用过去式。无论如何,为了保持一致性和清晰度,项目应始终使用相同的时态。

我理解一些其他人提出使用现在时态的论点,但它们通常不适用。以下是写在现在时态中的常见论点以及我的回应。

  • 使用现在时态告诉某人应用提交(commit)会做什么,而不是你做了什么。

这是使用现在时态的最正确的原因,但只适用于特定类型的项目。这种思考方式将所有提交(commit)都视为可选的改进或功能,您可以自由决定在特定存储库中保留哪些提交(commit),并拒绝哪些提交(commit)。

如果您正在处理真正分布式的项目,则此论点有效。如果您正在处理分布式项目,则可能正在处理开源项目。如果真的是一个非常大的项目,那么这可能是Linux内核或Git。由于Linux很可能是引起Git传播和流行的原因,因此很容易理解为什么人们认为其风格具有权威性。是的,这种风格在这两个项目中很有意义。或者,一般来说,它适用于大型、开源、分布式项目。

尽管如此,大多数源代码控制的项目不是这样工作的。对于大多数存储库而言,通常是不正确的。这是提交的现代思考方式:Subversion(SVN)和CVS存储库几乎无法支持这种存储库检入(check-in)样式。通常,集成分支处理过滤掉的错误检入(check-in),但这些通常被认为不是“可选”或“好玩”的功能。

在大多数情况下,当您向源代码库提交更改时,您正在撰写一篇日志记录,描述这次更新的变化,以便其他人在将来更容易理解为什么进行了更改。这通常不是可选的更改 - 项目中的其他人需要合并或基于它进行重置。你不会写一个像“亲爱的日记,今天我见到了一个男孩,他向我打招呼”这样的日记记录,而是写“我遇到了一个男孩,他向我打招呼。”
对于这种非分布式项目,99.99%的时间读取提交消息是为了阅读历史记录 - 历史记录以过去时态读取。只有0.01%的时间,人们才会决定是否应该应用此提交或将其集成到他们的分支/存储库中。
  • 一致性。在许多项目(包括git本身)中都是这样做的。还有生成提交的git工具(如git merge或git revert)。
不,我可以保证,在版本控制系统中记录大多数项目的历史记录都是过去式(我没有参考资料,但考虑到现在时态的论点是自Git以来新出现的,这可能是正确的)。只有真正分布式的项目才开始使用以现在时态撰写的“修订”消息或提交消息 - 请参见上面的第一点。
  • 人们读取历史记录不仅是为了了解“这个代码库发生了什么”,还要回答诸如“当我采用这个提交时会发生什么”,或者“因为这些提交,我可能会合并到未来的代码中产生什么样的新变化”之类的问题。
请参见第一点。99.99%的时间读取提交消息是为了阅读历史记录 - 历史记录以过去时态读取。只有0.01%的时间,人们才会决定是否应该应用此提交或将其集成到他们的分支/存储库中。99.99%击败0.01%。
  • 通常更短

我从未见过一个好的论点,认为使用不恰当的时态/语法因为它更短。对于标准的50个字符的消息,你可能只会平均节省3个字符。话虽如此,现在时态平均来说可能会少几个字符。

  • 你可以更一致地使用问题/特性跟踪器中的标题来命名提交(这些标题不使用过去时,尽管有时使用将来时)

问题被写成正在发生的事情(例如,应用正在显示错误行为),或者需要在未来完成的事情(例如,文本将需要编辑审查)。

历史记录(即提交消息)是以过去完成的事情作为基础编写的(例如,问题已经被修复)。


121
我今天第一次听说所谓的命令式样式提交。对我来说,这听起来是如此不自然和奇怪,以至于我决定寻求更多的意见。很高兴看到我不是唯一一个认为过去式更适合作为提交信息的人。 :) - karadoc
79
Git自动生成的合并和变基(commit)提交信息使用祈使句和现在时态("Merge"而不是"Merged";"Rebase"而不是"Rebased"),因此为了一致性,您可能希望在自己的提交信息中保持这种风格。 - mjs
21
看起来区别在于关注软件的变化-“通过做Y修复X”-或代码库-“通过做Y修复X”。对于这个有很好的论点,但我认为代码库通常应该关注自身而不是最终的软件。 - l0b0
35
问题在于,对于大型项目(例如Linux),使用命令式和现在时态是有效的,因此它显然具有可扩展性。此外,与过去时态相比,使用命令式和现在时态几乎不需要付出任何努力。因此,我认为没有任何理由(除了“老年人习惯于以过去时态编写提交消息”之外)使用除命令式和现在时态之外的任何其他语态。如果您可以学会git命令集,那么您也可以学会使用命令式和现在时态编写提交消息。 - Mikko Rantalainen
48
"Imperative is not 'new since git'. ChangeLog existed long before git, and the use of imperative has always been the recommended style in the GNU Project." 这句话的意思是,“命令式语气并不是自从 git 出现才有的。在 git 以前,ChangeLog 就已经存在了,并且在 GNU 项目中一直推荐使用命令式语气。” 参考链接:http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html - adl
显示剩余13条评论

99

我在365git上写了一篇更详细的描述。

使用祈使句和现在时态需要一点适应时间。当我开始提起这个问题时,会遇到一些抵制。通常是“提交记录应该记录我的操作”。但是,Git是一个分布式版本控制系统,有很多地方可以获取更改。与其编写记录你做了什么的消息;考虑把这些消息作为应用提交的指令。因此,不要使用下面标题的提交:

重命名iVars并去除公共前缀

使用如下标题:

将iVars重命名以去除公共前缀

这样可以告诉使用者应用提交后会发生什么而不是你做了什么。此外,如果查看存储库历史记录,可以看到Git生成的消息也是使用这种时态的-“合并”而不是“已合并”,“变基”而不是“已变基”,所以使用相同的时态可以保持一致性。虽然一开始感觉奇怪,但它确实有道理(可以提供证明),并且最终会变得自然。

话虽如此-这是你的代码,你的存储库:因此请设置自己的指南并坚持遵守。

如果您决定采用这种方法,可以考虑使用具有重命名选项的git rebase -i


12
你已经混淆了两个不同的指南:Git开源项目和Git的常规用法。提供的链接根本没有提到时态。官方Git文档只提到50个字符的限制。Git是一个分布式版本控制系统,有很多地方可以获取更改,将这些消息视为应用提交所需执行的说明。这仅适用于一些实际上是分布式项目的项目。99.999%的Git提交永远不会以这种方式手动应用。在大多数项目中,历史记录是一个变更日志,应使用过去时态。 - Matt Quigley
4
"并且应该跳过句号" - takeshin

47

坚持使用现在时的祈使句,因为

  • 这样有一个标准可循;
  • 它与 bug 追踪器中的工单自然匹配,这些工单的形式通常是“实现某事”,“修复某事”或“测试某事”。

23

你写这条信息给谁?那个读者通常是在提交代码之前还是之后阅读这条信息的?

我认为从两个角度都给出了好的答案,但可能不会建议对于每个项目都有最佳答案。投票结果可能暗示了这一点。

即总结如下:

  • 这条信息主要是给其他人的,通常是在他们假定更改之前某个时间阅读的:关于采取变化会对他们现有的代码产生什么影响的提议。

  • 这条信息主要是作为自己(或团队)的日志/记录,但通常是从假定更改的角度阅读并回顾发生了什么。

也许这将引导您的团队/项目的动力。


14

重要吗?人们通常足够聪明,能正确解释消息。如果他们不能理解,你也不应该让他们访问你的存储库!


43
对于一些人来说,这样的事情相当重要。 - Wesley Murch
3
@mog这个链接没有提及过去或现在的任何陈述。 - ceving
2
如果项目规模变得很大,进行代码审查和错误调试的人将看到如此多的提交,他们需要我们提供的所有帮助。现在节省几秒钟没有意义,因为不写适当的提交消息将在未来造成重大问题。 - Mikko Rantalainen
我并不是说不要写一个好的提交信息。我是说,使用过去时或现在时并不重要。 - Michael Baldry
1
你怎么知道,无法解释你的提交信息的人是因为他不够能力,还是因为你没有写好提交信息? - Haris
这是关于精力的问题。在一天的多个项目中,我们越能减少认知负荷 - 这里指保持信息一致性 - 就越好。这有点像“性能很重要”- 好习惯和一致性有助于应对“认知负载很重要”的情况。 - CodeFinity

11

由您决定。只需按照您的意愿使用提交信息即可。 但是,如果您不在时间和语言之间切换,那么这将更容易。

如果您是团队开发,请进行讨论并设置固定规则。


网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接