当前位置：首页 > news >正文

git命名分支规范

news 2025/9/26 13:16:35

以下是一些广泛认可且实用的 Git 分支命名规范建议：

核心原则

清晰性： 看一眼分支名称就应该大致知道这个分支的目的（是开发新功能？修复 Bug？准备发布？）。
一致性： 整个团队（甚至整个组织）使用相同的规范。
简洁性： 在保证清晰的前提下尽量简短。
可读性： 使用分隔符（如 /, -, _）提高可读性，避免特殊字符或空格。
工具友好性： 命名应易于被 CI/CD 工具、项目管理工具（如 Jira, GitHub Issues）解析和集成。

常用分支类型及命名模式

最常见的做法是使用前缀来标识分支的类型，后面跟上描述性的名称。以下是一些核心分支类型及其命名建议：

主分支 (长期存在)
- main/ master: 代表生产环境的稳定代码。这是最重要的分支，通常受保护（禁止直接推送）。
- develop: 代表下一个发布版本的集成开发分支。功能分支通常合并到这里。
功能/特性分支 (短期存在)
- 模式： feature/<简短描述>或 feat/<简短描述>
- 示例：
  - feature/user-authentication
  - feat/add-search-filter
  - feature/ISSUE-123-add-payment-gateway(如果关联了问题跟踪编号，如 Jira ISSUE-123)
- 说明： 用于开发单个新功能或特性。分支名应清晰描述该功能。
Bug 修复分支 (短期存在)
- 模式： bugfix/<简短描述>或 fix/<简短描述>或 hotfix/<简短描述>
- 示例：
  - bugfix/login-page-crash
  - fix/ISSUE-456-typo-in-error-message
  - hotfix/critical-security-patch(用于需要紧急修复生产环境 Bug 的分支，通常直接从 main创建，修复后合并回 main和 develop)
- 说明： 用于修复代码库中的缺陷。区分 bugfix(针对 develop分支) 和 hotfix(针对 main分支的生产环境紧急修复)。
发布分支 (短期存在，用于发布准备)
- 模式： release/<版本号>或 release/v<版本号>
- 示例：
  - release/1.2.0
  - release/v2.0.0-rc1(带候选版本标识)
- 说明： 当 develop分支的功能达到一个稳定状态，准备发布时创建。用于最后的测试、小修小补和版本号标记。合并到 main后通常会被打上 Tag。
环境分支 (可选，长期存在)
- 模式： environment/<环境名称>
- 示例：
  - environment/staging
  - environment/uat(用户验收测试)
- 说明： 代表特定环境（如预发布环境、测试环境）的部署状态。这些分支通常由 CI/CD 系统自动更新（例如，将 release/1.2.0合并到 environment/staging触发部署到预发布环境）。
重构分支 (短期存在)
- 模式： refactor/<简短描述>
- 示例：
  - refactor/user-service-modularization
- 说明： 专门用于进行代码重构，不引入新功能或修复 Bug（除非是重构过程中发现的明显错误）。
实验性/探索性分支 (短期存在)
- 模式： spike/<简短描述>或 experiment/<简短描述>
- 示例：
  - spike/integrate-new-database
  - experiment/new-ui-framework
- 说明： 用于技术调研、原型验证或尝试新想法，结果可能不会合并回主分支。

命名最佳实践和技巧

使用小写字母： 推荐全部使用小写字母，避免大小写混淆（不同操作系统对大小写敏感度不同）。
分隔符： 使用连字符 -或下划线 _连接单词。斜杠 /常用于分隔类型前缀和描述（如 feature/）。避免使用空格！
描述性： 在类型前缀之后的部分要足够描述分支的目的。如果使用了问题跟踪系统（Jira, GitHub Issues），强烈建议包含问题编号（如 ISSUE-123）。这提供了直接的追溯链接。
简洁： 在清晰的前提下尽量简短。避免过长的描述。
避免特殊字符： 不要使用 ~, ^, :, *, ?, [, ], @, !, #, $, &, |, ;, <, >等特殊字符。它们可能在 Git 命令或脚本中引起问题。
日期（谨慎使用）： 通常不推荐在分支名中加入日期，因为分支的创建时间 Git 本身会记录。但在某些特定场景（如每日构建分支）可能有用。
作者/所有者（谨慎使用）： 通常不推荐加入作者名，因为 git blame或提交历史可以追踪。团队协作中，分支可能被多人修改。

示例汇总

feature/ISSUE-789-implement-checkout-flow
bugfix/ISSUE-101-fix-cart-total-calculation
hotfix/critical-api-timeout-issue
release/v1.3.0
refactor/cleanup-legacy-config
spike/evaluate-graphql-for-reporting
environment/staging(由 CI 管理)

如何实施

团队讨论： 与团队成员一起讨论并确定最适合你们工作流的规范。
文档化： 将最终确定的规范写入团队的 Wiki、README 或共享文档中。
工具辅助：
- Git Hooks: 可以编写客户端 pre-commit或 commit-msg钩子来检查分支名是否符合规范（需要团队成员安装）。
- CI/CD 检查： 在 CI 流程中加入步骤，检查 Pull Request 的来源分支名是否符合规范，不符合则阻止合并。
- 项目管理工具集成： 利用 Jira、GitHub Issues 等的功能，在创建分支时自动生成符合规范的分支名（例如，Jira 的 "Create Branch" 按钮）。
Code Review： 在 Code Review 中，将分支命名是否符合规范也作为一项检查点。