[DOCS] Search and @ file autocomplete docs omit Jujutsu/Sapling metadata exclusions

Open 💬 4 comments Opened Mar 28, 2026 by coygeek

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

respectGitignore and File suggestion settings, especially the default exclusions that affect Search/Grep and built-in @ file autocomplete

Current Documentation

The settings page currently says:

| respectGitignore | Control whether the @ file picker respects .gitignore patterns. When true (default), files matching .gitignore patterns are excluded from suggestions |

It also says:

Configure a custom command for @ file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.

Related docs currently say:

| respectGitIgnore | true | Exclude .gitignore patterns from file searches |

If Search tool, @file mentions, custom agents, and custom skills aren't working, install system ripgrep:

No current code.claude.com page explains that Claude Code also has an internal exclusion list for version-control metadata directories, or that v2.1.86 added .jj and .sl so Grep and file autocomplete skip Jujutsu and Sapling metadata.

What's Wrong or Missing?

Changelog v2.1.86 says:

Added .jj and .sl to VCS directory exclusion lists so Grep and file autocomplete don't descend into Jujutsu or Sapling metadata

The current docs explain .gitignore-based filtering and mention built-in file traversal, but they do not document the separate always-on VCS metadata exclusions that shape search results and @ suggestions.

That leaves two user-visible behaviors undocumented:

A. Search/Grep exclusions are unclear

Users working in Jujutsu or Sapling repositories cannot tell from the docs that missing results under .jj or .sl are intentional, rather than a Search tool failure or ripgrep installation problem.

B. `@` file autocomplete exclusions are unclear

The docs say respectGitignore controls .gitignore-based filtering, but they do not explain that built-in file autocomplete also skips VCS metadata directories via a separate exclusion list. That makes it unclear why metadata directories remain absent from suggestions even when .gitignore is not the cause.

Suggested Improvement

Add a short note wherever file-search filtering is described:

Claude Code applies built-in exclusions for version-control metadata directories when running Search/Grep and built-in @ file autocomplete. This is separate from respectGitignore / respectGitIgnore, which only controls .gitignore-based filtering. As of v2.1.86, the VCS exclusion list includes .jj and .sl, so Jujutsu and Sapling metadata are intentionally skipped.

Then mirror that note on the VS Code / IDE settings pages and add a brief troubleshooting/reference note so users know that missing results can come from built-in VCS exclusions, not just .gitignore rules or missing ripgrep.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/settings | respectGitignore and File suggestion settings describe .gitignore filtering and built-in traversal, but not VCS metadata exclusions |
| https://code.claude.com/docs/en/vs-code | respectGitIgnore is documented as excluding .gitignore patterns from file searches |
| https://code.claude.com/docs/en/ide-integrations | The same extension setting description appears here |
| https://code.claude.com/docs/en/interactive-mode | @ is introduced as file path autocomplete with no note about intentionally skipped metadata directories |
| https://code.claude.com/docs/en/tools-reference | Grep is listed as a core tool, but no page explains VCS metadata exclusions that affect its results |
| https://code.claude.com/docs/en/troubleshooting | Search troubleshooting discusses ripgrep installation but not built-in VCS exclusions |

Total scope: 6 pages affected

Source: Changelog v2.1.86