前言

剛開始使用 Git 的時候，我其實也常常把 commit message 寫得很隨意。

例如：

1
2
3
git commit -m "update"
git commit -m "fix bug"
git commit -m "改一下"

當下看起來沒有問題，因為自己還記得剛剛改了什麼。

但只要過了一兩週，或是專案裡有其他人一起開發，再回頭看這些 commit，就會發現它們幾乎沒有提供任何有效資訊。

這篇就整理一下，我自己在寫 commit message 時會注意的幾個方向。

Commit Message 的用途

commit message 不是寫給 Git 看的，而是寫給「未來需要理解這段變更的人」看的。

這個人可能是同事，也可能是幾個月後的自己。

好的 commit message 至少要能回答兩個問題：

  • 這次改了什麼？
  • 為什麼要這樣改？

如果 commit message 只寫 fix，那未來看到的人就只能進 diff 裡慢慢猜。

可以用動詞開頭

我自己會習慣用一個清楚的動詞開頭，讓 commit 看起來像一個明確的操作。

例如：

1
2
3
git commit -m "Fix login redirect after session expired"
git commit -m "Add validation for empty email input"
git commit -m "Refactor user profile update flow"

如果是中文也可以：

1
2
3
git commit -m "修正登入過期後的導向流程"
git commit -m "新增 Email 空值驗證"
git commit -m "整理使用者資料更新流程"

重點不是一定要英文或中文，而是要讓訊息本身清楚。

不要只寫結果，也可以補上原因

有些變更只看標題就足夠，但有些變更背後會有原因。

例如：

1
git commit -m "Change retry count from 1 to 3"

這句話只說明了「改了什麼」，但沒有說明「為什麼」。

如果補成：

1
git commit -m "Increase API retry count to reduce transient failures"

讀起來就會更清楚：這次調整是為了降低短暫網路錯誤造成的失敗率。

如果內容比較複雜，也可以用多行 commit message：

1
git commit

然後在編輯器裡寫：

1
2
3
4
5
Increase API retry count

Some third-party API calls fail occasionally because of short network
interruptions. Increasing retry count from 1 to 3 reduces avoidable
job failures without changing the request payload.

第一行簡短描述，下面再補充背景。

每次 Commit 盡量只做一件事

commit message 寫不好，有時候不是文字問題，而是一次 commit 塞了太多東西。

例如同一個 commit 同時包含：

  • 修登入 bug
  • 調整按鈕樣式
  • 改資料表欄位
  • 順手整理 README

這種情況下，不管 message 怎麼寫都很難清楚。

比較好的做法是把變更拆開：

1
2
3
4
git commit -m "Fix login redirect after session expired"
git commit -m "Adjust primary button spacing"
git commit -m "Add user last_login_at column"
git commit -m "Update setup steps in README"

這樣未來要查問題、還原變更或 code review，都會輕鬆很多。

可以參考的格式

如果團隊沒有特別規範，我覺得可以先用簡單格式就好：

1
動詞 + 變更對象 + 目的或結果

例如：

1
2
3
4
Fix login redirect after session expired
Add pagination to article list
Update API timeout setting
Remove unused profile helper

中文也可以：

1
2
3
4
修正登入過期後的導向流程
新增文章列表分頁
調整 API timeout 設定
移除未使用的 profile helper

格式不用一開始就追求完美，先做到「看得懂」比什麼都重要。

結語

commit message 看起來只是小事，但它其實會影響專案的可維護性。

寫得清楚一點，未來在追 bug、看歷史、整理 release note 的時候，都會省下不少時間。

我的原則很簡單：

  • 不只寫 fix、update 這種模糊字眼。
  • 一個 commit 盡量只處理一件事。
  • 讓未來的自己看得懂當時為什麼這樣改。

工程很多時候不是只把功能做出來，而是讓後面的人能接得下去。