技术头条 - 一个快速在微博传播文章的方式     搜索本站
您现在的位置首页 --> 其他 --> Git commit 注释格式

Git commit 注释格式

浏览:5666次  出处信息

   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常用命令备忘    (阅读:53139)
  2. Git log diff config高级进阶    (阅读:23686)
  3. Git subtree 要不要使用 –squash 参数    (阅读:22224)
  4. 我的git笔记    (阅读:18747)
  5. Zend Studio集成Git使用    (阅读:7967)
  6. GIT和SVN之间的五个基本区别    (阅读:4863)
  7. 为何改用Git    (阅读:3898)
  8. Git安装使用手记    (阅读:3855)
  9. 用git部署php站点    (阅读:3479)
  10. GIT分支管理是一门艺术    (阅读:3397)
QQ技术交流群:445447336,欢迎加入!
扫一扫订阅我的微信号:IT技术博客大学习
© 2009 - 2024 by blogread.cn 微博:@IT技术博客大学习

京ICP备15002552号-1