前端新米

Heidi's Blog

0%

[學習筆記] 如何撰好的 Git Commit Message

發表於 分類於
1.6k 1 分鐘

為什麼 Commit Message 很重要？

Git 在每次 Commit 時，需要寫下 Git Commit Message（提交說明），用來記錄提交版本更動的摘要。

任何專案都至少由兩個以上的開發者共同合作開發。

除了專案開發者，任何專案都會是跟其他開發者、以及未來的自己共同開發維護的。當不同開發者接手專案時，能藉由瀏覽 Commit Message 內容快速進入狀況，瞭解程式異動的原因，如此也利於後續的維護。

何謂好的 Commit Message？

一個好的 Git Commit Message 必須兼具 What & Why & How，能幫助開發者瞭解這個提交版本：

  1. 做了什麼事情（What）
  2. 為什麼要做這件事情（Why）
  3. 用什麼方法做到的（How）

Commit Message 的規範與準則

在團隊之間，撰寫 commit log 的方式應一致，也就是定義風格與內容，可透過遵守現有的慣例來實現。

一個 Commit Message 主要由 Header + Body + Footer 組成：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Message Header: <type>(<scope>): <subject>

  • type（必要）：commit 的類別
    • 如：feat, fix, docs, style, refactor, test, chore
  • scope（可選）：commit 影響的範圍
    • 如：資料庫、控制層、模板層等，視專案不同改變
  • subject（必要）：commit 的簡短描述
    • 不超過 50 個字元
    • 結尾不加句號
    • 盡量讓 Commit 單一化，一次只更動一個主題

Message Body

  • 對本次 Commit 的詳細描述，解釋 What & Why & How
  • 可以分成多行，每一行不超過 72 個字元
  • 說明程式碼變動的項目與原因，還有與先前行為的對比
  • 填寫任務編號 issue #1246
  • BREAKING CHANGE（可略），記錄不兼容的變動，後面是對變動的描述、以及變動原因和遷移方法

Header：<type> 類別規範

type 代表提交 Commit 的類別，以下為使用慣例：

  • feat：新增或修改功能（feature）
  • fix：修補 bug（bug fix）
  • docs：文件（documentation）
  • style：格式
    • 不影響程式碼運行的變動，例如：white-space, formatting, missing semi colons
  • refactor：重構
    • 不是新增功能，也非修補 bug 的程式碼變動
  • perf：改善效能（improves performance）
  • test：增加測試（when adding missing tests）
  • chore：maintain
    • 不影響程式碼運行，建構程序或輔助工具的變動，例如修改 config、Grunt Task 任務管理工具
  • revert：撤銷回覆先前的 commit
    • 例如：revert：type(scope):subject

Commit Message 範例

以下舉幾個範例：

feat: message 新增信件通知功能
feat(優惠券): 加入搜尋按鈕，調整畫面

fix: 圓餅圖圖例跑版
fix: 意見反應，信件看不到圖片問題

style: 統一換行符號 CRLF to LF

docs: 更新 README 相關資訊
docs: 修正型別註解

chore(submoudle): 變更 git url
chore: 調整單元測試環境

refactor(每日通知信件): 重構程式結構

參考資料：

  • Git Commit Message 這樣寫會更好，替專案引入規範與範例
  • 撰寫有效的 Git Commit Message
  • 如何寫一個Git Commit Message | louie_lu’s blog
  • AngularJS Git Commit Message Conventions