Based on the Conventional Commits 1.0.0-beta.4 specification, analyze git staged changes and automatically generate a Traditional Chinese commit message and suggested branch name.
Core Features
- Branch Suggestion: Automatically generate semantic Git branch names based on the content of changed files.
- Commit Message: Automatically generate Traditional Chinese commit messages that comply with the Conventional Commits specification.
- Main Branch Protection: Prevent committing directly on
main/masterand guide switching to a suggested branch. - Atomic Split Guide: Detect high-complexity changes and guide users to commit in batches.
For the complete specification, refer to
references/conventional-commits-spec.md
Structure
<類型>[可選的作用範圍]: <描述>
[可選的正文]
[optional footer]
### 類型（Type）
根據官方規範，以下兩種類型具有語意化版本意義：
| 類型 | SemVer | 說明 |
|------|--------|------|
| `feat` | MINOR | 新增功能 |
| `fix` | PATCH | 修正臭蟲 |
以下類型由 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) 推薦使用：
| 類型 | 說明 |
|------|------|
| `docs` | 文件更新 |
| `style` | 程式碼格式調整（不影響功能） |
| `refactor` | 重構程式碼 |
| `perf` | 效能優化 |
| `test` | 測試相關 |
| `build` | 建置系統或外部相依性 |
| `ci` | CI 設定檔案 |
| `chore` | 其他雜項（工具、配置等） |
| `revert` | 撤銷先前的 commit |
### 作用範圍（Scope）- 可選
- 作用範圍**必須**由描述程式區段的名詞組成，並用括號包覆
- 範例：`feat(parser):`、`fix(api):`、`chore(eslint):`
### 描述（Subject）
- **必須**緊接在類型/作用範圍的冒號與空格之後
- **本 Skill 要求使用繁體中文撰寫**
- 限制在 50 字元以內
- 使用祈使句（如：「新增」、「修正」、「更新」）
- 不加句號
- 清楚描述變更的核心內容
### 正文（Body）- 可選
- **必須**在描述後的一個空行之後開始
- **本 Skill 要求使用繁體中文撰寫**
- 使用項目符號列表（`-` 開頭）
- 每個項目描述一個具體變更
- 優先說明做了什麼，必要時補充原因
- 使用台灣常用技術詞彙（如：「套件」、「設定」、「腳本」）
### 頁腳（Footer）- 可選
- 包含關於提交的詮釋資訊
- 範例：相關的拉取請求、審核者、重大變更
- 每個詮釋資訊一行
### 重大變更（Breaking Changes）
根據官方規範，重大變更對應到 SemVer 的 `MAJOR` 版本。標示方式：
**方式一：在類型後加 `!`**
feat(api)!: change user authentication mechanism
BREAKING CHANGE: remove legacy API endpoints; all clients must update to the new SDK
**方式二：僅在頁腳標示**
feat: change user authentication mechanism
- Implement the new OAuth 2.0 flow
- Remove legacy session authentication
BREAKING CHANGE: remove legacy API endpoints; all clients must update to the new SDK
**規範要求：**
- `BREAKING CHANGE` **必須**大寫
- 使用 `!` 提示時，正文或頁腳內**必須**包含 `BREAKING CHANGE: description`
## 執行步驟
### 步驟 1：取得分析資訊
首先執行輔助腳本，自動檢查分支與計算複雜度評分：
```bash
python scripts/analyze_git.py
In addition to the original fields, the script output now also includes each staged file'schange type：
| Field | Description |
|---|---|
NewFiles |
Added file (git status shows A） |
ModifiedFiles |
Modified existing file (shows M） |
DeletedFiles |
Deleted file (shows D） |
RenamedFiles |
Renamed or copied file (git status shows R/C, format old -> new） |
Step 2: Check branch
Determine based on the script output's IsMain and Branch fields:
Case A (safe branch): If IsMain: false
- Continue to step 3
Case B (main branch): If IsMain: true
- Stopsubsequent operations
- Based on the changes, suggest a compliantnew branch name(example:
feat/login-form-validation、fix/payment-bug） - report error：
請先切換至建議的分支（或自訂分支）後，再執行 commit。
Step 3: Analyze complexity and mode
Based on the script output's Score and RiskFactors fields, determine the mode:
Case A: Simple mode (Score < 4)
- Directly use the
-mparameter to generate the commit message - Suitable for small, low-risk changes
git commit -m "feat: 新增使用者登入功能"
Case B: Complex mode (Score >= 4)
- Important: If the Score is significantly too high (e.g., Score > 8), splitting the commit is strongly recommended.
- Suggest that the user use the file method to generate a detailed commit message, or assist with atomic splitting.
Step 4: Atomic split commit (for Score > 8 or multiple types of changes)
If you decide to split the commit, guide the user to perform the following steps:
- Undo all current adds：
git reset - First stage add: Select highly relevant files, for example
git add src/auth.ts src/security.ts - Execute the first-stage commit: Generate the corresponding commit message
- Second-stage add: For example
git add package-lock.json - Execute the second-stage commit: Generate the corresponding commit message
Step 5: Generate the Commit Message and Confirm
-
Determine the commit type based on file status(prioritize this, then confirm with the diff content):
Situation Suggested Type NewFilesmainly, and it is functional codefeatNewFilesmainly, and it is a test file (*.test.*,*.spec.*）testNewFilesmainly, and it is documentation (.md,.txt）docsOnly ModifiedFiles, fix problem logicfixOnly ModifiedFiles, code refactoring (no functional changes)refactorOnly RenamedFilesor file movesrefactorOnly DeletedFiles(cleaning up old code)choreorrefactorMixing multiple states, involving feature additions feat(and consider splitting) -
Combine with
git diffcontent to confirm the accuracy of the description -
Based on the mode selected in step 3, output the complete Commit Message
-
Output the corresponding
git commitcommand -
Ask the user: Do you need assistance executing the commit?
Example
Example of split commit suggestions
### ⚠️ 偵測到高複雜度變更 (Score: 10)
本次變更涉及認證邏輯重構與套件更新，建議拆分為兩個提交以符合原子化原則：
#### 第一步：重構認證邏輯
1. 執行：`git reset`
2. 執行：`git add src/auth.ts src/security.ts`
3. Commit Message：`refactor(auth): 重構認證模組安全性邏輯`
#### 第二步：更新套件
1. 執行：`git add pnpm-lock.yaml`
2. Commit Message：`build: 更新相依性鎖定檔`
Notes
- Lock file detection scope: Includes
package-lock.json、yarn.lock、pnpm-lock.yaml、bun-lock.json、Cargo.lock、go.sum、poetry.lock、Gemfile.lock, etc. - Only changes in the staged state will be considered。
- If the changes are too complex, it is recommended to split them into multiple independent commits.
- When a commit matches one or more commit types, it should be split into multiple commits as much as possible.
Example
For detailed examples, please refer to references/examples.md, covering:
- Basic examples：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert
- Advanced examples: including scope, breaking changes, issue numbers, co-authors, complex changes
- Bad examples: common incorrect phrasings and correction suggestions
Quick reference:
feat: 新增使用者登入功能
- 實作 JWT 認證機制
- 新增登入表單驗證
fix(cart): 修正購物車金額計算錯誤
- 修正折扣碼套用順序問題
Notes
- Only changes in the staged state will be considered
- Unstaged changes will not be included in the commit message analysis
- It is recommended to first use
git addto selectively stage the changes to be committed - If the changes are too complex, it is recommended to split them into multiple independent commits
- When a commit matches one or more commit types, it should be split into multiple commits as much as possible
Common technical term reference
| English | Traditional Chinese (Taiwan usage) |
|---|---|
| package | Package |
| config/configuration | Settings |
| script | Script |
| dependency | Dependencies |
| component | Component |
| module | Module |
| function | Function |
| variable | Variable |
| parameter | Parameter |
| implement | Implementation |
| initialize | Initialization |
| optimize | Optimization |
| refactor | Refactoring |
| validate | Verification |
| authentication | Authentication |
| authorization | Authorization |
| bug | Bug |
| pull request | Pull Request |
References
references/conventional-commits-spec.md- Conventional Commits 1.0.0-beta.4 Full Specificationreferences/examples.md- Examples of commit messages for each type- Conventional Commits Official Website
- SemVer Semantic Versioning
- @commitlint/config-conventional