Git Stash: Untracked Files Follow Branches – CI Failures

git stash shelves uncommitted working directory and index changes into a stack. It is the standard tool for context switching — you stash your current work, switch to a hotfix branch, then unstash when you return. The core failure mode: stash pop deletes the stash even on merge conflicts, leaving you with no backup. Use apply + manual drop when conflicts are possible.

The second failure mode: stash does not include untracked files by default. New files you have not git add'd remain in the working directory when you switch branches. They get committed to the wrong branch. Use stash -u to include them.

Stashes are global to the repository, not scoped to a branch. You can pop a stash made on feature/x onto main. This is sometimes intentional and sometimes a very bad day. Always use stash push -m 'description' to label your stashes — unnamed stashes become mystery boxes within 24 hours.

Git Stash: The Hidden Trap of Untracked Files

Git stash temporarily shelves changes in your working directory, letting you switch branches without committing half-finished work. The core mechanic: git stash records tracked file modifications and staged changes, then reverts your working tree to match HEAD. But by default, it ignores untracked and ignored files — a detail that routinely causes CI failures.

When you stash, Git creates a stash entry as a special commit-like object reachable via stash@{0}. Crucially, the stash is not branch-specific; it lives on the refs/stash reflog. Applying a stash merges its changes into the current working tree, which can produce conflicts if the branch has diverged. Untracked files remain untouched unless you explicitly use git stash -u or git stash --include-untracked.

The practical danger: a developer stashes changes, switches to a feature branch, builds, and commits — but untracked files (like generated configs or IDE artifacts) from the original branch remain in the working directory. Those files get committed, polluting the branch and breaking CI builds that expect a clean environment. Use git stash -u when you need a truly clean slate, or git stash --all to also clear ignored files.

Basic Stash: Save and Restore Work

The core workflow is three commands. git stash shelves everything in your working directory and index that differs from HEAD. git stash pop restores the most recent stash and removes it from the stack. git stash apply restores without removing — useful when you want to apply the same stash to multiple branches.

One thing that surprises developers coming from other VCS systems: git stash by default only stashes tracked files. If you created a new file that hasn't been git add-ed yet, it won't be stashed. It'll sit there in your working directory when you switch branches, which can lead to unintended commits on the wrong branch. Use git stash -u (or --include-untracked) to include new files.

The stash is a stack — each git stash pushes a new entry. git stash pop pops the top (most recent). This is correct behaviour for the common case but becomes confusion when you stash, do some more work, stash again, and then try to figure out which stash has what.

# io.thecodeforge — Git Stash Basics

# ─────────────────────────────────────────────────────────────
# Save current work to stash (tracked files only)
# ─────────────────────────────────────────────────────────────
git stash

# Save with a descriptive message — always do this
git stash push -m "WIP: payment retry exponential backoff"

# Include untracked files (new files not yet git add'd)
git stash push -u -m "WIP: new PaymentRetryService class"

# ─────────────────────────────────────────────────────────────
# Restore most recent stash AND remove it from the stack
# ─────────────────────────────────────────────────────────────
git stash pop

# Restore most recent stash but KEEP it in the stack
git stash apply

# ─────────────────────────────────────────────────────────────
# List all stashes
# ─────────────────────────────────────────────────────────────
git stash list
# Output:
# stash@{0}: On feature/payment-retry: WIP: payment retry exponential backoff
# stash@{1}: On main: WIP: hotfix debug logging

# ─────────────────────────────────────────────────────────────
# Restore a specific stash by index
# ─────────────────────────────────────────────────────────────
git stash pop stash@{1}
git stash apply stash@{1}

# ─────────────────────────────────────────────────────────────
# See what's in a stash before applying
# ─────────────────────────────────────────────────────────────
git stash show stash@{0}
git stash show -p stash@{0}   # Full diff

Stash Pop vs Apply: When to Use Each

The difference matters more than most tutorials let on.

git stash pop = apply + delete from stack. Use this 95% of the time. The moment you successfully restore your work, the stash entry is gone. Clean, no accumulation.

git stash apply = apply but leave in stack. Use this when: you want to apply the same changes to multiple branches (e.g. a config change you need on both a feature branch and a hotfix branch), or when you're not 100% sure the stash applies cleanly and you want to keep it as a backup while you verify.

There's one critical behaviour difference: if git stash pop encounters a conflict, it still removes the stash from the stack before throwing the conflict. You're now in a conflicted state with the stash gone. This is a Git footgun — you want git stash apply when there's any chance of conflicts, so the stash survives even if the apply fails.

# io.thecodeforge — Stash Pop vs Apply

# ─────────────────────────────────────────────────────────────
# Scenario: you might have conflicts — use apply, not pop
# ─────────────────────────────────────────────────────────────
git stash apply stash@{0}

# If it applied cleanly with no conflicts, manually drop the stash
git stash drop stash@{0}

# If there ARE conflicts, resolve them, then drop manually
# The stash is still in the stack — you haven't lost anything
git status                # Shows conflicted files
# ... resolve conflicts ...
git add .
git stash drop stash@{0}  # Now safe to remove

# ─────────────────────────────────────────────────────────────
# Apply same stash to two branches
# ─────────────────────────────────────────────────────────────
git checkout feature/branch-a
git stash apply stash@{0}    # Applied to branch A — stash still exists
git checkout feature/branch-b
git stash apply stash@{0}    # Applied to branch B too
git stash drop stash@{0}     # Now clean up

# ─────────────────────────────────────────────────────────────
# Clear ALL stashes (nuclear — use with care)
# ─────────────────────────────────────────────────────────────
git stash clear

Stashing Partial Changes and Specific Files

Sometimes you only want to stash part of your changes — for example, you've been working on two unrelated things in the same branch (happens to everyone, don't judge) and you want to commit one thing cleanly before stashing the other.

git stash push -- <path> stashes only the specified files. Everything else stays in your working directory.

git stash push -p (patch mode) drops you into an interactive hunk-by-hunk selection — exactly like git add -p. You choose yes/no for each chunk. This is powerful but slow for large changesets.

# io.thecodeforge — Stashing Partial Changes and Specific Files

# ─────────────────────────────────────────────────────────────
# Stash only specific files
# ─────────────────────────────────────────────────────────────
git stash push -m "WIP: retry config" -- src/main/java/io/thecodeforge/payment/RetryConfig.java

# Stash multiple specific files
git stash push -m "WIP: two related files" \
  -- src/main/java/io/thecodeforge/payment/RetryConfig.java \
  -- src/main/java/io/thecodeforge/payment/RetryPolicy.java

# ─────────────────────────────────────────────────────────────
# Interactive patch mode — choose which hunks to stash
# ─────────────────────────────────────────────────────────────
git stash push -p -m "WIP: partial changes"
# Git shows each change hunk and asks: stash this hunk? [y/n/q/a/d/?]

# ─────────────────────────────────────────────────────────────
# Create a branch from a stash (useful for long-lived stashes)
# ─────────────────────────────────────────────────────────────
git stash branch feature/retry-config stash@{0}
# Creates new branch at the commit where you stashed, applies the stash, drops it

Git Stash vs Git Reset: The Nuclear Option vs The Snooze Button

Junior devs treat git stash like a magical undo button. It's not. Let's kill this confusion right now.

Git reset --hard throws away your working directory changes permanently. That's the nuclear option. Git stash temporarily shelves changes so you can pick them up later. That's the snooze button.

When you're mid-refactor and a critical production bug drops in your lap, you stash your messy working tree, fix the bug, then pop the stash. If you had used reset, those refactored files are gone. Forever.

Here's the real-world distinction: reset moves the HEAD pointer and optionally overwrites the index and working tree. Stash is a stack of compressed delta objects stored in .git/refs/stash. Reset is destructive by design. Stash is a save-state for your incomplete work.

If you're using git stash as a habit because you're scared of commits, you're doing it wrong. Commit early, commit often. Only stash when you cannot commit — dirty debug code, half-failed experiments, or when you absolutely must switch branches without a second commit.

// io.thecodeforge — devops tutorial

// Scenario: You're refactoring payment-api and need to fix P1 bug

# Wrong way — permanent loss
git reset --hard
# All refactoring work gone, customer data models deleted

# Right way — safe shelving
git stash push -m "payment-api refactor WIP"
# Saved as stash@{0}: On payment-api-wip: payment-api refactor WIP

git checkout main
git pull origin main
# Fix the emergency bug, commit, push

git checkout payment-api-wip
git stash pop
# Back to work, zero lost changes

Where Does Git Stash Actually Live? (.git/refs/stash Exposed)

Every stash is a commit object. Not a temp file. Not a config entry. A real, bonafide Git commit with a parent tree.

Look inside .git/refs/stash and you'll find nothing but a SHA. Run 'git log --oneline stash@{0}' and you'll see a commit history of your stashes. That's because stash creates a merge commit with three parents: the original HEAD, the index state, and the working tree state. This is why you can branch off a stash, diff it, or even merge it.

Multiple stashes stack on .git/refs/stash as a reflog. 'git stash list' shows you the stack. 'git stash drop' removes the top commit from that reflog. 'git stash clear' nukes the entire reflog.

There's no magic repository in the sky. It's all refs and commits in your local .git directory. That also means stashing is purely local — no remote, no backup, no safety net. If your laptop catches fire, so do all your stashes.

Knowing this changes how you use stash. You can cherry-pick from a stash. You can merge stash changes. You can even push a branch from a stash when you realize it's a feature, not a quick fix.

// io.thecodeforge — devops tutorial

// Visualize stash as real commits

# See stash commits with full history
git log --oneline --graph stash@{0}

# Output:
# *   3a4b5c6 WIP on payment-api-wip
# |\  
# | * 2b3c4d5 index on payment-api-wip: checkpoint
# |/  
# * 1a2b3c4 checkpoint before refactoring

# Diff a specific file from stash
git diff stash@{0} -- src/payment/api/validators.go

# Create a branch from a stash (saves it permanently)
git stash branch production-hotfix/payment-fix stash@{2}

Git Stash Best Practices

Stashing is a safety net, not a workflow crutch. The primary reason to stash is to temporarily set aside uncommitted changes when you need to switch branches, pull updates, or fix an urgent bug. Never stash as a substitute for meaningful commits. Before stashing, commit your work if it's logically complete—stashes are ephemeral and easy to lose. Use descriptive stash messages: git stash push -m "WIP: refactor auth module" saves hours of confusion later. Avoid piling up multiple stashes; each stash is a hidden breadcrumb that accumulates technical debt. Instead, pop and integrate each stash immediately after the interruption passes. Untracked files are not stashed by default unless you add -u or --include-untracked. This hidden trap causes accidental data loss when switching branches expecting all changes to travel with you. Finally, never keep a stash older than a few days—it signals that either the work should have been committed or it's dead code waiting to bite.

// io.thecodeforge — devops tutorial

stash_rules:
  messages: required
  max_age_hours: 48
  pop_before_new_work: true
  untracked_flag: -u

commands:
  save_work:
    cmd: git stash push -m "refactor: extract billing service"
  restore:
    cmd: git stash pop
  check_stash_list:
    cmd: git stash list

Git Fundamentals

Git's core architecture is a directed acyclic graph of snapshots, not diffs. Every commit is a full snapshot of your tracked files at that moment—this is why operations like checkout and reset are fast. The three main areas working directory, staging index, and commit history define your workflow. Changes move from working tree to staging with git add, then to a commit with git commit. Git stash is a fourth temporary area: it saves the dirty state of your working directory and index as two separate commits stored under .git/refs/stash. Understanding this triad prevents confusion: git reset --soft only moves HEAD, --mixed resets the index, and --hard wipes working directory changes. Branches are lightweight pointers to commits; merging creates a new commit with two parents, rebasing rewrites history by replaying commits. Git's distributed nature means every clone has the full history. This makes local operations instant but adds complexity with remotes. Use git fetch before merging to inspect upstream changes without danger. The golden rule: never rewrite public history with rebase or reset --hard.

// io.thecodeforge — devops tutorial

areas:
  working_directory:
    state: dirty or clean
  staging_index:
    command: git add
  commit_history:
    command: git commit

stash_structure:
  path: .git/refs/stash
  type: two parent commits

key_rules:
  fetch_before_merge: true
  no_rewrite_public: true