Skip to main content

Delete and Recover a Worktree

Deleting a worktree: what the dialog spells out before you confirm, what force delete costs, what happens to running agents, and the deleted-worktree rescue card that keeps surviving sessions alive.

Updated
Reviewed

Deleting a Worktree

Open the delete dialog by right-clicking a card and choosing Delete worktree…, from the card's three-dot menu, or from the action palette. A worktree whose pull request has merged also gets a trash button on its card, so cleanup is one click. The main worktree (your repository root) is protected and can't be deleted.

The dialog is titled with the branch it deletes and opens on a summary of the worktree: its Branch and Path, then every changed file with its status, so you see the actual paths at stake before choosing anything.

The dialog fetches a fresh git status when it opens and re-checks it immediately before a force delete dispatches (Checking current work before deleting). A backgrounded worktree's cached snapshot can be half a minute old, which would let a force delete skip the typed-name gate and discard work an agent wrote while the dialog was sitting open. If that fresh check fails, the dialog fails closed: a Couldn't check this worktree for uncommitted work banner with Retry appears, and the confirmation is escalated as though the tree were dirty.

Review the consequences before typing the worktree name

What will happen

Three options sit under Options:

  • Force delete: permits discarding uncommitted and untracked files. When the worktree has changes, a line under it reads Required to delete this worktree and names what is at stake; on the main worktree or a protected branch (main, master, develop, development) it warns that a force delete asks you to type the name.
  • Close all terminals, with the count: starts checked, and only appears when the worktree has terminals. Uncheck it to keep them running after the directory goes; see Deleted worktrees.
  • Delete branch: requests Git's safe branch deletion. Not offered for a protected branch or a detached HEAD.

Below them, What will happen lists only the outcomes that will actually occur under the options as currently set, and updates as you toggle them:

  • Worktree directory will be deleted from disk, always.
  • N terminals will be closed, noting how many are running an agent.
  • Dev server will be stopped, when one is running for the worktree.
  • Resource teardown will run first and Project teardown will run first, each with the exact commands it will run and the note that the delete continues if it fails. A teardown whose commands come from the repository and haven't been approved reads will be skipped instead. See lifecycle scripts and Remote Compute.
  • A red row for each kind of work force delete would destroy, such as Uncommitted changes to 3 tracked files and 1 untracked file will be permanently lost.
  • Branch {name} will be deleted if Git allows it, with Kept if it isn't fully merged, or if Git refuses for any other reason.

Anything the dialog couldn't verify says so rather than guessing, for example A running dev server will be stopped. Its state couldn't be read, so it isn't known whether one is running.

Force delete and Delete branch are separate consents. Even with Force delete checked, an unmerged branch is kept if Git refuses to remove it, so the worktree can disappear while its branch remains available for a later checkout.

Worktrees containing submodules

The preview inspects direct submodule work as well as the parent repository. Inside submodules lists nested modified and untracked files, and, under Unpushed commits, commits that are not reachable from any remote-tracking ref known to this clone. A clean parent status alone is not proof that a submodule has nothing to lose.

  • Nested modified or untracked files require Force delete and the appropriate confirmation.
  • At-risk submodule commits block deletion, including force deletion. A Push the submodule commits first banner names the submodule. Push the commits from inside it, or fetch there if they are already published, then choose Retry.
  • An incomplete submodule inspection blocks deletion too: Couldn't finish checking this worktree's submodules. Fix the read or Git error and choose Retry.

While the delete is blocked, the options and the consequence list are hidden, since they would only describe a delete that can't happen, and the footer says what clears the block: Delete unavailable until the submodule commits are on a remote.

The host repeats these safeguards on the deletion path, so bulk removal and agent-initiated deletion cannot bypass them. The inventory is bounded and direct-submodule based; a failed or incomplete check is never presented as safe. Automatic git worktree prune also leaves a submodule's absorbed store alone, so its commits survive maintenance. See the submodule risk contract.

Publish the submodule commits, then retry the deletion preview.

The confirm button

  • Delete worktree: the default, safe path. With uncommitted work in the tree and Force delete unchecked, the footer reads Select Force delete to continue.
  • Force delete worktree: force is on but the action is still low-risk.
  • For a risky force deletion (a dirty tree, nested submodule changes, or the main worktree or a protected branch), a typed-name input appears above the footer with a sentence naming the reason, and Force delete worktree stays unavailable until the name matches (Confirm the name above to enable).
Note
Destructive actions sit on three tiers. D1 is a single-click confirm, D2 adds a checkbox or option gate, D3 requires typing the target name. Worktree delete starts at D2 and escalates to D3 when force delete meets a dirty or protected target, and it re-derives that tier from live git state at submit, not from what it saw at open.

Progress, failure and abandonment

On confirm the dialog closes and the card takes over: its status row becomes a Deleting… spinner, the card dims and stops accepting clicks, and it stays mounted until the delete finishes. Any approved teardown runs first. A failure shows an inline banner titled Couldn't delete worktree with Git's error text and Retry and Dismiss buttons. The banner sits outside the collapsible details, so collapsing the card doesn't hide it.

One refusal comes from Daintree rather than Git: a worktree that has another registered worktree nested inside its directory can't be deleted, because removing it would destroy the nested one. The error names the nested path; delete that worktree first.

Dismissing a failed attempt clears its error state. Dismissing while a host request is still in flight does not cancel that request; Daintree continues tracking its result rather than pretending the deletion stopped.

Force delete also shortens the project's own teardown commands from 120 seconds to 15, so a hung teardown can't hold a forced delete for long. A resource teardown keeps its 300-second budget either way.

To delete several worktrees at once, see Worktrees Overview.

Deleted Worktrees

Deleting a worktree does not have to kill the agents running in it. Close all terminals is checked by default in the delete dialog; uncheck it and the directory goes while the terminals keep running, with the row surviving in the sidebar as a deleted-worktree card, a rescue surface with a visible countdown.

The same happens when a worktree is removed outside Daintree, for example with git worktree remove in a terminal: any terminals still filed under it get a deleted-worktree card, and a dev server running for it is stopped.

The card deliberately shares the live card's design: same header scale, the same terminal section and the same select-on-click behavior, so activating it shows its surviving terminals in the grid and dock. Its terminal list starts open, with each terminal's agent state, and clicking a terminal opens that session directly. What marks the row as deleted is a FolderX icon, a Deleted pill and the struck-through path; the row is not dimmed, because its sessions are live. A trash button in the header, labeled Close N terminals, ends the survivors before the timer does; it asks for confirmation first, and the countdown holds while that confirmation is open.

Rescuing a session means dragging its terminal out onto a live worktree, or using Move to worktree from the terminal's menu. A deleted row never accepts a terminal dropped onto it: it is excluded from the drop-target machinery by construction, not by a flag.

The row anchors itself to the live neighbor it sat above when it was deleted, so the terminals you are looking for stay roughly where you left them instead of jumping to the end of the list. Once two or more pile up they collapse into a single group row with one bulk clear, a readout of the next one to close, and a rail carrying every surviving terminal under the worktree it came from, each still draggable and each with its own countdown.

The directory is gone while its surviving session waits for cleanup

The countdown

The header shows the seconds remaining (hover it for Closes automatically in Ns), and the row's bottom rule drains as the time runs out. Leftover terminals move to trash when the timer ends, after which the row prunes itself, and a quiet inbox entry records it: Deleted worktree cleaned up. Closed 1 terminal left open in {branch}. Deleted rows are deliberately ephemeral and never survive a restart.

The countdown measures time you could actually have seen it, not wall time. It refuses to run while the project's view is cached or the window is hidden, and credits any gap it finds on the way back. It also holds (pinned at whatever remained, not reset) while firing would break something:

HoldLabelWhy
A drag is in progressDraggingDragging a terminal out is the rescue gesture; expiring mid-drag would yank the source away.
The row's close confirmation is openConfirmingYou are mid-decision.
A surviving agent is still workingAgent workingActive output resets the idle clock.

Every hold is capped, so a condition that never clears can't pin a row open forever: five minutes for a drag or a confirmation, an hour for a working agent. The hold's label appears as a badge on the row's path line, with the reason in its tooltip, then the preserved countdown resumes.

Set the timer in Settings > Worktree > Deleted worktrees > Close leftover terminals: after 30 seconds, after 1 minute (default), after 5 minutes, or never (close them yourself).