Git Commit Message规范

1、Commit Message的好处

规范化后的commit message主要好处有以下几点：

让维护者知道变化的性质和原因
方便过滤快速查找信息
自动化生成格式化的Change Log

2、Commit Message格式

Angular规范是目前应用最为广泛的写法，包括三个部分：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

conventional-changelog是一款可以根据项目的commit 和 metadata信息自动生成 changelogs 和 release notes的系列工具，并且在辅助 standard-version 工具的情况下，可以自动帮你完成生成version、打tag, 生成CHANGELOG等系列过程。

支持的插件有：grunt、gulp、atom、vscode，其生态主要模块如下：

conventional-changelog-cli - 通过提交记录生成 CHANGELOG.md
standard-changelog - 针对 angular commit 格式的命令行工具
conventional-github-releaser - 通过提交记录生成 github release 中的变更描述
conventional-recommended-bump - 根据提交记录判断需要升级语义化版本哪位版本号
conventional-commits-detector - commit message 规范引用检测
commitizen - 针对开发者简单的 commit 规范
commitlint - 检查提交记录是否符合约定

这里主要介绍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），那么你可以使用这个标准conventional-changelog-angular-bitbucket。如果使用 redmine 来管理 isssue，那么在生成 changelog 后可以使用命令 bash ./script/changeissueurl.sh CHANGELOG.md 处理文本中的原有地址，脚本文件如下：

#!/bin/bash
sed -i 's|https://github.com/aaron-shu/gitStudy/issues/|https://redmine.example.com/|g' $1

conventional-changelog 更多的选项配置可以看这里。

3.4 standard-version生成

standard-version是一款遵循语义化版本（ semver）和 commit message 标准规范的版本和 changlog 自动化工具。通常情况线下，我们会在 master 分支进行如下的版本发布操作：

git pull origin master
根据 pacakage.json 中的 version 更新版本号，更新 changelog
git add -A, 然后 git commit
git tag 打版本操作
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生成）

posted on 2020-11-23 14:04 aaron_shu 阅读(1080) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

Arron的博客

导航

公告