Git - 如何写好你的提交信息?

7

前言

平时我们在提交的时候,肯定是会对自己所做的事情做一些或多或少的说明。但怎么写好就不是那么容易了。于是就跑到github上看看人家是怎么写的,或者Google下,看看有没有什么好的实践经验。特此做了总结,希望能抛砖引玉。

坏栗子

我们从坏栗子开讲,这样就有的对比了,也好对号入座。正如这个命令,10个人有9个绝对写过。

git commit -m "Fix login bug"

我们还会这么写。

git commit -am "Fix login bug"

也会这样。

git commit -am "Fix bug!"

很明显,你是在说这个提交是在修改一个登录的BUG,因为没有拼写错误所以我能大概看明白。但我要是管理员我就难过了,会有一大堆的问题席卷而来。心理会想大哥,你修得这个BUG是哪个?哪个登录的?什么样的?怎么改的?。~~然后你后脊梁骨发凉,因为有人在骂街。~~

你也可以这么想,管理员可以耐着性子把我的修改看完,这样就不就行了?不好意思,这样的话管理员会疯的,所以不可以这么做。

提倡的做法

粒度

说的是做的修改的粒度。如果你一天做了很多的修改,但是就只提交了一次,那么你的粒度就有点大了。这样在你描述你的行为的时候就会显得模糊,如果你详细描述的话,提交信息会变得长篇大论。但也不要做一点提交一点,这样粒度就会变得太小,会导致一天到晚在写提交信息,没有必要。

在我看来,这个事情真的只能凭感觉提交,用经验来做判断。因为一个BUG可能可大可小,大的话,你就得分割修复。如果小,那么就一次提交修复就可。

粒度的掌握绝对会影响你的提交信息,因为二者是一一对应的。

段落

还记得上学的时候,写英语作文的三段法吗?和那个差不多,开头阐明观点,中间论述观点,最后总结。
这里我们把提交信息也分为三段,具体如下。

refactor($browser): remove private polling mechanism

The only feature of Angular using this mechanism was `$cookies`,
which no longer mirrors the browser cookie values and so does not
need to poll.

Closes #11222

感觉如何?该有的有,该没得没。做了什么?为什么这么做?影响了什么?可以说是一目了然。

现在我们来说说为什么这样做好。

开头

首先,开头部分单起一行,这在git中就会做为默认显示的部分,在你查看提交信息的时候就会显示这行,其他的部分则在进一步查看的时候才会显示。

你可以指定模块,或者说明动作(Add - Update - Delete)。

中间

其次,在中间的部分就是你的详细说明,这个时候就要你做一个全面的说明了。说说你大概搞了什么东西,是怎么搞的。

最后

最后的这句话有妙用,他会根据你提到的issue编号自动地关闭你的issue。当然这个和你使用的git服务端有关系,在gitlab中会用Fix来进行关闭。实现了一定的自动化,然后你的团队的成员就会受到通知,多么美好。

实际运用

三段式在通常情况下是标配,当然也有例外。在没有相关issue的时候,最后部分可以省略掉。在标题解释了所有的事情的时候,中间的部分可以省略,如你重命名了一个文件,或者是删除了一个文件的时候。所以说只写一个标题也是可以的,前提是够准确。

像是这样

Rename cropper.css -> cropper.scsss

或是

Add calendar setting file

宽度

是的,是宽度,不是长度。和代码一样,如果你平时注意的话,就不要让你的代码在一行上超过80,不然谁读代码都不好受,包括你自己。所以提交信息的宽度也有限制。

分别是标题不要超过50,内容部分不要超过70。你可能会想,写的时候还要查字数好难过。其实稍微配置一下就可以了,具体操作会在后面说道。

统一

只要统一了格式,那么团队的各位都会明白你要表达的意思,所以你完全可以撇开上面的建议自己另起一套。

规范提交信息的格式的目的就是能快速准确的表达信息,只要达到了这个目的就可以。习惯而已。

小技巧

配置提交信息的宽度

我随时可能忘记宽度的限制,所以要做一个设置,这样就能自动的对提交信息做格式化了。对于这样的设置要取决于你的git默认选择的编辑器是什么,一般都是vim什么的。

~/.vimrc 里加上下面的命令,然后就会有神奇的事情发生了。

例如我用webstorm就集成了这个功能,我也就没有太折腾。

autocmd Filetype gitcommit setlocal spell textwidth=72

不要使用 -m 或者 --message 做提交

这个命令让你能够在一次操作中就把信息提交了。看起来很好,但事实上就是这个命令让大家懒惰了。真正好的提交信息真的很难用用一句话说好,你不是在给一行代码做注释,你是在给一连串的改变做出解释。做了什么?为什么这么做?影响了什么?至少得把这三个问题给回答了。当你认知在编辑器里写提交信息的时候,你会想起很多事,经验之谈。

好栗子

其实大家也是满随意的,但又很统一。

Jquery

shellCSS: Restore the hack to get pixels for .css('width') etc.

This hack turns out to be needed by Android 4.0-4.3.

Add a support test so that the hack is invoked only where needed.

Refs gh-1815
Refs gh-1820
Closes gh-1842

angular

fix(filterFilter): Fix filtering using an object expression when the …
…filter value is undefined

Fixes #10419
Closes #10424

backbone

Merge pull request #3443 from jridgewell/history-root

History's root

react

Sync out another jsx transform test.

We added this test internally and it never got added here. We haven't broken it
with any transforms *yet* but it's still good to actually run all of our tests
here too.

结语

不一定要把上面提到的所有的要求都强制的推给团队的所有人,要因地制宜,但一定要规范。正如代码的注释,合适就好。但这个合适要让人明白和清楚,没有额外的废话。

没有最好的,只有合适的。

望大家看完可以做点评。

相关

你可能感兴趣的

snriud · 2016-11-11

感谢分享,早就发现自己的好多提交写得模模糊糊的。

回复

载入中...