Skip to content

Git Flow Workflow

The Git Flow branching model — feature, release, and hotfix branches for structured releases.

What you'll learn

  • The Git Flow branching model and its branch types
  • How feature, release, and hotfix branches work
  • When Git Flow is appropriate vs simpler workflows
  • The git-flow extension commands

Concept

What Is Git Flow?

Git Flow is a branching model proposed by Vincent Driessen in 2010. It defines a strict set of branch types and rules for how they interact, designed for projects with scheduled releases (like versioned software products).

The Branch Types

Git Flow uses five types of branches:

  1. main — production-ready code. Every commit on main is a release. Tags mark versions.
  2. develop — the integration branch for features. Contains the latest delivered features for the next release.
  3. **feature/*** — branched from develop, merged back to develop. Each new feature gets its own branch.
  4. **release/*** — branched from develop, merged to both main and develop. Prepares a release (version bumps, last fixes).
  5. **hotfix/*** — branched from main, merged to both main and develop. Fixes production bugs urgently.

The Workflow

main:    A-------------------M---H---  (tags: v1.0, v1.1)
              \             / \ /
develop:       B---F---G---R---/
                    \   / 
feature/x:          C---D---F  (merged to develop)
  1. Start a feature: git checkout -b feature/login develop
  2. Finish a feature: merge into develop
  3. Start a release: git checkout -b release/1.1 develop
  4. Finish a release: merge into main and develop, tag on main
  5. Hotfix: git checkout -b hotfix/bug main, fix, merge into main and develop

The git-flow Extension

The git-flow extension provides shortcut commands:

git flow init                    # initialize Git Flow
git flow feature start login     # create feature/login from develop
git flow feature finish login    # merge feature into develop
git flow release start 1.1       # create release/1.1
git flow release finish 1.1      # merge to main + develop, tag
git flow hotfix start bug        # create hotfix/bug from main
git flow hotfix finish bug       # merge to main + develop, tag

Install it with brew install git-flow (macOS) or your package manager.

Git Flow vs GitHub Flow

Git Flow is powerful but complex. For many projects, a simpler model works better:

GitHub Flow (simpler):

  • One main branch
  • Feature branches off main
  • Pull requests to merge into main
  • Deploy from main continuously

Trunk-Based Development (simplest):

  • Everyone commits to main (or short-lived branches)
  • Feature flags for incomplete work
  • Continuous deployment

When to Use Git Flow

Git Flow is a good fit for:

  • Versioned products with scheduled releases (e.g., desktop apps, libraries)
  • Multiple maintained versions (you need to hotfix old releases)
  • Teams that need structure and clear release phases

It is overkill for:

  • Web apps with continuous deployment
  • Small teams that can communicate informally
  • Projects where releases happen multiple times per day

Choose the simplest workflow that works for your team. You can always adopt Git Flow later if you need more structure.

Example

              # --- Initialize Git Flow (creates develop branch, etc.) ---
git flow init

# --- Feature branch workflow ---
git flow feature start user-auth
# ... work on the feature ...
git add .
git commit -m "feat: add user authentication"
git flow feature finish user-auth
# merges feature/user-auth into develop, deletes the feature branch

# --- Release workflow ---
git flow release start 1.2.0
# bump version numbers, last-minute fixes
git commit -am "chore: bump version to 1.2.0"
git flow release finish 1.2.0
# merges release into main AND develop, tags v1.2.0

# --- Hotfix workflow (urgent production bug) ---
git flow hotfix start critical-security-bug
# fix the bug
git commit -am "fix: patch security vulnerability"
git flow hotfix finish critical-security-bug
# merges into main AND develop, tags the hotfix

# --- Without the extension (manual Git Flow) ---
git checkout develop
git checkout -b feature/new-api
# ... work ...
git checkout develop
git merge --no-ff feature/new-api
git branch -d feature/new-api

# Release branch manually
git checkout develop
git checkout -b release/2.0.0
# ... version bump, fixes ...
git checkout main
git merge --no-ff release/2.0.0
git tag -a v2.0.0 -m "Release 2.0.0"
git checkout develop
git merge --no-ff release/2.0.0
git branch -d release/2.0.0
            

Shows the git-flow extension commands for features, releases, and hotfixes, plus the equivalent manual Git commands. The key insight is that releases merge to both main and develop, and hotfixes do the same. This ensures main and develop stay in sync.

Try it

Common mistakes

The mistake

Using Git Flow for a continuously deployed web app

The fix

Git Flow's release branches add overhead that does not pay off for web apps deployed multiple times per day. For continuous deployment, use GitHub Flow (feature branches + PRs to main) or Trunk-Based Development. Reserve Git Flow for versioned products with scheduled releases.

The mistake

Forgetting to merge release/hotfix branches back to both main and develop

The fix

In Git Flow, release and hotfix branches must be merged into BOTH main and develop. If you only merge into main, develop will be missing the changes and they will not be in the next release. The git-flow extension handles this automatically; if doing it manually, always merge to both.

Related Cheatsheets

Practice Git Flow Workflow

2 exercises

Practice Git Flow Workflow

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors