學習 Git (4) - 淺談 Commit 規範


Posted by Calon on 2022-04-25

在前一篇裡講到了要使用 Commit 指令將暫存區的檔案存放到儲存庫才是完成 Git 的整個流程,也有提到在使用 git commit 指令的時候需要在後面寫上這次版本的訊息,可能有人會問說我一定要寫版本訊息嗎?

一定要,而且非常重要,如果沒有寫 Git 是不會將檔案存放到儲存庫的。另外,版本訊息是讓你和其他人知道這次版本變動「做了哪些事情」,所以一定要寫。

那既然是需要讓別人和自己知道做了什麼,所以建議撰寫的時候寫清楚,不要只寫 '修正 bug' 等等,這樣在第一時間很難知道你修改了哪裡、什麼 bug。


Commit 規範

在一開始練習的時候可以朝著寫清楚的方向就好,但慢慢地可以試著照著 Commit 規範去做撰寫。

為什麼要有 Commit 規範?
當今天我 Commit 了新的版本並且訊息為 '加入購物車 btn 商品數量提示',這樣看雖然沒什麼不妥,但看到訊息的人不知道你是新增了這一項功能還是修正原本沒顯示提示的 bug,變成需要花時間去點開程式碼,去看你做了什麼,而規範會就是來減少這種問題的發生。

社群中有許多的 Commit 規範,目前使用較多的是 AngularJS 團隊的規範,這裡也以此規範來做簡單的介紹。


Commit Message 規範格式

Commit Message 依照 AngularJS 團隊提供的規範,其基本格式為:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
  • Header:():
    • type:代表 commit 的類別,為必填欄位。
    • scope:代表 commit 的影響範圍,為選填欄位。
    • subject:代表 commit 的簡短描述,為必填欄位。
  • Body:針對這次變動做詳細描述,為選填欄位。
  • Footer:填寫任務編號,為選填欄位。


Header type

type 只能根據以下類別去填寫:

  • feat - 新增/修改功能 (feature)
  • fix - 修正 bug (bug fix)
  • docs - 文件 (documentation)
  • style - 修改程式碼格式或風格,不影響運作,例如:ESLint、whtie-space、missgin semi colons、formatting 等等
  • refactor - 重構或是優化,不屬於修正 bug 或是新增功能
  • test - 增加測試功能 (when adding missing tests)
  • chore - 第三方套件或是輔助工具等的變動 (maintain)


撰寫 Commit

最簡單和偷懶的方式就是使用平常用的 git commit -m 'docs: 新增打招呼的規範'

但既然導入了 AngularJS 團隊的規範,我們就來嘗試一下完整的 Commit Message 寫法,在這裡我們使用 git commit 不加上任何參數:

$ git commit

輸入之後就會跳出上一篇提到的讓許多人不知如何離開的編輯器 Vim(或 vi),界面會長這樣:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch newGulpfile
# Your branch is up to date with 'origin/newGulpfile'
#
# Changes to be committed:
#      modified:   helloWorld.txt
#

中文的話是下面這樣:

# 請輸入描述您變更的提交訊息。開頭是「#」
# 的行皆會忽略。提交訊息空白則取消本次提交作業。
#
# 位於分支 master
# 要提交的變更:
#   新檔案:   helloWorld.txt
#

簡單介紹一下 Vim 的操作方法:

  • h、j、k、l:分別為「左、下、上、右」
  • 按下 i 會進入輸入模式(Insert mode),可以輸入文字
  • esc:回到 Normal 模式
  • :wq:在 Normal 模式輸入會存檔離開 Vim,並上傳 Commit 到儲存庫
    • w:存檔
    • q:離開

使用規範去寫的話如下:

docs: 新增打招呼的規範

新增了打招呼時需要注意的事項、禮儀……

# 專案編號
project #2243

以 # 符號開頭的行句會被忽略,所以如果使用 git log 來查看紀錄的話會呈現(git log 會在之後介紹到):

commit a42cf2784381ca2135995d569b1a9d99af3c8b7b (HEAD -> master)
Author: 使用者名稱 <信箱>
Date:   Sun Apr 24 15:35:34 2022 +0800

docs: 新增打招呼的規範

新增了打招呼時需要注意的事項、禮儀……

project #2243

有興趣可以到 AngularJS 團隊所撰寫的文件去做查看。


參考資料

#Git







Related Posts

補充教學-陣列

補充教學-陣列

Python 程式設計函式的參數和回傳值入門教學

Python 程式設計函式的參數和回傳值入門教學

瀏覽器渲染流程

瀏覽器渲染流程


Comments