Codebase Index Does Not Include Files Within Symlinked Directory Pointing Outside Project Root

Bug Reports
1

Bug Report: Codebase Index Does Not Include Files Within Symlinked Directory Pointing Outside Project Root

Summary:
Cursor’s ‘Codebase Index’ feature fails to index files contained within a symbolic link directory when the symlink’s target resides outside the main project workspace folder. This occurs even when the search.followSymlinks setting is enabled, files within the symlink are searchable via standard file search, and the target files are confirmed to be locally available (not cloud-only placeholders). Other files of the same type (e.g., Markdown) located directly within the project are indexed correctly.

Environment:

  • OS: Windows 11 (User environment: win32 10.0.26100)
  • Cursor Version: [Specify your Cursor version if known]
  • Relevant Settings:
    • search.followSymlinks: true
    • files.watcherExclude: Confirmed no relevant exclusions for the project path or the symlink target path.
  • Filesystem Details: The symlink target in this case points to a folder managed by Google Drive for Desktop (configured in Stream mode, with the target folder marked ‘Available offline’ and files confirmed locally present).

Steps to Reproduce:

  1. Create a project directory (e.g., C:\Project).
  2. Create a separate directory outside the project containing source/documentation files (e.g., Markdown files in G:\SharedDocs\DocsFolder). Ensure these files are physically present locally if using a cloud sync tool like Google Drive.
  3. Within the project directory, create a symbolic link pointing to the external directory:
    # Example using PowerShell on Windows
cd C:\Project
New-Item -ItemType SymbolicLink -Path ".\linked_docs" -Target "G:\SharedDocs\DocsFolder"
  4. Open C:\Project in Cursor.
  5. Ensure the search.followSymlinks setting is true in Cursor’s settings.
  6. Allow Cursor to build/rebuild its codebase index.
  7. Attempt to use features reliant on the codebase index (e.g., @ symbol search for files/symbols within linked_docs, Go to Definition if applicable to file types) for files inside the .\linked_docs directory.
  8. Perform a standard file search (e.g., Ctrl+P or Ctrl+Shift+F) for content or filenames known to be within .\linked_docs.

Expected Behavior:

  • Files within the .\linked_docs symlinked directory should be included in Cursor’s Codebase Index.
  • Features like @ file/symbol search, Go To Definition, etc., should work for content within the symlinked directory, just as they do for files directly within C:\Project.

Actual Behavior:

  • Files within .\linked_docs are not included in the Codebase Index. Features relying on the index do not find or recognize content within this directory.
  • Standard file search does successfully find files and content within .\linked_docs, confirming that basic symlink traversal for search purposes is functional.
  • Other files of the same type located directly within C:\Project are correctly indexed.

Troubleshooting Performed:

  • Verified symlink functions correctly at the OS level (dir .\linked_docs shows target contents).
  • Confirmed search.followSymlinks is true.
  • Checked and confirmed no relevant files.watcherExclude patterns.
  • If applicable (like Google Drive), ensured target files are locally available (‘Available offline’).
  • Triggered manual rebuilds of the Cursor index.

Hypothesis:
The codebase indexing mechanism may have intentional limitations preventing it from indexing filesystem objects outside the primary workspace root, even when symlinks point to them. Alternatively, there might be an issue with how the indexer interacts with specific filesystem characteristics, such as those presented by virtual drives (like Google Drive’s G: drive) via symlinks, which differs from how the standard file search mechanism operates.

Impact:
This prevents the full integration of linked external documentation or shared code components into Cursor’s intelligent features, limiting the effectiveness of codebase-aware navigation and analysis for projects utilizing symlinks to organize resources outside the immediate project directory.

1 Like
2

+1 for this on Mac Os X Sonoma
Cursor version: 0.49.6
It’s annoying because you have to specify it every time, leading to discussions.