跳至主要内容

一個好的 git commit message 應該要包含什麼？

資訊

我已經寫好程式碼了，準備要 commit，
但是 commit message 該怎麼寫？
寫得太簡略會不會被退回來？

基本結構​

一個好的 commit message 通常包含兩個部分：

  1. 標題（Subject）：簡潔描述這次變更
  2. 內文（Body）：詳細說明為什麼改、改什麼、影響範圍（可選）

標題的規範​

格式要求​

  • 長度：建議 50 字以內，最多不超過 72 字
  • 動詞開頭：使用祈使語氣，例如「新增」、「修正」、「更新」
  • 首字母大寫：標題第一個字大寫
  • 結尾不加句號：標題結尾不需要標點符號

好的標題範例​

feat:新增使用者登入功能
fix:修正購物車計算錯誤
docs:更新 API 文件說明
chore:移除未使用的依賴套件

不好的標題範例​

fix bug                    # 太簡略，不知道修什麼
更新                      # 太模糊，不知道更新什麼
fix: 修正了購物車的問題。  # 結尾不應該有句號

內文的說明（可選但建議）​

如果變更需要更多說明，可以在標題後空一行，接著寫內文：

  • 為什麼改：說明變更的原因或背景
  • 改什麼：具體描述做了哪些修改
  • 影響範圍：這次變更會影響哪些功能或檔案

範例​

feat:新增使用者登入功能

實作 JWT token 驗證機制，讓使用者可以透過
email 和密碼登入系統。

影響範圍：
- 新增 auth.js 處理登入邏輯
- 更新 user model 加入 token 欄位
- 修改 API 路由加入驗證 middleware

常見的規範格式：Conventional Commits​

許多團隊會使用 Conventional Commits 規範，格式如下：

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

<body>

Type 類型​

  • feat: 新功能
  • fix: 修正 bug
  • docs: 文件變更
  • style: 程式碼格式調整（不影響功能）
  • refactor: 重構程式碼
  • test: 測試相關
  • chore: 建置流程或工具變更

範例​

feat(auth): 新增使用者登入功能

實作 JWT token 驗證機制

fix(cart): 修正購物車總額計算錯誤

當商品數量為 0 時，總額會顯示負數，
已修正計算邏輯。

docs(readme): 更新專案安裝說明

加入環境變數設定步驟
提示

如果團隊有使用 Conventional Commits，建議遵循團隊規範，
這樣可以讓 commit 歷史更清晰，也方便自動生成 changelog。

應該避免的事項​

  • ❌ 寫得太簡略：update、fix、改好了
  • ❌ 寫得太詳細：把每一行程式碼的變更都寫出來
  • ❌ 使用過去式：fixed bug → 應該用 fix: 修正 bug
  • ❌ 標題太長：超過 72 字會被截斷
  • ❌ 一次 commit 包含多個不相關的變更
備註

一次 commit 應該只做一件事，如果同時修改了多個不相關的功能，
建議分成多個 commit，這樣之後要 revert 或 cherry-pick 會比較方便。

團隊協作時的注意事項​

  • 使用團隊約定的格式（如果有）
  • 標題要清楚，讓其他成員快速了解變更內容
  • 如果變更較複雜，記得寫內文說明
  • 參考其他成員的 commit message 風格，保持一致性