git-branch-naming

Git 分支命名约定

统一的分支命名有助于追踪、实现自动化，并让仓库历史更易于浏览。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他内容……
创建新的功能／修复分支	管理 PR 工作流 → git-branch-pr-workflow
设置团队分支约定	提交更改 → git-commit-workflow
讨论命名标准	Rebase／合并策略 → git-branch-pr-workflow

分支名称格式

{type}/{issue}-{short-description}

组成部分	格式	必需	示例
type	小写前缀	是	feat、fix
issue	问题编号，不带 #	如果存在问题	123
description	kebab-case，2-5 个词	是	user-authentication

示例

# With issue number (preferred when issue exists)
feat/123-oauth-login
fix/456-null-pointer-crash
chore/789-update-dependencies
docs/101-api-reference

# Without issue number (when no issue exists)
feat/oauth-integration
fix/memory-leak-cleanup
chore/update-eslint-config
refactor/auth-service-split

分支类型

类型	用途	Conventional Commit
feat/	新功能、新能力	feat:
fix/	修复错误	fix:
chore/	维护、依赖项、配置	chore:
docs/	仅限文档	docs:
refactor/	重构代码，不改变行为	refactor:
test/	添加／更新测试	test:
ci/	CI/CD 流水线更改	ci:
hotfix/	紧急生产环境修复	fix:（带紧急标记）
release/	准备发布	chore: 或 release:

创建分支

标准工作流

# With issue number
git switch -c feat/123-user-authentication

# Without issue number
git switch -c fix/login-timeout-handling

# From specific base
git switch -c feat/456-payment-api main
git switch -c hotfix/security-patch production

验证格式

创建前，先验证格式：

# Branch name regex pattern
^(feat|fix|chore|docs|refactor|test|ci|hotfix|release)/([0-9]+-)?[a-z0-9]+(-[a-z0-9]+)*$

有效：

• feat/123-user-auth ✓
• fix/memory-leak ✓
• chore/update-deps ✓

无效：

• feature/user-auth ✗（使用 feat，而不是 feature）
• fix/UserAuth ✗（使用 kebab-case，而不是 PascalCase）
• my-branch ✗（缺少类型前缀）
• feat/fix_bug ✗（使用连字符，而不是下划线）

关联问题的最佳实践

何时包含问题编号

场景	是否包含问题编号？	示例
工作由 GitHub Issues 跟踪	是	feat/123-add-oauth
工作由外部系统（Jira、Linear）跟踪	可选	feat/PROJ-456-oauth 或 feat/oauth
探索性／预研工作	否	spike/auth-approaches
无关联问题的快速修复	否	fix/typo-readme
Dependabot／自动化 PR	否	chore/bump-lodash

外部工单系统

对于 Jira、Linear 或其他系统，请使用工单 ID：

feat/PROJ-123-user-dashboard
fix/LINEAR-456-api-timeout
chore/JIRA-789-update-sdk

描述指南

良好的描述

模式	示例	优点
动作 + 目标	add-oauth-login	清楚说明正在进行的工作
组件 + 更改	auth-service-refactor	指明受影响的部分
错误 + 背景	null-pointer-user-save	描述问题

避免使用

反模式	问题	更好的写法
fix/bug	太含糊	fix/123-login-validation
feat/new-feature	没有实际含义	feat/user-dashboard
feat/john-working-on-stuff	描述不清	feat/456-payment-flow
fix/issue-123	内容重复，且没有描述	fix/123-timeout-error
feat/add-new-user-authentication-system-with-oauth	太长	feat/oauth-authentication

长度指南

• 最少： 类型／问题编号后至少 2 个词（feat/123-user-auth）
• 最多： 5 个词，总计约 50 个字符
• 最佳范围： 3-4 个词（feat/123-oauth-token-refresh）

特殊分支模式

发布分支

release/1.0.0
release/2.1.0-beta
release/v3.0.0-rc1

热修复分支

hotfix/security-vulnerability
hotfix/critical-data-loss
hotfix/production-crash-fix

长期运行的分支

对于持续数周的工作，可考虑添加日期后缀：

feat/123-major-refactor-2026q1
epic/new-billing-system

团队约定

用户名前缀分支（可选）

对于需要关注分支所有权的大型团队：

# Pattern: {user}/{type}/{description}
alice/feat/123-oauth
bob/fix/456-memory-leak

# Or: {type}/{user}-{description}
feat/alice-oauth-integration
fix/bob-memory-leak

受保护的分支模式

为以下分支配置保护规则：

main
master
develop
release/*
hotfix/*

自动化集成

分支名称 → 提交范围

分支类型可为提交信息的范围提供参考：

分支	建议的提交信息
feat/123-auth	feat(auth): ...
fix/456-api	fix(api): ...
docs/readme	docs: ...

CI/CD 触发条件

CI 流水线触发条件的常见模式：

# GitHub Actions example
on:
  push:
    branches:
      - 'feat/**'
      - 'fix/**'
      - 'hotfix/**'
  pull_request:
    branches:
      - main

快速参考

创建分支检查清单

• 以有效的类型前缀开头（feat/、fix/ 等）
• 包含问题编号（如果工作有追踪）
• 描述采用 kebab-case 格式
• 描述为 2-5 个词
• 总长度少于 50 个字符
• 不含下划线、空格或大写字母

命令参考

操作	命令
创建分支	git switch -c feat/123-description
按类型列出	git branch --list 'feat/*'
删除本地分支	git branch -d feat/123-description
删除远程分支	git push origin --delete feat/123-description
重命名	git branch -m old-name new-name

类型选择流程图

Is it a bug fix? → fix/
Is it a new capability? → feat/
Is it documentation? → docs/
Is it maintenance/deps? → chore/
Is it restructuring code? → refactor/
Is it adding tests? → test/
Is it CI/CD changes? → ci/
Is it an emergency? → hotfix/