写出好的 commit message

Git · victor · Created at · Last by acgtyrant Replied at · 20591 hits
449
本帖已被设为精华帖!

为什幺要关注提交信息

  • 加快 Reviewing Code 的过程
  • 帮助我们写好 release note
  • 5年后帮你快速想起来某个分支,tag 或者 commit 增加了什么功能,改变了哪些代码
  • 让其他的开发者在运行 git blame 的时候想跪谢
  • 总之一个好的提交信息,会帮助你提高项目的整体质量

基本要求

  • 第一行应该少于50个字。 随后是一个空行 第一行题目也可以写成:Fix issue #8976
  • 喜欢用 vim 的哥们把下面这行代码加入 .vimrc 文件中,来检查拼写和自动折行
autocmd Filetype gitcommit setlocal spell textwidth=72
  • 永远不在 git commit 上增加 -m <msg>--message=<msg> 参数,而单独写提交信息

一个不好的例子 git commit -m "Fix login bug"

一个推荐的 commit message 应该是这样:

Redirect user to the requested page after login

https://trello.com/path/to/relevant/card

Users were being redirected to the home page after login, which is less
useful than redirecting to the page they had originally requested before
being redirected to the login form.

* Store requested path in a session variable
* Redirect to the stored location after successfully logging in the user
  • 注释最好包含一个连接指向你们项目的 issue/story/card。一个完整的连接比一个 issue numbers 更好
  • 提交信息中包含一个简短的故事,能让别人更容易理解你的项目

注释要回答如下信息

为什么这次修改是必要的?

要告诉 Reviewers,你的提交包含什么改变。让他们更容易审核代码和忽略无关的改变。

如何解决的问题?

这可不是说技术细节。看下面的两个例子:

Introduce a red/black tree to increase search speed
Remove <troublesome gem X>, which was causing <specific description of issue introduced by gem>

如果你的修改特别明显,就可以忽略这个。

这些变化可能影响哪些地方?

这是你最需要回答的问题。因为它会帮你发现在某个 branch 或 commit 中的做了过多的改动。一个提交尽量只做1,2个变化。

你的团队应该有一个自己的行为规则,规定每个 commit 和 branch 最多能含有多少个功能修改。

小提示

  • 使用 fix, add, change 而不是 fixed, added, changed
  • 永远别忘了第2行是空行
  • Line break 来分割提交信息,让它在某些软件里面更容易读
  • 请将每次提交限定于完成一次逻辑功能。并且可能的话,适当地分解为多次小更新,以便每次小型提交都更易于理解。

例子

Fix bug where user can't signup.

[Bug #2873942]

Users were unable to register if they hadn't visited the plans
and pricing page because we expected that tracking
information to exist for the logs we create after a user
signs up.  I fixed this by adding a check to the logger
to ensure that if that information was not available
we weren't trying to write it.
Redirect user to the requested page after login

https://trello.com/path/to/relevant/card

Users were being redirected to the home page after login, which is less
useful than redirecting to the page they had originally requested before
being redirected to the login form.

* Store requested path in a session variable
* Redirect to the stored location after successfully logging in the user

本文参考阅读

共收到 50 条回复
3469

git commit -am "阅"

460

已阅 哈
经常 git commit -m "Fix login bug"

5130
song940 · #3 ·

git commit -am "已阅"

96

这样写commit message的难度可能会比写code的难度还大。。。大多数程序员只能呵呵了

202
xds2000 · #5 ·

git commit -am '我们就是这么做的,效果很好' --reuse HEAD

1638

这篇文章真好。多谢

244

我会告诉你们我曾经在commit里写了一篇bug分析的blog么

449
victor · #9 ·

#8楼 @fsword 膝盖已碎,不过赶不上用符号画小人的吧

827
chairy11 · #10 ·

其实我真的想用中文message,这样可以的吗?

1573
nightire · #11 ·

#10楼 @chairy11 当然可以

449

#10楼 @chairy11 团队如果都是中国人,当然用中文写了。就是大家的工具得协调一下。要不你写完了中文注释,小伙伴们看你的注释是乱码就不好了。

827
chairy11 · #13 ·

#11楼 @nightire 是嘛?那我问问我合作哥们,他同意我就用中文了……要不看git log一看英文我大脑自动忽略……
#12楼 @Victor 目前都中国人,虽然小伙伴身在美国,哈哈哈哈,我问问他……

96

commit message还是非常难写的,除了typo什么的,都是对抽象的抽象啊 ...

5255

果断顶一个,每次写commit message都异常痛苦,肯定是因为我太懒了……

96

请问为什么要在“第一行随后空一行”?

5610
jarorwar · #17 ·

#6楼 @aptx4869 很牛啊~

522

2564
kikyous · #20 ·

update

728

赞,最近确实感觉自己的commit 有问题全是 git commit -a -m 'xxx''

简短的一行,过一段时间后,自己也不知道提交的什么了

后以争取不再-a -m了。。。

96

#16楼 @imwilsonxu 空行用于区分commit信息的title和body,有的时候可能只需要显示title,有的时候则希望看到详细的信息,没有空行就没法区分了

比如 git log --oneline就只显示commit message的title,又比如在github上 在commit list页面,默认也是只显示title

96
murphy · #23 ·

非常好,这样开发更专业一些。

7292
cestivan · #24 ·

点赞,一直都是

一个不好的例子 git commit -m "Fix login bug"

如果在命令行中怎么编辑多行commit message咧……?

5907

#24楼 @cestivan 提交的时候别加 -m,这样就会出现一个编辑页面

7292
cestivan · #26 ·

#25楼 @mozillazg 谢提点

96
loddit · #27 ·

#8楼 @fsword 还是来膜拜一下吧

7482
fantasy · #28 ·

一般都写 git commit -m 'update' o(╯□╰)o

96
zhlwish · #29 ·

原来这是样写的,拜读!

1638

我看到一种不错的 git message 格式: 50/72 Formatting

觉得不错,拿来分享。

Provide a brief description of the change in the first line.

  • Insert a single blank line after the first line.
  • Provide a detailed description of the change in the following lines, breaking paragraphs where needed.
  • The first line should be limited to 50 characters and should not end with a period.
  • Subsequent lines should be wrapped at 72 characters.
  • Put the 'Change-id', 'Closes-Bug #NNNNN' and 'blueprint NNNNNNNNNNN' lines at the very end.

For example

Switch libvirt get_cpu_info method over to use config APIs    

The get_cpu_info method in the libvirt driver currently uses    XPath queries to extract information from the capabilities    XML document. Switch this over to use the new config class    LibvirtConfigCaps. Also provide a test case to validate    the data being returned.    

Closes-Bug: #1003373    
Implements: blueprint libvirt-xml-cpu-model    
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

read more

https://wiki.openstack.org/wiki/GitCommitMessages

449

#16楼 @imwilsonxu 转述别人的话:可以很方便的用工具把commit注释变成email通知,第一行作为标题,剩下的部分就作email的正文。

4113
cod7ce · #32 ·

好吧,我长时间独自开发,已经养成了 git ci -m "message" 的习惯了,这咋整啊~

96

git commit -am "up"

15
huobazi · #35 ·

经常 git commit -m "update" haa~~

96
jjx · #36 ·

git commit -m“update”

96
oec2003 · #37 ·

时间越长就会觉得用处越大

7659

记录花费时间2d 3h

othermsg #time 2d 3h

关联任务号或bug号1234

othermsg 项目关键字-1234

提交的同时,有代码审查,审查人user1 user2

othermsg +review @user1 @user2

提交的同时,和1112号代码审查相关联

othermsg +review 项目代码审查关键字-1112

任何项目管理工具(即使使用文本文件管理)都会很容易解析上述信息,无论用的是git还是svn

另外更详细的信息会在代码中或者项目管理工具中出现,不需要提交太多"othermsg",一两句概述的话或单词说清楚就行.

10270
egg_show · #39 ·

最新在学习ruby,尝试在做一个论坛,我是来看回复效果的

487

这个实践是好的。不过有时候确实太懒了,要改了。

1986

mark,得改改习惯了

2454
nate_yu · #42 ·

Task #123 task name
* change xxxx
* fix xxx

3760

#40楼 @blackanger 老师,你总说 确实太懒了 ,看来是真的,嘿嘿

487

#43楼 @perfectfoolish 真的是因为「懒」。

10316
chiangdi · #45 ·

使用 fix, add, change 而不是 fixed, added, changed

请问这是什么原因呢?

不好意思,我挖坟了...

449
victor · #46 ·

#45楼 @chiangdi
如果你使用的是 github,那么根据 https://help.github.com/articles/closing-issues-via-commit-messages 的解释,在 github issue 系统中,fix 和 fixed 都会关 close issue。这里看来并无不同。

至于你问为什么不用 fixed ,我想更多的原因是一种习惯性约定,当执行 merge 和 revert 的时候能让 commit message 更符合语义?

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug." This convention matches up with commit messages generated
by commands like git merge and git revert.

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

我是从这里看到的。如果有错漏,请一定帮忙指正,谢谢。

10316
chiangdi · #47 ·

#46楼 @Victor

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug." This convention matches up with commit messages generated
by commands like git merge and git revert.

这句话的意思应该是:使用祈使语气写 commite message。 因为很多命令( 比如 git merge 和 git revert ) 生成的 commit messages 都是这样的,这样比较一致吧。

应该是这样的。

449
victor · #48 ·

#47楼 @chiangdi 谢谢

6829
hiveer · #49 ·

always git commit -m "just on line"

8265

#4楼 @loveky 如果感觉写提交消息比代码还困难,说明逻辑变动本身可能有很大的问题,毕竟开发者都搞不清楚他到底做了啥。除非开发者语言能力本身就低下。

需要 Sign In 后方可回复, 如果你还没有账号请点击这里 Sign Up