Branch Naming Conventions
Git does not care what your branches are called — xyz, aaa, final-final-fix all work. But people care. Good branch names make the branch list readable, make PR titles intelligible, and help automation (linters, CI rules, deploy scripts) treat branches consistently. A convention costs nothing and pays back every time you scan a long list of branches.
The most common convention
prefix/short-description
feature/login-form feature/dark-mode fix/login-redirect fix/safari-flicker hotfix/critical-payment-bug chore/upgrade-react chore/eslint-config refactor/extract-auth-hook refactor/simplify-router docs/contributing-guide test/checkout-flow
The slash is just a convention — Git treats it as part of the name. Some tools (GitHub, GitLab) use it to display branches in a hierarchical tree, which keeps long lists tidy.
Common prefixes
feature/— a new feature or capability.fix/— a bug fix.hotfix/— an urgent fix going straight to production.chore/— maintenance work, dependency upgrades, build config.refactor/— restructuring code without changing behaviour.docs/— documentation only.test/— tests only.release/— preparing a release (oftenrelease/v1.2.0).experiment/— exploration, may be thrown away.
Including ticket IDs
If your team uses Jira / Linear / GitHub Issues
feature/PROJ-123-login-form fix/JIRA-4567-safari-redirect-loop chore/issue-89-bump-react
Linking the ticket in the branch name lets automation (Jira/GitHub integrations) auto-link PRs and update ticket status as the branch progresses.
Style rules
Use hyphens (
-) between words. Spaces are not allowed; underscores are valid but less common.All lowercase. Mixed case works but is harder to type and remember.
Keep it short. 3–6 words after the prefix is usually enough.
feature/lfis too cryptic;feature/refactor-the-whole-auth-flow-to-support-oauth-passwords-and-magic-linksis too long.Be specific.
fix/loginis vague;fix/login-redirect-loop-safariis searchable.Avoid generic words.
fix/bug,update/changes,wip— all of these are no better than no name at all.No personal pronouns. Not
my-fixoralice-feature. Branches outlive the person who created them.
What Git does and does not allow
✅ Letters, digits, hyphens, dots, slashes (used as separators).
❌ Cannot start with
-.❌ Cannot contain
..,~,^,:, spaces, or?.❌ Cannot end with
/or.lock.❌ Cannot contain ASCII control characters.
❌ Component cannot be a single character
@.
git check-ref-format --branch "some/branch" — non-zero exit means the name is invalid.Conventions in popular workflows
Gitflow: uses
feature/,release/,hotfix/,develop,main, andsupport/.GitHub Flow: any descriptive branch name from
main. Nodevelopbranch.Trunk-Based: very short-lived branches, often named with just the ticket ID or a few words.
Conventional Branch (community): mirrors Conventional Commits —
feat/,fix/,docs/, etc.
What about long-lived branches?
main(ormaster) — the production-ready branch.develop— integration branch in Gitflow.staging/production— environment branches in some workflows.release/v1.x— a stabilising line for a major release.
These have no prefix because they are not throwaway work — they are the trunks the feature branches sprout from.
Enforcing the convention
Pre-push hooks (e.g., with Husky) can reject pushes to names not matching a regex.
Server-side hooks on self-hosted Git servers can reject non-conforming branch names at receive time.
Branch protection rules on GitHub/GitLab can require certain naming patterns for protected paths.
Examples — good vs bad
Good
feature/oauth-google-login fix/cart-total-rounding chore/upgrade-typescript-5 docs/api-rate-limits refactor/extract-payment-service
Less good
fix ← too vague new-thing ← what new thing? alice-branch ← Alice may leave; the branch outlasts her WIP ← will every branch be 'WIP'? my-fix-final-v2 ← Git itself versions things .fix ← starts with a dot, suspicious