Git Stash

Park incomplete changes, switch context without losing work, and know when a second worktree is clearer than a stash.

Context switching is a state-management problem

Choose commit, stash, or worktree

What a stash stores

A stash entry is commit-based repository data representing working-tree and index state relative to a base commit. The friendly stack names—such as stash@{0}—are references used to find those objects. After a normal stash, tracked files are restored toward HEAD so you can switch context.

The base commit matters. Applying the entry later asks Git to place those recorded changes onto a possibly different current tree. The longer histories diverge, the more context and conflict risk grows.

Create a named, reviewed stash

git status --short
git diff
git diff --cached

# Stash tracked staged and unstaged changes with a useful label
git stash push -m "wip: validate checkout address"

# Include untracked files only after inspecting them
git stash push -u -m "wip: checkout form and fixture"

git status --short
git stash list

1. INSPECT
   Classify every path

   Know what is tracked, staged, unstaged, untracked, ignored, generated, or sensitive.

2. NAME
   Record why work paused

   A message such as wip: validate checkout address is searchable and more useful than the default branch summary.

3. VERIFY
   Check both destinations

   Confirm the working tree now has the expected state and the new stash appears at the intended stack position.

4. SWITCH
   Begin the interruption cleanly

   Only change branches after status proves no wanted path was left behind accidentally.

Control stash scope deliberately

# Stash only selected paths
git stash push -m "wip: checkout UI" -- src/checkout/ tests/checkout.test.js

# Keep staged changes in place and stash other tracked edits
git stash push --keep-index -m "wip: unrelated unstaged edits"

# Interactively choose patch hunks
git stash push --patch -m "wip: selected checkout hunks"

Pathspecs and patch mode can isolate coherent work, but partial state requires careful verification. Run all three views—status, plain diff, and cached diff—afterward. --keep-index is useful when staged content is ready for testing or committing while unrelated tracked edits need to move aside.

Inspect before restoring

git stash list
git stash show --stat stash@{0}
git stash show --patch stash@{0}

# Apply without deleting the stash entry
git stash apply stash@{0}

# After verification, delete the exact entry
git stash drop stash@{0}

Always name the exact entry. Stack positions change when entries are added or dropped. Re-run git stash list immediately before using a stash@{n} selector, and prefer the entry’s message and patch over memory.

Resolve stash conflicts without losing the source

Applying a stash can conflict because the current branch changed the same context. Git writes conflict markers and leaves the working tree for resolution. The stash entry remains available when application does not complete cleanly.

git stash apply stash@{0}
git status

# Resolve each file to the intended current result, then:
git add path/to/resolved-file
git diff --cached

# Commit when the recovered unit is coherent:
git commit -m "Resume checkout validation"

# Drop only after proving the recovered commit contains the wanted work:
git stash drop stash@{0}

Recover old work on its original base

When an entry is old and the current branch has diverged, git stash branch can create a new branch at the stash’s original base commit, check it out, and apply the stash there.

git stash list
git stash show --patch stash@{1}
git stash branch recover/checkout-wip stash@{1}

This often reduces conflicts because the recorded changes return to the history they began from. On successful application, Git drops the stash entry, so verify the new branch, status, and diff immediately.

A linked worktree is another active checkout

git worktree lets one repository support multiple working directories. Linked worktrees share the object database and most refs, but each has its own working files, index, and HEAD. A commit created in one worktree is immediately available as an object and branch update to the others.

Create a parallel branch workspace

# From the main repository, create a new branch and linked worktree
git worktree add -b hotfix/checkout ../shop-hotfix main

git worktree list

# Work inside the new directory
cd ../shop-hotfix
git status

# After committing, merging as appropriate, and cleaning the worktree:
cd ../shop
git worktree remove ../shop-hotfix
git worktree list

The example creates hotfix/checkout from main and checks it out in a sibling directory. Choose a path outside the main worktree so build tools and recursive searches do not accidentally treat one checkout as content inside the other.

Manage the full worktree lifecycle

1. 01
   Create from a named base

   Use an explicit starting revision and branch name so the new context is reproducible.

2. 02
   Install and run independently

   Each checkout may need its own generated dependencies, environment setup, development server, and ports.

3. 03
   Commit on the correct branch

   Check git branch --show-current and status inside that worktree before every commit.

4. 04
   Integrate deliberately

   Merge, rebase, or review according to the project workflow; shared objects do not mean branches merge automatically.

5. 05
   Remove only when clean

   Prove wanted work is committed or preserved, remove the linked directory through Git, then delete the branch only if its lifecycle is complete.

If a worktree directory was removed manually or became unavailable, git worktree prune --dry-run previews stale administrative entries and git worktree prune removes eligible records. Preview before cleanup.

Match the tool to the interruption

Guided practice: interrupt and resume safely

Use a disposable repository with two tracked source files and one committed baseline. Create a feature branch and begin an unfinished change.

1. 01
   Build mixed state

   Stage one source edit, leave another unstaged, and create one reviewed untracked fixture.

2. 02
   Create a named stash

   Include the fixture explicitly, then prove the expected clean state and inspect the stored patch.

3. 03
   Make an interruption commit

   Switch branches, create a small unrelated fix, and commit it coherently.

4. 04
   Resume with apply

   Return to the feature branch, apply the exact stash without dropping it, and verify all three original states.

5. 05
   Preserve and clean up

   Commit the recovered feature, prove its contents, then drop only the verified stash entry.

Independent lab: handle a hotfix in parallel

Create a disposable repository with a main branch and an unfinished feature branch. Keep meaningful uncommitted feature work visible in the original directory while completing a simulated hotfix:

1. Record the feature work’s status and both diffs.
2. Create a sibling worktree and new hotfix branch from main.
3. Prove each directory has a different branch, HEAD, index, and working state.
4. Commit and test the hotfix in the linked worktree without altering feature files.
5. Make the hotfix commit visible in the original worktree’s graph.
6. Integrate the hotfix using the course’s current branch policy.
7. Verify the hotfix worktree is clean, remove it through Git, and prove the branch remains available.
8. Resume the untouched feature context and explain why a worktree was clearer than stashing it.

Common context-switching mistakes

Lesson review

You can now pause work without turning the repository into an unexplained pile of state. Named stashes support brief, inspected interruptions; linked worktrees support simultaneous branches with independent checkout state; coherent commits remain the durable record.

• I inspect tracked, staged, unstaged, untracked, and ignored paths before stashing.
• I name and inspect the exact stash entry rather than relying on stack position from memory.
• I use apply before drop when recovery needs verification.
• I understand which repository data worktrees share and which checkout state remains separate.
• I remove worktrees only after clean status and preservation evidence.