mcpField
C
conventional-branch

conventional-branch

github.com/github开发40.8k260 次安装1 天前更新
代码仓库

关于 conventional-branch

conventional-branch 面向希望统一 Git 分支命名的开发者，提供分支类型选择、名称校验、基准分支检测和创建分支的指引。

主要功能

  1. 01Conventional Branch 命名
  2. 02用途与 AI Agent 前缀
  3. 03分支名称校验
  4. 04检测基准分支
  5. 05创建并切换分支

适用场景

  1. 01为功能或修复工作命名分支
  2. 02创建 AI Agent 分支
  3. 03检查分支名是否符合规范

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/github/awesome-copilot --skill conventional-branch

安装后在 Claude Code 中输入/conventional-branch确认已加载。

详细介绍

Conventional Branch

创建符合 Conventional Branch 规范的 Git 分支，这是一套简单、一致的 Git 分支命名约定。

分支名称格式

<type>/<description>
分支类型

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

类型别名用途
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 是主干分支，不使用前缀。切勿创建与主干分支同名的新分支；应从主干分支创建分支。

命名规则

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

有效示例

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

工作流

按以下步骤操作：

步骤 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 --branch、使用其 check-branch pre-commit hook，或在 GitHub Actions 中使用 commit-check-action。GitHub rulesets、GitLab、Bitbucket 和 Git hooks 的配置请参见 https://conventionalbranch.org/enforce/。

与 Conventional Commits 的关系

Conventional Branch 与 Conventional Commits 相辅相成：

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

尽可能让分支类型与提交类型保持一致（例如，feature/* 分支搭配 feat: 提交）。

评论

支持 Markdown