Git Checkout -b — Direct Push to Main Broke Payments

git checkout -b creates a branch and switches to it in one command. It solves the core problem of parallel development: isolating your changes from everyone else's work without asking permission or copying files.

A branch is a 41-byte pointer to a commit — not a folder copy. Creating one is free and instant regardless of repository size. This mental model explains why branching feels instant, why switching is fast, and why merging is possible.

Common misconceptions: that branches duplicate files (they don't — they're pointers), that checkout -b is the only way to create branches (switch -c is the modern replacement), instead of a clunky file copy, it creates a lightweight and that you can safely branch without pulling first (you can't — stale base creates merge conflicts). The most dangerous mistake is committing to main without realizing you never created a branch.

What Git Is Actually Doing When You Run checkout -b

Before you touch the command, you need a mental model of what a branch actually is — because if you think it's a folder copy, you'll be confused forever.

A branch in Git is nothing more than a named pointer to a commit. That's it. A tiny text file containing a 40-character hash. When you run git checkout -b feature/user-authentication, Git does two things: it creates that pointer file in .git/refs/heads/ pointing at your current commit, then it moves a special pointer called HEAD to point at your new branch. HEAD is Git's way of saying 'this is where I am right now.' No files are copied. No new directory is created. The whole operation takes milliseconds regardless of how large your codebase is.

Why does this matter? Because it explains everything about how branches behave. Switching branches feels instant because Git is just updating two pointers and swapping out the files that differ between commits. Creating a branch is free because it's literally creating a 41-byte file. And merging is possible because Git can trace the commit history through those pointers and figure out exactly what changed on each branch.

Without this mental model, branch operations feel like magic. With it, they feel inevitable.

# io.thecodeforge — Git Branch Internals

# Check where HEAD currently points before creating a branch
# This shows you your current branch — in this case, main
git branch
# Output: * main

# Create and switch to a new branch in a single command
# The -b flag means 'create this branch if it doesn't exist, then switch to it'
git checkout -b feature/user-authentication

# Now let's look at what Git actually created on disk
# Git stores branch pointers as plain text files under .git/refs/heads/
cat .git/refs/heads/feature/user-authentication
# Output: a3f8c1d2e4b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0
# That 40-char hash IS the branch — it's just a pointer to a commit

# HEAD now points to the new branch, not main
cat .git/HEAD
# Output: ref: refs/heads/feature/user-authentication

# Confirm the switch worked — asterisk shows your active branch
git branch
# Output:
#   main
# * feature/user-authentication

# The new branch starts at exactly the same commit as main
# No files changed, nothing was copied — just a new pointer was created
git log --oneline -1
# Output: a3f8c1d (HEAD -> feature/user-authentication, main) Initial commit

The Right Way to Create Branches Before You Touch a Single File

Here's the discipline that separates controlled development from chaos: you create the branch before you write any code. Not after. Not halfway through. Before.

I've seen developers write two hours of code on main, then try to retroactively move it to a branch. It works — git stash and git checkout -b can rescue you — but it's a mess you're creating for yourself unnecessarily. The correct reflex is: new task, new branch, then code.

The branch name matters more than most tutorials admit. A branch named 'fix' or 'test2' is a gift to your future self that keeps giving pain. Use a consistent naming convention your whole team agrees on. The most common patterns are feature/short-description, bugfix/issue-number-description, and hotfix/critical-thing. The forward slash creates a visual namespace without any technical special meaning in Git itself — it just groups branches when you list them.

Also: always know which branch you're branching from. Running git checkout -b without checking where you are is how you branch off someone else's half-finished feature branch by accident. I've seen this cause a 45-minute merge headache during a release. Always confirm with git branch or git status first.

# io.thecodeforge — Git Branch Workflow

# STEP 1: Always confirm where you are before creating a branch
# Never skip this — branching from the wrong base is a silent killer
git status
# Output: On branch main — good, we're on the right base

# STEP 2: Pull the latest changes so your branch starts up-to-date
# Branching from a stale main means a painful merge later
git pull origin main

# STEP 3: Create and switch to your feature branch
# Convention: feature/<ticket-number>-<short-description>
# This ties the branch to a ticket in Jira/Linear/GitHub Issues
git checkout -b feature/PAY-421-stripe-webhook-handler
# Output: Switched to a new branch 'feature/PAY-421-stripe-webhook-handler'

# STEP 4: Verify the switch — never assume
git branch
# Output:
#   main
# * feature/PAY-421-stripe-webhook-handler

# STEP 5: Do your work — add files, make commits
# Your changes are now completely isolated from main
touch stripe_webhook_handler.py
git add stripe_webhook_handler.py
git commit -m "PAY-421: scaffold Stripe webhook handler"

# STEP 6: Push the branch to remote so others can see it and CI can run
# -u sets the upstream tracking, so future 'git push' needs no arguments
git push -u origin feature/PAY-421-stripe-webhook-handler
# Output: Branch 'feature/PAY-421-stripe-webhook-handler' set up to track remote branch

checkout -b vs git switch -c: The Command That's Replacing It

Here's something most beginner tutorials skip entirely: git checkout is an overloaded command that does too many unrelated things. It checks out branches, checks out individual files, detaches HEAD, restores file content — it's a Swiss Army knife that's genuinely confusing. Git 2.23 (released 2019) introduced git switch specifically to handle branch operations cleanly, separating concerns properly.

git switch -c feature/my-branch does exactly what git checkout -b does. The -c flag means 'create'. There's also git restore for the file-restoration job that checkout used to do. The Git team is not deprecating checkout, so nothing will break. But if you're learning Git today, you should know that git switch -c is the more intentional choice for branch creation — it can't accidentally clobber your file changes because it doesn't know how.

That said, you'll see git checkout -b in virtually every existing tutorial, script, CI pipeline, and StackOverflow answer for the next decade. You need to know both. Use git switch -c in your own new work. Recognise git checkout -b everywhere else. They're identical in outcome for the branch creation use case — the difference is purely about command clarity and intent.

# io.thecodeforge — Checkout vs Switch

# THE OLD WAY — git checkout -b (still works, still everywhere)
# Creates branch 'feature/order-refund-api' and switches to it
git checkout -b feature/order-refund-api
# Output: Switched to a new branch 'feature/order-refund-api'

# Go back to main to demonstrate the equivalent modern command
git checkout main

# THE NEW WAY — git switch -c (available since Git 2.23)
# Identical outcome, but the command can ONLY deal with branches
# It cannot accidentally restore file content — safer mental model
git switch -c feature/order-refund-api-v2
# Output: Switched to a new branch 'feature/order-refund-api-v2'

# SWITCHING between existing branches — no flag needed
git switch main
# Output: Switched to branch 'main'

# BRANCH FROM A SPECIFIC COMMIT — not from HEAD
# Useful when you need to hotfix an older release tag
# Both commands support this equally
git checkout -b hotfix/v2.4.1-null-pointer-crash v2.4.1
# Creates a new branch starting at the v2.4.1 tag, not current HEAD
# Output: Switched to a new branch 'hotfix/v2.4.1-null-pointer-crash'

# The equivalent with git switch:
git switch -c hotfix/v2.4.1-null-pointer-crash-alt v2.4.1
# Output: Switched to a new branch 'hotfix/v2.4.1-null-pointer-crash-alt'

Recovering From the Branch Mistakes That Actually Happen

You will mess up a branch at some point. Everyone does. The goal is to know the recovery path before panic sets in at 11pm.

The most common disaster is realising you've been committing to main instead of a feature branch. This happens more than people admit — you start coding, get into flow, make three commits, then look up and see you're on main. Don't push. Here's the exact recovery: create a new branch from your current position with git checkout -b feature/the-thing-i-was-building, which captures all your commits. Then reset main back to where it was with git checkout main followed by git reset --hard origin/main. Your commits now live only on the feature branch, and main is clean again.

The second common mess is naming a branch wrong. You can rename your current branch with git branch -m new-name — the -m flag moves/renames it. If you've already pushed the old name to remote, you'll need to push the new name with git push origin -u new-name and delete the old remote branch with git push origin --delete old-name. It's annoying but fully recoverable.

Branching from the wrong base — like branching from someone else's feature branch instead of main — requires a git rebase --onto to replay your commits onto the correct base. That's a topic on its own, but know the symptom: your PR contains commits you didn't write.

# io.thecodeforge — Git Branch Recovery

# SCENARIO: You've made commits directly on main by accident
# DO NOT push — check your log first to confirm the damage
git log --oneline -5
# Output:
# 9c4f2a1 (HEAD -> main) Add Stripe webhook signature validation
# 7b3e1d8 Add Stripe webhook endpoint
# a3f8c1d (origin/main) Initial project scaffold  <-- this is where main should be

# RECOVERY STEP 1: Create a new branch at your current position
# This saves all your accidental main commits
git checkout -b feature/PAY-421-stripe-webhook-handler
# Output: Switched to a new branch 'feature/PAY-421-stripe-webhook-handler'
# Your commits are now safely on the feature branch

# RECOVERY STEP 2: Go back to main
git checkout main

# RECOVERY STEP 3: Reset main to match origin — erases your local commits from main
# --hard means working directory is also reset — your files revert to origin/main state
# This is safe because your commits still exist on the feature branch
git reset --hard origin/main
# Output: HEAD is now at a3f8c1d Initial project scaffold

# Confirm main is clean
git log --oneline -3
# Output: a3f8c1d (HEAD -> main, origin/main) Initial project scaffold

# SEPARATE SCENARIO: Renaming a badly named branch
# You're on the branch you want to rename
git checkout -b fixstuff  # bad name — too vague
git branch -m bugfix/AUTH-88-jwt-expiry-missing  # rename it
# Output: (no output — success is silent in git branch -m)
git branch
# Output:
#   main
# * bugfix/AUTH-88-jwt-expiry-missing

Branching From Tags and Commits: Hotfix Patterns

Not all branches start from HEAD. Production hotfixes often need to branch from a specific release tag — you're patching v2.4.1 while v2.5.0 development continues on main. Both git checkout -b and git switch -c accept a starting point as the final argument.

The syntax: git checkout -b hotfix/name v2.4.1 creates a new branch starting at the commit tagged v2.4.1, not your current HEAD. This is critical for release management — you don't want unreleased feature code from main leaking into your hotfix.

After fixing and merging the hotfix, you need to ensure the fix reaches main too. In GitFlow, this means merging the hotfix branch into both main (for the patched release) and develop (so the fix isn't lost in the next release). In GitHub Flow, the hotfix merges to main and you rely on the next deploy to include it.

# io.thecodeforge — Hotfix Branching from Tags

# SCENARIO: Production is running v2.4.1. A null pointer crash is reported.
# Main has moved on to v2.5.0-rc1 with unreleased features.
# You need to patch v2.4.1 without pulling in v2.5.0 changes.

# Step 1: Verify the tag exists
git tag -l 'v2.4*'
# Output: v2.4.0, v2.4.1

# Step 2: Create a branch starting from the v2.4.1 tag
git checkout -b hotfix/v2.4.2-null-pointer-crash v2.4.1
# Output: Switched to a new branch 'hotfix/v2.4.2-null-pointer-crash'
# Note: you're now on a branch that has ONLY v2.4.1 code.
# No v2.5.0 features are present.

# Step 3: Verify you're at the right commit
git log --oneline -3
# Output shows only commits up to v2.4.1 tag

# Step 4: Fix the bug
echo '// null check added' >> src/main/java/io/thecodeforge/payment/PaymentService.java
git add src/main/java/io/thecodeforge/payment/PaymentService.java
git commit -m "HOTFIX: add null check for PaymentService.processPayment()"

# Step 5: Tag the hotfix release
git tag -a v2.4.2 -m "Hotfix v2.4.2: null pointer crash in PaymentService"

# Step 6: Merge into main (for deployment) and into develop (for future releases)
git checkout main
git merge --no-ff hotfix/v2.4.2-null-pointer-crash

git checkout develop
git merge --no-ff hotfix/v2.4.2-null-pointer-crash

# Step 7: Push everything
git push origin main develop v2.4.2

git push origin --delete hotfix/v2.4.2-null-pointer-crash