anthropics / anthropics/claude-code

[Docs] worktrees: exit-time cleanup of an ADOPTED worktree (opened by name, not created by Claude Code) removes the directory but not the branch; WorktreeRemove hook contract is undocumented

Aperta Adatta ai principianti
#92,425 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area:hooks documentation enhancement platform:macos
Lingua principale
Python
Stelle
145k
Fork
23.1k
Metriche di merge delle PR
Metriche PR in attesa

Descrizione

## Docs gap

Page: https://code.claude.com/docs/en/worktrees § "Clean up worktrees", and https://code.claude.com/docs/en/hooks (`WorktreeRemove`).

The cleanup section says:

> **The worktree is clean**: for an unnamed session, Claude removes the worktree and its branch automatically. A named session prompts you first so you can keep the worktree for later

This describes a worktree Claude Code created itself (`.claude/worktrees/` on `worktree-`). The page also says, under "Reuse a worktree name":

> Passing `--worktree` a name whose directory already exists opens that existing worktree instead of creating a new one.

The docs do not say what exit-time cleanup does to a worktree that was **adopted** this way — one created with `git worktree add` (or by another tool) on its own branch, then opened with `--worktree ` from the main checkout.

## What we measured (Claude Code 2.1.261, macOS)

Ten sessions on 2026-09-05, each `claude --worktree --permission-mode auto` from the main checkout with no `--name`, where `.claude/worktrees/` already existed as a linked worktree on a `feat/` branch created by `git worktree add`:

- At `/exit` with a clean tree, the **worktree directory was removed** with no prompt (the transcript ends with a `relocated` record to the launch directory, then `worktree-state: null`; the binary carries `Worktree removed (no changes)` for this path).
- The **branch survived** every time (`git branch --list feat/` still showed it).

So "removes the worktree and its branch" is half true for an adopted worktree: the directory goes, the branch stays. Nothing on the page tells a reader that an adopted worktree is subject to the same silent removal as a Claude-created one, nor that its branch is treated differently.

## What we could only learn from the binary

The hooks reference has no `WorktreeRemove` entry describing the hook's contract. From `strings` on the 2.1.261 binary:

- `Input to command is JSON with worktree_path (absolute path to worktree).`
- `Exit code 0 - worktree removed successfully`
- `WorktreeRemove hook did not remove worktree, kept at: `
- `No WorktreeRemove hook configured; falling back to git worktree remove for: `

i.e. a registered `WorktreeRemove` hook **replaces** the removal (like `WorktreeCreate` replaces creation), and a hook that leaves the path in place keeps the worktree. That is the lever we ended up using to keep adopted worktrees, and it is not documented.

## Suggested doc changes

1. In "Clean up worktrees", add a sentence for the adopted case: a worktree opened by name (not created by Claude Code) is removed by the same unnamed-session rule when clean, but its branch is left in place.
2. In the hooks reference, give `WorktreeRemove` the same treatment as `WorktreeCreate`: the input fields (`worktree_path`, `session_id`, `cwd`, …), that it replaces the default `git worktree remove` when configured, that leaving the path in place keeps the worktree ("kept at" is reported to the user), and that exit codes are logged in debug mode only.
3. Optionally, note in "Clean up worktrees" that registering a `WorktreeRemove` hook is the way to opt a repo's worktrees out of exit-time removal without naming every session.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Start from the docs pages named in the issue: worktrees, especially “Clean up worktrees” and “Reuse a worktree name”, plus the hooks reference for WorktreeRemove. Use the measured behavior and suggested changes as the source for wording. Done means the docs explain adopted worktree cleanup, branch retention, and the WorktreeRemove hook contract.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
git
Ambito
cli, documentation
Tipo di issue
Documentazione
Difficoltà
2/5
Tempo stimato
1-3 ore
Stato di attività
Attiva
Chiarezza
Specificata chiaramente
Idoneità per principianti
74/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.