claude-code - 💡(How to fix) Fix [DOCS] Worktree cleanup docs omit failed-removal safety behavior for gitignored and in-progress files

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Clean up worktrees and related worktree-removal guidance

Current Documentation

The worktrees page currently says:

• 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

It also says:

• 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

The agent view docs also say:

Deleting removes the session from agent view and cleans up its worktree, including any uncommitted changes in it, so push or commit work you want to keep before deleting.

Worktrees are removed when you delete the session that created them. If a session ended without cleaning up, list leftover entries with git worktree list in the project directory and remove each with git worktree remove <path>.

What's Wrong or Missing?

Changelog v2.1.143 includes this user-visible fix:

Worktree cleanup no longer falls back to rm -rf when git worktree remove fails, preventing loss of gitignored or in-progress files

The current docs still describe worktree removal as if deletion is unconditional once the user chooses remove, but they do not explain the failure behavior when git worktree remove cannot complete.

That leaves two important gaps:

A. Failed cleanup safety behavior is undocumented

The docs do not say that Claude now avoids a destructive filesystem-level fallback when Git refuses to remove a worktree. Users reading the current wording could reasonably assume Claude will always delete the directory once they choose removal.

B. Protection for gitignored and in-progress files is not stated

The fix specifically protects worktrees that still contain gitignored files or other in-progress local state when git worktree remove fails. That safety guarantee is not reflected anywhere in the worktree cleanup docs.

Suggested Improvement

Update the worktree cleanup guidance to distinguish between a successful Git removal and a failed one.

Suggested wording for worktrees.md:

When you choose to remove a worktree, Claude first uses git worktree remove. If Git refuses to remove the worktree, Claude leaves the directory in place instead of force-deleting it, so gitignored files and other in-progress local changes are not lost.

Add a short note near the manual cleanup guidance:

If git worktree remove fails, inspect the worktree contents before retrying or deleting it manually. This commonly happens when the worktree still contains local state Git will not remove safely.

Optionally mirror the same note in agent-view.md and the desktop worktree cleanup guidance so all session-deletion surfaces describe the same safety behavior.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.143

Exact changelog entry:

Worktree cleanup no longer falls back to rm -rf when git worktree remove fails, preventing loss of gitignored or in-progress files