GitFlow Branching

Why Branching Strategy Matters

Without a branching strategy, teams stumble over each other. Code gets lost, deployments break, and nobody knows what is in production. A well-defined branching model gives you:

• 🔀 Parallel development without stepping on toes
• 🚢 Predictable releases with clear staging areas
• 🐛 Fast hotfix paths that bypass in-progress work
• 📜 Traceable history linking commits to stories and PRs
• 🛡️ Protection for production code from untested changes

The Five Branch Types

GitFlow defines five distinct branch types, each with a clear purpose and lifecycle.

GitFlow Visual Overview

Branch Naming Conventions

Consistent naming makes branches searchable, sortable, and self-documenting.

# Feature branches
feature/STORY-123-user-authentication
feature/STORY-456-export-csv

# Release branches
release/v1.2.0
release/v2.0.0-beta

# Hotfix branches
hotfix/FIX-789-null-pointer-crash
hotfix/FIX-012-security-patch

The Complete GitFlow Workflow

Step 1: Create a Feature Branch

git checkout develop
git pull origin develop
git checkout -b feature/STORY-123-add-login

Step 2: Develop and Commit

# Work in small, focused commits
git add src/auth/login.ts
git commit -m "feat(auth): add login form component"

git add src/auth/login.test.ts
git commit -m "test(auth): add login form unit tests"

Step 3: Open a Pull Request into develop

git push origin feature/STORY-123-add-login
# Open PR: feature/STORY-123-add-login → develop
# Get code review, pass CI checks

Step 4: Merge to develop

# Squash merge for a clean history
git checkout develop
git merge --squash feature/STORY-123-add-login
git commit -m "feat(auth): add login form (#123)"
git branch -d feature/STORY-123-add-login

Step 5: Create a Release Branch

git checkout develop
git checkout -b release/v1.2.0
# Bump version, update changelog, final QA

Step 6: Merge Release to main and Tag

git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# Back-merge to develop
git checkout develop
git merge --no-ff release/v1.2.0
git branch -d release/v1.2.0

Step 7: Hotfix Workflow

# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/FIX-789-null-pointer-crash

# Fix the bug, commit
git add src/auth/session.ts
git commit -m "fix(auth): handle null session on token refresh"

# Merge hotfix into main with --no-ff
git checkout main
git merge --no-ff hotfix/FIX-789-null-pointer-crash
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git push origin main --tags

# Back-merge hotfix into develop with --no-ff
git checkout develop
git merge --no-ff hotfix/FIX-789-null-pointer-crash
git branch -d hotfix/FIX-789-null-pointer-crash

Commit Conventions

We follow Conventional Commits to make history readable and enable automated changelogs.

Merge Strategies

git merge --squash feature/STORY-123-add-login

git merge --no-ff release/v1.2.0

Golden Rules

• 🔒 Never force push to main or develop. These are protected branches.
• 🗑️ Delete branches after merge. Stale branches create confusion and clutter.
• 🔄 Rebase feature branches on develop regularly to avoid painful merge conflicts at PR time.
• 🏷️ Tag every production release with semantic versioning (v1.2.0).
• 📝 Every merge to main should be traceable to a release or hotfix branch.

Agile Framework Commands for GitFlow

The agile framework provides commands that implement this branching model. Each command prompts you for the required inputs.