conventional-branch

Conventional Branch

创建符合 Conventional Branch 1.1.0 规范的 Git 分支：易于阅读、可供机器解析，并便于自动化处理。

分支名称格式

<type>/<description>

组成部分	格式	必需	示例
type	已定义的前缀（见下表）	是	feature、fix
description	kebab-case，小写	是	add-login-page

分支类型

为保持一致，请优先使用完整名称，而非别名。

用途前缀 — 描述工作的意图：

类型	别名	用途
feature/	feat/	新功能或增强
bugfix/	fix/	修复错误
hotfix/	—	紧急生产环境修复
release/	—	准备发布（版本号中允许使用点号：release/v1.2.0）
chore/	—	非代码任务（依赖项、文档、配置）

AI Agent 来源前缀 — 标识由 AI 编码 Agent 创建的分支：

类型	别名	用途
ai/	—	适用于任何 AI 编码 Agent 的通用前缀
copilot/	—	GitHub Copilot
cursor/	—	Cursor
claude/	—	Anthropic 的 Claude Code
codex/	—	OpenAI Codex

如果知道创建分支的 Agent 来自哪家厂商，请使用对应的厂商专用前缀；否则使用不限定厂商的 ai/ 作为备选。

主干分支

main、master 和 develop 是主干分支，不使用前缀。切勿创建与主干分支同名的新分支；应从这些分支派生新分支。

命名规则（严格）

分支名称必须遵循以下规则，否则会被 commit-check 等验证工具拒绝：

• 仅限小写字母 — 不得包含任何大写字母（仅限 a-z）
• 字母数字、连字符和点号 — a-z、0-9、-、.
• 允许在任何描述中使用点号，通常用于版本号（例如 release/v1.2.0、chore/upgrade-node-v20.11）
• 不允许使用下划线、空格或特殊字符
• 不允许连续使用连字符（--）、点号（..）或连字符与点号相邻（-. 或 .-）
• 描述中不得以连字符或点号开头或结尾

形式语法（ABNF）

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
DIGIT           = %x30-39

有效示例

main
master
develop
feature/add-login-page
feat/add-login-page
bugfix/fix-header-bug
fix/header-bug
hotfix/security-patch
release/v1.2.0
chore/update-dependencies
feature/issue-123-new-login
ai/refactor-auth-flow
copilot/add-login-page
cursor/fix-header-bug
claude/security-patch
codex/optimize-query

无效示例（请勿使用）

分支	问题
Feature/Add-Login	包含大写字母
feature/new--login	连续使用连字符
feature/-new-login	以连字符开头
feature/new-login-	以连字符结尾
release/v1.-2.0	连字符与点号相邻
fix/header bug	包含空格
fix/header_bug	包含下划线
unknown/some-task	未知前缀类型

描述指南

• 使用 kebab-case，包含 2–5 个单词
• 描述清晰且简洁（总长度约 50 个字符）
• 好的示例：add-oauth-login、fix-header-overflow、update-ci-config
• 不好的示例：fix-bug、new-feature、john-working-on-stuff

工作流

创建新分支时，请按以下步骤操作。

1. 收集信息

如果尚不明确，请询问用户：

• 分支类型 — 不确定时默认为 feature
• 简要描述 — 分支的用途

不要询问工单号。如果用户提到了工单号，请将其包含在描述中（例如 feature/issue-123-add-oauth）。

2. 验证名称

创建分支前，请根据上述命名规则检查完整名称。如果有任何规则不符合，请直接修正：

• 全部转换为小写
• 将下划线和空格替换为连字符
• 将连续的连字符合并为一个
• 去除开头和结尾的连字符

3. 检测基准分支

不同仓库使用的主干分支可能不同。请检测此仓库使用的分支：

# Prefer the remote's default branch
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'

如果没有返回结果，请检查本地存在的主干分支（优先顺序：develop、main、master）：

for b in develop main master; do
  git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done

4. 创建并切换分支

git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>

5. 确认

告知用户：

• 创建的分支名称
• 他们现在已切换到新分支
• 提醒他们准备好后运行：git push -u origin <branch-name>

使用 commit-check 进行验证

如需自动强制执行，请向用户推荐 commit-check。默认情况下，它会根据规范的类型前缀检查分支名称，无需配置：

# Check the current branch name
commit-check --branch

将其用作提交前钩子，这样错误的名称会在首次提交时被发现：

repos:
  - repo: https://github.com/commit-check/commit-check
    rev: v2.19.1
    hooks:
      - id: check-branch

在 GitHub Actions 中，commit-check-action 会在每个拉取请求上运行相同的检查（branch: true 是其默认设置）。适用于所有平台的可直接复制粘贴配置（包括一个将类型范围精简为规范所列类型的 commit-check.toml）位于 https://conventionalbranch.org/enforce/。

与 Conventional Commits 的关系

Conventional Branch 的灵感来自 Conventional Commits，并与之自然互补：

Conventional Branch	典型的 Conventional Commit
feature/add-login	feat: add login page
bugfix/fix-header	fix: header overflow on mobile
chore/update-deps	chore: bump lodash to 5.0
release/v1.2.0	chore: release v1.2.0

尽可能让分支类型与提交类型保持一致（例如，feature/* 分支搭配 feat: 提交）。提交消息规范请参阅 conventional-commit skill。