git-branch-naming（git 分支命名）

Git Branch Naming Conventions

Consistent branch naming improves traceability, enables automation, and makes repository history easier to navigate.

When to Use This Skill

Branch Name Format

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

Examples

# 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

Branch Types

Creating Branches

Standard Workflow

# 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

Validation Pattern

Before creating, validate the format:

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

Valid:

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

Invalid:

• feature/user-auth ✗ (use feat, not feature)
• fix/UserAuth ✗ (use kebab-case, not PascalCase)
• my-branch ✗ (missing type prefix)
• feat/fix_bug ✗ (use hyphens, not underscores)

Issue Linking Best Practices

When to Include Issue Numbers

External Ticket Systems

For Jira, Linear, or other systems, use the ticket ID:

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

Description Guidelines

Good Descriptions

Avoid

Length Guidelines

• Minimum: 2 words after type/issue (feat/123-user-auth)
• Maximum: 5 words, ~50 characters total
• Sweet spot: 3-4 words (feat/123-oauth-token-refresh)

Special Branch Patterns

Release Branches

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

Hotfix Branches

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

Long-Running Branches

For multi-week efforts, consider date suffix:

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

Team Conventions

User-Prefixed Branches (Optional)

For large teams where branch ownership matters:

# 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

Protected Branch Patterns

Configure branch protection for:

main
master
develop
release/*
hotfix/*

Automation Integration

Branch Name → Commit Scope

The branch type can inform commit message scope:

CI/CD Triggers

Common patterns for CI pipeline triggers:

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

Quick Reference

Branch Creation Checklist

• Starts with valid type prefix (feat/, fix/, etc.)
• Issue number included (if tracked work)
• Description is kebab-case
• Description is 2-5 words
• Total length under 50 characters
• No underscores, spaces, or uppercase

Command Reference

Type Selection Flowchart

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/