git commit message

一直以来我的git项目都是生命周期十分短的,基本上就是成型后就不大管,后续的维护一般是没有的。所以在用git的时候,不大会考虑一些项目维护方面的事情,很少会注意到自己在commit时写的东西。然而好的commit message对一个项目的延续是很重要的。

实际上,commit message是项目开发的历史记录的一部分,好的commit message不仅能帮助回顾项目的开发过程,还能够帮助开发者快速了解每一个commit做了什么以及为什么要那么做。这对项目后期维护,譬如说修复一些bug,是有很大作用的。同时,好的commit message也可以让新的开发者更快了解一个项目的开发情况,从而更快参与到项目的开发当中。

首先推荐一下下面这篇不太长的文章How to Write a Git Commit Message。下面的讨论将就围绕这篇文章进行。

文章里最主要的是提出了commit message的7条原则:

  1. Separate subject from body with a blank line
    在主题和主体部分之间用一个空行间隔开

  2. Limit the subject line to 50 characters
    主题长度应该不超过50个字母

  3. Capitalize the subject line
    主题行开头大写

  4. Do not end the subject line with a period
    主题行不用句号结尾

  5. Use the imperative mood in the subject line
    主题行用祈使语气

  6. Wrap the body at 72 characters
    主体每行不超72个字母

  7. Use the body to explain what and why vs. how
    主体用于解释做了什么和为什么这么做,而不是说怎么做的

为什么要这么做

实际上很多是一些约定俗成的惯常做法,譬如说1、4、5这样的。但如果在commit的时候都按这些原则来写,会让这个项目的commit message看起来很舒服,风格很统一,甚至会提升每一个commit的质量。

在原文章里也有一些关于每一条原则的解释,下面就其中一些展开讨论。

Limit the subject line to 50 characters

把主题行长度尽量限制在50个字母以内,其实是在让每个commit的主题都简洁明了。如果主题太长的话,很有可能会让人不想读这行东西。如果所有commit主题行都很长很长的话,那么在看git log的时候就会变得十分难受。

我们不愿看git log很有可能就是因为其中的commit message都太过冗长,如此一来项目的开发历史就被我们忽视了。对开发历史的忽视,也往往是commit message写得随便的原因之一。如此一来,我们就陷入到了一个死循环当中。

所以实际上,对于commit message的关注,是对项目开发历史的关注。毕竟,在写commit message的时候,我们就相当于在给这个正在开发的项目写史书。每一个commit是这个项目成长的过程,而每一条commit message就是对这个过程的一个记录和注释。

除此之外,正如原文里说的,由于要写一个简洁明了的主题,我们在commit的时候就会思考,这一个commit究竟都做了些什么。有时候,写不出一个50字母内的主题,很可能就是我们往这个commit里塞的东西太多了。

Use the body to explain what and why vs. how

我们可以写commit message想象成写一封电子邮件,主题应该简洁明了,而主体部分则是一些更为详细的细节。

对于commit来说,主体部分并不是必要的。很多时候,主题部分已经把commit的用意都说清楚了,也就不需要主体部分了。

在commit message的主题里,我们应该写的是这个commit做了什么,以及是为什么这么做。至于我们是怎么做的,实际上是在commit本身体现出来的。我们增加或删减的代码以及其中的注释其实就是对我们怎么做最好的解释。所以说,我们应该吧主体部分当作一个补充和总结,说明这些代码都在做什么,这么做的目的是什么。

当我们需要写一个主体的时候,很有可能这个commit涉及的代码改动已经相对较大了。有一个对这个commit做了什么的总结,能够减少别的开发者阅读这个commit时所要耗费的精力,让别人舒服一点。(也让自己在回头看自己做的commit的时候舒服一点。)而对为什么有这个commit的解释是对项目历史的一种充实,将commit时开发者的想法和动机记录下来。这对项目的将来继续开发以及code review是有好处的。在项目的后续开发中,我们可能会遇到这样的情况:遇到一段不熟悉的代码(有可能是自己很久之前写的),觉得很怪,不知道为什么它写成这样。这时候,commit message里面的解释很有可能就帮上大忙。如果commit message都遵循7原则,再配合上git blame这样的工具,我们遇到这种情况时也就不会那么绝望了。

小结

以上是我对git commit message的7原则的简单讨论。更多的是和大家分享一些使用git的良好习惯。非常推荐大家阅读一下原文:How to Write a Git Commit Message