概述
每次提交代码的时候,我们都需要为我们本次修改的内容添加一段描述,例如:
git commit -m "Initial commit";
git commit -m "修复了一些已知问题。";
git commit -m "增加了新特性。";
但实际上有些 commit message 千奇百怪,比如以下这种:
一次 commit 应该准确的说明本次提交的目的和修改内容,比如:
git commit -m "chore: upgrade org.bouncycastle:bcprov-jdk15on from 1.69 to 1.70";
git commit -m "perf: optimize the code on global zookeeper";
git commit -m "docs(readme): fix typo";
这种写法来源于 Angular 团队的 Git 约定式提交,你可以从以下链接来阅读它们的规范:
- Git Commit Message Conventions
- Understanding Semantic Commit Messages Using Git and Angular
- Angular提交信息规范
- 约定式提交
使用约定式提交
约定式提交约定了 commit message 的格式,如下所示:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LIKE>
<footer>
提交消息由 header、body、footer 组成,我们来详细介绍它们。
Message header
header 由 type、scope、subject 组成,在完整的约定式提交格式,它占据的部分是:
<type>(<scope>): <subject>
所代表的含义是:
- type: 必选,本次提交的类型。
- scope: 可选,表示本次提交影响的范围。
subject: 必选,对本次提交简短的描述。
type
type 的值必须是以下列表中的一个:
- build/chore👷♀️: 用于构建系统(包括脚本、配置或工具)和依赖的变化。
- ci: 用于系统持续集成、持续部署相关的配置文件、脚本文件、配置或者工具。
- docs📝: 用于标识项目相关文档的更改。
- feat✨: 用于标识新功能。
- fix🐛: 用于标识bug修复。
- perf⚡️: 用于标识性能提升。
- refactor: 用于标识代码重构,既不添加新功能也不修复错误--例如删除冗余代码、简化代码、重命名变量等。
- style: 用于标记代码格式化,代码风格调制,修复checkstyle等问题。
- tets: 用于标记测试相关的更改,修改现有测试或添加新的测试。
- revert: 用户分支回滚。
用一张图说明:
scope
scope 可以按照模块、包进行划分,具体使用可根据团队制定的规范,例如:
git commit -m "feat(logger): support JSONL log output format";
git commit -m "feat(dao): add global controller excepiton handler";
git commit -m "feat(api): add reqeust interceptor"
subject
对本次提交简短的描述,有以下准则:
- 首字母小写。
- 不以句号结尾。
示例
header 只是 commit message 的第一行,可以使用 git commit -m
来完成本次提交,例如:
git commit -m "chore(pom.xml): upgrade jackson-databind from 2.10.1 to 2.11.4"
上述例子中提交的 type 是 chore
,紧接着在 ()
中间指定了 scope 影响的范围或者说修改的文件是 pom.xml
,然后跟上一个英文 :
与一个空格就是我们的 subject。需要注意的的是 :
是英文的,在 :
之后还需要一个空格与 subject
作为分割。
之前提到过 scope 是可选的,如果我们忽略 scope,那么上述例子可以改为:
git commit -m "chore: upgrade jackson-databind from 2.10.1 to 2.11.4"
Message body
body 是可选的,可以介绍修改的原因以及详细的内容:
fix(users): remove getFriends API endpoint
In accordance with new privacy policy, remove the getFriends API endpoint.
(The endpoint will continue to exist for a while and return a deprecation notice)
需要注意的是,在 header 与 body 之前需要有一个空行。
Message footer
footer 也是可选的,如果本次提交是修改 issue
的话,那么可以在页脚引用 issue ,例如:
fix(users): remove getFriends API endpoint
In accordance with new privacy policy, remove the getFriends API endpoint.
(The endpoint will continue to exist for a while and return a deprecation notice)
Implements #2105
在 footer 与 body 之间也需要一个空行。
带来的好处
生成changelog
浏览记录
我们可以浏览指定 type 的提交记录,例如显示 feat、fix、perf 的提交记录:
git log --oneline --grep "^feat|^fix|^perf"
commit message emoji
将 emoji 添加到 commit message 中会使我们的提交更加有趣,也方便浏览,例如:
你可以在以下链接找到 commit message type 对应的 emoji:
- https://gitmoji.dev/
- commit-message-emoji
- GitCommitEmoji
- why-i-use-emojis-in-my-git-commits
- how-to-use-emoji-in-your-commit-message
如果你使用的是 VS Code 编辑器或者你使用的包管理器是 npm ,那么你还可以找到对应的插件:
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。