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/