GitCommitMessage规范
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
GitCommitMessage规范
1、Commit Message的好处
规范化后的commit message主要好处有以下⼏点：
让维护者知道变化的性质和原因
⽅便过滤快速查找信息
⾃动化⽣成格式化的Change Log
2、Commit Message格式
是⽬前应⽤最为⼴泛的写法，包括三个部分：Header，Body 和 Footer，和，格式如下：
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
其中，header 是必需的，body 和 footer 可以省略。
不管哪个部分，任⼀⾏都不得超过72个字符（或100个字符）。
2.1 Header
Header部分只有⼀⾏，包括三个字段：type（必需）、scope（可选）和subject（必需）。
type
commit类型，只能是下⾯其中⼀个：
build: 构造⼯具的或者外部依赖的改动，如 gulp, broccoli, npm
ci: 与CI（持续集成服务）配置⽂件和脚本有关的改动，如 Travis, Circle, BrowserStack, SauceLabs
docs: 只改动了⽂档相关的内容
feat: 增加新功能
fix: 修复bug
perf: 提⾼性能的改动
refactor: 代码重构，没有加新功能或者修复bug
style:不影响代码含义的改动，例如去掉空格、改变缩进、增删分号
test: 增加或修正测试
chore: 不修改src或者test的其余修改，例如构建过程或辅助⼯具的变动
以上⼏种类型，推荐使⽤feat和fix，两者分别和中的minor和patch相对应，且⼀定会出现在Change Log中。
scope
⽤于描述改动的范围，格式可以是项⽬名/模块名，如：angular/common。
如果⼀次commit修改多个模块，建议拆分成多次commit，以便更好追踪和维护。
subject
subject是commit的简短描述，其要求：
以动词开头，使⽤祈使语句和现在时态，⽐如change，⽽不是changed或changes
第⼀个字母⼩写
结尾不加句号（.）
2.2 Body
Body为详细描述，可以写成多⾏。
对于⼩的修改不作要求，但是重⼤需求、更新等必须添加body来作说明。
使⽤第⼀⼈称现在时，⽐如使⽤change⽽不是changed或changes。
应该说明代码变动的动机，以及与以前⾏为的对⽐。
2.3 Footer
Footer包含两种情况：不兼容变动和关闭Issue。
破坏性变更
如果当前代码与上⼀版本不兼容，则 Footer 部分以 BREAKING CHANGE: 开头，后⾯是对变动的描述、以及变动理由和迁移⽅法。
如：
BREAKING CHANGE: environment variables now take precedence over config files.
涉及破坏性变更和语义化版本中的major相对应，如果存在则必须指明该项，如：版本升级、接⼝参数减少、接⼝删除、迁移等。
关闭Issue
如果当前commit针对某个issue，那么可以在 Footer 部分关闭这个 issue 。
如：
Closes #111
re #222
fix #333
fix #444,#555
2.4 Revert
Revert是⼀种特殊情况，如果当前commit⽤于撤销以前的commit，则必须以 revert: 开头，后⾯跟着被撤销commit的Header。
Body部分的格式是固定的，必须写成 This reverts commit <hash>. ，其中的hash是被撤销 commit 的 SHA 标识符，如：
revert: feat(pencil): add 'graphiteWidth' option
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
2.5 ⼀个commit例⼦
build(pom): 升级springboot版本到XXX
为了⽀持XXX特性，需要升级springboot版本到XXX
BREAKING CHANGE: 随着springboot版本更新到XXX，项⽬中使⽤的XXX⽅法不再被⽀持
Closes #323
下图是angular项⽬github上的：
3、Conventional-Changelog
是⼀款可以根据项⽬的commit 和 metadata信息⾃动⽣成 changelogs 和 release notes的系列⼯具，并且在辅助 standard-version ⼯具的情况下，可以⾃动帮你完成⽣成version、打tag, ⽣成CHANGELOG等系列过程。
⽀持的插件有：、、、，其⽣态主要模块如下：
- 通过提交记录⽣成 CHANGELOG.md
- 针对 angular commit 格式的命令⾏⼯具
- 通过提交记录⽣成 github release 中的变更描述
- 根据提交记录判断需要升级哪位版本号
- commit message 规范引⽤检测
- 针对开发者简单的 commit 规范
- 检查提交记录是否符合约定
这⾥主要介绍commitizen、commitlint、conventional-changelog-cli 和standard-version 等4个⼯具。
3.1 commitizen提交
commitizen是⼀个撰写合格commit message的⼯具，⽤于代替git commit 指令。
commitizen安装
# 全局安装
npm install -g commitizen
# 本地安装
npm install --save-dev commitizen
安装适配器（Adapter)
commitizen⽀持不同适配器的扩展，从⽽去满⾜不同的构建需求。
cz-conventional-changelog适配器提供conventional-changelog标准（约定式提交标准），更多。
###全局安装###
npm install -g commitizen cz-conventional-changelog
# 全局模式需要配置⽂件指定adapter
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
###本地安装###
npm install cz-conventional-changelog --save-dev
# 或者使⽤ commitizen ⼯具
commitizen init cz-conventional-changelog --save-dev --save-exact
安装并添加完后，使⽤ git cz 命令替换 git commit 提交记录，如下图所⽰：
3.2 commitlint验证
安装commitlint
# Install commitlint cli and conventional config
npm install --save-dev @commitlint/{config-conventional,cli}
# For Windows:
npm install --save-dev @commitlint/config-conventional @commitlint/cli
# Configure commitlint to use conventional config
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
安装husky
#npm
npm install husky --save-dev
#yarn
yarn add -D husky
添加如下代码到package.json⽂件中
{
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
}
安装完成后，输⼊测试命令，如下图所⽰：
3.3 conventional-changelog-cli⽣成
conventional-changelog-cli 默认推荐的 commit 标准是来⾃angular项⽬,除了angular标准以外，⽬前集成了包括 atom, codemirror, ember, eslint, express, jquery 等项⽬的标准。
安装
npm install -g conventional-changelog-cli
使⽤
conventional-changelog -p angular -i CHANGELOG.md -s
上⾯命令会在CHANGELOG.md头部加上⾃上次tag版本的之后的变更（Feature、Fix、Breaking Changes等）。
如果要⽣成所有发布的Change Log，则运⾏命令如下：
conventional-changelog -p angular -i CHANGELOG.md -s -r 0
参数说明：-p⽤来指定使⽤的commit message标准；-i表⽰从哪⾥读取changelog；-s表⽰读写changelog为同⼀⽂件；-r表⽰⽣成changelog所需要使⽤的release版本数量，默认为1，全部则是0。
为了⽅便使⽤，可以将其写⼊package.json的scripts字段，如下所⽰：
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
}
}
以后使⽤时，直接运⾏命令 npm run changelog 即可。
⾃定义参数
⽣成的 changlog 中有些常⽤内容可以通过⾃定义参数来根据需求更改，例如版本号、commit 地址等。
changelog 中⽣成的版本号即是从package.json 中获取 version 字段来的。
commit 连接的仓库地址我们需要修改 package.json 中的repository地址，changelog 中 issuse 默认的连接地址也是根据 repository 来⽣成的。
如果你使⽤了第三⽅的协作系统（例如 bitbucket），那么你可以使⽤这个标准。
如果使⽤redmine 来管理 isssue，那么在⽣成 changelog 后可以使⽤命令 bash ./script/changeissueurl.sh CHANGELOG.md 处理⽂本中的原有地址，脚本⽂件如下：
#!/bin/bash
sed -i 's|https:///aaron-shu/gitStudy/issues/|https:///|g' $1
conventional-changelog 更多的选项配置可以看。
3.4 standard-version⽣成
standard-version是⼀款遵循语义化版本（ semver）和 commit message 标准规范的版本和 changlog ⾃动化⼯具。
通常情况线下，我们会在 master 分⽀进⾏如下的版本发布操作：
1. git pull origin master
2. 根据 pacakage.json 中的 version 更新版本号，更新 changelog
3. git add -A, 然后 git commit
4. git tag 打版本操作
5. push 版本 tag 和 master 分⽀到仓库
其中2，3，4是 standard-version ⼯具会⾃动完成的⼯作，配合本地的 shell 脚本，则可以⾃动完成⼀系列版本发布的⼯作。
安装&使⽤
# 全局
npm install -g standard-version
# 本地
npm install --save-dev standard-version
# 使⽤
# Help standard-version --help
standard-version
执⾏ standard-version 命令，我们会在控制台看到整个执⾏流程的 log 信息。
默认情况下，⼯具会⾃动根据主版本（major）、次版本（minor）和修订版（patch）规则⽣成版本号，⽐如package.json中的version为1.0.0，那么执⾏后则是：1.0.1。
⼏个常⽤参数
--release-as, -r 指定版本号
--prerelease, -p 预发版本命名
--tag-prefix, -t 版本 tag 前缀
# 如果当前是1.0.1，则输出版本1.1.0
standard-version -r minor
# 指定输出版本2.0.0
standard-version -r 2.0.0
# 指定输出版本2.0.0-test
standard-version -r 2.0.0-test
# 如果当前是2.0.0-alpha.0，则输出版本2.0.0-alpha.1
standard-version --prerelease alpha
# 如果当前是2.0.0，则输出stable-2.0.1
standard-version --tag-prefix "stable-"
3.5 npm集成
将命令集成到 npm package.json的 scripts 中, 并配合 shell 脚本使⽤，如下：
"scripts": {
"release": "bash ./scripts/release.sh",
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md && npm run changeissueurl",
"changeissueurl": "bash ./scripts/changeissueurl.sh CHANGELOG.md"
}
// 配置好后使⽤ npm run 执⾏发布
npm run release
添加 release.sh 脚本：
#!/bin/bash
# Release branch
master="master"
prefix="stable-"
git pull origin $master
echo"Current pull origin $master."
# Auto generate version number and tag
standard-version --tag-prefix $prefix
git push --follow-tags origin $master
echo"Git push origin $master"
echo"Release finished."
上⾯的脚本只是做了简单的分⽀ pull，执⾏ standard-version 和最后的版本 push ⼯作，如果要做⼀些定制化的执⾏参数，则需要做定制修改了。
4、⼀些插件
IDEA：Git Commit Template（提交模板）
VSCode：git-commit-plugin（提交模板，不同的提交类型前会添加图标）、changelog-generator（change log⽣成）。