Git 約定式提交

async wait發表於2021-12-25
Git

概述

每次提交程式碼的時候，我們都需要為我們本次修改的內容新增一段描述，例如：

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

相關文章