Git 提交的正确姿势:Commit message 编写指南
http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html
Git 每次提交代码,都要写 Commit message(提交说明),否则就不允许提交。
$ git commit -m "hello world"
上面代码的-m
参数,就是用来指定 commit mesage 的。
如果一行不够,可以只执行git commit
,就会跳出文本编辑器,让你写多行。
$ git commit
但是,一般来说,commit message 应该清晰明了,说明本次提交的目的。
目前,社区有多种 Commit message 的写法规范。本文介绍Angular 规范(见上图),这是目前使用最广的写法,比较合理和系统化,并且有配套的工具。
一、Commit message 的作用
格式化的Commit message,有几个好处。
(1)提供更多的历史信息,方便快速浏览。
比如,下面的命令显示上次发布后的变动,每个commit占据一行。你只看行首,就知道某次 commit 的目的。
$ git log <last tag> HEAD --pretty=format:%s
(2)可以过滤某些commit(比如文档改动),便于快速查找信息。
比如,下面的命令仅仅显示本次发布新增加的功能。
$ git log <last release> HEAD --grep feature
(3)可以直接从commit生成Change log。
Change Log 是发布新版本时,用来说明与上一个版本差异的文档,详见后文。
二、Commit message 的格式
每次提交,Commit message 都包括三个部分:Header,Body 和 Footer。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
其中,Header 是必需的,Body 和 Footer 可以省略。
不管是哪一个部分,任何一行都不得超过72个字符(或100个字符)。这是为了避免自动换行影响美观。
2.1 Header
Header部分只有一行,包括三个字段:type
(必需)、scope
(可选)和subject
(必需)。
(1)type
type
用于说明 commit 的类别,只允许使用下面7个标识。
- feat:新功能(feature)
- fix:修补bug
- docs:文档(documentation)
- style: 格式(不影响代码运行的变动)
- refactor:重构(即不是新增功能,也不是修改bug的代码变动)
- test:增加测试
- chore:构建过程或辅助工具的变动
如果type
为feat
和fix
,则该 commit 将肯定出现在 Change log 之中。其他情况(docs
、chore
、style
、refactor
、test
)由你决定,要不要放入 Change log,建议是不要。
(2)scope
scope
用于说明 commit 影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同。
(3)subject
subject
是 commit 目的的简短描述,不超过50个字符。
- 以动词开头,使用第一人称现在时,比如
change
,而不是changed
或changes
- 第一个字母小写
- 结尾不加句号(
.
)
2.2 Body
Body 部分是对本次 commit 的详细描述,可以分成多行。下面是一个范例。
More detailed explanatory text, if necessary. Wrap it to
about 72 characters or so. Further paragraphs come after blank lines. - Bullet points are okay, too
- Use a hanging indent
有两个注意点。
(1)使用第一人称现在时,比如使用change
而不是changed
或changes
。
(2)应该说明代码变动的动机,以及与以前行为的对比。
2.3 Footer
Footer 部分只用于两种情况。
(1)不兼容变动
如果当前代码与上一个版本不兼容,则 Footer 部分以BREAKING CHANGE
开头,后面是对变动的描述、以及变动理由和迁移方法。
BREAKING CHANGE: isolate scope bindings definition has changed. To migrate the code follow the example below: Before: scope: {
myAttr: 'attribute',
} After: scope: {
myAttr: '@',
} The removed `inject` wasn't generaly useful for directives so there should be no code using it.
(2)关闭 Issue
如果当前 commit 针对某个issue,那么可以在 Footer 部分关闭这个 issue 。
Closes #234
也可以一次关闭多个 issue 。
Closes #123, #245, #992
2.4 Revert
还有一种特殊情况,如果当前 commit 用于撤销以前的 commit,则必须以revert:
开头,后面跟着被撤销 Commit 的 Header。
revert: feat(pencil): add 'graphiteWidth' option This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
Body部分的格式是固定的,必须写成This reverts commit <hash>.
,其中的hash
是被撤销 commit 的 SHA 标识符。
如果当前 commit 与被撤销的 commit,在同一个发布(release)里面,那么它们都不会出现在 Change log 里面。如果两者在不同的发布,那么当前 commit,会出现在 Change log 的Reverts
小标题下面。
三、Commitizen
Commitizen是一个撰写合格 Commit message 的工具。
安装命令如下。
$ npm install -g commitizen
然后,在项目目录里,运行下面的命令,使其支持 Angular 的 Commit message 格式。
$ commitizen init cz-conventional-changelog --save --save-exact
以后,凡是用到git commit
命令,一律改为使用git cz
。这时,就会出现选项,用来生成符合格式的 Commit message。
四、validate-commit-msg
validate-commit-msg 用于检查 Node 项目的 Commit message 是否符合格式。
它的安装是手动的。首先,拷贝下面这个JS文件,放入你的代码库。文件名可以取为validate-commit-msg.js
。
接着,把这个脚本加入 Git 的 hook。下面是在package.json
里面使用 ghooks,把这个脚本加为commit-msg
时运行。
"config": {
"ghooks": {
"commit-msg": "./validate-commit-msg.js"
}
}
然后,每次git commit
的时候,这个脚本就会自动检查 Commit message 是否合格。如果不合格,就会报错。
$ git add -A
$ git commit -m "edit markdown"
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" ! was: edit markdown
五、生成 Change log
如果你的所有 Commit 都符合 Angular 格式,那么发布新版本时, Change log 就可以用脚本自动生成(例1,例2,例3)。
生成的文档包括以下三个部分。
- New features
- Bug fixes
- Breaking changes.
每个部分都会罗列相关的 commit ,并且有指向这些 commit 的链接。当然,生成的文档允许手动修改,所以发布前,你还可以添加其他内容。
conventional-changelog 就是生成 Change log 的工具,运行下面的命令即可。
$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w
上面命令不会覆盖以前的 Change log,只会在CHANGELOG.md
的头部加上自从上次发布以来的变动。
如果你想生成所有发布的 Change log,要改为运行下面的命令。
$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0
为了方便使用,可以将其写入package.json
的scripts
字段。
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"
}
}
以后,直接运行下面的命令即可。
$ npm run changelog
(完)
Git 提交的正确姿势:Commit message 编写指南的更多相关文章
- (转)Git 提交的正确姿势:Commit message 编写指南
Git 每次提交代码,都要写 Commit message(提交说明),否则就不允许提交. $ git commit -m "hello world" 上面代码的-m参数,就是用来 ...
- Git 提交的正确姿势
Git 提交的正确姿势:Commit message 编写指南 SCOP范围 middleware core config plugin test type范围 Git 每次提交代码,都要写 Comm ...
- git中Please enter a commit message to explain why this merge is necessary.
Please enter a commit message to explain why this merge is necessary. 请输入提交消息来解释为什么这种合并是必要的 git 在pul ...
- git提示Please enter a commit message to explain why this merge is necessary
Please enter a commit message to explain why this merge is necessary. 请输入提交消息来解释为什么这种合并是必要的(提交信息) gi ...
- git修改已经push的commit message
git中修改上一次提交的commit的message git commit --amend -m "你的新的注释" git push -f 多个commit https://www ...
- IDEA 中 Git Commit message 编写
IDEA安装插件 Git Commit Template 1. HeaderHeader的部分只有一行,包括三个字段: type(必需), scope(可选), subject(必需) 对应到idea ...
- Markdown笔记(git提交带有emoji的commit描述)
用法:> git commit -m ' :tada: initial ' emoji来源:> ![gitmoji](https://gitmoji.carloscuesta.me/sta ...
- Git提交代码冲突:commit your changes or stash them before you can merge.
用git pull拉取远程分支代码时候遇到如下问题: error: Your local changes to the following files would be overwritten by ...
- 查看,添加和删除GIT配置的正确姿势
查看GIT所有配置的命令: git config --list 查看GIT全局配置的命令: git config --global --list 添加GIT全局配置(HTTPS代理) git conf ...
随机推荐
- 按渠道计算 PV 和 UV
按渠道计算 PV 和 UV: ------------------按指定channel_id按月求PV.UV------------ drop table if exists tmp_pvuv; cr ...
- 栈(stack)和堆(heap)
栈(stack)和堆(heap), Java程序在运行时都要开辟空间,任何软件在运行时都要在内存中开辟空间,Java虚拟机运行时也是要开辟空间的.JVM运行时在内存中开辟一片内存区域,启动时在自己的内 ...
- flask请求钩子、HTTP响应、响应报文、重定向、手动返回错误码、修改MIME类型、jsonify()方法
请求钩子: 当我们需要对请求进行预处理和后处理时,就可以用Flask提供的回调函数(钩子),他们可用来注册在请求处理的不同阶段执行的处理函数.这些请求钩子使用装饰器实现,通过程序实例app调用,以 b ...
- 使用SpringBoot的优势。
Spring Boot 让开发变得更简单 Spring Boot 对开发效率的提升是全方位的,我们可以简单做一下对比: 在没有使用 Spring Boot 之前我们开发一个 web 项目需要做哪些工作 ...
- Anaconda下载及安装及查看安装的Python库用法
Anaconda下载及安装及查看安装的Python库用法 Anaconda 是一个用于科学计算的 Python 发行版,提供了包管理与环境管理的功能.Anaconda 利用 conda 来进行 pac ...
- linux的错误码error
在程序出错时,我们通过全局变量错误号errno和perror函数能够很快的定位到错误原因. Linux错误代码及其含义 C Name Value Description 含义Success 0 Suc ...
- input 的radio checkbox 和 select 相关操作
1 select 获取和设置值,以及onchange事件 1下拉框option没有checked事件 可通过select 的 onchange事件进行监控,以获取其值 <select name ...
- 细数那些不懂Spring底层原理带来的伤与痛
1. 什么是spring? Spring 是个Java企业级应用的开源开发框架.Spring主要用来开发Java应用,但是有些扩展是针对构建J2EE平台的web应用.Spring 框架目标是简化Jav ...
- 怎样从外网访问内网PostgreSQL数据库?
本地安装了一个PostgreSQL数据库,只能在局域网内访问到,怎样从外网也能访问到本地的PostgreSQL数据库呢?本文将介绍具体的实现步骤. 1. 准备工作 1.1 安装并启动PostgreSQ ...
- Prometheus监控学习笔记之Prometheus的架构及持久化
0x00 Prometheus是什么 Prometheus是一个开源的系统监控和报警工具,特点是 多维数据模型(时序列数据由metric名和一组key/value组成) 在多维度上灵活的查询语言(Pr ...