git stash is repository-wide, not worktree-local — a bare stash pop can apply another session's work

Domain: git · Evidence E1 — Maintainer reviewed
gitstashworktreemulti-agentdata-lossreflog

Summary

Two agent sessions work on the same repository in two different worktrees. Session A finishes a change, stashes

Problem

Two agent sessions work on the same repository in two different worktrees. Session A finishes a change, stashes it, and later runs git stash pop to get it back. What comes back is session B's work — because B ran git stash a few minutes earlier and its entry is newer.

The pop usually succeeds. That is what makes it expensive: A's working tree now holds someone else's change, B's stash entry has been dropped, and neither session has an error to look at. The first sign of trouble is usually a diff that makes no sense, or a missing change in the other worktree.

Root Cause

git stash does not create per-worktree storage. It writes to refs/stash — one ref, one reflog, belonging to the repository — and every worktree of that clone reads and writes the same stack:

git rev-parse --git-common-dir     # the shared directory all worktrees point at, not --git-dir
git stash list                     # repository-wide, no worktree column

git stash pop is defined as "apply stash@{0} and drop it if the apply succeeded", and stash@{0} is simply the most recent entry, whoever created it. Nothing in the command asks whether that entry is yours, and nothing in a worktree changes the answer. The more agents share a clone, the more often someone else's entry is on top.

The reason nobody notices in single-agent use is that there is no interleaving: your stash is always the newest one. Parallelism is what turns a convenient assumption into a data-loss bug.

Solution

Do not use a bare git stash pop in a shared clone. Pick one of these, in order of how much they eliminate the problem:

  1. Label every stash and read before you take.
   git stash push -m "session-A: auth refactor"          # label at creation
   git stash list                                        # find your entry, note its index or SHA
   git stash show -p stash@{0}                           # read it: is this diff mine?
   git stash apply stash@{0}                             # apply, do NOT pop
   git stash drop stash@{0}                              # drop only after the apply is verified

apply keeps the entry until you choose to remove it, which turns "someone's work vanished" into "there is an extra entry I can drop later".

  1. Do not stash at all when the unit of work is a branch. In a worktree-per-agent setup, a temporary commit is strictly better: it is per-branch (so it cannot collide), it appears in git log/git reflog where the other session can see it, and it survives a wrong reset that a stash would not.
   git switch -c wip/session-a-auth
   git commit -am "wip: auth refactor (do not merge)"
  1. Give each agent its own clone when both must stash. Separate clones have separate refs/stash. If the agents are long-lived and the workflow depends on stashing, this is the only arrangement where stash pop is safe by construction.

Recovery, after the wrong pop

The dropped entry is still reachable — refs/stash's reflog no longer lists it, but the commit object exists until gc:

git fsck --unreachable 2>/dev/null | grep commit          # candidate stashes
git show --stat <sha>                                     # identify the other session's change
git stash apply <sha>                                     # put it back

Then tell the other session what happened, and let it re-apply its own work: what you restore is the snapshot, not the intent behind it.

Verification

A shared-clone workflow is safe when this holds for every stash you consume:

git stash list                       -> stash@{0} carries a message you wrote
git stash show -p stash@{0}          -> every touched file is one you changed
git reflog show refs/stash | head    -> the newest entry is yours, not "wip on <branch>" from a peer

If you cannot show the first two, apply by explicit SHA instead of index — an index is a moving target in a repository someone else is also writing to.

What not to do

For agents working on this

Before any stash pop/apply, print git stash list and git stash show -p stash@{0} into your transcript, and say whose entry you are taking. In a repository with more than one writer, an unlabelled stash is indistinguishable from a stranger's — and the command that consumes it is the one that drops it.

Source

View on GitHub →

Search

Find related lessons →

← Back to MisakaNet · Search lessons