[DOCS] [Worktrees] cleanup docs omit the v2.1.205 Windows NTFS junction / directory symlink safety fix

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/worktrees

Section/Topic

The "Clean up worktrees" section (under the "Start Claude in a worktree" / "Manage worktrees manually" content) and the "Non-git version control" section. Both describe worktree removal as a straightforward delete, but neither mentions Windows-specific safety around NTFS junctions or directory symlinks.

Current Documentation

From https://code.claude.com/docs/en/worktrees (worktree cleanup section around line 89):

When you exit a worktree session, cleanup depends on whether you made changes: No uncommitted changes, no untracked files, and no new commits: the worktree and its branch are removed automatically. If the session has a name, Claude prompts instead so you can keep the worktree for later Uncommitted changes, untracked files, or new commits exist: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding any uncommitted changes, untracked files, and commits * Non-interactive runs: worktrees created with --worktree alongside -p are not cleaned up automatically since there is no exit prompt. Remove them with git worktree remove

A few paragraphs below, manual cleanup guidance reads:

Remove one when you're done with it: ``bash theme={null} git worktree remove ../project-feature-a `` See the Git worktree documentation for the full command reference.

The "Non-git version control" section (line 137) similarly describes WorktreeRemove hooks as straightforward removal without any Windows-specific caveat.

What's Wrong or Missing?

A. The worktrees.md cleanup prose does not mention the v2.1.205 Windows NTFS junction / directory symlink safety fix

The v2.1.205 changelog entry reads:

Fixed Windows worktree removal deleting files outside the worktree when an NTFS junction or directory symlink existed inside it

Before v2.1.205, removing a worktree on Windows could traverse an NTFS junction (or a directory symlink) inside that worktree and delete files reachable through it, including files outside the worktree directory. The cleanup section still describes removal as "deletes the worktree directory and its branch" without qualifying that on Windows the deletion is now bounded to the worktree itself and will not follow junctions or directory symlinks into other paths.

A Windows user reading the current cleanup section cannot tell whether removing a worktree might still touch files outside it, and there is no documented boundary that tells them which directories are protected by the v2.1.205 fix.

B. The manual git worktree remove example and the WorktreeRemove hook framing are also unbracketed

The manual git worktree remove ../project-feature-a example and the WorktreeRemove hook that pairs with WorktreeCreate in the "Non-git version control" section describe the same removal operation. After v2.1.205, Claude Code's own worktree cleanup is bounded on Windows, but the manual removal example does not say so, and the hook description ("WorktreeRemove hooks … can perform cleanup tasks like removing version control state or archiving changes") does not mention the new safety bound either.

A Windows user wiring up a WorktreeRemove hook today has no documentation entry that tells them the hook will only ever be called with the worktree's own path, not the path of a directory the worktree points to via a junction.

C. The cleanup page neither names the v2.1.205 fix nor anchors on a version marker

Other recent fixes on this page carry an inline {/* min-version: <version> */} note (e.g., the v2.1.200 plugin-loading note in "Start Claude in a worktree" or the v2.1.198 transcript-relocation note). The Windows junction/directory-symlink fix has no such marker anywhere on worktrees.md, so a user following the version history cannot tell from the docs alone when the Windows cleanup became bounded.

Suggested Improvement

Add a short Windows-specific paragraph under "Clean up worktrees", and a one-line version-history marker for the fix.

Suggested addition under "Clean up worktrees" (for example, between the cleanup-bullet list and the cleanupPeriodDays paragraph):

{/ min-version: 2.1.205 /}On Windows, removing a worktree no longer follows NTFS junctions or directory symlinks that exist inside it, so cleanup is bounded to the worktree's own directory and will not delete files reachable through a junction that points back into the main repository (or anywhere else on disk). Requires Claude Code v2.1.205 or later. Earlier versions could delete files outside the worktree when a junction inside the worktree pointed outside it.

If preferred, the same note can also be added at the manual-removal example so it covers both git worktree remove (when invoked by Claude) and the explicit git worktree remove ../project-feature-a example.

Suggested wording for the WorktreeRemove hook section:

WorktreeRemove hooks have no decision control. They can't block worktree removal but can perform cleanup tasks like removing version control state or archiving changes. Hook failures are logged in debug mode only. On Windows, the path the hook receives is always the worktree directory itself; cleanup does not descend into NTFS junctions or directory symlinks beneath it. See the hooks reference for the input schema and a removal example.

Optional: Add a sentence to the "Manage worktrees manually" section noting that on Windows, when Claude invokes git worktree remove for one of its own worktrees, the operation will not touch files outside the worktree directory. Manual users who run git worktree remove themselves rely on Git's own behavior, which is unaffected by this fix.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/worktrees | 89-97, 129-135 | "Clean up worktrees" section and "Manage worktrees manually" removal example |
| https://code.claude.com/docs/en/worktrees | 137-160 | "Non-git version control" section's WorktreeCreate/WorktreeRemove hook pairing |
| https://code.claude.com/docs/en/hooks | 2533 | WorktreeRemove hook description (cross-reference for the hook contract change) |

Total scope: 1 page directly affected, plus 1 cross-reference page.

Version context: The v2.1.205 fix is the broader version of an earlier NTFS-junction fix. The earlier fix (v2.1.146) targeted "removing a background-job worktree" specifically, while the v2.1.205 entry broadens the same safety to any Windows worktree removal. The worktrees.md cleanup section currently mentions neither fix, so a reader following v2.1.205 release notes cannot confirm the safety behavior from the worktrees guide.