Git and GitHub / Intermediate: collaborative change management / Lesson 9

Stash, worktrees, and interrupted work

Choose a temporary save or a separate checkout without treating either as a substitute for durable shared history.

About 5 min readContent reviewed 2026-10-25

On this page

Lesson goals

Explain stash scope, apply, and conflict behavior.
Use separate worktrees with clear ownership and cleanup.

Choose how the interrupted task should live

When an urgent task arrives, first inspect the current branch, staged changes, unstaged edits, and untracked files. A coherent checkpoint commit on a private topic can be clearer than an opaque stash. A stash can temporarily save working state, while a linked worktree gives another checkout without disturbing the first. These choices have different visibility and recovery properties. None automatically publishes work or replaces backups. Decide whether the task needs a named history, a short local pause, or simultaneous checkouts, and preserve valuable content before changing context.

Save exactly the intended local state

Ordinary stash behavior focuses on tracked modifications and index state; untracked files require an explicit option, and ignored files have another broader option. Avoid sweeping private or large generated files into a stash without understanding the scope. A message makes later identification easier but does not make the stash a permanent archive. The example uses --include-untracked in a temporary lab with a modified tracked file and one scratch file. Inspect the saved entry before switching tasks. The stash list is repository-local knowledge and is not automatically transferred to collaborators with normal branch sharing.

bash Inspect a temporary local stash

git stash push --include-untracked -m "lab notebook interruption"
git stash list
git stash show --stat stash@{0}

Requires synthetic modifications in the isolated lab. The list includes the supplied message and a generated description. The working state is saved according to the chosen scope; exact stat output depends on the files. No stash is created in the workspace project.

Apply first when retaining a recovery point matters

stash apply attempts to restore a saved state without deleting the stash entry. stash pop combines application with dropping the entry on success; when conflicts occur, the entry is ordinarily retained. Restoring index state requires the documented --index behavior and can fail when the current state differs. Applying a stash to a changed base can create conflicts, so inspect status and resolve deliberately. Do not repeatedly apply the same entry to a partially applied tree. Verify restored content before removing the saved entry, and use a durable commit for work that should outlive a short interruption.

Use a second checkout with shared repository history

A linked worktree has its own working files, index, and HEAD while sharing much of the repository’s object and reference storage. It is not an independent clone or an isolation boundary for every repository-level setting. Git normally prevents checking the same branch out in multiple worktrees to avoid conflicting updates. The example creates a new temporary topic at main in a separate path inside the lab’s parent directory. Existing changes remain in the original checkout. Build outputs, ports, and local services still need their own isolation if both checkouts are used for tests.

bash Add a second checkout only inside the temporary lab

git worktree add -b lab/urgent ../urgent-checkout main
git worktree list --porcelain
git -C ../urgent-checkout branch --show-current

The parent directory and urgent-checkout path must belong to the disposable lab. The last command prints lab/urgent. Use a separately managed temporary parent during validation; never assume an arbitrary ../ path is safe in a real project.

Clean up through repository-aware operations

Inspect linked worktrees before removal and preserve uncommitted work. Use supported worktree removal and pruning workflows rather than deleting directories blindly and leaving stale metadata. Stash entries likewise need deliberate review before dropping. A temporary save is easy to forget, so record why it exists and return to it promptly. For longer-running tasks, prefer a named branch with understandable commits and the project’s normal backup or sharing policy. Keep lab cleanup confined to the allocated temporary parent, and verify that no real repository, global configuration, remote, or credential store was changed.

Common errors and fixes

An untracked scratch file is not in the stash

Why it happens: The chosen stash scope omitted untracked files.
How to fix it: Inspect remaining files and choose an explicit suitable save.
Prevent it next time: Review tracked, untracked, and ignored state before stashing.

Applying the stash creates conflicts

Why it happens: The current base differs from the saved context.
How to fix it: Inspect the operation and resolve or preserve state before retrying.
Prevent it next time: Apply once and verify before dropping the entry.

Two checkouts contend for one branch

Why it happens: Worktree ownership was treated like independent clones.
How to fix it: Use distinct topic branches under the supported worktree model.
Prevent it next time: Inspect worktree list before adding or removing checkouts.

Check your understanding

1. You need to inspect an urgent fix while preserving a complex dirty checkout. Which option avoids changing its files?

Show worked solution

A separate temporary worktree on a distinct branch can provide another checkout while the original stays intact. Keep repository-level shared state and test-resource isolation in mind. It does not automatically back up the original edits.

2. stash apply succeeds. Is the entry gone?