目录:
提交操作规范
为了保持分支提交历史的清晰、独立,在提交更改时,我们应做到:
- 每一个提交都应该是一个完整、独立的变更单元;
- 撰写符合提交说明规范 的提交说明信息;
- 对于修复错别字、添加遗漏的更改等等之类的提交应与对应的提交合并,不应为其创建单独的提交;
多个提交合并成一个的各种方法请看Git中合并多个提交的各种方法
提交说明规范
Git 每次提交代码,都必须要写 提交说明; Git 对 提交说明 的格式是没有限制的,你想怎么写就怎么写,如下:
但是,类似这种没有格式的提交说明有以下缺点:
- 不能很快分辨出提交的代码是增加了新功能、还是修复了bug、还只是更新了文档等等;
- 不能有效地过滤某一类提交,比如:只想查看修复bug类的提交;
- 不能根据需要过滤并导出提交信息,作为变更日志:比如,应用的升级的新功能说明、问题修复说明等等;
为了 方便 查看、过滤 提交说明,我需要将提交说明格式化、规范化;目前,有多种 提交说明 的写法规范。但我推荐 Angular提交说明规范,这是目前使用最广的写法,比较合理和系统化,并且有配套的工具。
关于 Angular提交说明规范 的详细文章请见:
下面是我对 Angular提交说明规范 一个汇总描述;
Angular提交说明规范
Angular提交说明的格式如下:
-
[]
表示可选的; -
<>
表示必须的;
<Type>[(Scope)]:<Subject>
<空一行>
[Body]
<空一行>
<Footer>
只有
Type
和Subject
是必须的,其它的都是可选的;提交说明包括三个部分:Header(第一行)、Body(可选) 和 Footer(可选),用空行分隔;其中 Body、Footer 都是可选的,可以省略;
任何一行都不得超过72、100个字符;这是为了避免自动换行影响美观
-
Header:只占第一行,包括三个字段:Type(必需)、Scope(可选)和 Subject(必需);
-
Type:必需;用于说明提交的类别,只允许使用下面7个标识:
- feat:新功能(feature)
- fix:修补bug
- doc:文档(documentation),(很多规范里使用的是复数
docs
,但我更建议使用doc
) - style: 格式(不影响代码运行的变动)
- refactor:重构(即不是新增功能,也不是修改bug的代码变动)
- test:增加测试
- chore:构建过程或辅助工具的变动
如果type为feat和fix,则该 commit 将肯定出现在 Change log 之中。其他情况(doc、chore、style、refactor、test)由你决定,要不要放入 Change log,建议是不要。
提示: 为了醒目,也可以为每个 Type 分别指定一个 Emoji 表情,将其放在 Type 前面 或 后面; Scope:可选;用于说明提交的影响范围,比如数据层、控制层、视图层等等,视项目不同而不同。
-
Subject:提交目的 的简短描述;要求如下:
- 不超过50个字符。
- 以动词开头,使用第一人称现在时,比如 change,而不是 changed 或 changes
- 第一个字母小写
- 结尾不加句号
.
-
-
Body:对本次提交的详细描述,
- 可以分成多行。
- 使用第一人称现在时,比如使用change而不是changed或changes。
- 应该说明代码变动的动机,以及与以前行为的对比。
-
Footer:Footer 部分只用于两种情况。
- 不兼容变动:如果当前代码与上一个版本不兼容,则 Footer 部分以
BREAKING CHANGE
开头,后面是对变动的描述、以及变动理由和迁移方法。 - 关闭 Issue:如果当前 提交 针对某个 issue 的,那么可以在 Footer 部分用
Closes #234
关闭这个 issue ;也可以用Closes #123, #245, #992
一次关闭多个 issue ;
- 不兼容变动:如果当前代码与上一个版本不兼容,则 Footer 部分以
-
特殊情况: 如果当前 提交 用于撤销以前的 提交,则:
- Header 必须以
revert:
开头,后面跟着被撤销的提交的 Header。 - Body 部分的格式是固定的,必须写成
This reverts commit <hash>.
,其中的hash
是被撤销的 提交 的 SHA 标识符。
如果当前提交 与 被撤销的 提交,在同一个发布(release)里面,那么它们都不会出现在 Change log 里面。如果两者在不同的发布,那么当前 commit,会出现在 Change log 的Reverts
小标题下面。
- Header 必须以