git-branch-naming

Git Branch Naming Conventions

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

When to Use This Skill

Use this skill when...	Use something else when...
Creating a new feature/fix branch	Managing PR workflows → git-branch-pr-workflow
Setting up team branch conventions	Committing changes → git-commit-workflow
Discussing naming standards	Rebase/merge strategies → git-branch-pr-workflow

Branch Name Format

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

Component	Format	Required	Example
type	Lowercase prefix	Yes	feat, fix
issue	Issue number, no #	If issue exists	123
description	kebab-case, 2-5 words	Yes	user-authentication

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

Type	Purpose	Conventional Commit
feat/	New features, capabilities	feat:
fix/	Bug fixes	fix:
chore/	Maintenance, deps, config	chore:
docs/	Documentation only	docs:
refactor/	Code restructuring, no behavior change	refactor:
test/	Adding/updating tests	test:
ci/	CI/CD pipeline changes	ci:
hotfix/	Emergency production fixes	fix: (with urgency)
release/	Release preparation	chore: or release:

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

Scenario	Include Issue?	Example
Work tracked in GitHub Issues	Yes	feat/123-add-oauth
Work tracked in external system (Jira, Linear)	Optional	feat/PROJ-456-oauth or feat/oauth
Exploratory/spike work	No	spike/auth-approaches
Quick fix without issue	No	fix/typo-readme
Dependabot/automated PRs	No	chore/bump-lodash

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

Pattern	Example	Why Good
Action + Target	add-oauth-login	Clear what's being done
Component + Change	auth-service-refactor	Identifies affected area
Bug + Context	null-pointer-user-save	Describes the issue

Avoid

Anti-pattern	Problem	Better
fix/bug	Too vague	fix/123-login-validation
feat/new-feature	Meaningless	feat/user-dashboard
feat/john-working-on-stuff	Not descriptive	feat/456-payment-flow
fix/issue-123	Redundant, no description	fix/123-timeout-error
feat/add-new-user-authentication-system-with-oauth	Too long	feat/oauth-authentication

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:

Branch	Suggested Commits
feat/123-auth	feat(auth): ...
fix/456-api	fix(api): ...
docs/readme	docs: ...

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

Action	Command
Create branch	git switch -c feat/123-description
List by type	git branch --list 'feat/*'
Delete local	git branch -d feat/123-description
Delete remote	git push origin --delete feat/123-description
Rename	git branch -m old-name new-name

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/