Branch Naming Conventions

Also Known As

TL;DR

Explanation

Common convention: type/short-description where type is feature, fix, hotfix, release, chore, refactor, or docs. Examples: feature/user-oauth-login, fix/checkout-total-rounding, hotfix/critical-xss-patch, release/2.1.0. Rules: lowercase only, hyphens not spaces (spaces are awkward in shell), descriptive but concise. Include ticket/issue number for traceability: feature/PROJ-123-user-oauth. Protected branches (main, develop, release/*) enforced via branch protection rules.

Common Misconception

Why It Matters

Common Mistakes

• Spaces in branch names: git checkout -b 'my feature' — problematic in many shell contexts.
• All changes in main/develop without feature branches — no code review, no CI isolation.
• Single-letter or cryptic names: fix/abc, wip2, test-branch.
• No type prefix — cannot distinguish features from fixes from hotfixes at a glance.

Code Examples

# Cryptic branch names:
git checkout -b paul
git checkout -b fix
git checkout -b new-stuff
git checkout -b wip-checkout
git checkout -b 'my feature branch'  # Space causes problems
# In GitHub: 23 open PRs, no idea what any of them are

# Clear convention: type/ticket-description
git checkout -b feature/PROJ-123-user-oauth-login
git checkout -b fix/PROJ-456-checkout-total-rounding
git checkout -b hotfix/critical-xss-in-comment-form
git checkout -b release/2.1.0
git checkout -b chore/upgrade-dependencies-march

# Enforced by CI: branch must match pattern
# ^(feature|fix|hotfix|release|chore|refactor|docs)\/[a-z0-9-]+$

References

• ↗ https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow

Tags

Related Terms