Branching Strategy

Choose and apply the right branching model for the project's size, team, and release cadence.

When to Use

• Creating a new branch for a feature, fix, or release
• Deciding between merge and rebase
• Setting up a new repository's branching conventions
• Discussing release management and deployment strategies
• Resolving merge conflicts or untangling branch history

Core Patterns

Branch Naming Conventions

Use a consistent prefix/slug format:

# Format: <type>/<ticket-id>-<short-description>
feature/AUTH-123-add-sso-login
fix/BUG-456-null-pointer-on-logout
refactor/TECH-789-extract-auth-service
hotfix/SEC-101-patch-xss-vulnerability
release/v2.3.0
chore/TECH-202-upgrade-node-20

# Without ticket system
feature/add-user-registration
fix/prevent-race-condition-in-cache

Rules:

• Lowercase with hyphens (kebab-case)
• Keep under 50 characters after the prefix
• Include ticket ID when available
• Use descriptive slugs, not cryptic abbreviations

Git Flow (Structured Releases)

Best for: projects with scheduled releases, multiple environments, or compliance requirements.

main ────────●────────────────●──────────── (production)
              \              /
release/v2.1   ●────●──────●               (stabilization)
              /      \
develop ────●────●────●────●────●────────── (integration)
            \        /          \
feature/x    ●──●──●            \
                                 \
feature/y                         ●──●──●

# Start a feature
git checkout develop
git checkout -b feature/AUTH-123-add-sso

# Complete a feature — merge back to develop
git checkout develop
git merge --no-ff feature/AUTH-123-add-sso
git branch -d feature/AUTH-123-add-sso

# Create a release branch
git checkout develop
git checkout -b release/v2.1.0

# Finalize release
git checkout main
git merge --no-ff release/v2.1.0
git tag -a v2.1.0 -m "Release v2.1.0"
git checkout develop
git merge --no-ff release/v2.1.0

# Hotfix from production
git checkout main
git checkout -b hotfix/SEC-101-patch-xss
# ... fix applied ...
git checkout main
git merge --no-ff hotfix/SEC-101-patch-xss
git tag -a v2.1.1 -m "Hotfix v2.1.1"
git checkout develop
git merge --no-ff hotfix/SEC-101-patch-xss

Trunk-Based Development (Continuous Delivery)

Best for: small teams, CI/CD pipelines, frequent deployments.

main ──●──●──●──●──●──●──●──●──●── (always deployable)
        \   /  \   /      \   /
         ●─●    ●─●        ●─●     (short-lived branches, <2 days)

# Short-lived feature branch
git checkout main
git pull --rebase origin main
git checkout -b feature/add-search

# Keep branch fresh (daily)
git fetch origin
git rebase origin/main

# Merge back quickly (within 1-2 days)
git checkout main
git merge --no-ff feature/add-search
git push origin main

Key rules for trunk-based:

• Branches live less than 2 days
• Feature flags for incomplete work
• Main is always deployable
• No long-lived branches except main

Merge vs Rebase Decision

# REBASE: Use for local branch cleanup before merging
# Produces linear history, easier to read
git checkout feature/my-work
git rebase main
git checkout main
git merge --no-ff feature/my-work

# MERGE: Use for integrating shared/public branches
# Preserves full history and merge points
git checkout main
git merge --no-ff feature/my-work

# SQUASH MERGE: Use for PRs with messy intermediate commits
# Produces single clean commit on target branch
git checkout main
git merge --squash feature/my-work
git commit -m "feat: add search functionality"

Golden rule: Never rebase commits that have been pushed to a shared branch.

Anti-Patterns

What NOT to Do

• Long-lived feature branches: Branches open for weeks accumulate merge conflicts and drift from main. Keep branches short-lived.
• Committing directly to main: Even solo developers benefit from branch-based workflow for rollback safety.
• Rebasing shared branches: Rewriting history on branches others work on causes lost commits and confusion.
• Inconsistent naming: Mixing feature/, feat/, Feature/, and no prefix makes automation and filtering impossible.
• No branch protection: Main/develop should require PR reviews and CI checks. Never force-push to protected branches.

# BAD: Direct commit to main
git checkout main
git commit -m "feat: add new feature"
git push

# BAD: Rebase a shared branch
git checkout develop
git rebase main  # Others are also working on develop!

# GOOD: Feature branch with PR
git checkout -b feature/add-search
# ... work ...
# Open PR, get review, merge via PR

Quick Reference

Branch Naming:
  feature/<ticket>-<description>
  fix/<ticket>-<description>
  hotfix/<ticket>-<description>
  release/v<semver>
  chore/<ticket>-<description>

Strategy Selection:
  Scheduled releases + multiple envs  -> Git Flow
  Continuous delivery + small team    -> Trunk-based
  Open source + many contributors     -> GitHub Flow (fork + PR)

Merge Strategy:
  Local cleanup         -> rebase then merge --no-ff
  Shared branch         -> merge --no-ff (never rebase)
  Messy PR commits      -> squash merge

Rules:
  - Never rebase public/shared branches
  - Never force-push to main or develop
  - Keep feature branches under 2 days (trunk-based)
  - Always use --no-ff for merge commits (preserves branch history)
  - Delete branches after merging