在我们开始看这个例子之前,我们先快速的了解一下commit注释信息的规范问题。
这里有个很好的commit指导规范可以帮助用户轻松的使用git提交自己的代码,就是Git工程自身提供了一个文档。里面列举了很多关于commit patches的注意事项,你可以在Git源码的Documentation/SubmittingPatches目录下找到它。
一、你不能提交仅含空格的冗余修改。
Git提供了一个很简单的方法去检查空格这样的字母信息,在commit之前先运行
git diff --check
,这将很容易标示出不必要的空格信息。
这就是 git diff –check 的输出结果。
之所以要在commit前检查多余的空格,是为避免影响到小组里面的其他开发者。
二、每一次的commit都应该是一个逻辑上独立的完整修改。
你应该尝试让你的修改变得容易区分, 而不是修改了一整个星期的代码后然后作为一次修改提交。即使你不能每次修改都及时独立提交,你也应该保证在提交时以issue为单位进行commit,并且写上有用的修改信息。如果一些问题涉及到修改同一个文件,使用
git add --patch
命令去部分预存(stage)文件(在“交互预存”有详细的介绍这种方法)。只要你用上面的方法一次提交修改,和分多次提交的结果是一样的,这也使得项目中的其他开发人员可以更轻松的评审你的代码。这个方法也使得拉取代码到本地或者在需要的时候撤销某个修改集。“重写记录”描述了一组好用的关于重写记录和交互式预存(stage)文件的Git技巧,使用这些工具可以帮助制作一个清晰易于理解的提交记录。
三、不要忘了最重要的提交注释。
创建高质量的提交注释的习惯会使得Git的使用变得轻松无比。这里有个常用的提交注释的模板可以参考:
你的提交注释应该首先是单独的一行,50字符以内,准确的描述你的修改;紧接着留下一个空行;另起一行,你就可以开始写更详细的说明性信息。
Git要求提交者应该在详细说明中描述你修改的动机和软件修改前后的行为对比,这是个很值得参考。 提交者被建议采用祈使语态来描述这些信息,换句话说其实应该是要求而不是建议。使用”Add tests for “这样的形式,而不是使用”I added tests for”或者”Adding tests for”。这里有一个有Tim Pope写的模板:
Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to
about 72 characters or so. In some contexts, the first
line is treated as the subject of an email and the rest of
the text as the body. The blank line separating the
summary from the body is critical (unless you omit the body
entirely); tools like rebase can get confused if you run
the two together.
Further paragraphs come after blank lines.
Bullet points are okay, too
Typically a hyphen or asterisk is used for the bullet,
preceded by a single space, with blank lines in
between, but conventions vary here
如果所有提交注释都参照如此,对于你和你的团队使用Git都将是无比便利的。一个使用Git管控的工程如果有很好的格式化的提交注释,开发人员可以使用
git log --no-merges
去查看到漂亮易读的规范化的提交记录。