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

オープン 初心者向け
#92,425 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
area:hooks documentation enhancement platform:macos
主要言語
Python
スター
145k
フォーク
23.1k
PR マージ指標
PR 指標を取得中

説明

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

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
git
領域
cli, documentation
issue の種類
ドキュメント
難易度
2/5
見積もり時間
1〜3時間
活発さ
活発
明瞭さ
明確に書かれている
初心者へのやさしさ
74/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。