約定式分支

約定式分支 1.1.0

概述

約定式分支（Conventional Branch）是指針對 Git branch 的結構化、標準化命名慣例，旨在讓 branch 更易讀且更具可操作性。我們提供一些您可能想採用的 branch 前綴建議，但您也可以自行制定命名慣例。一致的命名慣例能讓您更容易依類型辨識 branch。

要點

1. 以目的為導向的 branch 名稱：每個 branch 名稱都清楚表明其目的，讓所有開發人員都能輕鬆理解該 branch 的用途。
2. 與 CI/CD 整合：透過一致的 branch 命名，它可以協助自動化系統（例如 Continuous Integration/Continuous Deployment 管線）根據 branch 類型觸發特定動作（例如，從 release branch 自動部署）。
3. 團隊協作：藉由明確標示 branch 的目的，促進團隊協作、降低誤解，並讓成員更容易在不同任務間切換而不致混淆。

規範

branch 命名前綴

此 branch 規範支援以下前綴，並應採用如下結構：

<type>/<description>

用途前綴（Purpose Prefixes） — 描述工作的意圖：

• feature/（或 feat/）：用於新功能（例如 feature/add-login-page、feat/add-login-page）
• bugfix/（或 fix/）：用於 bug 修復（例如 bugfix/fix-header-bug、fix/header-bug）
• hotfix/：用於緊急修復（例如 hotfix/security-patch）
• release/：用於準備發布的 branch（例如 release/v1.2.0）
• chore/：用於非程式碼任務，例如相依套件、文件更新（例如 chore/update-dependencies）

AI 智能體來源前綴（AI Agent Source Prefixes） — 識別由 AI 編碼智能體產生的分支：

主幹分支（main、master、develop）不使用前綴。

基本規則

1. 使用小寫英數、連字號與點：一律使用小寫字母（a-z）、數字（0-9）與連字號（-）分隔單字，避免特殊字元、底線或空白。任何 branch 的描述中都可以使用點（.），通常用於表示版本號（例如 release/v1.2.0、chore/upgrade-node-v20.11）。
2. 禁止連續、開頭或結尾的連字號或點：連字號與點不得連續出現（例如 feature/new--login、release/v1.-2.0），也不得出現在描述的開頭或結尾（例如 feature/-new-login、release/v1.2.0.）。
3. 保持清楚且精簡：branch 名稱應在具描述性的同時保持精簡，清楚表達工作的內容與目的。
4. 包含工單編號：若適用，請包含專案管理工具的工單編號，方便追蹤。例如，對於工單 issue-123，branch 名稱可以是 feature/issue-123-new-login。

形式文法

以下 ABNF（Augmented Backus-Naur Form）文法正式定義了有效的 branch 名稱：

branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
                / "ai" / "copilot" / "cursor"
                / "claude" / "codex"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; 小寫字母 a-z
DIGIT           = %x30-39   ; 數字 0-9

注意：禁止連續的連字號或點，以及出現在描述開頭或結尾的連字號或點。

示例

結論

• 清楚溝通：僅從 branch 名稱即可清楚理解此程式碼變更的目的。
• 自動化友善：容易串接自動化流程（例如針對 feature、release 等的不同工作流程）。
• 可擴充性：適用於大型團隊，同時有許多開發人員處理不同任務的情境。

總結來說，Conventional Branch 的設計目標是改善 Git 工作流程中的專案組織、溝通與自動化。

工具

使用這些工具在您的專案中採用並強制執行約定式分支：

• commit-check: 在本機檢查 branch 名稱、commit 訊息與相關 Git metadata。
• commit-check-action: 在 GitHub Actions 中自動驗證 branch 名稱。
• Conventional Branch Skill: 教 AI 程式助理建立有效的約定式 branch 名稱。

使用以下指令安裝該 skill：

npx skills add conventional-branch/conventional-branch --skill conventional-branch

FAQ

什麼是 branch 名稱？

branch 名稱是 Git 為一條開發線所取的標籤，例如 main 或 feature/add-login-page；Git 會把它存成 refs/heads/ 底下的一個 ref。Git 接受的名稱範圍很廣，因此光看 branch 名稱，無法可靠地得知 branch 上在進行什麼工作。約定式分支為它規定了 <type>/<description> 的結構：先是說明工作用途的 type，接著是簡短的小寫描述，單字之間以連字號分隔。例如：

• feature/add-login-page
• bugfix/fix-header-bug
• release/v1.2.0

主幹分支（main、master、develop）不使用前綴。

feature branch 應該如何命名？

以 feature/ 或其簡寫形式 feat/ 開頭，並在斜線後描述該功能。若這項工作在專案管理工具中有對應的工單，請包含工單編號。例如：

• feature/add-login-page
• feat/add-login-page
• feature/issue-123-new-login

什麼是 chore branch？

chore/ branch 用於非程式碼任務，例如更新相依套件或文件。branch type 刻意比 Conventional Commits 的 type 少（見下文），因此這類維護工作都歸入 chore/。例如：

• chore/update-dependencies
• chore/upgrade-node-v20.11
• chore/update-generated-files

Renovate 等部分相依套件更新機器人也可以設定為使用這個前綴；請參閱機器人與自動化。

release branch 應該如何命名？

使用 release/，後面接上該 branch 要準備的內容，通常是版本號。可以使用點，但不能出現在描述的開頭或結尾，也不能緊鄰連字號：

• release/v1.2.0 — 有效
• release/v1.2.0. — 無效：以點結尾
• release/v1.-2.0 — 無效：連字號緊鄰點號

一致的前綴也能讓管線針對 release/* 觸發動作，例如從 release branch 自動部署。

hotfix branch 應該如何命名？

緊急修復使用 hotfix/，不緊急的修復則使用 bugfix/（或 fix/）。描述要修復的內容；若有工單，請包含工單編號。例如：

• hotfix/security-patch
• hotfix/issue-123-security-patch
• bugfix/fix-header-bug，用於不緊急的修復

約定式分支與約定式提交（Conventional Commits）有什麼關係？

約定式分支的靈感來源於 Conventional Commits，遵循相似的理念：為 Git 中繼資料引入人機可讀的結構。約定式提交規範提交訊息，約定式分支規範 branch 名稱，兩者相輔相成、天然互補。

約定式分支發明了這些前綴嗎？

沒有。feature/、hotfix/、release/ 這類前綴約在 2010 年由 git-flow 工具推廣開來，也是 Bitbucket branching model 等工具的預設值。約定式分支建立在這項實務之上，而非取而代之。它補上的是一份人與工具都能共用的精確定義：固定的 type 集合、形式文法、發布於 spec.json 的驗證正規表示式，以及一致性測試案例，讓每個驗證工具接受的名稱完全相同。

為什麼 branch type 不像 Conventional Commits（例如 build、ci、docs、style、refactor）那麼詳細？

branch 與 commit 不同——branch 是暫時性的，通常只會使用到 merge 為止。若為 branch 引入過多 type 並無必要，反而會讓管理與記憶變得更困難。

我可以定義規範列表之外的自訂 branch type 嗎？

可以，作為團隊層級的擴充。文法中列出的 type 是所有符合規範的工具都會接受的 type，因此像 unknown/some-task 這樣的 branch 依規範本身是無效的。若團隊需要更多 type（例如 experiment/），應在驗證工具中明確列出（例如 commit-check 的 allow_branch_types），並寫入文件，讓團隊成員與自動化工具保持一致。例如，本規範自己的 repository 就在 commit-check 設定中為 Dependabot 建立的 branch 加入了 dependabot/。

為什麼 branch 名稱必須小寫？

原因有二。第一，Git 通常將 branch 參照存成 .git/refs/heads/ 下的檔案，而 macOS 與 Windows 預設的檔案系統不區分大小寫：Feature/login 與 feature/login 在這些機器上指向同一路徑，在 Linux 上卻是兩個不同的 branch，因此同時允許兩種寫法的 repository 在不同 clone 中的行為可能不一致。第二，只有一種寫法更容易輸入、搜尋與比對：依 release/* 觸發的工具不必再考慮 Release/*。

v1.1.0 與 v1.0.0 的主要差異是什麼？

v1.1.0 的主要新功能是引入了 AI 智能體來源前綴（AI Agent Source Prefixes）（具體原因見下一條常見問題）。同時，版本化網站增加了版本切換器，使用者可以瀏覽 v1.0.0 和 v1.1.0 兩種規範。所有現有的 v1.0.0 branch 名稱仍然完全有效 —— 沒有不相容的變更。

為什麼要添加 AI 智能體來源前綴（AI Agent Source Prefixes）？

AI 編碼智能體（GitHub Copilot、Cursor、Claude Code、OpenAI Codex 等）越來越多地被用於生成程式碼和建立 Pull Request。每個智能體都使用自己的分支前綴（例如 copilot/、cursor/）。透過在約定式分支規範中標準化這些前綴，我們可以實現：

1. 快速識別 — 審查者和工具可以立即識別 AI 生成的 PR
2. 工具驗證 — 諸如 commit-check 之類的工具可以驗證 AI 智能體分支是否符合規範
3. 註冊標準 — 新的 AI 智能體可以採用已記錄的前綴，而不是自行建立臨時的模式

ai/ 通用前綴適用於沒有專用前綴的 AI 智能體，或者適用於傾向於使用供應商中立識別碼的團隊。這是 v1.1.0 發佈的關鍵新特性 —— 版本間變更的完整摘要請參見上一條常見問題。

如何處理 develop 或 staging 等長期存在的 branch？

長期存在的整合或環境 branch（例如 develop、staging、production）通常在專案層級被視為主幹分支，不需要前綴，且應在整個專案中保持一致的命名。依照本規範前文所述的 ABNF 正式文法，預設的 trunk-branch 僅包含標準主幹名稱（例如 main、master、develop）；其他名稱（如 staging、production）則屬於專案自訂的延伸，建議在團隊文件中明確記錄，以便工具與成員正確辨識。

有哪些工具可以自動識別團隊成員是否符合此規範？

您可以使用 commit-check 檢查 branch 規範；若您的程式碼託管於 GitHub，則可使用 commit-check-action。