[DOCS] Worktree settings page missing prose explanation and cross-link for worktree.sparsePaths

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

"Worktree settings" section and the "Run parallel Claude Code sessions with Git worktrees" section in common-workflows

Current Documentation

The settings page has a one-line table entry:

| worktree.sparsePaths | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk, which is faster in large monorepos | ["packages/my-app", "shared/utils"] |

The "Worktree cleanup" section in the worktrees how-to (common-workflows) covers creation and cleanup but never mentions worktree.sparsePaths or worktree.symlinkDirectories.

What's Wrong or Missing?

A. No explanatory prose beyond the table row

The table entry is the entirety of the documentation. There is no explanation of when to use worktree.sparsePaths versus worktree.symlinkDirectories, what git sparse-checkout cone mode means in practice, or what happens to files outside the listed paths during a worktree session.

B. No cross-link from the primary worktrees workflow page

The "Run parallel Claude Code sessions with Git worktrees" section in common-workflows is the page most users reach first when learning about --worktree. It covers creation, subagent worktrees, and cleanup, but never mentions the worktree settings. A user following that guide would never discover worktree.sparsePaths exists.

C. No practical guidance for monorepo users

There is no guidance on which setting to use for which problem (sparse checkout vs. symlinking), no caveats about files outside sparse paths being inaccessible during a task, and no note on whether paths must be top-level or can be nested.

Suggested Improvement

A. Add a prose paragraph to the Worktree settings section in settings.md

After the section heading, before the table, add:

Two settings let you optimize worktree performance in large monorepos. worktree.sparsePaths uses git sparse-checkout (cone mode) to write only the listed directories to disk—useful when your repo has many directories but a task only needs a subset. worktree.symlinkDirectories symlinks specific directories from the main repo into each worktree instead of copying them—useful for large dependency directories like node_modules. You can combine both settings. Note that files outside sparsePaths are not checked out in the worktree; tasks that need them will fail to read those files.

B. Add a cross-reference in common-workflows.md

In the "Run parallel Claude Code sessions with Git worktrees" section, after the Subagent worktrees subsection, add a "Monorepo performance" subsection:

For large monorepos, configure worktree.sparsePaths and worktree.symlinkDirectories in your settings to reduce disk usage and startup time. See Worktree settings.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/settings | "Worktree settings" section — table entry lacks prose explanation |
| https://code.claude.com/docs/en/common-workflows | "Run parallel Claude Code sessions with Git worktrees" — no mention of worktree settings |

Total scope: 2 pages affected

Source: Changelog v2.1.76

Added worktree.sparsePaths setting for claude --worktree in large monorepos to check out only the directories you need via git sparse-checkout