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

Đang mở Phù hợp với người mới
#92,425 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
area:hooks documentation enhancement platform:macos
Ngôn ngữ chính
Python
Star
145k
Fork
23.1k
Chỉ số merge pull request
Chỉ số pull request đang chờ

Mô tả

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

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
git
Lĩnh vực
cli, documentation
Loại issue
Tài liệu
Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
74/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.