GitFlow Workflow Explained — Branches, Releases and Real-World Usage

# io.thecodeforge — GitFlow Project Setup

# ─────────────────────────────────────────────────────────────
# 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."

# io.thecodeforge — GitFlow Hotfix Cycle

# ─────────────────────────────────────────────────────────────
# 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 hot 1.0.0 is live, and a criticalfix"

# 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."

# io.thecodeforge — GitFlow CLI Quickstart

# ─────────────────────────────────────────────────────────────
# 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."