Git Stash and Cherry-Pick Explained — Real-World Patterns and Pitfalls

# ─── SCENARIO ──────────────────────────────────────────────────────────────
# You're halfway through refactoring the payment module when your lead
# asks you to jump on branch 'hotfix/order-total-rounding' immediately.
# ───────────────────────────────────────────────────────────────────────────

# Check what you currently have in progress
git status
# Output shows: modified payment_gateway.rb, new file: stripe_adapter.rb

# Stash EVERYTHING — tracked modifications AND untracked new files
# -u flag = --include-untracked (critical — stripe_adapter.rb is new)
# -m flag = a human-readable label so you can find this stash later
git stash push -u -m "wip: payment gateway refactor — stripe adapter half done"

# Confirm the working tree is now clean
git status
# Output: nothing to commit, working tree clean

# Switch to the hotfix branch safely
git checkout hotfix/order-total-rounding

# ... do your hotfix work, commit it, done ...

# Come back to your feature branch
git checkout feature/payment-gateway

# List all stashes to find the right one (you might have multiple)
git stash list
# stash@{0}: On feature/payment-gateway: wip: payment gateway refactor — stripe adapter half done

# Pop the stash — restores files AND removes the stash entry from the stack
# Use 'apply' instead of 'pop' if you want to keep the stash as a safety copy
git stash pop

# Verify your files are back exactly where you left them
git status
# Output: modified: payment_gateway.rb, new file: stripe_adapter.rb

# ─── SCENARIO ──────────────────────────────────────────────────────────────
# You have two separate in-progress tracks stashed. You need to
# inspect, apply the right one, and clean up the other.
# ───────────────────────────────────────────────────────────────────────────

# See all stashes with their index positions
git stash list
# stash@{0}: On feature/user-auth: wip: JWT refresh token logic
# stash@{1}: On feature/user-auth: wip: email validation spike

# Preview what's inside stash@{1} before applying it
# -p flag shows the actual diff (patch format)
git stash show -p stash@{1}

# Apply ONLY the email validation spike (stash@{1}) without removing it yet
git stash apply stash@{1}

# After confirming the apply looks good, remove it from the stack explicitly
git stash drop stash@{1}

# List again — note that indexes shift after a drop
git stash list
# stash@{0}: On feature/user-auth: wip: JWT refresh token logic

# ─── POWER MOVE ────────────────────────────────────────────────────────────
# The JWT stash has grown into a real feature — give it its own branch
# This creates 'feature/jwt-refresh' from the original stash point
# and pops stash@{0} onto it automatically
git stash branch feature/jwt-refresh stash@{0}

# Confirm the new branch has the stashed changes applied and stash is gone
git status
git stash list  # Empty — stash was consumed by branch creation

# ─── SCENARIO ──────────────────────────────────────────────────────────────
# A critical SQL injection fix was committed to 'main' as commit abc1234.
# The 'release/3.1' branch is already cut and needs this fix NOW,
# but the 2 commits after abc1234 on main are incomplete features
# that must NOT go into the release.
# ───────────────────────────────────────────────────────────────────────────

# First, find the exact SHA of the fix commit on main
git log main --oneline
# abc1234 fix: sanitize user input in search query builder
# def5678 wip: new dashboard widget (incomplete)
# ghi9012 wip: migrate analytics to ClickHouse (incomplete)

# Switch to the release branch
git checkout release/3.1

# Cherry-pick ONLY the security fix commit by its SHA
# Git will replay that commit's diff onto the current branch
git cherry-pick abc1234

# Verify the fix landed — note the NEW SHA (different from abc1234)
git log --oneline -3
# xyz9999 fix: sanitize user input in search query builder  <-- new SHA!
# aaa1111 chore: bump version to 3.1.0
# bbb2222 feat: order confirmation email template

# ─── CHERRY-PICKING A RANGE ────────────────────────────────────────────────
# If you need commits abc1234 AND def5678 (but NOT ghi9012), use dot-dot notation.
# The range abc1234..def5678 means: commits AFTER abc1234 up to AND including def5678.
# To INCLUDE abc1234 itself, use the caret on the start: abc1234^..def5678
git cherry-pick abc1234^..def5678

# ─── CHERRY-PICK WITH EDIT ─────────────────────────────────────────────────
# --edit (-e) opens the commit message editor before finalising
# Useful when you want to note it was cherry-picked from main
git cherry-pick --edit abc1234
# Opens editor — you can append: "(cherry picked from commit abc1234 on main)"

# ─── SCENARIO ──────────────────────────────────────────────────────────────
# Cherry-picking commit abc1234 hits a conflict in search_query_builder.rb
# because the release branch edited that same function independently.
# ───────────────────────────────────────────────────────────────────────────

git cherry-pick abc1234
# Git stops and reports a conflict:
# error: could not apply abc1234... fix: sanitize user input in search query builder
# hint: After resolving the conflicts, mark them with
# hint: git add <pathspec>, then run git cherry-pick --continue

# See exactly which files have conflicts
git status
# both modified: app/queries/search_query_builder.rb

# Open the file and resolve the conflict markers manually
# <<<<<<< HEAD         = your current release/3.1 version
# =======              = separator
# >>>>>>> abc1234...   = the incoming cherry-picked version

# After editing the file to the correct merged state:
git add app/queries/search_query_builder.rb

# Continue the cherry-pick — Git will create the commit
git cherry-pick --continue
# Editor opens for commit message — save and close to finalise

# ─── ALTERNATIVE: BAIL OUT CLEANLY ─────────────────────────────────────────
# If the conflict is too complex and you want to reconsider your approach:
git cherry-pick --abort
# Restores the branch exactly as it was before you started — no residue

# ─── NO-COMMIT MODE: COMBINE MULTIPLE CHERRY-PICKS INTO ONE COMMIT ─────────
# Apply changes from two commits without committing either one yet
git cherry-pick --no-commit abc1234
git cherry-pick --no-commit def5678

# Now both sets of changes sit in the staging area
git status
# Changes to be committed: modified: search_query_builder.rb, modified: query_sanitizer.rb

# Create one clean, well-described commit from both changes combined
git commit -m "fix: apply comprehensive input sanitization across query layer (backport from main)"