GitFlow

GitFlow is a branching model that assigns specific roles to branches and defines how and when they interact. It was proposed by Vincent Driessen in 2010 and became the standard for teams with scheduled releases.

How it works

Permanent branches

• main — always reflects production code. Every commit is a release.
• develop — integration branch. Completed features accumulate here for the next release.

Temporary branches

• feature/* — one per feature, branches from develop, merges back to develop
• release/* — release preparation, branches from develop, merges to main and develop
• hotfix/* — urgent production fix, branches from main, merges to main and develop

Visual flow

main:     ──●──────────────────●──────────●──
              \               / \        / \
release:       \        ──●──●   \      /   \
                \       /         \    /     \
develop:  ──●────●────●────●───●───●──●───●───●──
              \      /   \      /
feature:       ●──●──●    ●──●──●

Complete example

# 1. Start a feature
git checkout develop
git checkout -b feature/user-auth
 
# ... work, make commits ...
git commit -m "feat: add login form"
git commit -m "feat: add JWT validation"
 
# 2. Finish the feature
git checkout develop
git merge --no-ff feature/user-auth
git branch -d feature/user-auth
 
# 3. Prepare release
git checkout develop
git checkout -b release/1.2.0
 
# ... only bug fixes and preparation ...
git commit -m "fix: typo in login page"
git commit -m "chore: bump version to 1.2.0"
 
# 4. Publish release
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
 
git checkout develop
git merge --no-ff release/1.2.0
git branch -d release/1.2.0
 
# 5. Urgent hotfix
git checkout main
git checkout -b hotfix/1.2.1
 
git commit -m "fix: critical security vulnerability"
 
git checkout main
git merge --no-ff hotfix/1.2.1
git tag -a v1.2.1 -m "Hotfix 1.2.1"
 
git checkout develop
git merge --no-ff hotfix/1.2.1
git branch -d hotfix/1.2.1

When to use it

Good fit when:

• Scheduled releases (every 2 weeks, monthly, etc.)
• Multiple versions in production simultaneously
• Large team with parallel features needing controlled integration
• Software with formal QA cycle before each release
• Products with long-term support (LTS)

Avoid when:

• Continuous deployment — if you deploy multiple times a day, GitFlow adds unnecessary friction
• Small team (1-5 people) — the ceremony doesn't justify the overhead
• Web applications with a single production environment
• Projects prioritizing speed over control

Alternatives

GitHub Flow

Simplified model: only main + feature branches. Ideal for continuous deployment.

main:     ──●────●────●────●──
              \  /  \  /
feature:       ●     ●

1. Create branch from main
2. Make commits
3. Open PR
4. Review + CI
5. Merge to main
6. Deploy

Trunk-Based Development

Everyone works on main (or very short-lived branches). Requires feature flags and robust CI.

main:     ──●──●──●──●──●──●──●──

• Direct commits to main or branches that live < 1 day
• Feature flags for incomplete code
• Releases by tags or directly from main

Comparison

Tools

# git-flow CLI (official extension)
brew install git-flow-avh
 
# Initialize in a repo
git flow init
 
# Use simplified commands
git flow feature start user-auth
git flow feature finish user-auth
git flow release start 1.2.0
git flow release finish 1.2.0
git flow hotfix start 1.2.1
git flow hotfix finish 1.2.1

Anti-patterns

• Develop eternally divergent from main — if develop and main diverge too much, merges are painful
• Long-lived feature branches — branches living for weeks accumulate conflicts
• Skipping release branches — merging features directly to main breaks the model
• Not deleting finished branches — accumulation of dead branches makes navigation difficult

Why it matters

Understanding GitFlow remains relevant because many teams still use it and because its limitations teach why the industry moved toward simpler models. Knowing when GitFlow is appropriate — and when it is not — is an architectural decision that affects the delivery velocity of the entire team.

References

• A Successful Git Branching Model — Vincent Driessen, 2010. The original post that defined GitFlow.
• Note of Reflection (2020) — Vincent Driessen, 2020. The author himself acknowledges GitFlow isn't ideal for continuous delivery.
• GitHub Flow — GitHub, 2024. Official documentation of the simplified model.
• Trunk-Based Development — Paul Hammant, 2024. Complete reference for the trunk-based model.