Virtual Paths

The extension logo is saved as media/logo.png.

A VS Code extension that organizes real project files into a virtual tree, without moving or copying files.

Try it

Open this virtual-paths folder in VS Code and press F5. In the Extension Development Host, open your project. Right-click a real file or folder and choose Virtual Paths: Map File or Folder, enter a virtual path such as Product/Authentication, and choose a color. You can also use the Virtual Explorer view's + button.

Adding the first mapping switches to Virtual Paths, a dedicated folder icon in the Activity Bar. It becomes your main project browser, with only your virtual structure visible. Existing installations with mappings switch once when upgrading to 0.3. Subsequent launches preserve your selected sidebar. Use Virtual Paths: Open Virtual Explorer to return at any time. Refreshing and editing existing mappings preserve expanded/collapsed folders and never switch sidebars. VS Code's built-in Explorer remains available through its usual icon; its Files view cannot be replaced through the public extension API.

The usual Explorer shortcut, Ctrl+Shift+E (Cmd+Shift+E on macOS), opens Virtual Explorer when at least one mapping exists. Removing all mappings restores the normal shortcut. You can override this binding in VS Code's Keyboard Shortcuts settings.

Mapped folders expand into their actual contents. Selecting a file opens the original file, so editing and saving work normally. Map several unrelated folders into a common virtual parent to organize by feature, workflow, or responsibility. The same real folder can appear at multiple virtual paths.

Mappings can nest inside other mapped folders: map real folder B to virtual A, then real folder C to virtual A/D. Expanding A shows B's real contents alongside D, which opens C. Mapping order does not matter. A virtual entry replaces a real entry with the same displayed name; intermediate virtual groups merge with matching real directories.

Right-click a mapping to edit or remove it. Reveal Real Path finds the original in the built-in Explorer. Removing a mapping never deletes files.

Multiple mappings

Use the view menu's New Mapping to create alternative virtual structures such as By feature, Backend, or Tests. Existing mappings stay in Default. New sets start empty and are selected immediately; use + to add mappings to the selected set. When several sets are displayed, adding a mapping asks which set to use.

• Switch Mapping (list icon, Ctrl+Alt+M) opens a quick picker for one set or all sets.
• Next Mapping (down arrow, Ctrl+Alt+PageDown) and Previous Mapping (Ctrl+Alt+PageUp) cycle through sets.
• Show All Mappings (layers icon) stacks sets vertically, each as its own expandable section. Each set keeps its own expansion state, even when virtual paths are identical.
• Right-click a set header to show only that set or delete a named set. Default cannot be deleted.

These shortcuts apply while Virtual Paths has focus. On macOS use Cmd instead of Ctrl. Set selection is remembered locally per workspace folder; the mapping definitions are saved in workspace settings and can be shared. Hiding paths has been removed; old virtualPaths.hiddenPaths settings are ignored and can be deleted.

Drag, reveal, and reuse layouts

Drag files or folders from the regular Explorer into a virtual folder, a mapping header, or empty space to add paths. You can drop several workspace paths together. Dropping ordinary contents from Virtual Paths adds another virtual path to those files or folders. Drag mapped paths or virtual groups within one mapping to relocate their virtual subtree; the real files stay in place. Drop onto a mapping header or empty space to move a path to the virtual root. Conflicting destinations and dropping a path inside itself are rejected. Paths must belong to the same workspace folder; rearranging across different mappings is not supported.

Use Reveal Active File (target icon, Ctrl+Alt+R while the tree has focus) to select the current editor's file in the virtual tree. If necessary, it switches to a mapping that contains the file. It prefers a visible mapping and the most specific mapped source folder.

Right-click a named mapping header to Rename Mapping or Duplicate Mapping. Both commands are also in the view menu for use when a header is not visible. Duplicating copies the complete layout and selects the copy. Default can be duplicated; its reserved name cannot be renamed. Editing a duplicate does not change the original.

Repair, create, and share

• Repair Source Path is available on mapped paths and in the view menu. The view-menu action lists unavailable sources. Select a replacement file or folder inside the same workspace folder; its virtual path and color stay unchanged.
• Right-click a mapped folder or any real folder inside it for New File or New Folder. Enter a single name. The item is created in the real folder, and new files open in the editor. Existing items are never overwritten. Pure virtual groups have no physical creation location.
• Export Mappings in the view menu exports one or all mappings to JSON. The header context menu exports just that mapping. Exports contain layout definitions with relative source paths, not file contents.
• Import Mappings adds layouts to the chosen workspace folder. Existing mappings are preserved; duplicate names get an imported suffix. Imported Default layouts become named mappings. Use Repair Source Path for locations that differ between projects.

Real file and folder actions

Right-click ordinary files and folders inside a mapped folder for Open, Open to the Side, Rename, Move to Trash, Copy, Cut, Copy Path, Copy Relative Path, Reveal in File Manager, and Open in Integrated Terminal. Folder menus also offer Find in Folder and Open in New Window; files support Select for Compare and Compare with Selected. Existing New File and New Folder actions are available on real folders. Rename/move uses VS Code workspace edits; deletion asks for confirmation and requests Trash. If Trash is unavailable (for example on a WSL network share), a separate dialog offers permanent deletion. Cancelling leaves the item in place.

Copy/cut/paste operates within Virtual Paths, including across virtual folders. Paste rejects overwrites and pasting a folder into itself. Multi-selection works for copy, cut, path copying, and deletion. Standard F2, Delete, Ctrl+C/X/V shortcuts apply while the tree has focus and real items are selected (platform equivalents on macOS). Virtual drag-and-drop still edits the layout; Cut/Paste moves real items.

Mapping headers and mapped roots retain their layout controls rather than physical rename/delete commands. Renaming or moving a real folder may leave separately configured sources pointing at the old location; Repair Source Path can reconnect those sources. Third-party Explorer menu contributions and native Explorer clipboard integration are not automatically inherited by a custom tree; use Reveal Real Path for those actions.

Settings reference

Mappings are saved in each workspace folder's .vscode/settings.json, making them shareable with your project. Multi-root workspaces get a separate virtual tree for each root. You can edit settings directly:

{
  "virtualPaths.mappings": [
    { "realPath": "src/features/auth", "virtualPath": "Product/Authentication", "color": "blue" },
    { "realPath": "tests/auth", "virtualPath": "Product/Auth tests", "color": "green" },
    { "realPath": "README.md", "virtualPath": "Reference/Overview", "color": "yellow" }
  ],
  "virtualPaths.mappingSets": [
    {
      "name": "Tests",
      "mappings": [
        { "realPath": "tests", "virtualPath": "Quality/Tests", "color": "green" }
      ]
    }
  ]
}

Real paths are workspace-relative; . maps the workspace root. Virtual paths use / separators. Mapping set names must be unique; Default is reserved for virtualPaths.mappings. Colors are blue, green, yellow, orange, red, purple, or none. Mappings without a color default to blue; existing explicit none values stay uncolored. Edit a mapping to change its color. Shared virtual parents use the first mapping's color.

Colors apply to explicitly mapped paths and virtual groups. Files and folders inside mapped folders keep their normal label colors and icon theme; they do not inherit the mapped root's color. A nested explicitly mapped path has its own color. Direct file mappings also use normal file icons, even when their virtual labels differ from the original filenames. Label colors have defaults for light, dark, and high contrast themes, and can be customized through workbench.colorCustomizations using virtualPaths.blue, etc. Label coloring requires VS Code's Explorer: Decorations Colors setting to be enabled. The built-in Explorer and editor tabs keep their normal colors.

Version 0.3 gives the tree a fresh view registration under its own Virtual Paths Activity Bar entry (alongside Explorer, Source Control, and Extensions). This avoids reusing an older saved placement inside Explorer. Existing mappings and folder expansion settings are preserved. Use Virtual Paths: Open Virtual Explorer if the entry is hidden.

The view supports browsing, opening, creating, renaming, copying, moving and deleting ordinary files and folders. File operations and settings changes refresh the tree automatically. While visible, the tree also checks opened directories every 1.5 seconds to catch missed notifications on network/WSL paths. Returning to the view or window triggers a refresh. External renames of mapped roots leave mappings pointing at their old paths until repaired.

Development and installation

For Linux projects, open the folder through WSL: Reopen Folder in WSL rather than Windows UNC access through \\wsl.localhost. Windows filesystem watchers may fail on those paths. Virtual Paths skips its own native watcher on network shares and uses periodic checks; it cannot repair VS Code's own watcher. Background directory errors appear in Output → Virtual Paths without repeated popups.

If upgrading from the development publisher, uninstall local-dev.virtual-paths and keep Lionheart2007.virtual-paths. Both identities share command and view IDs and must not be enabled together. Your workspace mappings stay in .vscode/settings.json.

After installing an update, run Developer: Reload Window to load new configuration registrations. If creating a set reports that virtualPaths.mappingSets is not registered, reload and retry. When debugging with F5, stop and relaunch the Extension Development Host after manifest changes; restarting only the extension host may leave old configuration contributions loaded.

Requires Node.js 22+ for development and VS Code 1.90+. Run npm install, npm test, then npm run package. Install the generated .vsix with Extensions: Install from VSIX…. Runtime has no npm dependencies. No telemetry or network requests.