Git commit提交信息规范
在一个多人开发团队中,使用统一的Git commit提交规范有助于后续的代码评审、版本发布及日志自动化生成。
基于阮一峰的文章及其它资料构建Git comit提交规范。
注意: 不要使用git commit -m message
方式提交记录,建议使用git commit
打开编辑器窗口进行多行记录撰写。
Commit message格式
message由三部分组成:Header,Body和Footer。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
其中,Header 是必需的,Body 和 Footer 可以省略。
不管是哪一个部分,任何一行都不得超过72个字符(或100个字符)。这是为了避免自动换行影响美观。
Header
Header由一行构成,包括三个字段:type(必需)、scope(可选)和subject(必需)。
- type
type用于说明commit的类别,只允许定义的标识。
- feat:新功能(feature)
- fix:修正bug
- docs:文档(documentation)
- style: 格式(不影响代码运行的变动)
- refactor:重构(即不是新增功能,也不是修改bug的代码变动)
- perf: 优化相关,比如提升性能、体验。
- test:增加测试
- chore:构建过程或辅助工具的变动
- revert:回滚到上一个版本
- merge:代码合并
- sync:同步主线或分支的Bug
- scope
scope
用于说明 commit 影响的范围,对于数值模式开发,可以使用dynamic
,physics
,parallel
等等。
- subject
subject
是 commit提交主题的简短描述,不超过50个字符。
- 以动词开头,使用第一人称现在时,比如`change`,而不是`changed`或`changes`
- 第一个字母小写
- 结尾不加句号(`.`)
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)应该说明代码变动的动机,以及与以前行为的对比。
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
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
小标题下面。
Commit-msg Hook
我们可以通过自动化工具规范团队代码风格。这里我们使用git hook
提供的功能强制执行提交信息规范检查。
commit-msg钩子(hook)会在提交commit信息后进行调用,可用于检验commit信息是否规范。如果提交的commit信息不符合要求,不能执行git commit操作。
通常commit-msg钩子放在项目根目录下.git/hooks
中。
commit-msg示例:
#!/bin/sh
# 忽略merge request
MERGE_MSG=$(cat $1 | grep -E '^Merge branch*')
if [ "$MERGE_MSG" != "" ]; then
exit 0
fi
COMMIT_MSG=$(cat $1 | grep -E "^(feat|fix|docs|style|refactor|perf|test|chore|revert|merge|sync)(\(\w+\))?:\s(\S|\w)+")
if [ "$COMMIT_MSG" = "" ]; then
echo "Commit Message Irregular,Please check!"
echo "Recommended Commit Message Format:"
echo "========================================="
echo "<type>(<scope>): <subject>"
echo "// blank line"
echo "<body>"
echo "// blank line"
echo "<footer>"
echo "========================================="
echo "<type>: feat|fix|docs|style|refactor|perf|test|chore|revert|merge|sync are supported"
exit 1
fi
if [ ${#COMMIT_MSG} -lt 15 ]; then
echo "Commit Message Too Short,Please show me more detail!\n"
exit 1
fi
注意commit-msg脚本要有可执行权限。
$ chmod 700 commit-msg
下面测试commit-msg脚本是否工作。
$ git commit -m "add new file"
Commit Message Irregular,Please check!
Recommended Commit Message Format:
========================================================
<type>(<scope>): <subject>
// blank line
<body>
// blank line
<footer>
========================================================
<type>: feat|fix|docs|style|refactor|perf|test|chore|revert|merge|sync are supported
$ git commit -m "feat: new file"
Commit Message Too Short,Please show me more detail!\n
commit-msg脚本不限于使用shell实现,还可以使用Python、node等语言实现。
项目组共享commit-msg脚本
commit-msg脚本如果放在项目.git/hooks
目录下是不能推送到远程仓库的。
一种解决方法是在项目内创建一个目录,比如.githooks
,将commit-msg脚本放到该目录下,然后使用git管理,推送到远程仓库。项目其它人员克隆项目后,使用git config core.hooksPath /path/to/project/.githooks
设置即可(/path/to/project代替实际项目路径)。