提交技能
遵循常規提交風格和原子性提交原則,暫存並提交變更。
提交訊息格式
<類型>(<可選作用域>): <簡短摘要>
- 全部小寫 — 類型、作用域和摘要
- 摘要結尾無句號
- 祈使語氣 — 使用「新增功能」而非「已新增功能」或「新增了功能」
- 摘要行最多 50 個字元(軟限制,硬限制為 72 字元)
- 摘要描述原因,而非內容(diff 顯示內容)
類型
| 類型 | 使用時機 | 範例 |
|---|---|---|
feat | 新功能或能力 | feat: add user authentication flow |
fix | 錯誤修復 | fix: resolve null pointer on empty input |
refactor | 既不修復錯誤也不新增功能的程式碼變更 | refactor: extract parser into standalone module |
style | 格式化、空白、分號 — 無邏輯變更 | style: apply formatter to config files |
docs | 僅文件相關 | docs: add API usage examples to readme |
test | 新增或更新測試 | test: add edge case coverage for validator |
chore | 建置流程、工具、依賴、設定 | chore: update dependency lockfile |
perf | 效能改善 | perf: cache repeated database lookups |
ci | CI/CD 管道變更 | ci: add lint step to PR workflow |
作用域(可選)
當類型單獨使用時意義模糊,可使用作用域來縮小範圍。從專案的目錄結構或領域區域推導出作用域:
feat(auth): add OAuth2 token refresh
fix(api): handle timeout on large payloads
docs(contributing): add setup instructions
工作流程
- 審查變更 — 執行
git status和git diff(暫存 + 未暫存)以了解變更內容 - 檢查近期歷史 — 執行
git log --oneline -10以符合專案現有的提交風格 - 確認意圖 — 確認變更構成單一邏輯單元;若不是,建議拆分為多個提交
- 執行 CI 檢查 — 在暫存之前,執行專案的 linter、格式化程式和測試套件以提早發現問題。檢查
package.json腳本、Makefile或 CI 設定以取得可用的命令。在繼續之前修復任何失敗。 - 暫存檔案 — 按名稱添加特定檔案(
git add file1 file2),切勿使用git add -A或git add . - 撰寫訊息 — 選擇正確的類型,如有幫助則添加作用域,撰寫祈使句摘要
- 提交 — 使用 heredoc 處理訊息以確保格式整潔
- 驗證 — 提交後執行
git status以確認提交成功
多行提交
對於需要主體的提交(少見 — 偏好簡潔的單行訊息):
<類型>(<作用域>): <摘要>
<解釋原因而非內容的主體>
- 摘要和主體之間空一行
- 主體在 72 個字元處換行
- 僅在摘要單獨無法傳達理由時使用主體
規則
- 原子性提交 — 每次提交一個邏輯變更。一個功能及其測試可以是一個提交。不相關的格式化修復應為單獨的提交。
- 無機密資訊 — 絕不提交
.env、憑證、API 金鑰或令牌。如果這些已被暫存,請警告使用者。 - 無生成產物 — 不提交建置輸出、依賴目錄或編譯檔案。在暫存前檢查
.gitignore的涵蓋範圍。 - 僅新提交 — 始終建立新提交。除非使用者明確要求,否則絕不修改(amend)。
- 不跳過鉤子 — 絕不使用
--no-verify。如果鉤子失敗,請修復根本問題。 - 共同作者行 — 當 Claude 撰寫或共同撰寫了變更時,附加共同作者結尾:
Co-Authored-By: Claude <[email protected]>
範例
# 功能 — 新能力
feat: add webhook notification system
# 帶作用域的功能
feat(api): add rate limiting middleware
# 修復 — 錯誤修正
fix: prevent crash on malformed JSON input
# 風格 — 僅格式化
style: apply consistent indentation across modules
# 文件 — 文件
docs: add architecture decision records
# 雜務 — 工具/設定
chore: broaden gitignore to cover build artifacts
# 帶作用域的測試
test(auth): add integration tests for token refresh
# 帶作用域的重構
refactor(db): replace raw queries with query builder
參考文件
- conventional-commits.md — 類型選擇指南、重大變更、作用域策略、多檔案提交決策、主體格式、結尾以及常見錯誤