Git commit 之注释的技巧

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

Git commit 提交注释信息的作用

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

Git注释的基本要求

简而言之:第一行一句话改过你做的修改(少于50个字)、第二行空行、剩余行请描述为什么你做的这些改动是好的。

commit 第一行题目

可以写成:Fix issue #8976 (使用 fix, add, change ) 或者:

    Mod: remove unused code, 表示修改(Modify)
    Add: a new module to have faster process, 表示新增(Add)
    Rem: deprecate unused modules, 表示移除(Remove)
    Ref: improved the implementation of module X, 表示重构(Refactory)

如果一个Git commit 里的内容无法用上述任意一种语句陈述,应该怎么办?那说明你的commit应该被拆分成多个小部分。 估计很多开始使用 git 的同学把握不住什么时候应该 commit, 什么时候又应该把未提交的 commits 都 push 上去,一般 : 提交描述 = 提交的修改,这样提交的描述才精准。 git 的提交描述可以是多行的,描述的内容可以非常详细, 在不填写描述的情况下提交 git 弹出的这个对话框就介绍了这一点。

因此请将每次提交限定于完成一次逻辑功能。并且可能的话,适当地分解为多次小更新,以便每次小型提交都更易于理解。commit 是一次目的性明确的改动, 但改动的地方不宜过多(否则看起来会晕), 我们应该将一个功能分解为几个 commit, 一个 commit 负责一个部分的改动, 当这几个 commit 都完成了再 push。这样做是因为没有 push 上去的提交保存在本地, 万一有什么当时没想好的,还可以修改 (未 push 的 commit 是有办法修改的,后续文章会讲), 要是 push 上去了,最好就不要改了, 而是用新的 commit 来弥补 (git 允许冲掉以前 push 的变更:git push -f)。照以上的建议来做的话,可以保证每个 commit 的质量,以致提高每个功能的质量。

commit 第三行及后续剩余行

永远别忘了第2行是空行。第三行开始主要回答如下信息:

  1. 为什么这次修改是必要的? 要告诉 Reviewers,你的提交包含什么改变。让他们更容易审核代码和忽略无关的改变。
  2. 如何解决的问题?
  3. 这些变化可能影响哪些地方?

这是你最需要回答的问题。因为它会帮你发现在某个 branch 或 commit 中的做了过多的改动。一个提交尽量只做1,2个变化。 你的团队应该有一个自己的行为规则,规定每个 commit 和 branch 最多能含有多少个功能修改。用 Line break 来分割提交信息,让它在某些软件里面更容易读 不用 git commit 上增加 -m <msg>--message=<msg> 参数,而单独写提交信息。 一个推荐的 commit message 应该是这样:

Redirect user to the requested page after login

https://www.higrid.net/

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 更好 提交信息中包含一个简短的故事,能让别人更容易理解你的项目

修改已经git commit的注释信息

首先,使用下面这个命令来设置git默认的编辑器,其中的“editor”替换成你自己的编辑器,如Vim、Emacs、gedit、subl等:

git config --global core.editor "editor -w"

然后,在做提交的时候使用命令不要写”-m”参数,直接写成git commit这样子就行,这样就会自动打开你刚才指定的编辑器,你可以在里面添加大段注释。 设置使用vim编辑,git config —global core.editor vim

  • 执行’git commit --amend’ 修改最后一次提交的信息
  • 执行’git push origin +master:master’ 强制更新远程服务器上的commit 尽量慎用此方法

随机文章 Random Posts