Subject: [RFC] stash: let the stash stack live in a configurable ref

Subject: [RFC] stash: let the stash stack live in a configurable ref

[Vladimir Sitnikov]

Hi,

refs/stash is shared by the main checkout and every linked worktree, so
two worktrees push onto and pop from the same stack.  With git 2.52.0:

    git init wt-a && cd wt-a
    git commit --allow-empty -m base
    git worktree add ../wt-b -b b

    echo A >file-a && git add file-a
    git stash push -m "worktree A: half-finished refactor"

    cd ../wt-b
    echo B >file-b && git add file-b
    git stash push -m "worktree B: unrelated fix"
    git stash pop      # worktree B's own entry, as expected
    git stash pop      # worktree A's entry, applied here

After the second pop, wt-b holds both file-a and file-b, and wt-a has an
empty stash and a clean tree.  Nothing warned about it, and the entry is
gone from the stack, so wt-a has no way to find out where its changes
went.

This is documented behavior: git-worktree(1) lists refs/bisect,
refs/worktree and refs/rewritten as the per-worktree exceptions, and
refs/stash is not among them.  For a human who drives one worktree at a
time it is mostly harmless, and sharing is occasionally useful - stash
in one worktree, apply in another, as a way to move work across
checkouts.

What changed is who runs these commands.  Running one coding agent per
worktree, against one repository, has become a common setup, and the
agents stash and pop on their own schedule.  The failure above then
turns into silent data movement between unrelated sessions.  The same
report has already been filed against at least two such tools:

    https://github.com/github/copilot-cli/issues/1725
    https://github.com/stablyai/orca/issues/13695

I would like to propose a configuration knob rather than a new concept,
because most of the machinery is already in the tree:

  - refs/worktree/* is per-worktree, so a private stack has somewhere
    to live;
  - `git stash export --to-ref` and `git stash import` already read and
    write a stash stack under an arbitrary ref;
  - extensions.worktreeConfig and `git config --worktree` already give
    a worktree its own configuration.

The missing piece is telling stash itself which ref to use.  Say
stash.ref, defaulting to refs/stash, honored by push, save, list,
show, pop, apply, drop, branch and clear.  A worktree that wants
isolation then asks for it once:

    git config extensions.worktreeConfig true
    git config --worktree stash.ref refs/worktree/stash

Nothing changes for anyone who does not set it, and the tools that
manage worktrees for agents can set it when they create a worktree.

Alternatives I considered and rejected:

  - Making the stash per-worktree unconditionally.  It breaks the
    stash-here-apply-there workflow, and it moves existing entries out
    from under scripts.  If that is the destination, it belongs in
    Documentation/BreakingChanges.adoc for Git 3.0, with a warning
    released first - but it does not have to block a knob today.

  - Named stashes.  A name that survives a push by another process is
    what a ref already is, so this would grow a second naming scheme
    over the one branches and tags already use, plus commands to list
    and delete those names.

  - Leaving it to tooling.  It works - `git stash create` writes a
    stash commit without touching any ref, so a wrapper can store it
    under refs/worktree/<name> and apply it later - but every tool
    reimplements it, and the failure mode for anyone who does not is
    silent.

Points I am not sure about, and where I would like guidance before
writing a patch:

  - Whether stash.ref is the right name, and whether it should be
    restricted to refs/ (rejecting a value that is not a ref name).

  - Whether `git stash list` should be able to show the other stacks -
    a worktree's entries becoming invisible to the main checkout is the
    cost of the knob, and `git stash list --all` over
    worktrees/*/refs/worktree/stash might be a reasonable answer.

  - Reachability.  fsck and reflog expiry learned to iterate
    per-worktree refs, and I would like a second opinion on whether
    stash entries under refs/worktree/* are safe from gc in the same
    way refs/stash entries are.

If the direction sounds reasonable, I am happy to write the patch.

Thanks,
Vladimir Sitnikov

Re: Subject: [RFC] stash: let the stash stack live in a configurable ref

[Kristoffer Haugsbakk]

On Sun, Aug 23, 2026, at 16:19, Vladimir Sitnikov wrote:
> refs/stash is shared by the main checkout and every linked worktree, so
> two worktrees push onto and pop from the same stack.  With git 2.52.0:
>
>     git init wt-a && cd wt-a
>     git commit --allow-empty -m base
>     git worktree add ../wt-b -b b
>
>     echo A >file-a && git add file-a
>     git stash push -m "worktree A: half-finished refactor"
>
>     cd ../wt-b
>     echo B >file-b && git add file-b
>     git stash push -m "worktree B: unrelated fix"
>     git stash pop      # worktree B's own entry, as expected
>     git stash pop      # worktree A's entry, applied here
>
> After the second pop, wt-b holds both file-a and file-b, and wt-a has an
> empty stash and a clean tree.  Nothing warned about it, and the entry is
> gone from the stack, so wt-a has no way to find out where its changes
> went.
>
> This is documented behavior: git-worktree(1) lists refs/bisect,
> refs/worktree and refs/rewritten as the per-worktree exceptions, and
> refs/stash is not among them.

Yes. Both the existing behavior and per-worktree stashes are useful in
the abstract:

• I sometimes make changes in the wrong worktree and then just push
  there and pop in the correct one. So it has practical uses. But it
  doesn’t feel like it jives with modern Git (Git 2015, when worktrees
  came). It does not feel elegant.
• Pushing and popping in isolation also makes sense and surely has just
  as many practical uses for people who both use worktrees and the stash
  compared to someone who only uses the stash.

If not for hysterical raisins, I think per-worktree would make sense as
the default. But with history in mind a configuration option makes the
most sense.

> For a human who drives one worktree at a
> time it is mostly harmless, and sharing is occasionally useful - stash
> in one worktree, apply in another, as a way to move work across
> checkouts.

I see the narrative crescendo in the first clause.

I don’t see how it is mostly harmless. Yes, it is useful, but it could
also be confusing because it IMO isn’t consistent with (again IMO)
modern Git with worktrees. So people might only get confused while using
Git all manually, stalling the current session and sending them to ask
SO/LLM; there is no massively parallel cluster of Git sessions going off
the rails as one automated entity creates a merge conflict that somehow
cascades and wastes many dollars.

But the bar for introducing configuration options for porcelain commands
for can’t-break-default has always been, my my knowledge, those lone
manual sessions that merely get stalled and leads to confusion in the
person operator. So this could be worth implementing just based on
that. (And it benefiting other cases is also great.)

>
> What changed is who runs these commands.

The reveal.

> Running one coding agent per
> worktree, against one repository, has become a common setup, and the
> agents stash and pop on their own schedule.  The failure above then
> turns into silent data movement between unrelated sessions.  The same
> report has already been filed against at least two such tools:
>
>     https://github.com/github/copilot-cli/issues/1725
>     https://github.com/stablyai/orca/issues/13695

To my uninformed, not-using-agents mind, what agents do with the tool
seems like the least concerning thing. They can be non-deterministically
instructed to not use the stash.

The stash has already been optional, something that you can achieve with
the other porcelain commands. So any code-changing entity can adapt to
not being allowed to use the stash.

And for determinism you can give them a git(1) wrapper that bans
git-stash(1).

>
> I would like to propose a configuration knob rather than a new concept,
> because most of the machinery is already in the tree:
>
>   - refs/worktree/* is per-worktree, so a private stack has somewhere
>     to live;
>   - `git stash export --to-ref` and `git stash import` already read and
>     write a stash stack under an arbitrary ref;
>   - extensions.worktreeConfig and `git config --worktree` already give
>     a worktree its own configuration.
>
> The missing piece is telling stash itself which ref to use.  Say
> stash.ref, defaulting to refs/stash, honored by push, save, list,
> show, pop, apply, drop, branch and clear.  A worktree that wants
> isolation then asks for it once:
>
>     git config extensions.worktreeConfig true
>     git config --worktree stash.ref refs/worktree/stash

Opting in to `refs/worktree/stash` makes sense.

>[snip]
>   - Reachability.  fsck and reflog expiry learned to iterate
>     per-worktree refs, and I would like a second opinion on whether
>     stash entries under refs/worktree/* are safe from gc in the same
>     way refs/stash entries are.

See gitdatamodel(7).

    Git may delete objects that aren’t "reachable" from any reference or
    reflog.

Any particular ref namespace is not special with regards to
reachability and GC.

>[snip]

Re: Subject: [RFC] stash: let the stash stack live in a configurable ref

[Phillip Wood]

Hi Vladimir

On 23/08/2026 15:19, Vladimir Sitnikov wrote:
> Hi,
> 
> refs/stash is shared by the main checkout and every linked worktree, so
> two worktrees push onto and pop from the same stack.  With git 2.52.0:
> 
>      git init wt-a && cd wt-a
>      git commit --allow-empty -m base
>      git worktree add ../wt-b -b b
> 
>      echo A >file-a && git add file-a
>      git stash push -m "worktree A: half-finished refactor"
> 
>      cd ../wt-b
>      echo B >file-b && git add file-b
>      git stash push -m "worktree B: unrelated fix"
>      git stash pop      # worktree B's own entry, as expected
>      git stash pop      # worktree A's entry, applied here

When I'm not trying to move changes between branches I associate a stash 
with the branch that's checked out when it is created, not the worktree 
where that the branch happens to be checked out. We already record the 
branch name when creating the stash so perhaps we should add an option 
to pop the last stash that was created on the current branch. Assuming 
agents are working on a branch rather than a detached HEAD that would 
stop them from treading on each others toes and it would mean it is 
still easy to move stashed changes between branches/worktrees when 
needed. It also makes it easy to retrieve a stash for the current branch 
that was created when the branch was checked out in a different 
worktree. If an agent really needs a private stash it can use "git stash 
create" and record the oid of the stash under "refs/worktree/".

On a related note I've been meaning to add an option to specify an 
alternative branch name when creating a stash, so that "git checkout -m" 
and "git rebase --autostash <upstream> <branch>" can record the branch 
that we're switching to, rather than the one that's currently checked 
out when creating stashes.

Thanks

Phillip

> After the second pop, wt-b holds both file-a and file-b, and wt-a has an
> empty stash and a clean tree.  Nothing warned about it, and the entry is
> gone from the stack, so wt-a has no way to find out where its changes
> went.
> 
> This is documented behavior: git-worktree(1) lists refs/bisect,
> refs/worktree and refs/rewritten as the per-worktree exceptions, and
> refs/stash is not among them.  For a human who drives one worktree at a
> time it is mostly harmless, and sharing is occasionally useful - stash
> in one worktree, apply in another, as a way to move work across
> checkouts.
> 
> What changed is who runs these commands.  Running one coding agent per
> worktree, against one repository, has become a common setup, and the
> agents stash and pop on their own schedule.  The failure above then
> turns into silent data movement between unrelated sessions.  The same
> report has already been filed against at least two such tools:
> 
>      https://github.com/github/copilot-cli/issues/1725
>      https://github.com/stablyai/orca/issues/13695
> 
> I would like to propose a configuration knob rather than a new concept,
> because most of the machinery is already in the tree:
> 
>    - refs/worktree/* is per-worktree, so a private stack has somewhere
>      to live;
>    - `git stash export --to-ref` and `git stash import` already read and
>      write a stash stack under an arbitrary ref;
>    - extensions.worktreeConfig and `git config --worktree` already give
>      a worktree its own configuration.
> 
> The missing piece is telling stash itself which ref to use.  Say
> stash.ref, defaulting to refs/stash, honored by push, save, list,
> show, pop, apply, drop, branch and clear.  A worktree that wants
> isolation then asks for it once:
> 
>      git config extensions.worktreeConfig true
>      git config --worktree stash.ref refs/worktree/stash
> 
> Nothing changes for anyone who does not set it, and the tools that
> manage worktrees for agents can set it when they create a worktree.
> 
> Alternatives I considered and rejected:
> 
>    - Making the stash per-worktree unconditionally.  It breaks the
>      stash-here-apply-there workflow, and it moves existing entries out
>      from under scripts.  If that is the destination, it belongs in
>      Documentation/BreakingChanges.adoc for Git 3.0, with a warning
>      released first - but it does not have to block a knob today.
> 
>    - Named stashes.  A name that survives a push by another process is
>      what a ref already is, so this would grow a second naming scheme
>      over the one branches and tags already use, plus commands to list
>      and delete those names.
> 
>    - Leaving it to tooling.  It works - `git stash create` writes a
>      stash commit without touching any ref, so a wrapper can store it
>      under refs/worktree/<name> and apply it later - but every tool
>      reimplements it, and the failure mode for anyone who does not is
>      silent.
> 
> Points I am not sure about, and where I would like guidance before
> writing a patch:
> 
>    - Whether stash.ref is the right name, and whether it should be
>      restricted to refs/ (rejecting a value that is not a ref name).
> 
>    - Whether `git stash list` should be able to show the other stacks -
>      a worktree's entries becoming invisible to the main checkout is the
>      cost of the knob, and `git stash list --all` over
>      worktrees/*/refs/worktree/stash might be a reasonable answer.
> 
>    - Reachability.  fsck and reflog expiry learned to iterate
>      per-worktree refs, and I would like a second opinion on whether
>      stash entries under refs/worktree/* are safe from gc in the same
>      way refs/stash entries are.
> 
> If the direction sounds reasonable, I am happy to write the patch.
> 
> Thanks,
> Vladimir Sitnikov
> 

Re: Subject: [RFC] stash: let the stash stack live in a configurable ref

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

> On a related note I've been meaning to add an option to specify an 
> alternative branch name when creating a stash, so that "git checkout -m" 
> and "git rebase --autostash <upstream> <branch>" can record the branch 
> that we're switching to, rather than the one that's currently checked 
> out when creating stashes.

Interesting.  I think we have seen ideas floated to allow per-branch
and per-worktree stashes in the past.  I am not sure how much we
should rely on the stash message, though.  The more heavily we rely
on it, the more restricted the end-user messages supplied via the
'-m' option would become.  If we were to officially support
per-branch stashes, we may have to adopt a more structured format
(which could be something simple like "at the end of the message
after the last ':' is the name of the branch the stash entry
targets", alongside a tweak to the '-m' option to always append
': target-branch' after whatever the user gives as the message).

Re: Subject: [RFC] stash: let the stash stack live in a configurable ref

[Phillip Wood]

On 24/08/2026 15:58, Junio C Hamano wrote:
> Phillip Wood <phillip.wood123@gmail.com> writes:
> 
>> On a related note I've been meaning to add an option to specify an
>> alternative branch name when creating a stash, so that "git checkout -m"
>> and "git rebase --autostash <upstream> <branch>" can record the branch
>> that we're switching to, rather than the one that's currently checked
>> out when creating stashes.
> 
> Interesting.  I think we have seen ideas floated to allow per-branch
> and per-worktree stashes in the past.  I am not sure how much we
> should rely on the stash message, though.  The more heavily we rely
> on it, the more restricted the end-user messages supplied via the
> '-m' option would become.  If we were to officially support
> per-branch stashes, we may have to adopt a more structured format
> (which could be something simple like "at the end of the message
> after the last ':' is the name of the branch the stash entry
> targets", alongside a tweak to the '-m' option to always append
> ': target-branch' after whatever the user gives as the message).

We add the branch name to the beginning of the user-supplied message in 
create_stash(). If the user supplies the message then we prepend "On 
$branch: ", if the user does not supply a message we use "WIP on $branch 
..." so I think we already have simple structured messages.

Thanks

Phillip

Re: Subject: [RFC] stash: let the stash stack live in a configurable ref

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

> We add the branch name to the beginning of the user-supplied message in 
> create_stash(). If the user supplies the message then we prepend "On 
> $branch: ", if the user does not supply a message we use "WIP on $branch 
> ..." so I think we already have simple structured messages.

Makes sense.

Re: [RFC] stash: let the stash stack live in a configurable ref

[Vladimir Sitnikov]

Kristoffer Haugsbakk writes:

> To my uninformed, not-using-agents mind, what agents do with the tool
> seems like the least concerning thing. They can be non-deterministically
> instructed to not use the stash.
[...]
> And for determinism you can give them a git(1) wrapper that bans
> git-stash(1).

A wrapper that bans git-stash(1) misses it, because a command that never
mentions the stash still writes to refs/stash:

    git rebase topic --autostash
    Created autostash: 637ca99
    Applying autostash resulted in conflicts.
    Your changes are safe in the stash.
    You can run "git stash pop" or "git stash drop" at any time.

The entry sits in refs/stash afterwards, where every worktree sees it.
rebase.autoStash lives in the shared .git/config, so one worktree can
turn this on for all of them, and the flag then never appears in any
command line to ban.

Having a stash subcommand and forbidding it to execute is fishy.
Agents might miss the instructions and they might still attempt calling stash.

Your point about the bar for a configuration option is well taken, and
so is the one about the framing.  The single confused session justifies
the option on its own; the agents changed how often it happens, not
whether it is worth fixing.

Phillip Wood writes:

> When I'm not trying to move changes between branches I associate a stash
> with the branch that's checked out when it is created, not the worktree
> where that the branch happens to be checked out.  We already record the
> branch name when creating the stash so perhaps we should add an option
> to pop the last stash that was created on the current branch.

That covers more of my case than I expected.  Git refuses to check the
same branch out in two worktrees, so a per-branch filter separates every
worktree that sits on a branch, and the entries stay visible to
`git stash list`, which a private ref gives up.

The gap is a detached HEAD:

    git checkout --detach
    echo v2 >f && git stash push -m "my own text"
    git stash list
    stash@{0}: On (no branch): my own text

Every detached worktree records the same "(no branch)", so a per-branch
filter groups them together rather than separating them.  That is not a
corner case for the tools I have in mind: one repository here has 436
linked worktrees, 23 of them on a detached HEAD, because a worktree
created to look at someone else's commit has no branch to be on.

> If an agent really needs a private stash it can use "git stash create"
> and record the oid of the stash under "refs/worktree/".

That is what I do today, and it works.  It is also what every tool has
to reimplement, and the ones that skip it produce the failure I opened
with.

The two ideas may well be one knob.  If the scope of the stack were
configurable (the shared ref, the current branch, or a per-worktree
ref), then "pop what this branch stashed" and "pop what this worktree
stashed" become two values rather than two features, and a detached
worktree can choose the one that still separates it.

I am happy to write the patch for whichever direction you prefer, or to
test yours.

Thanks,
Vladimir Sitnikov

Re: [RFC] stash: let the stash stack live in a configurable ref

[Phillip Wood]

Hi Vladimir

On 25/08/2026 19:24, Vladimir Sitnikov wrote:
> Kristoffer Haugsbakk writes:
> 
>> To my uninformed, not-using-agents mind, what agents do with the tool
>> seems like the least concerning thing. They can be non-deterministically
>> instructed to not use the stash.
> [...]
>> And for determinism you can give them a git(1) wrapper that bans
>> git-stash(1).
> 
> A wrapper that bans git-stash(1) misses it, because a command that never
> mentions the stash still writes to refs/stash:
> 
>      git rebase topic --autostash
>      Created autostash: 637ca99
>      Applying autostash resulted in conflicts.
>      Your changes are safe in the stash.
>      You can run "git stash pop" or "git stash drop" at any time.
> 
> The entry sits in refs/stash afterwards, where every worktree sees it.
> rebase.autoStash lives in the shared .git/config, so one worktree can
> turn this on for all of them, and the flag then never appears in any
> command line to ban.
> 
> Having a stash subcommand and forbidding it to execute is fishy.
> Agents might miss the instructions and they might still attempt calling stash.

Right, your wrapper would need to be a bit more complicated. It would 
need to pass "-c rebase.autoStash=false -c merge.autoStash=false -c 
pull.autoStash=false", disallow command-lines containing --autostash and 
probably set GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=true to enforce that.

> Your point about the bar for a configuration option is well taken, and
> so is the one about the framing.  The single confused session justifies
> the option on its own; the agents changed how often it happens, not
> whether it is worth fixing.
> 
> Phillip Wood writes:
> 
>> When I'm not trying to move changes between branches I associate a stash
>> with the branch that's checked out when it is created, not the worktree
>> where that the branch happens to be checked out.  We already record the
>> branch name when creating the stash so perhaps we should add an option
>> to pop the last stash that was created on the current branch.
> 
> That covers more of my case than I expected.  Git refuses to check the
> same branch out in two worktrees, so a per-branch filter separates every
> worktree that sits on a branch, and the entries stay visible to
> `git stash list`, which a private ref gives up.
> 
> The gap is a detached HEAD:
> 
>      git checkout --detach
>      echo v2 >f && git stash push -m "my own text"
>      git stash list
>      stash@{0}: On (no branch): my own text
> 
> Every detached worktree records the same "(no branch)", so a per-branch
> filter groups them together rather than separating them.  That is not a
> corner case for the tools I have in mind: one repository here has 436
> linked worktrees, 23 of them on a detached HEAD, because a worktree
> created to look at someone else's commit has no branch to be on.

When we create a stash entry its first parent is HEAD. So I think you 
can find the last stash that was created in the current worktree by 
using HEAD's reflog and the first parents of the stashes. You want to 
find the most recent stash entry stash@{M} where

     object-id(HEAD@{N}) == object-id(refs/stash@{M}^1) &&
     reflog-date(HEAD@{N}) <= commit-date(refs/stash@{M}) &&
     commit-date(refs/stash@{M}) <= reflog-date{HEAD@{N-1})

that will give you the stash whose first parent is the same commit as 
HEAD in the current worktree when the stash was created.

>> If an agent really needs a private stash it can use "git stash create"
>> and record the oid of the stash under "refs/worktree/".
> 
> That is what I do today, and it works.  It is also what every tool has
> to reimplement, and the ones that skip it produce the failure I opened
> with.
> 
> The two ideas may well be one knob.  If the scope of the stack were
> configurable (the shared ref, the current branch, or a per-worktree
> ref), then "pop what this branch stashed" and "pop what this worktree
> stashed" become two values rather than two features, and a detached
> worktree can choose the one that still separates it.
> 
> I am happy to write the patch for whichever direction you prefer, or to
> test yours.

My preference would be to add options to "git stash pop" to pop the most 
recent stash created on the current branch, or the most recent stash 
created in the current worktree. That keeps the convenience of the 
global store for moving changes between different branches/worktrees 
while making it easy to pop the stash that you intended. It would be 
nice to have options to filter the output of "git stash list" by branch 
or worktree as well but that could be added separately.

I'd be interested to hear what others think

Thanks

Phillip