Git 分支命名规范与策略

一个明确的 Git 分支命名规范是高效团队协作的基石。当每个开发者都遵循相同的命名模式时，代码审查变得更快，CI/CD 管道可以根据分支类型自动部署，整个提交历史也变得自文档化。本全面指南涵盖了最流行的分支命名策略、强制执行技术以及各种规模团队的实际示例。

使用我们的 Git 命令生成器交互式生成命令 →

使用我们的 Slug 生成器创建 URL 友好的别名 →

为什么分支命名规范很重要

分支名不仅仅是标签，它们是沟通工具，告诉你的团队正在进行什么工作、属于哪个模块以及应该如何处理。没有一致的命名规范，仓库很快就会充斥着“fix”、“test2”、“johns-branch”和“final-final-v3”这样的分支。以下是规范重要的原因：

团队协作：当同事看到 feature/PROJ-123-add-oauth-login 时，他们立即知道这是一个功能分支，关联工单 PROJ-123，与 OAuth 登录相关。不需要发 Slack 消息询问。

CI/CD 自动化：构建系统可以根据分支前缀触发不同的管道。功能分支只运行测试，发布分支部署到测试环境，热修复分支快速上线到生产环境。

可读性和可搜索性：在有数百个分支的情况下，一致的命名使 git branch --list "feature/*" 和拉取请求过滤器真正变得有用。你可以立即找到与特定区域相关的所有工作。

自动清理：脚本可以根据命名模式识别和删除过时分支，无需手动干预即可保持仓库整洁。

# Without conventions - chaos:
git branch
  fix
  test2
  johns-branch
  final-final-v3
  new-feature
  temp

# With conventions - clarity:
git branch
  feature/PROJ-101-user-dashboard
  feature/PROJ-102-search-api
  bugfix/PROJ-200-login-redirect
  hotfix/PROJ-301-payment-timeout
  release/2.1.0
  chore/upgrade-dependencies

常见分支前缀

最广泛采用的规范使用类型前缀加斜杠。每个前缀表明分支的意图和范围，让人立即明白分支包含什么类型的工作。

feature/ — 新功能或增强。这是最常见的前缀。示例：feature/user-profile-page、feature/JIRA-456-search-api

bugfix/ — 非紧急的错误修复，计划在下个版本中发布。示例：bugfix/fix-login-redirect、bugfix/PROJ-789-null-pointer

hotfix/ — 需要立即部署的紧急生产修复。示例：hotfix/payment-gateway-timeout、hotfix/security-patch-xss

release/ — 用于版本发布和最终测试的发布准备分支。示例：release/2.1.0、release/2024-q1-sprint

chore/ — 维护任务、依赖更新、配置变更。示例：chore/upgrade-node-20、chore/update-ci-config

docs/ — 仅文档变更。示例：docs/update-api-reference、docs/add-contributing-guide

test/ — 添加或更新测试。示例：test/add-e2e-checkout-flow、test/increase-coverage-auth

refactor/ — 不改变行为的代码重构。示例：refactor/extract-payment-service、refactor/simplify-middleware

# Creating branches with proper prefixes
git checkout -b feature/add-user-authentication
git checkout -b bugfix/fix-cart-total-calculation
git checkout -b hotfix/critical-security-patch
git checkout -b release/3.0.0
git checkout -b chore/update-eslint-config
git checkout -b docs/add-api-documentation
git checkout -b test/add-integration-tests
git checkout -b refactor/extract-auth-module

格式模式与示例

最有效的分支命名格式结合了类型前缀、可选的工单号和简短的 kebab-case 描述。以下是行业中最常用的模式：

模式 1：type/description — 简单清晰，适合小团队或没有工单系统的开源项目。

模式 2：type/TICKET-123-description — 企业团队的黄金标准。将分支直接链接到 Jira、Linear 或 GitHub Issues 等工单追踪器。

模式 3：username/type/description — 在大型组织中很有用，可以一眼看出谁拥有这个分支。

# Pattern 1: type/description (simple)
feature/add-dark-mode
bugfix/fix-email-validation
hotfix/patch-sql-injection

# Pattern 2: type/TICKET-ID-description (enterprise)
feature/PROJ-123-add-oauth-login
bugfix/PROJ-456-fix-null-pointer
hotfix/PROJ-789-fix-payment-gateway

# Pattern 3: username/type/description (large teams)
john/feature/add-search-filters
sarah/bugfix/fix-timezone-offset
alex/hotfix/fix-rate-limiter

# Creating a branch with ticket ID
git checkout -b feature/PROJ-123-add-oauth-login

# Listing branches by prefix
git branch --list "feature/*"
git branch --list "hotfix/*"
git branch --list "*/PROJ-123*"

分支命名规则

Git 对分支名有特定的技术约束，团队在此基础上添加自己的规范。遵循这些规则可以防止错误并保持仓库一致性：

不能有空格：Git 不允许分支名中包含空格。使用连字符（-）或下划线（_）作为分隔符。连字符是行业标准。

允许的字符：使用小写字母数字、连字符、下划线和斜杠。避免特殊字符，如 ~、^、:、?、*、[、\ 和连续的点（..）。

最大长度：虽然 Git 技术上允许最多 255 个字符，但应将分支名保持在 50-60 个字符以内以提高可读性。长名称在大多数 Git UI 中会被截断，且难以输入。

大小写规范：全部使用小写。混合大小写会导致混淆，并且在不区分大小写的文件系统（如 macOS 和 Windows）上可能会造成问题。唯一的例外是工单 ID，通常为大写（例如 PROJ-123）。

不能以点或 .lock 结尾：分支名不能以 .lock 或句号结尾，也不能以连字符开头。

# VALID branch names
feature/add-login-page
bugfix/PROJ-123-fix-null-check
release/2.1.0
chore/update-deps
john/feature/dark-mode

# INVALID branch names
feature/add login page       # spaces not allowed
feature/add..login           # consecutive dots not allowed
-feature/login               # cannot start with hyphen
feature/login.lock           # cannot end with .lock
feature/add~login            # tilde not allowed
feature/add:login            # colon not allowed

# Check if a branch name is valid before creating
git check-ref-format --branch "feature/my-new-branch"

# Rename a poorly named branch
git branch -m "bad name" feature/proper-name

Git Flow 分支策略

Git Flow 由 Vincent Driessen 于 2010 年提出，是最结构化的分支模型。它使用多个长期分支和严格的工作流，非常适合有计划发布的项目。

main（或 master）— 始终反映生产就绪状态。main 上的每个提交都应该是经过测试的发布。

develop — 功能汇聚的集成分支。该分支始终包含下一个版本的最新开发变更。

feature/* — 从 develop 分支创建，合并回 develop。每个功能都有自己的分支。

release/* — 当功能完成时从 develop 分支创建。用于最终测试、版本号更新和文档编写，然后合并到 main 和 develop。

hotfix/* — 从 main 分支创建，用于紧急生产修复。合并回 main 和 develop。

# Git Flow branch structure:
#
#  main ─────────●────────────●──────────●───▶ (production releases)
#                │            ▲          ▲
#                │         merge      merge
#                │            │          │
#  release/ ─────┼────── release/2.0 ────┘
#                │            ▲
#                │         merge
#                │            │
#  develop ──●───●───●───●────●───●───●──────▶ (integration)
#            │       ▲   │        ▲
#         branch  merge branch  merge
#            │       │   │        │
#  feature/ ─┴───●───┘   └──●────┘
#
#  hotfix/ ──────────────────────────── (from main, merge to main + develop)

# Start a new feature
git checkout develop
git checkout -b feature/PROJ-100-user-auth

# Complete a feature
git checkout develop
git merge --no-ff feature/PROJ-100-user-auth
git branch -d feature/PROJ-100-user-auth

# Start a release
git checkout develop
git checkout -b release/2.0.0

# Complete a release
git checkout main
git merge --no-ff release/2.0.0
git tag -a v2.0.0 -m "Release 2.0.0"
git checkout develop
git merge --no-ff release/2.0.0
git branch -d release/2.0.0

# Start a hotfix
git checkout main
git checkout -b hotfix/fix-critical-bug

# Complete a hotfix
git checkout main
git merge --no-ff hotfix/fix-critical-bug
git tag -a v2.0.1 -m "Hotfix 2.0.1"
git checkout develop
git merge --no-ff hotfix/fix-critical-bug
git branch -d hotfix/fix-critical-bug

GitHub Flow：简化的分支模式

GitHub Flow 是 Git Flow 的轻量级替代方案。它只有一个规则：main 上的任何内容都是可部署的。所有工作都在功能分支中进行，通过拉取请求合并。这种模式最适合实践持续部署的团队。

工作流很简单：（1）从 main 创建分支，（2）添加提交，（3）开启拉取请求，（4）讨论和审查代码，（5）从分支部署进行测试，（6）合并到 main。没有 develop、release 或 hotfix 分支——只有 main 和功能分支。

# GitHub Flow workflow:
#
#  main ──●──────────────●──────────────●──▶ (always deployable)
#         │              ▲              ▲
#      branch         merge          merge
#         │              │              │
#         └──●──●──●─PR─┘    └──●──PR──┘
#           feature/login    feature/search

# Step 1: Create a feature branch from main
git checkout main
git pull origin main
git checkout -b feature/add-search-functionality

# Step 2: Work on your feature, commit often
git add .
git commit -m "Add search input component"
git add .
git commit -m "Implement search API endpoint"
git add .
git commit -m "Add search results pagination"

# Step 3: Push and open a pull request
git push -u origin feature/add-search-functionality
# Then open a PR on GitHub

# Step 4: After PR approval, merge to main
# (Usually done via GitHub UI with "Squash and merge" or "Merge")

# Step 5: Clean up
git checkout main
git pull origin main
git branch -d feature/add-search-functionality
git push origin --delete feature/add-search-functionality

主干开发（Trunk-Based Development）

主干开发将简化做到了极致。开发者直接提交到单一分支（trunk/main），或使用非常短命的功能分支，只持续几个小时而不是几天。这种策略需要强大的测试覆盖率和功能标志来管理未发布的代码。

短命分支：功能分支只存在几个小时到最多两天。它们小而集中，频繁合并以避免偏离。

功能标志：未完成的功能隐藏在功能标志（也称功能开关）后面，允许代码合并到 main 而不会对用户可见。这消除了对长期运行分支的需求。

持续集成：每次提交到主干都会触发完整的 CI 管道。主干始终处于可发布状态。这是 Google、Meta 和许多高效能工程团队采用的模式。

# Trunk-based development workflow:
#
#  main ──●──●──●──●──●──●──●──●──●──●──●──▶ (trunk, always releasable)
#         │     ▲  │  ▲     │  ▲
#       branch  │ branch │  branch │
#         │  merge │  merge  │  merge
#         └──●──┘  └──●──┘  └──●──┘
#        (hours)   (hours)   (hours)
#     short-lived feature branches

# Create a short-lived branch (will merge within hours)
git checkout main
git pull origin main
git checkout -b feature/add-tooltip-component

# Work quickly, commit small changes
git add src/components/Tooltip.tsx
git commit -m "Add Tooltip component with feature flag"

# Merge back quickly (same day)
git checkout main
git pull origin main
git merge feature/add-tooltip-component
git push origin main
git branch -d feature/add-tooltip-component

# Feature flag example (code merged but hidden)
# if (featureFlags.isEnabled('new-tooltip')) {
#   return <NewTooltip />;
# }
# return <OldTooltip />;

使用 Git Hooks 自动强制执行

规范的价值取决于其执行力度。Git hooks 允许你在代码推送前自动验证分支名，确保每个分支都遵循团队的命名规则。

pre-push hook 在任何推送到远程之前在本地运行。它可以将分支名与正则表达式模式匹配，并拒绝不符合规范的分支的推送。

Git Hook: pre-push

Create a .git/hooks/pre-push script that validates branch names before pushing:

#!/bin/bash
# .git/hooks/pre-push - Validate branch naming convention

BRANCH=$(git symbolic-ref --short HEAD)

# Allow main, develop, and HEAD (detached)
if [[ "$BRANCH" == "main" || "$BRANCH" == "develop" || "$BRANCH" == "HEAD" ]]; then
  exit 0
fi

# Regex pattern for valid branch names
# Matches: feature/PROJ-123-description, bugfix/description, etc.
PATTERN="^(feature|bugfix|hotfix|release|chore|docs|test|refactor)/[a-zA-Z0-9._-]+(/?[a-zA-Z0-9._-]+)*$"

if [[ ! "$BRANCH" =~ $PATTERN ]]; then
  echo "ERROR: Branch name '$BRANCH' does not match naming convention."
  echo ""
  echo "Branch names must follow the pattern:"
  echo "  type/description"
  echo "  type/TICKET-123-description"
  echo ""
  echo "Valid prefixes: feature, bugfix, hotfix, release, chore, docs, test, refactor"
  echo ""
  echo "Examples:"
  echo "  feature/PROJ-123-add-login"
  echo "  bugfix/fix-email-validation"
  echo "  hotfix/critical-security-patch"
  exit 1
fi

exit 0

Husky 是 JavaScript/TypeScript 项目中最流行的 Git hooks 管理工具。它使 hooks 的安装和团队共享变得轻而易举。

Husky + commitlint Setup

# Install Husky and set up hooks
npm install --save-dev husky
npx husky init

# Create the pre-push hook
cat > .husky/pre-push << 'EOF'
#!/bin/bash
BRANCH=$(git symbolic-ref --short HEAD)

if [[ "$BRANCH" == "main" || "$BRANCH" == "develop" ]]; then
  exit 0
fi

PATTERN="^(feature|bugfix|hotfix|release|chore|docs|test|refactor)/[a-zA-Z0-9._-]+$"

if [[ ! "$BRANCH" =~ $PATTERN ]]; then
  echo "Branch name '$BRANCH' does not follow naming convention."
  echo "Use: type/description (e.g., feature/add-login)"
  exit 1
fi
EOF

chmod +x .husky/pre-push

# Verify it works
git checkout -b invalid-name
git push  # Will be rejected by the hook

git checkout -b feature/valid-branch-name
git push  # Will succeed

CI/CD 与分支模式集成

现代 CI/CD 系统使用分支模式触发不同的工作流。通过遵循一致的分支命名规范，你可以根据分支前缀自动化整个构建、测试和部署管道。

GitHub Actions 使用 on.push.branches 和 glob 模式来匹配分支名。你可以为 feature、release 和 hotfix 分支运行不同的任务。

GitHub Actions

# .github/workflows/ci.yml
name: CI Pipeline

on:
  push:
    branches:
      - main
      - develop
      - 'feature/**'
      - 'bugfix/**'
      - 'hotfix/**'
      - 'release/**'
  pull_request:
    branches: [main, develop]

jobs:
  # Run tests on ALL branches
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  # Deploy to staging only on release branches
  deploy-staging:
    needs: test
    if: startsWith(github.ref, 'refs/heads/release/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: ./deploy.sh staging

  # Deploy to production only on main
  deploy-production:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: ./deploy.sh production

  # Fast-track hotfixes
  deploy-hotfix:
    needs: test
    if: startsWith(github.ref, 'refs/heads/hotfix/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: ./deploy.sh hotfix-staging

  # Validate branch name
  validate-branch:
    runs-on: ubuntu-latest
    steps:
      - name: Check branch name
        run: |
          BRANCH=${GITHUB_REF#refs/heads/}
          PATTERN="^(main|develop|(feature|bugfix|hotfix|release|chore|docs|test|refactor)/.+)$"
          if [[ ! "$BRANCH" =~ $PATTERN ]]; then
            echo "::error::Branch '$BRANCH' does not follow naming convention"
            exit 1
          fi

GitLab CI 使用 rules 关键字和正则表达式模式来控制哪些任务在哪些分支上运行。这允许基于分支命名进行细粒度的管道控制。

GitLab CI

# .gitlab-ci.yml
stages:
  - validate
  - test
  - deploy

validate-branch-name:
  stage: validate
  script:
    - |
      PATTERN="^(main|develop|(feature|bugfix|hotfix|release|chore|docs|test|refactor)/.+)$"
      if [[ ! "$CI_COMMIT_BRANCH" =~ $PATTERN ]]; then
        echo "Branch name does not follow convention: $CI_COMMIT_BRANCH"
        exit 1
      fi
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"

test:
  stage: test
  script:
    - npm ci
    - npm test
  rules:
    - if: $CI_COMMIT_BRANCH

deploy-staging:
  stage: deploy
  script:
    - ./deploy.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH =~ /^release\/.+$/

deploy-production:
  stage: deploy
  script:
    - ./deploy.sh production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

受保护分支规则

受保护分支防止直接推送并强制代码审查。结合命名规范，它们创建了一个健壮的工作流，关键分支不会被意外修改。

保护 main 和 develop：合并前需要拉取请求审查。不允许直接推送。启用状态检查（CI 必须通过），并要求合并前分支是最新的。

分支保护模式：GitHub 和 GitLab 都支持通配符模式。你可以用 release/* 保护所有发布分支，用 hotfix/* 保护所有热修复分支。

# GitHub CLI: Configure branch protection rules
# Protect main branch
gh api repos/{owner}/{repo}/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["test"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":2}' \
  --field restrictions=null

# List protected branches
gh api repos/{owner}/{repo}/branches --jq '.[] | select(.protected) | .name'

# View protection rules for a branch
gh api repos/{owner}/{repo}/branches/main/protection

# GitHub branch ruleset (newer approach, supports wildcards)
# Settings > Rules > Rulesets > New ruleset
# Target branches: main, develop, release/*, hotfix/*
# Rules:
#   - Require pull request before merging (2 approvals)
#   - Require status checks to pass
#   - Require branches to be up to date
#   - Block force pushes
#   - Block deletions

按项目类型分类的示例

不同的项目类型和团队规模适合不同的规范。以下是实用建议：

开源项目：使用简单前缀，不带工单号。贡献者不应该需要访问你的工单系统来命名分支。模式：feature/add-dark-mode、fix/broken-link-readme。在 CONTRIBUTING.md 中更新命名规则。

初创公司（2-10 个开发者）：使用 GitHub Flow，短前缀加可选的工单 ID。速度比仪式更重要。模式：feat/onboarding-flow、fix/signup-validation。使用 Linear 或 GitHub Issues 进行轻量级跟踪。

企业团队（50+ 开发者）：使用 Git Flow，强制要求工单 ID 和所有者前缀。使用 hooks 和 CI 自动执行。模式：feature/PROJ-1234-payment-refund-api、hotfix/PROJ-5678-fix-rate-limiter。每个分支必须映射到一个被跟踪的工单。

# Open Source Project
feature/add-dark-mode
feature/improve-accessibility
fix/broken-link-readme
fix/typo-contributing-guide
docs/update-installation-guide
chore/upgrade-to-react-19

# Startup (GitHub Flow)
feat/onboarding-flow
feat/stripe-integration
fix/signup-validation
fix/mobile-responsive-nav
chore/setup-sentry

# Enterprise (Git Flow + Jira)
feature/PROJ-1234-payment-refund-api
feature/PROJ-1235-admin-dashboard-v2
bugfix/PROJ-2001-currency-rounding-error
hotfix/PROJ-3001-fix-rate-limiter
release/4.2.0
chore/PROJ-4001-upgrade-java-21
john.doe/feature/PROJ-1236-audit-logging

常见问题

最佳的 Git 分支命名规范是什么？

最佳规范取决于你的团队规模和工作流。对于大多数团队，type/TICKET-123-short-description 模式很合适。使用 feature/、bugfix/、hotfix/、release/ 和 chore/ 等前缀对工作进行分类。关键是一致性——选择一种格式并通过 Git hooks 或 CI 检查在整个团队中强制执行。

分支名应该用斜杠还是连字符？

两者都用，但用途不同。斜杠（/）将分支类型前缀与描述分开（例如 feature/add-login）。连字符（-）分隔描述中的单词。这创建了一个清晰的层次结构，Git UI 会将其显示为文件夹。尽量避免使用下划线作为主要分隔符，尽管它是有效的。

Git 分支名应该多长？

将分支名保持在 50-60 个字符以内。虽然 Git 允许最多 255 个字符，但较短的名称在终端输出、Git GUI 和拉取请求列表中更容易阅读。好的分支名应该足够描述性以便一瞄即懂，但足够简洁以避免输入错误。例如：feature/PROJ-123-add-oauth 比 feature/PROJ-123-add-oauth-login-with-google-and-github-providers 更好。

创建分支后可以重命名吗？

可以。使用 "git branch -m old-name new-name" 重命名本地分支，或使用 "git branch -m new-name"（如果你在要重命名的分支上）。如果已经推送了旧分支，需要推送新名称并删除远程的旧分支："git push origin new-name" 然后 "git push origin --delete old-name"。注意有开放 PR 的分支，PR 仍会引用旧名称。

如何在团队中强制执行分支命名规范？

结合使用 Git hooks 和 CI 检查。在本地，设置 pre-push hook（JS 项目使用 Husky，或自定义脚本）根据正则表达式模式验证分支名。在服务器端，在 GitHub 或 GitLab 中配置分支保护规则，只允许符合特定模式的分支。你还可以添加一个 CI 任务，如果分支名不符合规范则失败。在 CONTRIBUTING.md 文件中记录规则。

一致的 Git 分支命名规范可以将混乱的仓库转变为一个有组织、自动化且自文档化的代码库。从基础开始，用 hooks 强制执行，随团队增长迭代优化。试试我们下面的工具来简化你的 Git 工作流。

试试 Git 命令生成器 →

使用 Slug 生成器创建 URL 友好的分支名 →