Branching Strategies

Git Flow Branching Model

Git Flow uses long-lived branches with structured naming. The model defines main, develop, feature/*, release/*, hotfix/*, and support/* branches.

feature/TICKET-short-description — branched from develop
release/v1.2.0 — branched from develop, merged into main and develop
hotfix/TICKET-critical-fix — branched from main, merged into both main and develop
support/v1.1.x — long-lived support branch for older versions

Best for: scheduled releases, versioned software, teams needing strict separation between development and production.

GitHub Flow Simplified Model

GitHub Flow centers on main (always deployable) with short-lived descriptive branches merged via pull requests.

feature/add-login-page — any new work
bugfix/fix-header-alignment — bug fixes
chore/update-dependencies — maintenance

Best for: continuous deployment, small-to-medium teams, projects that ship frequently.

Trunk-Based Development

Trunk-Based Development uses short-lived branches (< 1 day) from main (the "trunk") with feature flags instead of long-lived branches.

short-descriptive-name — may omit prefix entirely since branches live < 1 day
username/short-desc — optionally prefixed with author
feature-flag-name — tied to a feature flag for incremental rollout

Best for: high-velocity teams, CI/CD-heavy projects, teams practicing feature flags and pair programming.

Common Prefixes

feature/

New feature or enhancement

bugfix/

Non-urgent bug fix

hotfix/

Urgent production fix

release/

Release preparation

chore/

Maintenance, tooling, deps

docs/

Documentation changes

test/

Test additions or updates

refactor/

Code refactoring

Naming Rules

Lowercase only — use feature/add-login not Feature/Add-Login. Branch names are case-sensitive on most systems; lowercase prevents collisions.
Hyphens, not underscores — use add-login-page not add_login_page. Hyphens are the standard separator in Git branch naming.
No special characters — avoid spaces, !, @, #, $, %, ^, &, *, (, ). Use only a-z, 0-9, and -.
Use a prefix slash — always categorize with a prefix like feature/, bugfix/, etc. for readability and tooling support.
Keep it concise — aim for 3–5 words in the description. Max recommended total length is 63 characters.
Include ticket number — when applicable, place the ticket before the description: feature/PROJ-123-add-auth.

Team Templates

.gitconfig Alias

Add to ~/.gitconfig to create properly-named branches quickly:

gitconfig# Quick branch creation with naming enforcement
[alias]
  fb = "!f() { git checkout -b \"feature/$1\"; }; f"
  bb = "!f() { git checkout -b \"bugfix/$1\"; }; f"
  hb = "!f() { git checkout -b \"hotfix/$1\"; }; f"
  rb = "!f() { git checkout -b \"release/$1\"; }; f"
  cb = "!f() { git checkout -b \"chore/$1\"; }; f"
  db = "!f() { git checkout -b \"docs/$1\"; }; f"
  tb = "!f() { git checkout -b \"test/$1\"; }; f"
  # Example: git fb PROJ-123-add-user-auth

Husky Pre-Push Hook

Install husky then add this to .husky/pre-push to validate branch names before push:

shell#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Validate current branch name against conventions
BRANCH=$(git rev-parse --abbrev-ref HEAD)
VALID_PREFIXES="^(feature|bugfix|hotfix|release|chore|docs|test|refactor)/"
VALID_PATTERN="${VALID_PREFIXES}[a-z0-9]+(-[a-z0-9]+)*$"

if ! echo "$BRANCH" | grep -qE "$VALID_PATTERN"; then
  echo "❌ Invalid branch name: $BRANCH"
  echo ""
  echo "Branch names must follow the pattern:"
  echo "  <type>/<short-description>"
  echo ""
  echo "Valid types: feature, bugfix, hotfix, release, chore, docs, test, refactor"
  echo "Use lowercase with hyphens. No underscores or special characters."
  echo ""
  echo "Example: feature/add-user-authentication"
  exit 1
fi

echo "✅ Branch name valid: $BRANCH"

Frequently Asked Questions

Should I use the ticket number in the branch name?

Yes, if your team uses a ticketing system (Jira, Linear, GitHub Issues), including the ticket number creates a direct link between branches and tasks. Place it right after the prefix: feature/PROJ-123-add-auth. This enables automatic ticket-to-branch linking in most project management tools.

What happens if I use underscores or uppercase?

Git allows underscores and uppercase, but they break consistency across teams. On case-insensitive file systems (macOS, Windows), branches like Feature/X and feature/x can collide. Underscores make names harder to read in logs. Stick to lowercase and hyphens for maximum compatibility.

How do I rename an existing branch?

Rename locally with git branch -m old-name new-name. If already pushed, delete the remote: git push origin --delete old-name, then push the new name: git push origin -u new-name. Coordinate with teammates before renaming shared branches.

Git Branch Naming