Git 分支命名规则详细指南

Git 分支命名规则详细指南

分支命名不是 Git 强制要求，但一个好的命名规范能大幅提升团队协作效率、代码可读性、CI/CD 自动化友好度、历史追溯能力。

核心原则

1. 全小写字母（a-z） + 数字（0-9） + 连字符 -（kebab-case）
   → 避免下划线 _ 、驼峰式、空格、大写（跨平台兼容性更好，排序更友好）

2. 使用 / 分组（前缀/具体描述）
   → 让同类分支自动聚在一起，便于筛选

3. 前缀（type）必须有
   → 一眼看出这是什么类型的工作

4. 描述部分简洁、有意义（3–8 个单词为宜）
   → 避免太泛（update、fix、new）或太长

5. 可选但强烈推荐：带 ticket/issue ID
   → 尤其在用 Jira、Linear、GitHub Issues、Trello 的团队中

6. 长度建议：整体不超过 50–60 个字符（GitHub UI 显示友好）

主流前缀分类

前缀	英文全称 / 含义	使用时机	示例（推荐写法）
feature/	新功能、特性开发	正常迭代新增功能	feature/user-profile-page feature/JIRA-456-payment-gateway
bugfix/	普通 bug 修复（开发/测试阶段）	非紧急 bug，开发或 staging 环境发现	bugfix/cart-total-miscalculation bugfix/PROJ-789-null-check
hotfix/	紧急生产环境修复	已上线版本的严重问题（影响用户/收入/安全）	hotfix/security-token-leak-2026-01 hotfix/payment-fail-urgent
release/	准备发布的版本分支	冻结功能，只修小 bug、改文案、打 tag	release/v2.3.1 release/2026-q1-stable
refactor/	重构（不改功能，只改结构/性能）	改善代码可读性、性能、架构	refactor/user-service-cleanup
docs/	纯文档变更	README、API doc、注释、CHANGELOG	docs/api-reference-update
chore/	杂务、维护类（不影响生产代码）	更新依赖、改 CI 配置、改 .gitignore	chore/upgrade-node-20 chore/remove-unused-deps
test/	纯测试相关	新增/改测试用例，不动业务代码	test/integration/payment-flow
experiment/ spike/	实验、调研、技术验证	不确定是否合入主干的尝试	experiment/new-ai-search
wip/	正在进行中（临时）	还没做完、不想 push、给自己占位	wip/payment-redesign

推荐完整命名模板（按优先级排序）

最高推荐（团队使用）
<type>/<ticket-id>-<kebab-case-description>

feature/JIRA-1234-add-social-login
bugfix/LINEAR-567-fix-mobile-navbar-overflow
hotfix/urgent-fix-2026-01-rce-vulnerability
refactor/remove-deprecated-auth-endpoint

无 ticket 系统时的简化版（个人/小团队常用）

feature/add-dark-mode-toggle
bugfix/login-button-disabled-state
hotfix/increase-api-timeout-30s

带日期的紧急 hotfix（安全事件常用）

hotfix/2026-01-15-security-patch-jwt

禁止 / 不推荐的命名方式

• test、tmp、fix、new、update、bug（太泛，无信息量）
• feature123、bug-456（没有前缀分类）
• Feature/LoginPage（大写 + 驼峰）
• feature_user_profile（下划线，排序不友好）
• 超长名字：this-is-a-very-very-long-branch-name-for-testing-purposes-only（阅读困难）
• 只用数字：12345、20260116（完全看不懂）

团队落地建议（如何强制执行）

1. 写进项目文档

   • README.md 或 docs/branch-naming.md
   • 放进 CONTRIBUTING.md

2. GitHub / GitLab 分支保护规则

   • 用正则限制：^(feature|bugfix|hotfix|release|refactor|docs|chore)/.+$
   • 禁止直接 push 到 main / master / develop

3. 本地 hook（推荐）

   • 用 husky + commitlint 的分支名校验插件
   • 或简单 shell hook 检查前缀

4. PR 模板

   • 提醒审阅者检查分支名是否规范

5. CI 校验

   • 在 CI pipeline 第一步检查分支名，不符合就 fail