git commit message 撰寫建議和範例

筆者常常不知道該如何正確的寫 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
    

修正語法錯誤(註:語法錯誤不該 commit)：

    
fix(client-app): syntax error
    

延伸閱讀： 使用小圖示(Emoji)建立一目瞭然 commit 訊息