IntelliSense incorrectly matches file after setting "recursiveIncludes": {"order": "depthFirst"}

[Amy-Li03]

Environment

• OS and Version: Win11 23H2
• VS Code Version: 1.100.0
• C/C++ Extension Version: 1.25.3
• If using SSH remote, specify OS of remote machine: NO

Bug Summary and Steps to Reproduce

Bug Summary:

My workspace have two files of the same name: common.h, one is under root folder->includeA->sub->common.h, the other is under root folder->includeA->common.h:

1. When I setting "recursiveIncludes": {"order": "depthFirst"}, the intelliSense process incorrectly matches the file under root folder->includeA->common.h, it should match the file under root folder->includeA->sub->common.h
2. When I setting "recursiveIncludes": {"order": "breadthFirst"}, the intelliSense process correctly matches the file under root folder->includeA->common.h

Steps to reproduce:

1. Make sure the version of C/C++ extension is updated to 1.25

2. Extract and open attached project with VS code
   Order.zip

3. Add follow code to c_cpp_properties.json and save

      "includePath": [
            "${workspaceFolder}/**"
        ],
        "recursiveIncludes": {
            "order": "depthFirst"
        }
   

4. Open main.cpp file and observe the intelliSense

Expected behavior:

No intelliSense error appears

Configuration and Logs

-------- Diagnostics - 5/13/2025, 4:38:12 PM
Version: 1.25.3
Current Configuration:
{
    "name": "Win32",
    "includePath": [
        "c:/Users/v-amyli3/Desktop/Blog/Order/**"
    ],
    "recursiveIncludes": {
        "order": "depthFirst"
    },
    "defines": [
        "_DEBUG",
        "UNICODE",
        "_UNICODE"
    ],
    "windowsSdkVersion": "10.0.26100.0",
    "cStandard": "c17",
    "cppStandard": "c++17",
    "intelliSenseMode": "windows-msvc-x64",
    "compilerPathIsExplicit": false,
    "cStandardIsExplicit": true,
    "cppStandardIsExplicit": true,
    "intelliSenseModeIsExplicit": true,
    "recursiveIncludesReduceIsExplicit": false,
    "recursiveIncludesPriorityIsExplicit": false,
    "recursiveIncludesOrderIsExplicit": true,
    "mergeConfigurations": false,
    "compilerPath": "C:\\Program Files\\Microsoft Visual Studio\\2022\\Preview\\VC\\Tools\\MSVC\\14.44.35112\\bin\\Hostx64\\x64\\cl.exe",
    "browse": {
        "limitSymbolsToIncludedHeaders": true
    }
}
Additional Tracked Settings:
{
    "editorTabSize": 4,
    "editorInsertSpaces": true,
    "editorAutoClosingBrackets": "languageDefined",
    "filesEncoding": "utf8",
    "filesAssociations": {
        "common.h": "c"
    },
    "filesExclude": {
        "**/.git": true,
        "**/.svn": true,
        "**/.hg": true,
        "**/.DS_Store": true,
        "**/Thumbs.db": true
    },
    "filesAutoSaveAfterDelay": false,
    "editorInlayHintsEnabled": true,
    "editorParameterHintsEnabled": true,
    "searchExclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true
    },
    "workbenchSettingsEditor": "ui"
}
cpptools version (native): 1.25.3.0
Current database path: C:\USERS\V-AMYLI3\APPDATA\LOCAL\MICROSOFT\VSCODE-CPPTOOLS\DA88C543EB5847DDCDE866B37088CE79\.BROWSE.VC.DB
Translation Unit Mappings:
[ C:\Users\v-amyli3\Desktop\Blog\Order\main.cpp - source TU]:
Translation Unit Configurations:
[ C:\Users\v-amyli3\Desktop\Blog\Order\main.cpp ]
    Process ID: 20708
    Memory Usage: 58 MB
    Compiler Path: C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.44.35112\bin\Hostx64\x64\cl.exe
    Include paths:
        system include: C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.44.35112\include
        system include: C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.44.35112\atlmfc\include
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\um
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\ucrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\shared
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\winrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\cppwinrt
        include (recursive): C:\Users\v-amyli3\Desktop\Blog\Order\includeA
    Defines:
        _DEBUG
        UNICODE
        _UNICODE
    Standard Version: ms_c++17
    IntelliSense Mode: windows-msvc-x64
Total Memory Usage: 58 MB

------- Workspace parsing diagnostics -------
Number of files discovered (not excluded): 5032

------- Potential include path issues --------
Some headers exist in multiple locations. If IntelliSense is behaving incorrectly,
try adding one of the alternate paths to the "includePath" in your configuration in
c_cpp_properties.json to override the automatic path discovery for that header.

Using: C:/Users/v-amyli3/Desktop/Blog/Order/includeA/common.h
    Alternative: "C:/Users/v-amyli3/Desktop/Blog/Order/includeA/sub"

Other Extensions

No response

Additional context

No response

[Colengms]

Hi @Amy-Li03 . Technically, depthFirst may be a bit inspecific, as preOrder, inOrder and postOrder tree traversals are all types of "depth-first" traversal. In this case, the depthFirst algorithm used is actually preOrder, in which directories are visited before exploring subdirectories, with each subdirectory's contents visited entirely before advance to the next subdirectory.

depthFirst was used to describe the existing/legacy behavior of this functionality, with breadthFirst added to allow preferring files closer to the root of the include path over files further away from the root, which seems like it may be preferrable for most user. We didn't change the default behavior, to avoid breaking existing working configurations for some users. Both approaches will visit directories prior to exploring their subdirectories.

[Colengms]

Closing a by-design.

In your case, I believe you are matching: includeA/common.h
over: includeA/sub/common.h
... because all contents of includeA will always be visited before any of its subdirectories. However, "includeaA/sub1/a/b/c" would be visited before "includeA/sub2" by default (in depthFirst mode) as sub1 is alphabetically before sub2.

[Amy-Li03]

@Colengms thanks for the detailed explanation, it's clear to me now.