约定式分支

约定式分支 1.1.0

概述

约定式分支是指 Git 分支的结构化和标准化命名约定，旨在使分支更具可读性和可操作性。我们建议了一些您可能想要使用的分支前缀，但您也可以指定自己的命名约定。一致的命名约定使按类型识别分支变得更加容易。

要点

1. 以目的为导向的分支名称：每个分支名称都清楚地表明了其目的，使所有开发人员都能轻松了解该分支的用途。
2. 与 CI/CD 集成：通过使用一致的分支名称，它可以帮助自动化系统（如持续集成/持续部署管道）根据分支类型触发特定操作（例如，从发布分支自动部署）。
3. 团队协作：它通过明确分支目的来鼓励团队内部的协作，减少误解并使团队成员更容易在任务之间切换而不会产生混淆。

规范

分支命名前缀

分支规范支持以下前缀，其结构应如下：

<type>/<description>

用途前缀（Purpose Prefixes） — 描述工作的意图：

• feature/ (或 feat/)：用于新功能（例如 feature/add-login-page, feat/add-login-page）
• bugfix/ (或 fix/)：用于错误修复（例如 bugfix/fix-header-bug, fix/header-bug）
• hotfix/：用于紧急修复（例如 hotfix/security-patch）
• release/：用于准备发布的分支（例如 release/v1.2.0）
• chore/：用于非代码任务，如依赖项、文档更新（例如 chore/update-dependencies）

AI 智能体源前缀（AI Agent Source Prefixes） — 识别由 AI 编码智能体生成的分支：

主干分支（main、master、develop）不使用前缀。

基本规则

1. 使用小写字母、数字、连字符和点：分支名称应全部使用小写字母 (a-z)、数字 (0-9) 及连字符 (-) 进行分隔。避免使用特殊字符、下划线或空格。任何分支的描述中都可以使用点 (.)，通常用于表示版本号（例如 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. 保持清晰简洁：分支名称应简明扼要，清楚表达工作的内容和目的。
4. 包含工单编号：如果适用，应包含项目管理工具中的工单编号，以便于追踪。例如，对于工单 issue-123，分支名称可以是 feature/issue-123-new-login。

形式文法

以下 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   ; 小写字母 a-z
DIGIT           = %x30-39   ; 数字 0-9

注意：禁止连续的连字符或点，以及出现在描述开头或结尾的连字符或点。

示例

结论

• 清晰的沟通：仅凭分支名称就能清楚地了解代码更改的目的。
• 自动化友好：轻松挂接自动化流程（例如，针对 feature, release 等的不同工作流程）。
• 可扩展性：适用于许多开发人员同时处理不同任务的大型团队。

总之，约定式分支旨在改善 Git 工作流程中的项目组织、沟通和自动化。

工具

使用这些工具在你的项目中采用并强制执行约定式分支：

• commit-check: 在本地检查分支名称、提交信息和相关 Git 元数据。
• commit-check-action: 在 GitHub Actions 中自动验证分支名称。
• Conventional Branch Skill: 教 AI 编程助手创建有效的约定式分支名称。

使用以下命令安装该 skill：

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

常见问题

什么是分支名称？

分支名称是 Git 给一条开发线起的标签，例如 main 或 feature/add-login-page；Git 把它作为 refs/heads/ 下的一个引用（ref）保存。Git 能接受的名称范围很广，所以分支名称本身并不能可靠地说明分支上在做什么工作。约定式分支为它规定了 <type>/<description> 的结构：先是说明工作用途的类型，然后是简短的小写描述，单词之间用连字符分隔。例如：

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

主干分支（main、master、develop）不使用前缀。

feature 分支应该如何命名？

以 feature/ 或其简写形式 feat/ 开头，在斜杠后描述该功能。如果这项工作在项目管理工具中有对应的工单，请包含工单编号。例如：

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

什么是 chore 分支？

chore/ 分支用于非代码任务，例如更新依赖项或文档。分支类型有意比 Conventional Commits 的类型少（见下文），因此这类维护工作都归入 chore/。例如：

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

Renovate 等一些依赖更新机器人也可以配置为使用这个前缀；参见机器人与自动化。

release 分支应该如何命名？

使用 release/，后面跟上该分支要准备的内容，通常是版本号。可以使用点，但不能出现在描述的开头或结尾，也不能紧邻连字符：

• release/v1.2.0 — 有效
• release/v1.2.0. — 无效：以点结尾
• release/v1.-2.0 — 无效：连字符紧邻点号

统一的前缀还能让管道针对 release/* 触发操作，例如从发布分支自动部署。

hotfix 分支应该如何命名？

紧急修复使用 hotfix/，不紧急的修复使用 bugfix/（或 fix/）。描述要修复的内容；如果有工单，请包含工单编号。例如：

• hotfix/security-patch
• hotfix/issue-123-security-patch
• bugfix/fix-header-bug，用于不紧急的修复

约定式分支与约定式提交（Conventional Commits）有什么关系？

约定式分支的灵感来源于 Conventional Commits，遵循相似的理念：为 Git 元数据引入人机可读的结构。约定式提交规范化了提交信息，约定式分支规范化了分支名称。两者相辅相成，天然互补。

约定式分支发明了这些前缀吗？

没有。feature/、hotfix/、release/ 这类前缀在 2010 年前后由 git-flow 工具推广开来，也是 Bitbucket 分支模型等工具的默认值。约定式分支建立在这一实践之上，而不是要取代它。它补充的是一份人和工具都能共用的精确定义：固定的类型集合、形式文法、发布在 spec.json 中的校验正则，以及一致性测试用例，让每个校验工具接受的名称完全相同。

为什么分支类型不像 Conventional Commits（例如 build、ci、docs、style、refactor）那么详细？

分支与提交不同 —— 分支是临时的，大部分只出现在合并前。为分支引入过多类型是没有必要的，也会让管理和记忆变得更困难。

我可以定义规范列表之外的自定义分支类型吗？

可以，作为团队层面的扩展。文法中列出的类型是所有符合规范的工具都会接受的类型，因此像 unknown/some-task 这样的分支按规范本身是无效的。如果团队需要更多类型（例如 experiment/），应在校验工具中显式列出它们（例如 commit-check 的 allow_branch_types），并写进文档，让团队成员和自动化工具保持一致。例如，本规范自己的仓库就在 commit-check 配置中为 Dependabot 创建的分支添加了 dependabot/。

为什么分支名称必须小写？

有两个原因。第一，Git 通常把分支引用存成 .git/refs/heads/ 下的文件，而 macOS 和 Windows 默认的文件系统不区分大小写：Feature/login 和 feature/login 在这些机器上指向同一个路径，在 Linux 上却是两个不同的分支，所以同时允许两种写法的仓库，在不同克隆中的行为可能不一致。第二，只有一种写法更容易输入、搜索和匹配：按 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 分支名称仍然完全有效 —— 没有不兼容的变更。

为什么要添加 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 智能体可以采用已记录的 prefix，而不是自行创建临时的模式

ai/ 通用前缀适用于没有专用前缀的 AI 智能体，或者适用于倾向于使用供应商无关标识符的团队。这是 v1.1.0 发布的关键新特性 —— 版本间变更的完整摘要请参见上一条常见问题。

如何处理 develop 或 staging 等长期存在的分支？

长期存在的集成或环境分支（如 develop，以及某些项目约定使用的 staging、production 等）通常被视为主干分支，不需要前缀，并应在整个项目中保持一致的命名。需要注意的是，在上文给出的 ABNF 语法中，trunk-branch 形式规则只包含 main / master / develop；staging、production 等仅作为各团队可选的长期分支示例，不属于该形式语法的一部分，语法校验工具可按需要在此基础上扩展支持。

如果团队成员不符合此规范，可以使用哪些工具来自动识别？

你可以使用 commit-check 来检查分支规范，或者如果你的代码托管在 GitHub 上，则使用 commit-check-action。