Workaround: @ file autocomplete for nested repos using git submodules

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://docs.anthropic.com/en/docs/claude-code/cli

Section/Topic

@ file mention autocomplete with nested repositories

Current Documentation

_No response_

What's Wrong or Missing?

The docs don't explain that @ file autocomplete doesn't work inside nested repositories (directories with their own .git). This is a common workspace setup and there's no documented workaround. Related: #15192

Suggested Improvement

Add a section under @ file mentions explaining:

If your workspace contains nested git repositories, @ autocomplete won't index files inside them.

Workaround: Convert nested repos to git submodules:

git submodule add <repo-url> <folder-name>

This makes all files across nested repos fully searchable via @ autocomplete.

To suppress submodule pointer noise in VS Code, add .vscode/settings.json:
{"git.ignoreSubmodules": true}

Impact

High - Prevents users from using a feature

Additional Context

Confirmed working on Claude Code v2.1.37, Linux. The root cause is documented in #15192: filesystem traversal treats nested .git directories as repository boundaries and excludes them from indexing. The submodule approach resolves this completely.