Git 工作流程強制執行器
強制執行一致的 Git 工作流程,包括提交訊息、分支命名和 PR 流程。
使用時機
- 建立提交或分支時
- 進行程式碼審查或建立 PR 時
- 使用者提及「git 工作流程」、「提交訊息」、「分支命名」或「Pull Request」時
指令
1. 偵測現有慣例
檢查以下項目:
.github/或.gitlab/範本CONTRIBUTING.md- 現有的提交訊息模式
- 分支命名模式
2. Conventional Commits
格式: type(scope): description
類型:
feat:新功能fix:錯誤修正docs:文件style:格式調整、缺少分號refactor:程式碼重構perf:效能改善test:新增測試chore:維護、依賴項
範例:
feat(auth): 新增 OAuth2 登入支援
fix(api): 處理使用者端點中的空值回應
docs(readme): 更新安裝說明
refactor(utils): 簡化日期格式化邏輯
3. 分支命名
常見模式:
feature/user-authentication
bugfix/login-error-handling
hotfix/critical-security-patch
release/v1.2.0
chore/update-dependencies
驗證項目:
- 使用小寫字母和連字號
- 以類型為前綴
- 敘述性名稱
- 若適用,包含問題編號:
feature/123-add-dark-mode
4. 提交訊息驗證
良好的提交範例:
feat(payments): 整合 Stripe 付款閘道
- 新增 Stripe SDK 設定
- 實作付款意圖建立
- 新增付款事件 Webhook 處理器
- 更新付款流程測試
關閉 #456
檢查項目:
- 主旨行 ≤ 50 個字元
- 內文在 72 個字元處換行
- 主旨和內文之間有空白行
- 使用祈使語氣(「新增」而非「已新增」)
- 參考問題/工單編號
5. PR 範本
建立 .github/PULL_REQUEST_TEMPLATE.md:
## 說明
<!-- 此 PR 做了什麼? -->
## 變更類型
- [ ] 錯誤修正
- [ ] 新功能
- [ ] 重大變更
- [ ] 文件更新
## 測試方式
<!-- 如何測試? -->
## 檢查清單
- [ ] 程式碼符合專案風格指南
- [ ] 已完成自我審查
- [ ] 為複雜程式碼新增註解
- [ ] 文件已更新
- [ ] 測試已新增/更新
- [ ] 所有測試通過
- [ ] 無新警告
## 相關問題
關閉 #
6. 提交鉤子
預先提交鉤子:
#!/bin/sh
# .git/hooks/pre-commit
# 執行 lint
npm run lint
# 執行測試
npm test
# 檢查敏感資料
if git diff --cached | grep -i "password\|api_key\|secret"; then
echo "錯誤:偵測到可能的敏感資料"
exit 1
fi
提交訊息鉤子:
#!/bin/sh
# .git/hooks/commit-msg
commit_msg=$(cat "$1")
# 檢查 Conventional Commits 格式
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore)(\(.+\))?: .+"; then
echo "錯誤:提交訊息必須遵循 Conventional Commits 格式"
echo "範例:feat(auth): 新增登入功能"
exit 1
fi
7. 驗證現有提交
檢查最近的提交是否符合模式:
git log --oneline -20 | grep -v "^[a-f0-9]\{7\} (feat|fix|docs|style|refactor|perf|test|chore)"
8. 產生變更日誌
從 Conventional Commits 產生:
# 使用 standard-version
npx standard-version
# 或手動按類型分組
git log --pretty=format:"%s" | grep "^feat" > features.txt
git log --pretty=format:"%s" | grep "^fix" > fixes.txt
9. 受保護分支
GitHub 設定:
- 要求 PR 審查
- 要求狀態檢查
- 要求簽署提交
- 限制誰可以推送
- 要求線性歷史
10. 最佳實務
- 原子提交:每個提交只包含一個邏輯變更
- 具描述性的訊息:說明「為什麼」,而非「做什麼」
- 頻繁提交:小而頻繁優於大而稀少
- 乾淨的歷史:合併前進行壓縮 (squash) 或變基 (rebase)
- 簽署提交:使用 GPG 簽章以確保安全
- 參考問題:連結到問題追蹤系統
Git 提交範本
建立 .gitmessage:
<type>(<scope>): <subject>
<body>
<footer>
# 類型:feat, fix, docs, style, refactor, perf, test, chore
# 範圍:受影響的元件或檔案
# 主旨:使用祈使語氣、小寫、不加句號、長度不超過 50 字元
# 內文:說明「什麼」和「為什麼」,而非「如何」,在 72 字元處換行
# 頁尾:重大變更、問題參考
設定為範本:
git config --global commit.template ~/.gitmessage
支援檔案
templates/PULL_REQUEST_TEMPLATE.mdtemplates/commit-msg-hook.shtemplates/.gitmessage