docs(worktree): record what git clean does to a nested worktree

[anilcancakir]

What

Six comment lines above the .claude/worktrees/ ignore rule.

Why

This repository was the pilot for the worktree-layout sweep and merged first, so it never received the correction the thirteen sibling repositories got afterwards. Their .gitignore now records that a nested worktree survives git clean -xdf and only git clean -xdff removes it; this one said nothing. Aligning the comment so the whole ecosystem reads the same.

The claim is measured rather than reasoned:

$ git clean -xdf --dry-run
Skipping repository .claude/worktrees/slug

$ git clean -xdf     # worktree intact, its untracked scratch file too
$ git clean -xdff    # gone, and git worktree list --porcelain reports it prunable

Git guards on the gitlink, not on whether .git is a directory or a file.

Testing

Comment only. No Dart, YAML or lib/ file is touched.

[kodizm]

Note

Kodizm (AI-generated). May contain mistakes; verify before acting.

Six comment lines above an unchanged ignore rule; the claims they record are accurate and nothing executable is touched - looks good to merge.

The only hunk adds comment text above .gitignore:54. The .claude/worktrees/ pattern itself is byte-identical, so matching behaviour cannot have shifted, and I confirmed that directly rather than assuming it.

Both factual claims in the new text hold up:

• git clean -xdf skipping a nested worktree - git's guard is is_nonbare_repository_dir(), which tries read_gitfile_gently() on <dir>/.git before falling back to is_git_directory(). A linked worktree has a gitfile there, so it resolves and the directory is skipped, exactly as a submodule is. The check sits at the top of remove_dirs() and so fires at every recursion depth, which is why the parent .claude/worktrees/ survives too rather than being removed around the skipped child.
• -xdff leaving .git/worktrees/<slug> behind - the admin directory lives inside .git, which git clean never walks, so removing the checkout leaves a registration that only git worktree prune clears. Correctly stated.

The wording is also consistent with .worktreeinclude, which already describes worktrees living at .claude/worktrees/<slug>.

Tests

None, and none needed: a comment in .gitignore has no behaviour to cover. CLAUDE.md's post-change checklist scopes CHANGELOG/README syncing to source code changes, so no entry is owed here.

Checks I ran

• git ls-files .claude/worktrees - empty, so no tracked file sits under the ignored path.
• git check-ignore -v .claude/worktrees/foo/bar.txt - matches .gitignore:54:.claude/worktrees/, unchanged by this PR.
• git check-ignore -v .claude/rules/tests.md - not ignored, confirming the "rest of .claude/ is tracked" claim in the pre-existing comment above the new lines.
• git diff --stat - one file, 6 insertions, 0 deletions.
• I could not execute the git clean reproduction from the description: git clean was blocked in this environment in every form, including --dry-run. The two claims above are verified against git's implementation and the existing behaviour of the guard, not re-measured here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!