Support Hierarchical Folder Structure in VS Code Workspace Explorer

[jolopezl]

VS Code Workspace Folders Flatten Hierarchical Structure in Explorer

Summary

VS Code flattens folder structure in the Explorer panel when using multi-root workspaces (.code-workspace), even if the underlying file system has a hierarchical layout. This breaks expectations for developers working in large codebases where subtrees matter.

---

Reproduction Steps

Given the following file structure:

big-repo/
├── libs/
│   └── core/
│       └── CMakeLists.txt
├── tools/
│   └── analyzer/
│       └── analyze.cpp
├── apps/
│   └── test-runner/
│       └── main.cpp

And a workspace file:

{
  "folders": [
    { "path": "libs/core" },
    { "path": "tools/analyzer" },
    { "path": "apps/test-runner" }
  ]
}

Current Behavior in VS Code

The Explorer shows:

core/
analyzer/
test-runner/

All folders appear as top-level roots, completely flattening the actual tree structure.

---

Expected Behavior

Folders should be shown hierarchically, respecting the full path:

libs/
  core/
tools/
  analyzer/
apps/
  test-runner/

This would better match real-world workflows in large monorepos or platform codebases.

---

Proposal

Extend .code-workspace to support hierarchical folder definitions to infer hierarchy based on path segments.

---

Why This Matters

• Developers in large codebases (e.g. monorepos, embedded platforms) often work on subsets of the project.
• Flattened folders lose the context and structure needed for understanding module ownership.
• File navigation becomes confusing when multiple folders named core, utils, etc. appear at the root level.

---

Final remarks

The current flat folder view for workspaces breaks alignment with the file system and developer mental model. Enabling hierarchical structure would drastically improve usability for large and modular codebases.

[vs-code-engineering]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[jolopezl]

Hi @lramos15,

Follow-up thoughts:

Design Consideration: I’d like to propose an alternative that may align better with VS Code’s existing architecture and user expectations. Rather than changing the semantics of the multi-root workspace or .code-workspace files, it may be more appropriate to introduce a distinct concept — something along the lines of a:

“Sparse Open Folder” mode: A mechanism that allows developers to select a set of subfolders (e.g., libs/core, tools/analyzer) from a larger repository and open them with their true directory hierarchy preserved, without needing to load the entire repository tree or flatten the structure into multiple roots.

This could be implemented as:

• A new command in the Command Palette (e.g., “Sparse Open…”), or
• A dialog-driven UI flow that builds a lightweight root-preserving structure

While a lightweight extension that creates a mirrored structure using symlinks is a possible workaround, in practice I’ve found that symlink-based approaches often break tooling integrations — particularly in environments using Perforce, which is a common choice for large-scale enterprise codebases. This makes a native solution far more robust and sustainable.

The underlying problem remains: developers in large monolithic or modular repositories frequently need to focus on a subset of the codebase, while maintaining the context provided by the folder structure. A sparse open model — distinct from multi-root workspaces — may be a more targeted and extensible way to support this use case.

I’d be interested in your thoughts on whether such a direction might be more consistent with VS Code’s design principles, and whether this idea could evolve into a more formal proposal.

[vs-code-engineering]

This feature request has not yet received the 20 community upvotes it takes to make to our backlog. 10 days to go. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[Spenhouet]

I was really surprised to just find that this is not a thing. As this wasn't mentioned yet, here my suggestion on a solution:

If the name specifies a path like structure e.g. components/backend/endpoint then this will be displayed as a folder hierarchy.

The following code-workspace config

{
  "folders": [
    { "path": "../components/backend/endpoint", "name": "components/backend/endpoint" },
  ]
}

will be displayed as

.
└── components/
    └── backend/
        └── endpoint

This way, none of the underlying VS code logic would need to change, nothing specific to explain to users, but just rendering the files in the explorer differently. This would be hugely appreciated.

The current flat list of all root folders, is hard to use with a project with many included root folders.

[vs-code-engineering]

🙁 In the last 60 days, this feature request has received less than 20 community upvotes and we closed it. Still a big Thank You to you for taking the time to create this issue! To learn more about how we handle feature requests, please see our documentation.

Happy Coding!