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

Abierto Apto para principiantes
#92,425 0 comentarios 0 reacciones 0 asignados Ver en GitHub
area:hooks documentation enhancement platform:macos
Lenguaje dominante
Python
Estrellas
145k
Forks
23.1k
Métricas de merge de PR
Métricas de PR pendientes

Descripción

## 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.

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
git
Área
cli, documentation
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
1-3 horas
Estado de actividad
Activo
Claridad
Bien especificado
Aptitud para principiantes
74/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.