git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v2 2/2] worktree: reap ephemeral branches created by "worktree add"

From
JNJason Newton <nevion@gmail.com>
Date
Oct 21, 2026, 07:40 UTC
Message-ID
<CAGou9MgdF_xA+e8YYn8ud8TUSmY3j_q9jbUTy2wLibTz1ObJ7A@mail.gmail.com>
In-Reply-To
<CAPig+cRsSN9gY405MGsCQzLuxzBKcfHo2Oc8Z4WB-U3BGd6m_Q@mail.gmail.com>
--detach and an ephemeral branch differ while the worktree exists.

--detach leaves HEAD with no branch, so status, push, rename, upstream, and symbolic-ref have nothing to name. An ephemeral branch is a normal refs/heads/ ref for the life of the worktree. Commits go on it, and another ref can point at them before "worktree remove" deletes that branch.

Deleting the branch that "worktree add <path>" creates today would change the default, so this has to be opt-in. That opt-in is not --detach: the worktree stays on a branch until removal.

These worktrees might be minutes or they might go on for months;
either way they should be easy to use and not require flags to assist
 in the majority of common case behaviors, moreover detached feels
ike a degraded halfway state, frequently allowing a gotcha to strike or
 a loss of a safety like a gc based reap.

"git worktree remove" does not delete whatever branch a worktree has checked out. It deletes a branch only when this "git worktree add" created it by DWIM (the final component of <path>) and recorded that in worktrees/<id>/owned-branch.

A branch named with -b/-B, a branch that already existed, and a detached HEAD are not owned and are not removed. A worktree created by an older Git has no marker, so removing it still leaves its branch in place.

"Unconditional" in the commit means that this one owned branch is deleted even if it has unmerged commits. --keep-branch turns that off. "git branch <name> <tip>" before removal keeps the commits on an ordinary branch; only the owned ref is deleted.

The call that changes is "git worktree add <path>" with no branch, followed by "git worktree remove". A caller who wants that branch to outlive the worktree already has a spelling this series does not touch: "git worktree add -b <name> <path>", or "git worktree add <path> <existing>". --detach still creates no branch, so it is not the same state while the worktree exists.

Ownership is written only when the worktree is created, so I'll confirm an older worktree still has no marker after an upgrade. The branch stays. Upgrading does not mark a worktree you already have so no upgrade headaches are expected.

-Jason
On Tue, Oct 20, 2026 at 11:52 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
Show 51 quoted lines
>
> On Tue, Oct 20, 2026 at 12:09 PM Jason Newton via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
> > When "git worktree add <path>" is given no branch to check out, it
> > auto-creates one named after the path. Such a branch exists only to back
> > the new worktree, yet it outlives it: removing the worktree leaves the
> > branch behind, so a fleet of throwaway worktrees fills refs/heads/ with
> > dead branches that have to be cleaned up by hand.
> >
> > Treat an auto-created branch as owned by the worktree. Record it in the
> > worktree's administrative directory (worktrees/<id>/owned-branch) at
> > creation time -- the one moment we can know for certain the branch is
> > worktree-private, since we are the one that created it. "git worktree
> > remove" then deletes the owned branch once the worktree is gone and it
> > is no longer checked out.
> >
> > Ownership is recorded only when "worktree add" itself creates the branch
> > via DWIM auto-naming; a branch named explicitly with -b/-B, or one that
> > already existed, is never owned and never reaped. Deletion is
> > unconditional (even for unmerged commits) because an ephemeral branch is
> > disposable by contract: to keep the work, pass --keep-branch, or anchor
> > the commits with an ordinary branch beforehand -- a normal branch can
> > point at the same commits, after which reaping the ephemeral ref loses
> > nothing. "git branch -m" updates the marker so ownership follows a
> > rename, and the branch stays ephemeral.
> >
> > The marker is just another per-worktree administrative file, so older
> > versions of Git simply ignore it (they keep the branch on removal, as
> > today).
> >
> > Signed-off-by: Jason Newton <nevion@gmail.com>
>
> Sorry, I may be missing something obvious, but this message never
> explains why we should add all this additional complexity for a
> use-case already directly supported by `git worktree add -d <path>`.
> Specifically, worktree's --detach option is exactly what you want when
> creating throwaway worktrees, even "fleets" of them (using terminology
> from this apparently fully or partially LLM-generated message). If
> your tooling or agent is not using -d/--detach for throwaway
> worktrees, then the problem is fixable by modifying the tooling or by
> teaching the agent about --detach, without bulking up the git-worktree
> implementation unnecessarily.
>
> Moreover, a change like this which makes the new behavior
> unconditional is certainly going to break existing tooling and
> workflows, thus it will not go over well, even with the --keep-branch
> escape-hatch. At minimum, to be acceptable, assuming such new
> functionality is even desirable, to avoid breaking existing setups, it
> would have to be opt-in, not opt-out (via --keep-branch). But if it's
> going to be opt-in, then you may as well just use --detach to achieve
> the same effect.
Previous: Eric SunshineNext: Eric Sunshine
Message 13 of 23 in “worktree: copy-on-write creation and shared-branch worktrees”
  1. 0/2 worktree: copy-on-write creation and shared-branch worktreesJason Newton via GitGitGadget, Jun 5, 2026
  2. 1/2 worktree: add --reflink for copy-on-write worktree creationJason Newton via GitGitGadget, Jun 5, 2026
  3. 2/2 worktree: allow sharing a checked-out branch across worktreesJason Newton via GitGitGadget, Jun 5, 2026
  4. brian m. carlsonJun 5, 2026
  5. Junio C HamanoJun 8, 2026
  6. 0/2 worktree: copy-on-write creation and ephemeral branchesJason Newton via GitGitGadget, Oct 20, 2026
  7. 1/2 worktree: add --reflink for copy-on-write worktree creationJason Newton via GitGitGadget, Oct 20, 2026
  8. brian m. carlsonOct 20, 2026
  9. Jason NewtonOct 21, 2026
  10. brian m. carlsonOct 22, 2026
  11. 2/2 worktree: reap ephemeral branches created by "worktree add"Jason Newton via GitGitGadget, Oct 20, 2026
  12. Eric SunshineOct 21, 2026
  13. Jason NewtonOct 21, 2026
  14. Eric SunshineOct 21, 2026
  15. Jason NewtonOct 21, 2026
  16. Phillip WoodOct 21, 2026
  17. Jason NewtonOct 21, 2026
  18. Eric SunshineOct 21, 2026
  19. 0/4 worktree: copy-on-write creation and ephemeral branchesJason Newton via GitGitGadget, Oct 21, 2026
  20. 1/4 worktree: add --reflink for copy-on-write worktree creationJason Newton via GitGitGadget, Oct 21, 2026
  21. 2/4 worktree: reap ephemeral branches created by "worktree add"Jason Newton via GitGitGadget, Oct 21, 2026
  22. 3/4 worktree: disable reflink on WindowsJason Newton via GitGitGadget, Oct 21, 2026
  23. 4/4 worktree: keep the reflink probe referenced on WindowsJason Newton via GitGitGadget, Oct 21, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.