GitFlow Hotfix Not Merged to Develop — Bug Returns

Most teams that struggle with deployments aren't bad at writing code — they're bad at managing change. Features half-done get pushed to production. A hotfix for a critical bug accidentally ships an unfinished feature alongside it. Two developers overwrite each other's work on the same branch. These aren't skill problems; they're workflow problems. And in a world where a single bad deploy can cost thousands in downtime or lost revenue, having a repeatable, structured branching strategy isn't optional — it's essential.

GitFlow, introduced by Vincent Driessen in 2010, solves exactly this chaos by giving every type of change its own lane on the road. New features live in isolation until they're ready. Releases get a dedicated stabilisation window before they go live. Emergency fixes can be applied to production without dragging half-finished work along for the ride. The model is opinionated — and that's the point. Opinions eliminate ambiguity, and ambiguity is what causes 2am incidents.

By the end of this article you'll understand not just the five branch types in GitFlow and how they relate to each other, but — more importantly — when GitFlow is the right tool and when it'll slow you down. You'll be able to set up a full GitFlow project from scratch, navigate a real-world feature-to-release cycle, apply an emergency hotfix without breaking anything, and walk into an engineering interview and confidently explain the trade-offs of GitFlow versus trunk-based development.

Why GitFlow Hotfixes Break Develop — And How to Prevent It

GitFlow is a branching model that structures releases around two long-lived branches: main (production) and develop (integration). The core mechanic is that all feature branches branch off develop, and all releases merge into both main and develop. Hotfixes branch off main to patch production, but must also merge back into develop — otherwise the fix is lost in the next release.

In practice, the hotfix branch is created from main, the fix is applied, then merged into main and tagged. The critical second merge into develop is often forgotten. When that happens, the bug reappears as soon as the next release is cut from develop. This is not a GitFlow flaw — it's a process failure. The model works only if every hotfix is merged into both branches.

Use GitFlow when you need strict release isolation and support multiple concurrent versions. It shines in regulated environments or when you must patch production without pulling in unfinished features. But it adds overhead: every hotfix requires two merges. Automate the second merge with a CI/CD pipeline or a merge-bot to eliminate the human error.

The Five-Branch Architecture — Why Each Branch Exists

GitFlow uses five branch types, and understanding the purpose of each is more important than memorising their names. Two branches are permanent and never get deleted: main and develop. Three are temporary and get cleaned up after use: feature/, release/, and hotfix/*.

main represents what's in production right now. Every commit on main is a tagged, deployed release. Nothing ever gets committed directly to main — it only ever receives merges from release or hotfix branches. Think of it as the restaurant's dining room: only finished, approved dishes arrive here.

develop is the integration branch — the staging kitchen. It holds the latest completed work that's been approved for the next release. Feature branches are cut from develop and merge back into develop when done. It's always ahead of main, and it might be slightly unstable on any given day, but it's never a mess.

Temporary branches are where the actual work happens. A feature/user-authentication branch gives one team or developer complete isolation. A release/2.4.0 branch freezes the feature set and allows only bug fixes before shipping. A hotfix/fix-payment-gateway-null-crash branch lets you patch production without touching any in-progress work. Every branch type has a strict source and a strict destination — that structure is what prevents the chaos described in the introduction.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# Full GitFlow project setup from scratch — no plugins required.
# This uses plain Git commands so you understand what's happening
# under the hood before you reach for the git-flow CLI extension.
# ─────────────────────────────────────────────────────────────

# Step 1: Create a new repo and establish the permanent branches.
git init ecommerce-platform
cd ecommerce-platform

# Create an initial commit so 'main' has a history to branch from.
echo "# E-Commerce Platform" > README.md
git add README.md
git commit -m "chore: initial project setup"

# Rename the default branch to 'main' if your Git version defaults to 'master'.
git branch -M main

# Step 2: Create the 'develop' branch from 'main'.
# 'develop' is the long-lived integration branch — all feature work lands here.
git checkout -b develop

# At this point we have our two permanent branches.
git branch
# * develop
#   main

# Step 3: Start a new feature branch.
# Feature branches are ALWAYS cut from 'develop', never from 'main'.
# The 'feature/' prefix is a convention, not a Git requirement — but follow it.
git checkout -b feature/user-authentication develop

# Simulate some development work on the feature.
echo "def authenticate_user(email, password): pass" > auth.py
git add auth.py
git commit -m "feat(auth): add user authentication scaffold"

echo "def validate_token(token): pass" >> auth.py
git add auth.py
git commit -m "feat(auth): add JWT token validation"

# Step 4: Merge the completed feature back into 'develop'.
# --no-ff (no fast-forward) forces a merge commit, which preserves the
# history of the feature branch in the graph. Without this, the feature's
# commits get absorbed into develop's linear history and you lose visibility.
git checkout develop
git merge --no-ff feature/user-authentication -m "merge: integrate user authentication feature into develop"

# Clean up the local feature branch — it's served its purpose.
git branch -d feature/user-authentication

# Step 5: Cut a release branch when develop is ready to ship.
# Release branches are cut from 'develop'. Only bug fixes, docs updates,
# and release-preparation commits should land here. No new features.
git checkout -b release/1.0.0 develop

# Simulate a pre-release bug fix found during QA.
echo "# auth module v1.0.0" >> auth.py
git add auth.py
git commit -m "fix(auth): handle empty password edge case before release"

# Step 6: Finalise the release — merge into BOTH main AND develop.
# main gets the release so production is updated.
git checkout main
git merge --no-ff release/1.0.0 -m "release: ship v1.0.0 to production"
git tag -a v1.0.0 -m "Version 1.0.0 — initial public release"

# develop must also receive the release branch changes (e.g., the QA bug fix)
# so that the fix isn't lost in future work.
git checkout develop
git merge --no-ff release/1.0.0 -m "merge: back-port release/1.0.0 fixes into develop"

# Clean up the release branch.
git branch -d release/1.0.0

echo "GitFlow project structure established successfully."

Handling Emergency Production Bugs With Hotfix Branches

Here's the scenario no one wants but every team eventually faces: it's Thursday afternoon, version 1.0.0 is live, and a critical payment processing bug is crashing checkouts for 15% of users. Meanwhile, develop already has three half-finished features merged into it that absolutely cannot ship with this emergency fix.

This is exactly why hotfix branches exist — and why their source branch being main (not develop) is so deliberate. By branching from main, you get a clean copy of exactly what's in production, untainted by anything on develop. You fix only the bug, merge back to main, tag a new patch version, and then — critically — also merge back to develop so the fix isn't lost.

That last step trips people up constantly. If you only merge the hotfix into main and forget develop, the bug you just fixed will silently re-appear in your next scheduled release when develop gets merged to main. It's one of the most insidious mistakes in GitFlow practice.

The hotfix branch also signals urgency to your team through its name. When someone sees hotfix/fix-payment-null-pointer, everyone on the team immediately knows this isn't routine work — it's a production incident, and it has priority.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# GitFlow Hotfix Cycle — Emergency production bug repair.
# Scenario: v1.0.0 is live. A null pointer crash is breaking
# the payment gateway for a subset of users. develop has
# unfinished work that cannot ship. We must fix prod NOW.
# ─────────────────────────────────────────────────────────────

# Step 1: Branch from 'main' — NOT from 'develop'.
# main = what's in production. develop = what's coming next.
# We want a clean snapshot of prod to work from.
git checkout main
git checkout -b hotfix/fix-payment-gateway-null-crash

# Step 2: Apply the targeted fix.
# In a real scenario this is where your developer fixes the bug.
cat > payment_gateway.py << 'EOF'
def process_payment(order_id, payment_details):
    # HOTFIX v1.0.1: Added None guard — payment_details was not
    # validated upstream, causing a NullPointerError on orders
    # created via the mobile API which omits the billing_zip field.
    if payment_details is None:
        raise ValueError("payment_details cannot be None — check mobile API payload")
    
    billing_zip = payment_details.get("billing_zip", "00000")  # safe default
    return {"status": "approved", "order_id": order_id, "zip": billing_zip}
EOF

git add payment_gateway.py
git commit -m "fix(payments): guard against None payment_details from mobile API"

# Step 3: Update the version number in the project metadata.
# This is important — production tags must be unique and meaningful.
echo "1.0.1" > VERSION
git add VERSION
git commit -m "chore(release): bump version to 1.0.1 for hotfix"

# Step 4: Merge hotfix into 'main' and tag the new production version.
git checkout main
git merge --no-ff hotfix/fix-payment-gateway-null-crash \
  -m "hotfix: merge payment gateway null crash fix into main"
git tag -a v1.0.1 -m "Version 1.0.1 — Emergency fix for payment gateway null crash"

# Step 5: CRITICAL — merge hotfix into 'develop' too.
# If you skip this, the bug will resurface in v1.1.0 when develop
# gets merged to main. This step is the one most teams forget.
git checkout develop
git merge --no-ff hotfix/fix-payment-gateway-null-crash \
  -m "hotfix: back-port payment gateway null crash fix into develop"

# Step 6: Delete the hotfix branch — it has served its purpose.
git branch -d hotfix/fix-payment-gateway-null-crash

# Verify the tag exists on main
git checkout main
git log --oneline --graph -5

echo "Hotfix v1.0.1 shipped and back-ported to develop successfully."

Release Management in GitFlow — The Stabilisation Window

A release branch (release/1.1.0) is cut from develop when the team agrees that the current set of features is complete enough for the next version. At that moment, no new features are allowed. Only bug fixes, version bumps, and release-related documentation changes land on this branch.

This freeze is the stabilisation window. It gives QA a fixed target; they know the feature set won't expand. It gives the ops team time to prepare deployment notes. And it gives developers time to fix the inevitable edge cases that surface when features interact for the first time in a release context.

When the release branch is stable, it merges into main with a tag, and — critically — also back into develop. The back-merge ensures that any bug fixes applied during stabilisation are carried forward. Without it, those fixes get lost in the next release cycle.

The stabilisation window is also where you handle versioning. Bump the version number in your semantic versioning scheme — MINOR for a feature release, MAJOR for breaking changes. This is the last chance for any changes before the release hits production.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# GitFlow Release Cycle — from develop to production.
# Assume develop has completed features. We now freeze for a
# release candidate.
# ─────────────────────────────────────────────────────────────

# Step 1: Cut release branch from develop.
git checkout develop
git pull origin develop
git checkout -b release/1.1.0 develop

# Step 2: Only bug fixes and version bumps from here on.
# Example: Fix a minor UI alignment issue found in QA.
echo "Version: 1.1.0" > VERSION
git add VERSION
git commit -m "chore(release): bump version to 1.1.0"

# Fix a bug: cart total rounding error
echo "def calculate_total(items): return round(sum(i.price for i in items), 2)" >> cart.py
git add cart.py
git commit -m "fix(cart): correct floating-point rounding in total calculation"

# Step 3: After QA approval, merge release into main and develop.
git checkout main
git merge --no-ff release/1.1.0 -m "release: ship v1.1.0 to production"
git tag -a v1.1.0 -m "Version 1.1.0 — Cart fixes and performance improvements"

git checkout develop
git merge --no-ff release/1.1.0 -m "merge: back-port release/1.1.0 fixes into develop"

# Step 4: Delete the release branch.
git branch -d release/1.1.0

echo "Release v1.1.0 shipped and back-ported successfully."

GitFlow vs Trunk-Based Development — Choosing the Right Workflow

GitFlow is a powerful model, but it isn't the right model for every team or every product — and knowing when not to use it is as important as knowing how to use it.

GitFlow shines when your team ships scheduled, versioned releases — think desktop software, mobile apps, open-source libraries, or enterprise SaaS with quarterly release windows. The structured branch lifecycle gives you clear separation between what's done, what's being stabilised, and what's in progress. QA teams love it because there's an explicit release branch to test against. Ops teams love it because main is always a known-good, tagged state.

Trunk-based development, by contrast, is better for teams deploying multiple times a day. Everyone commits to a single main branch (or very short-lived feature branches). Feature flags control what's visible in production. The overhead of maintaining five branch types would actively slow these teams down.

The honest answer: if your CI/CD pipeline deploys to production on every merge and your team has mature feature flagging, trunk-based is likely faster for you. If you have a QA cycle, multiple environments, compliance requirements, or a public API with versioned releases, GitFlow's structure pays for itself many times over.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# Using the git-flow CLI extension — the faster way once you
# understand the underlying model. Install first:
#   macOS:  brew install git-flow-avh
#   Ubuntu: apt-get install git-flow
#   Windows: included in Git for Windows
# ─────────────────────────────────────────────────────────────

# Initialise GitFlow in an existing repo.
# This sets up the branch naming conventions in .git/config.
# Accept all the defaults by pressing Enter through the prompts,
# or use -d flag for fully non-interactive default setup.
git flow init -d

# ── FEATURE WORKFLOW ──────────────────────────────────────────
# Start a feature — automatically branches from 'develop'
git flow feature start shopping-cart-persistence

# ... do your work, make commits ...
echo "def save_cart(user_id, cart_items): pass" > cart.py
git add cart.py
git commit -m "feat(cart): implement session-based cart persistence"

# Finish the feature — merges into develop with --no-ff, deletes branch
git flow feature finish shopping-cart-persistence
# Output: Switched to branch 'develop'
#         Merge made by the 'ort' strategy.
#         Deleted branch feature/shopping-cart-persistence

# ── RELEASE WORKFLOW ──────────────────────────────────────────
# Start a release branch from develop's current state
git flow release start 1.1.0

# Apply only bug fixes and release prep commits here
echo "1.1.0" > VERSION
git add VERSION
git commit -m "chore(release): bump version to 1.1.0"

# Finish the release:
# - merges into main AND develop
# - creates a tag automatically
# - deletes the release branch
# -m sets the tag message without opening an editor
git flow release finish -m "Version 1.1.0 — Shopping cart persistence" 1.1.0

# ── HOTFIX WORKFLOW ───────────────────────────────────────────
# Start a hotfix from main (production)
git flow hotfix start fix-cart-total-rounding-error

# Fix the bug
echo "def calculate_total(items): return round(sum(i.price for i in items), 2)" >> cart.py
git add cart.py
git commit -m "fix(cart): correct floating-point rounding in total calculation"

# Finish hotfix — merges to main AND develop, tags, deletes branch
git flow hotfix finish -m "Hotfix: cart total rounding" fix-cart-total-rounding-error

# Verify your tag history
git tag --list
echo "All workflows complete."

Common GitFlow Pitfalls and How to Avoid Them

Even experienced teams fall into these traps. The three most common:

1. Forgetting to back-port hotfixes to develop. This is the single most dangerous mistake — it causes duplicated debugging and production incidents repeated. The fix is a post-merge hook that checks the commit hash in both branches.
2. Committing new features to a release branch. The release branch is a freeze zone. When developers sneak in 'one small feature,' QA scope explodes and the release slips. The correction is strict pull request templates that reject feature commits on release branches.
3. Using fast-forward merges. Without --no-ff, the merge commit is skipped, and the branch structure disappears from the graph. Six months later, you can't tell which commits belonged to which feature. Bisecting a regression becomes guesswork. Enforce --no-ff in your Git config and CI.

These pitfalls share a root cause: the team treats GitFlow as a tool to be executed rather than a set of rules to be followed religiously. The structure only works if everyone commits to the structure.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# Post-merge hook for develop to verify hotfix back-port.
# Place this in .git/hooks/post-merge on the develop branch.
# ─────────────────────────────────────────────────────────────

REF=$1
OLDREV=$2
NEWREV=$3

# Only run on develop branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$CURRENT_BRANCH" != "develop" ]; then
    exit 0
fi

# Check if this merge was a hotfix (message contains "hotfix")
MERGE_MSG=$(git log -1 --pretty=%B)
if echo "$MERGE_MSG" | grep -qi "hotfix"; then
    echo "⚠️  Hotfix merge detected. Ensure the hotfix commit also exists in main."
    echo "   Run: git log main --oneline | grep $(git rev-parse HEAD)"
fi

exit 0

Initializing GitFlow Without the Training Wheels

Don't install the GitFlow extension. Seriously. That CLI sugar-coats the branching model and makes you forget which branches merge where. If you can't type git merge --no-ff develop from memory, you're not ready for production.

The extension creates an illusion of simplicity. When you run git flow feature finish, it auto-merges and deletes the branch. That's fine until a hotfix breaks develop and you can't trace which merge introduced the conflict because the tool hid the mechanics.

Instead, initialize a bare-bones GitFlow structure manually. Start with main and develop as orphan branches. Set develop as the default. Tag your first commit on main as v0.0.0. That's it. You now control every merge, every branch, every failure. If a junior asks why, tell them: the only way to master a workflow is to bleed through the commands your tools abstract away.

// io.thecodeforge — devops tutorial

# Create orphan branches to wipe commit history contamination
git checkout --orphan main
git rm -rf .
echo "# Project" > README.md
git add .
git commit -m "chore: initial commit on main"
git tag v0.0.0

# Branch develop from main and push both
git checkout -b develop
git push origin main develop

# Configure default branch in remote (GitHub CLI example)
gh api repos/:owner/:repo -f default_branch=develop

Hotfix Branches — Where GitFlow Meets Reality

Your pager goes off at 3:14 AM. Payment gateway is returning 500s in production. A hotfix branch is the only GitFlow construct that starts from main and merges into both main AND develop. This dual-merge creates the most common disaster: merge conflicts on develop when the hotfix changes code that's been refactored in a release branch.

Here's the fix. Create the hotfix off main, apply the patch, and test it in isolation. Before merging to main, cherry-pick the fix commit onto a temporary branch off develop. Resolve conflicts there. Then merge the hotfix to main and rebase develop onto the resolved branch. This keeps the history linear and prevents stale conflicts from poisoning the next release.

Never trust git flow hotfix finish. It assumes the hotfix codebase is identical to develop. That's a statistical lie. Manual cherry-pick and rebase gives you surgical control. The extra five minutes saves you an hour of untangling merge hell.

// io.thecodeforge — devops tutorial

# Step 1: Branch from main, apply fix
git checkout main
git checkout -b hotfix/payment-500
# ... apply fix, commit
git commit -m "fix: handle null response in payment callback"

# Step 2: Cherry-pick onto develop base, resolve conflicts
git checkout -b temp-resolve develop
git cherry-pick hotfix/payment-500
# resolve conflicts, then:
git commit -m "fix: apply hotfix to develop"

# Step 3: Merge hotfix to main, tag release
git checkout main
git merge --no-ff hotfix/payment-500 -m "hotfix: payment 500 error"
git tag -a v2.3.1 -m "hotfix payment emergency"

# Step 4: Rebase develop onto temp-resolve
git checkout develop
git rebase temp-resolve
git branch -D temp-resolve hotfix/payment-500

The Release Branch Stabilisation Window Your CI Pipeline Is Missing

Developers treat release branches like a staging environment — code gets pushed, tests run, then it's merged to main. That's cargo cult thinking. A release branch is a freeze zone. Only bug fixes, dependency patches, and documentation changes should land there. Feature additions get fast-rejected. Period.

Here's the CI hook that enforces this: configure your pipeline to fail any PR into a release branch that touches source files in more than one module. Use a diff check in the CI config. If git diff --name-only $PR_BASE...$PR_HEAD shows backend/ and frontend/ both changed, reject the merge. This forces surgical fixes and prevents scope creep.

Your stabilisation window should be three days max. Not two weeks while marketing picks a launch date. If a release takes longer than 72 hours to stabilise, your feature flags are broken or your develop branch is a landfill. Cut the window to 24 hours, learn to revert, and ship. Deadlines shrink to fit the time you give them.

// io.thecodeforge — devops tutorial

name: release-stabilization
on:
  pull_request:
    branches: ["release/*"]

jobs:
  check-scope:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Block multi-module changes
        run: |
          MODULES=$(git diff --name-only ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }} | cut -d/ -f1 | sort -u | wc -l)
          if [ "$MODULES" -gt 1 ]; then
            echo "❌ Release branch changed $MODULES modules. Only one module per PR."
            exit 1
          fi
          echo "✅ Single module change — approved"

Best Practices for Using GitFlow — Stop Copying the Pain

GitFlow isn't a religion; it's a tool for coordinating releases across teams that can't afford to break master. Most teams cargo-cult the branching model and wonder why they bleed velocity. The WHY is simple: you're treating branches like they're free. They're not. Every merge is a cognitive tax.

Start with feature flags. They let you merge incomplete work into develop without breaking the build. Never merge a feature branch that hasn't been rebased onto the latest develop — stale branches create merge hell. Keep feature branches alive for no longer than two days. If it takes longer, you're building a snowflake; split the feature.

Hotfix branches bypass develop for a reason: they're emergencies. Don't use them for regular patches. That's what release branches are for. And never merge a hotfix directly into master without also merging into develop within the same day. Otherwise, you'll orphan the fix in your next release.

Finally, tag every release commit on master. If you can't git log --oneline v1.2.0 and see exactly what shipped, you've already lost.

// io.thecodeforge — devops tutorial

// Enforce feature branch age limits in CI
git:
  branch_policy:
    feature_max_days_open: 2
    require_rebase_on_develop: true
    hotfix_sync_to_develop_within_hours: 12

release:
  tags:
    must_match: '^v\d+\.\d+\.\d+$'
    enforce_annotation: true

Preparing and Releasing with GitFlow — The Stabilization Window You're Missing

Here's the dirty secret: most teams cut a release branch and immediately start fixing bugs on it. You're treating the release branch as a garbage bin. The WHY is that you haven't built a true stabilization window into your pipeline.

A release branch is not a playground. It's a quarantine zone. You create it from develop when the feature set is frozen. Then you stop all feature merges and only push bugfixes — directly to the release branch. No develop merges, no master backports. This creates a single point of truth for what will ship.

The magic happens next: you run your full integration suite on the release branch. If it passes, you merge to master and tag. If it fails, you fix it on the release branch, not develop. Once the release ships, merge the release branch back into develop to capture those fixes. Do this within 24 hours or your develop branch rots.

Without this window, you're gambling that master is stable. It isn't. A proper stabilization window shaves hours off production outages and turns a fire drill into a checklist.

// io.thecodeforge — devops tutorial

// Example release branch workflow
jobs:
  prepare_release:
    steps:
      - git checkout -b release/1.4.0 develop
      - git push origin release/1.4.0
      # run full CI suite here — no feature merges allowed
      - if [ $? -eq 0 ]; then
          git checkout master
          git merge release/1.4.0 --no-ff
          git tag -a v1.4.0 -m "Release 1.4.0"
          git push origin master --tags
        fi
      - git checkout develop
      - git merge release/1.4.0 --no-ff
      - git branch -d release/1.4.0