2
头图

概述

每次提交代码的时候,我们都需要为我们本次修改的内容添加一段描述,例如:

git commit -m "Initial commit";
git commit -m "修复了一些已知问题。";
git commit -m "增加了新特性。";

但实际上有些 commit message 千奇百怪,比如以下这种:

image.png
一次 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 约定式提交,你可以从以下链接来阅读它们的规范:

  1. Git Commit Message Conventions
  2. Understanding Semantic Commit Messages Using Git and Angular
  3. Angular提交信息规范
  4. 约定式提交

使用约定式提交

约定式提交约定了 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: 用户分支回滚。
    用一张图说明:
    image.png
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

对本次提交简短的描述,有以下准则:

  1. 首字母小写。
  2. 不以句号结尾。
示例

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

image.png

浏览记录

我们可以浏览指定 type 的提交记录,例如显示 feat、fix、perf 的提交记录:

git log --oneline --grep "^feat|^fix|^perf"

commit message emoji

将 emoji 添加到 commit message 中会使我们的提交更加有趣,也方便浏览,例如:

image.png
你可以在以下链接找到 commit message type 对应的 emoji:

  1. https://gitmoji.dev/
  2. commit-message-emoji
  3. GitCommitEmoji
  4. why-i-use-emojis-in-my-git-commits
  5. how-to-use-emoji-in-your-commit-message

如果你使用的是 VS Code 编辑器或者你使用的包管理器是 npm ,那么你还可以找到对应的插件:

  1. npm-gitmoji-cli
  2. gitmoji-vscode

async_wait
10 声望3 粉丝