Multi-root workspaces in Visual Studio Code (2023)

You can work with multiple project folders in Visual Studio Code with workspaces that have multiple roots. This can be useful when working on several related projects at the same time. For example, you may have a repository of product documentation that you would like to keep up to date when you update the product source code.

note: If you want to learn more about VS Code's "workspace" concept, you can check this outWhat is a VS Code "workspace"?Unless you explicitly create a multi-root workspace, a "workspace" is just the single root folder of your project.

add folder

It's easy to add another folder to your existing workspace. There are several gestures for adding folders:

Add folder to workspace

Thefile>Add folder to workspaceThe command opens an Open Folder dialog box to select the new folder.

Once a root folder is added, Explorer will show the new folder as the root in File Explorer. You can right-click any of the root folders and use the context menu to add or remove folders.

File Explorer should work and behave as before. You can move files between root folders and use all typical file operation actions provided in context menu and explorer view.

Settings likefiles.excludeare supported for each root folder if configured and for all folders if configured as a global user setting.

drag and drop

You can add folders to a workspace using drag and drop. Drag a folder into File Explorer to add it to the current workspace. You can even select and drag multiple folders.

note: Dragging a single folder into the VS Code editor area still opens the folder in single folder mode. Dragging and dropping multiple folders into the editor area creates a new multi-root workspace.

You can also rearrange folders in the workspace using drag-and-drop.

Multi-select native file open dialogs

Opening multiple folders with your platform's native file open dialog creates a multi-root workspace.

command line --add

Add one or more folders to the last active VS Code instance for a multi-root workspace.

code --add vscode vscode-docs

remove folder

With you can remove a folder from a workspaceRemove folder from workspacecontext menu command.

workspace file

When you add multiple folders, they are initially placed in a titled workspaceUNTITLED WORKSPACEand this name persists until you save the workspace. You don't need to save a workspace until you want it in a permanent location, such as a desktop. B. on your desktop. Unnamed workspaces exist as long as the VS Code instance using them is open. Once you've completely closed an instance with an unnamed workspace, you'll be prompted to save it if you intend to open it again in the future:

When you save your workspace, a.code workspaceFile and the file name are displayed in File Explorer.

Save workspace as...

If you want to move your workspace file to a new location, you can use thefile>Save Workspace AsCommand that automatically sets the correct folder paths relative to the new workspace file location.

Open workspace files

To reopen a workspace, you can:

• Double-click the.code workspacefile in your platform explorer.
• Use thefile>Open workspacecommand and select the workspace file.
• Select the workspace from thefile>Open Recent(⌃R(Windows, LinuxStrg+R)) List.
  • Workspaces have one(Workplace)Suffix to distinguish them from folders.

As well asclose folderWhen a single folder is open in VS Code, there is oneClose workspace(⌘K F(Windows, LinuxCtrl+K F)) command to close the active workspace.

Workspace file schema

The scheme of.code workspaceis pretty easy. You have a set of folders with either absolute or relative paths. Relative paths are better when you want to share workspace files.

You can override the display name of your folders withNameattribute to give folders more meaningful names in Explorer. For example, you could name your project folders like "Product" and "Documentation" to easily identify the contents by folder name:

{ "Binder": [{ // Source code "Name":"Product", "Away":"vscode"},{ // Documents and release notes "Name":"Documentation", "Away":"vscode-docs"},{ // Yeoman extension generator "Name":"extension generator", "Away":"vscode-generator-code"}]}

resulting in the following Explorer display:

As you can see in the example above, you can add comments to your workspace files.

The workspace file can also be workspaceglobal settingsunderIdeasAndRenewal Recommendationsunderextensions, which we will discuss below.

General user interface

Editor

There are few changes to the VS Code UI when using multi-root workspaces, mainly to make files unique between folders. For example, if there is a naming conflict between files in multiple folders, VS Code puts the folder name in the tabbed headers.

If you want to always see the folder displayed in the tabbed header, you can use theworkbench.editor.labelFormat Attitude"medium" or "long" values ​​to show the folder or full paths.

"workbench.editor.labelFormat":"Middle"

VS Code UI like thatEDITORS OPENAndOpen quickly(⌘P(Windows, LinuxCtrl+P)) lists contain the folder name.

If you use oneFile Icon Designand the active theme supports it, you will see a special workspace icon.

Below are the workspace icons from the built-inMinimal (Visual Studio-Code)File Icon Theme:

Seek

VS Code features like global search work across all folders and group search results by folder.

If you have a multi-root workspace open, you can use to search in a single root folder./syntax in theinsert filesCrate. For example when you enter./projekt1/**/*.txt, that will search for all.txtfiles under theproject 1/root directory.

Ideas

If there are multiple root folders in a workspace, it is possible to.vscodeFolder in each root folder that defines the settings to apply to that folder. To avoid setting collisions, only resource settings (file, folder) are applied when using a multi-root workspace. Settings that affect the entire editor (e.g. UI layout) are ignored. For example, two projects cannot both set the zoom level.

User preferences are supported as with single-folder projects, and you can also set global workspace preferences that apply to all folders in your multi-root workspace. Global workspace settings are stored in your.code workspaceFile.

{ "Binder": [{ "Away":"vscode"},{ "Away":"vscode-docs"},{ "Away":"vscode-generator-code"}], "Ideas": { "window.zoomLevel":1, "files.autoSave":"after delay"}}

If you switch from a single folder instance to multiple folders, VS Code adds the appropriate editor-wide settings from the first folder to the new global workspace settings.

You can easily review and change the various settings files through the settings editor. The Settings Editor tabs allow you to choose your user settings, global workspace settings, and individual folder settings.

You can also open specific preference files with the commands:

• Settings: Open user settings- Open your global user settings
• Settings: Open workspace settings- Open the settings area of ​​your workspace file.
• Settings: Open folder settings- Open the settings for the active folder.

Global workspace settings override user settings and folder settings can override workspace or user settings.

Unsupported folder settings

Editor-wide folder settings that are not supported appear grayed out in your folder settings and are filtered out of theDEFAULT SETTINGS FOR FOLDERSList. You will also see an information icon in front of the setting.

Debugging

For multi-root workspaces, VS Code looks in all folderslaunch.jsondebugs configuration files and displays them with the folder name as a suffix. In addition, VS Code also shows launch configurations defined in the workspace configuration file.

The example above shows the debugging configurations for theTSLint extension. There is aStartconfiguration from thetslintextension folder to launch the extension running in the VS Code extension host and also aappendconfiguration from thetslint-serverFolder to attach the debugger to a running TSLint server.

The three can also be seenadd configcommands for the folders,tslint,tslint-server, Andtslint-tests, im vscode-tslintWorkplace. Theadd configCommand opens either an existinglaunch.jsonfile in folder.vscodeSubfolder or create a new one and show the Debug Configuration Template drop-down menu.

variablesused in a configuration (ex${workspaceFolder}or the now obsolete one${workspaceRoot}) are resolved relative to the folder they belong to. It is possible to set one variable per workspace folder by appending the root folder name to a variable (separated by a colon).

Workspace launch configurations

Workspace-related launch configurations live in the"Start"section of the workspace configuration file (Workspaces: Open the workspace configuration filein the command palette):

Alternatively, new launch configurations can be added via the "Add Config (workspace)" entry of the Launch Configuration drop-down menu:

A composite launch configuration can reference the individual launch configurations by name as long as the names are unique within the workspace, for example:

 "Links": [{ "Name":"Start Server & Client", "configurations": [ "Start server", "Start client"]}]

If each launch configuration name is not unique, the qualifying folder can be specified using a more verbose "folder" syntax:

 "Links": [{ "Name":"Start Server & Client", "configurations": [ "Start server",{ "Binder":"Webclient", "Name":"Start client"},{ "Binder":"Desktop-Client", "Name":"Start client"}]}]

In addition tolinks, DieStartThe workspace configuration file section can also contain regular launch configurations. Make sure that all variables used are explicitly mapped to a specific folder, otherwise they will not be valid for the workspace. For more details on explicitly scoped variables, see thevariable reference.

Here is an example of a launch configuration where the program is in a "Program" folder and all files from a "Library" folder should be skipped when stepping:

"Start": { "configurations": [{ "Typ":"Node", "Inquiry":"Start", "Name":"Start test", "Program":"${workspace folder:program}/test.js", "skipFiles": [ "${workspaceFolder:Library}/out/**/*.js"]}]}

Tasks

Similar to how VS Code looks for debugging configurations, VS Code also tries to automatically detect tasks from gulp, grunt, npm and TypeScript project files in all folders in a workspace and look for tasks defined inTasks.jsonfiles. The location of tasks is indicated by a folder name suffix. Note that tasks are defined inTasks.jsonmust be version 2.0.0.

From the TSLint extensionWorkplaceExample above you can see there are twoconfigured tasksout ofTasks.jsonfiles in thetslintAndtslint-testsFolders and numerous auto-detected npm and TypeScript compilersrecognized tasks.

Workspace task configuration

Workspace-related tasks live in the"Tasks"section of the workspace configuration file (Workspaces: Open the workspace configuration filein the command palette). Only"sleeve"And"Procedure"Tasks of type can be defined in the workspace configuration file.

source control

With multi-root workspaces, there is oneSOURCE CONTROL PROVIDERSection that gives you an overview if you have multiple active repositories. These can be contributed by multiple SCM vendors; For example, you can have Git repositories side-by-side with Azure DevOps Server workspaces. If you select repositories in this view, you can see the source control details below.

You can useCtrl+clickorShift+clickto select multiple repositories. Your details will appear as separate areas below.

extensions

If you are an extension author, you can check oursIntroduction of multi-root workspace APIsGuide to learn more about VS Code multi-root workspace APIs and how to make your extension work well in multiple folders.

Below are some of the popular extensions that have adopted the multi-root workspace APIs.

note: If an extension doesn't yet support multiple folders, it will still work in the first folder of your multi-root workspace.

Renewal Recommendations

VS Code supports folder-level extension recommendations through theextensions.jsonfiles under the folder.vscodesubfolders. You can also provide global workspace extension recommendations by adding them to yours.code workspaceFile. You can use the...Extensions: Configure recommended extensions (workspace folder)Command to open your workspace file and add extension IDs ({publisherName}.{extensionName}) to itExtensions.RecommendationsRow.

{ "Binder": [{ "Away":"vscode"},{ "Away":"vscode-docs"}], "extensions": { "Recommendations": ["eg2.tslint","dbaeumer.vscode-eslint","esbenp.prettier-vscode"]}}

Next Steps

• What is a VS Code "workspace"?- More about single folder and multi-root workspaces.
• Debugging- Learn how to set up debugging for your application.
• Tasks- Tasks allow you to run external tools like compilers in VS Code.

Frequently Asked Questions

How can I work with a single project folder again?

You can either close the workspace and open the folder directly, or remove the folder from the workspace.

What do I have to do as an extension author?

See oursIntroduction of multi-root workspace APIsGuide. Most extensions can easily support multi-root workspaces.

2.2.2023