IT技术博客大学习 共学习 共进步

Git commit 注释格式

Fwolf's Blog 2012-12-06 13:59:12 浏览 6,802 次

   Git 本身并没有硬性限制注释的格式,不过,对于多人参与的项目来说, 好的注释风格更加有利于团队合作。 即使是自己用,也应当坚持实用好的注释风格, 一来是对自己的工作历史负责,二来得以养成好的注释习惯。 虽然这里标题说的是 Git,其他源代码控制系统也可以参考的。

   可以先看看一些著名开源项目源代码管理系统当中的提交注释, 其中也有用 SVN 和 Bazaar 的, Apahe 的源码看不到 logview,可能是使用了 CVS 文件格式的原因:

  • Linux Kernel

  • Apache HTTPD

  • Mysql Server 5.6

  • PHP

  • Git

  •    结合其他参考文章,我总结 Git 的 推荐 注释风格如下:

  • 第一行为对改动的简要总结,建议长度不超过 50,用语采用命令式而非过去式。

       Vim 很贴心,在默认配置下,注释的第一行文字颜色是黄色, 超过 50 列之后就变成白色了。

  • 第一行结尾不要英文的句号 . ,中文的就也不要 。 吧。

       为啥?我给 rst2wp 提交的时候,对方也提出了这个要求, 后来查了查,大概原因是,第一行被认为是一个“标题”,也会作为邮件标题, 而标题是不需要标点的。 上面那些开源项目也都遵守了这一规则。 不过也有 例外的

  • 第二行为空行。

       如果配置了自动发送邮件,那么第一行就用来做邮件标题, 第三行开始的内容是邮件正文, 第二行是分隔线,用于区分两者。

  • 第三行开始,是对改动的详细介绍,可以是多行内容,建议长度不超过 72。

       可以包括原因、做法、效果等很多内容,一切你认为与当前改动相关的。 为何是 72 长度呢?因为 git log 输出的时候能显示得比较好看, 前面 4 个空格作为缩进,后面留 4 个空格机动(英文按单词排版)。 Vim 的 gq 命令排版很方便。

       一些项目还对这个部分的内容有特殊要求,比如加一些特定标签什么的。

  • 建议全部英文,首字母大写。如果一定要用中文,请尽量使用 UTF-8 编码。

  • 大项目中,可以用 module: 前缀作为第一行的开头,前缀首字母不必大写。

       前缀的冒号后面跟一个空格比较好看。 为了控制字符串长度,子模块名称可适当缩写,但应保持统一。

  •    我以前喜欢在注释第一行加上 New: Add: Fix: 这样的前缀, 看来也是没有必要了。

       Tips: 提交之前,用 git diff --check 可以检查有无空白字符错误, 比如行尾留有空白什么的。

       BTW,在使用 Git 或者其他 SCM 时,还应当避免下面这些做法:

  • 把 SCM 当做备份工具。

       SCM 是项目/代码管理工具,备份功能只是“福利”。 随意将未完成测试或临时的工作结果进行提交, 不仅破坏日志的“纯洁性”,还不利于日后的浏览、整理、汇总等工作。 在开源项目中这么做的话,没人会接受这种提交。 如果确实需要备份当前工作异地继续的话,可以采用这样的折衷方法:

    $ git commit                # 在本地进行提交
    $ git format-patch -n1      # 导出 Patch
                                # 这个 Patch 就是你的备份
    $ git am Path_To_Patch_File # 如果换了工作地点,导入 Patch
    $ git reset --mixed [hash]  # 撤销提交,保留更改,继续工作
  • 一个改动不一次提交完成。

       “提交”的概念是具有独立的功能、修正等作用。 小可以小到只修改一行,大可以到改动很多文件, 但划分的标准不变,一个提交就是解决一个问题的。

       对格式的修正,不应该和其他功能修补一起提交, 这种情况应该考虑使用 git add --edit , git add -p 也可以用用,更复杂和强大一些。

  • 注释不清晰。

       比如“修正 BUG”、“改错”、“升级”等,等于没说。

  • 参考

  • Pro Git - 5.2 Contributing to a Project - Commit Guidelines

  • A Note About Git Commit Messages

  • Git Commit Messages : 50/72 Formatting

  • Writing good commit messages

  • How to wrap git commit comments?

  • [git/git.git] / Documentation / SubmittingPatches

  • Shiny new commit styles

  • Who-T: On commit messages

  • Commit Comments - Whamcloud Community

  • How I Use Git

  • http://whatthecommit.com/ (要多刷新几次页面,仔细看)

建议继续学习

  1. Git常用命令备忘 (阅读 54,503)
  2. Git log diff config高级进阶 (阅读 24,721)
  3. Git subtree 要不要使用 –squash 参数 (阅读 23,283)
  4. 我的git笔记 (阅读 20,084)
  5. Zend Studio集成Git使用 (阅读 8,861)
  6. GIT和SVN之间的五个基本区别 (阅读 5,742)
  7. Git安装使用手记 (阅读 4,920)
  8. 为何改用Git (阅读 4,860)
  9. 用git部署php站点 (阅读 4,741)
  10. GIT分支管理是一门艺术 (阅读 4,503)