git commit 訊息撰寫建議和範例

筆者常常不知道該如何正確的寫 commit message,因為英文不夠好、不確定正確的格式,也很難用簡短的話說明完這堆新增加或修改的功能,導致拖很久才 commit,又給自己造成麻煩。

於是整理了以下幾個團隊常用的 commit message 格式和內容當作範例,希望能夠幫助需要幫助的人

格式

最泛用的格式:
    
[類型]: [標題]

稍微詳細一點的內容
    

在我們團隊還有額外加上類型右側的括弧:
    
[類型](位置/功能): [標題]

稍微詳細一點的內容
    

例如:
    
fix(client-app/user): 修正使用者大頭貼無法上傳 png 檔案

右上角帳戶選單中「變更大頭貼」功能的副檔名白名單增加 png 
    

類型:
  • feat: feature,新增或修改功能
  • fix: 修正錯誤
  • refactor: 重構,增加可讀性或簡化結構,但不影響功能
  • style: 樣式,只調整介面,不影響功能
  • docs: 文件變更
  • perf: 提升效能
  • chore: 輔助工具相關,例如 Docker、JenkinsFile 、資料庫物件關聯對應更新(如 Entity Framework)、更新版號
  • test: 測試相關,單元測試、整合測試程式更新
  • revert: 復原 commit,還原至先前版本
位置範例:
  • back-end
  • client-app (或是使用 front-end)
  • docker
功能範例:
  • theme
  • identity
  • style
  • api-doc

說明

「類型」是讓所有閱讀的人都能夠清楚的了解到這個 commit 的用途,類型後方接上括號,括號內分兩部分(可部分或全部省略),第一部分是此 commit 主要修改的位置(client-app),第二部分是主要修改的功能(user),中間使用斜線分隔。 然後使用一句話簡短的描述這個 commit 做了什麼,官方建議不要超過 50 個字。
在訊息中第二行都會保持空白(除非只有一行),最後在第三行和以後寫上詳細訊息或是要補充的說明。

上述使用到的「類型」、「位置」、「功能」的主要目的都只是為了方便團隊快速了解這個 commit 做了什麼、方便事後查閱,若團隊覺得沒有必要使用到 位置/功能 則不使用也無訪,也有的團隊不會留下「類型」,一切規範都是交由團隊決定,最重要的就是讓大家提交的訊息格式都能盡量一致,增加工作效率。

問答

Q: 是否應該使用全英文撰寫?
A: 若開發團隊溝通皆使用相同語言(例如中文),筆者覺得就不一定要全英文,畢竟若因為英文不好導致撰寫和閱讀出現問題反而降低開發效率,只要團隊方便並且有共識則使用任何語言都沒有問題,畢竟語言也只是工具的一種。

範例

C# Entity Framework 依照資料庫資料表欄位自動產生資料庫對應實體:
    
chore(db): sync EF to db
    

後端程式增加註解說明:
    
docs(back-end): add A class comments
    

網頁增加主題配色
    
feat(client-app/style): add template theme
    

留言