Git 本身并没有硬性限制注释的格式,不过,对于多人参与的项目来说, 好的注释风格更加有利于团队合作。 即使是自己用,也应当坚持实用好的注释风格, 一来是对自己的工作历史负责,二来得以养成好的注释习惯。 虽然这里标题说的是 Git,其他源代码控制系统也可以参考的。
简而言之:第一行一句话改过你做的修改(少于50个字)、第二行空行、剩余行请描述为什么你做的这些改动是好的。
可以写成: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 的质量,以致提高每个功能的质量。
永远别忘了第2行是空行。第三行开始主要回答如下信息:
这是你最需要回答的问题。因为它会帮你发现在某个 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默认的编辑器,其中的“editor”替换成你自己的编辑器,如Vim、Emacs、gedit、subl等:
git config --global core.editor "editor -w"
然后,在做提交的时候使用命令不要写”-m”参数,直接写成git commit这样子就行,这样就会自动打开你刚才指定的编辑器,你可以在里面添加大段注释。 设置使用vim编辑,git config —global core.editor vim