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/