principlegitTip

Branch naming conventions for team workflows

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

branch naminggit branch conventionfeature branchhotfix branchnaming patterns

Error Messages

error: 'refs/heads/my bad branch name' is not a valid branch name.

Problem

Inconsistent branch names make it impossible to understand the purpose of a branch at a glance, filter branches in CI, or enforce access control rules on branch patterns.

Solution

Adopt a prefix-based naming convention:

feature/ — new functionality
fix/ — bug fixes
hotfix/ — urgent production fixes
chore/ — maintenance, deps, config
docs/ — documentation only
refactor/ — code restructuring without behavior change
test/ — adding or fixing tests

Examples:
feature/user-authentication
fix/payment-gateway-timeout
hotfix/xss-vulnerability
chore/upgrade-node-18

Include ticket numbers when applicable:
feature/PROJ-123-user-authentication
fix/BUG-456-payment-timeout

Why

Consistent prefixes enable: CI rules scoped to branch type, automatic PR template selection, branch protection rules (require reviews for release/*), and human-readable branch lists.

Gotchas

Avoid slashes beyond one level deep — some tools have issues with nested slashes in branch names
Branch names cannot contain spaces, ~, ^, :, ?, *, [, or begin with / or end with .lock
Keep branch names short enough to read in terminal output — under 50 characters is a good target

Code Snippets

Branch naming convention examples

# Create branches with consistent naming
git checkout -b feature/PROJ-123-user-auth
git checkout -b fix/BUG-456-payment-timeout
git checkout -b hotfix/CVE-2024-security-patch
git checkout -b chore/upgrade-dependencies

# List all feature branches
git branch -r | grep 'feature/'

Context

Establishing or enforcing team git workflow standards

Revisions (0)

No revisions yet.