使用 Conventional Commits 進行 Git 提交
概述
根據 Conventional Commits 規範建立標準化、具語義的 git 提交。分析實際差異以決定合適的類型、範圍與訊息。
Conventional Commit 格式
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
提交類型
| 類型 | 用途 |
|---|---|
feat | 新功能 |
fix | 錯誤修復 |
docs | 僅文件 |
style | 格式/風格（不影響邏輯） |
refactor | 程式重構（無新功能/錯誤修復） |
perf | 效能改善 |
test | 新增/更新測試 |
build | 建置系統/相依套件 |
ci | CI/設定變更 |
chore | 維護/雜項 |
revert | 還原提交 |
破壞性變更
# 在類型/範圍後加驚嘆號
feat!: remove deprecated endpoint
# 使用 BREAKING CHANGE 頁尾
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key behavior changed
工作流程
1. 分析差異
# 若有暫存檔案，使用暫存差異
git diff --staged
# 若無暫存內容，使用工作目錄差異
git diff
# 同時檢查狀態
git status --porcelain
2. 暫存檔案（如有需要）
若無暫存內容，或想以不同方式分組變更：
# 暫存特定檔案
git add path/to/file1 path/to/file2
# 依模式暫存
git add *.test.*
git add src/components/*
# 互動式暫存
git add -p
切勿提交機密資訊（.env、credentials.json、私鑰）。
3. 產生提交訊息
提交訊息必須嚴格以英文撰寫——包括主旨與內文。即使儲存庫歷史上包含俄文提交，也絕不以俄文撰寫提交訊息。
分析差異以決定：
- 類型：這是哪種變更？
- 範圍：影響哪個區域/模組？
- 描述：一行摘要說明變更內容（現在式、祈使語氣、少於 72 字元）
4. 執行提交
# 單行
git commit -m "<type>[scope]: <description>"
# 多行（含內文/頁尾）
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>
<optional body>
<optional footer>
EOF
)"
最佳做法
- 僅以英文撰寫提交訊息（主旨與內文）
- 每次提交只處理一個邏輯變更
- 使用現在式："add" 而非 "added"
- 使用祈使語氣："fix bug" 而非 "fixes bug"
- 參照議題：
Closes #123、Refs #456 - 描述控制在 72 字元內
Git 安全協議
- 絕不更新 git 設定
- 未經明確要求，絕不執行破壞性指令（--force、hard reset）
- 除非使用者要求，絕不跳過掛鉤（--no-verify）
- 絕不強制推送到 main/master
- 若因掛鉤導致提交失敗，修正後建立新提交（不修改）
- 未經明確詢問使用者，絕不建立新分支。
直接提交到當前分支（包括
main），除非使用者要求建立分支。請勿「為了安全」自動建立分支——由使用者管理分支。若您認為需要建立分支，請先提問。 - 除非使用者要求，絕不推送到新的遠端分支或開啟 MR/PR。