天天看点

Git 提交的正确姿势:Commit message 编写指南

Git 提交的正确姿势:Commit message 编写指南

Git 每次提交代码,都要写 Commit message(提交说明),否则就不允许提交。

上面代码的<code>-m</code>参数,就是用来指定 commit mesage 的。

如果一行不够,可以只执行<code>git commit</code>,就会跳出文本编译器,让你写多行。

Git 提交的正确姿势:Commit message 编写指南

但是,一般来说,commit message 应该清晰明了,说明本次提交的目的。

Git 提交的正确姿势:Commit message 编写指南

格式化的Commit message,有几个好处。

(1)提供更多的历史信息,方便快速浏览。

比如,下面的命令显示上次发布后的变动,每个commit占据一行。你只看行首,就知道某次 commit 的目的。

Git 提交的正确姿势:Commit message 编写指南

(2)可以过滤某些commit(比如文档改动),便于快速查找信息。

比如,下面的命令仅仅显示本次发布新增加的功能。

(3)可以直接从commit生成Change log。

Change Log 是发布新版本时,用来说明与上一个版本差异的文档,详见后文。

Git 提交的正确姿势:Commit message 编写指南

每次提交,Commit message 都包括三个部分:Header,Body 和 Footer。

其中,Header 是必需的,Body 和 Footer 可以省略。

不管是哪一个部分,任何一行都不得超过72个字符(或100个字符)。这是为了避免自动换行影响美观。

Header部分只有一行,包括三个字段:<code>type</code>(必需)、<code>scope</code>(可选)和<code>subject</code>(必需)。

(1)type

<code>type</code>用于说明 commit 的类别,只允许使用下面7个标识。

feat:新功能(feature)

fix:修补bug

docs:文档(documentation)

style: 格式(不影响代码运行的变动)

refactor:重构(即不是新增功能,也不是修改bug的代码变动)

test:增加测试

chore:构建过程或辅助工具的变动

如果<code>type</code>为<code>feat</code>和<code>fix</code>,则该 commit 将肯定出现在 Change log 之中。其他情况(<code>docs</code>、<code>chore</code>、<code>style</code>、<code>refactor</code>、<code>test</code>)由你决定,要不要放入 Change log,建议是不要。

(2)scope

<code>scope</code>用于说明 commit 影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同。

(3)subject

<code>subject</code>是 commit 目的的简短描述,不超过50个字符。

以动词开头,使用第一人称现在时,比如<code>change</code>,而不是<code>changed</code>或<code>changes</code>

第一个字母小写

结尾不加句号(<code>.</code>)

Body 部分是对本次 commit 的详细描述,可以分成多行。下面是一个范例。

有两个注意点。

(1)使用第一人称现在时,比如使用<code>change</code>而不是<code>changed</code>或<code>changes</code>。

(2)应该说明代码变动的动机,以及与以前行为的对比。

Footer 部分只用于两种情况。

(1)不兼容变动

如果当前代码与上一个版本不兼容,则 Footer 部分以<code>BREAKING CHANGE</code>开头,后面是对变动的描述、以及变动理由和迁移方法。

(2)关闭 Issue

如果当前 commit 针对某个issue,那么可以在 Footer 部分关闭这个 issue 。

也可以一次关闭多个 issue 。

还有一种特殊情况,如果当前 commit 用于撤销以前的 commit,则必须以<code>revert:</code>开头,后面跟着被撤销 Commit 的 Header。

Body部分的格式是固定的,必须写成<code>This reverts commit &amp;lt;hash&gt;.</code>,其中的<code>hash</code>是被撤销 commit 的 SHA 标识符。

如果当前 commit 与被撤销的 commit,在同一个发布(release)里面,那么它们都不会出现在 Change log 里面。如果两者在不同的发布,那么当前 commit,会出现在 Change log 的<code>Reverts</code>小标题下面。

安装命令如下。

然后,在项目目录里,运行下面的命令,使其支持 Angular 的 Commit message 格式。

以后,凡是用到<code>git commit</code>命令,一律改为使用<code>git cz</code>。这时,就会出现选项,用来生成符合格式的 Commit message。

Git 提交的正确姿势:Commit message 编写指南

然后,每次<code>git commit</code>的时候,这个脚本就会自动检查 Commit message 是否合格。如果不合格,就会报错。

生成的文档包括以下三个部分。

New features

Bug fixes

Breaking changes.

每个部分都会罗列相关的 commit ,并且有指向这些 commit 的链接。当然,生成的文档允许手动修改,所以发布前,你还可以添加其他内容。

上面命令不会覆盖以前的 Change log,只会在<code>CHANGELOG.md</code>的头部加上自从上次发布以来的变动。

如果你想生成所有发布的 Change log,要改为运行下面的命令。

为了方便使用,可以将其写入<code>package.json</code>的<code>scripts</code>字段。

以后,直接运行下面的命令即可。

上一篇: kmp算法

继续阅读