Comprehensive Guide to Visual Studio Code Workspaces: From Single Folder to Multi-Root Workspaces

Basic Concepts of Workspaces

In Visual Studio Code, a workspace is a collection of one or more root folders that constitute a project, along with all VS Code configurations specific to that project. These configurations include:

• Specific settings applied when the project is open
• Recommended extensions for the project (particularly useful in team collaboration)
• Project-specific debugging configurations

Types and Differences of Workspaces

VS Code primarily features two types of workspaces: single-folder workspaces and multi-root workspaces.

Single-Folder Workspaces

When you open a folder in VS Code, the system automatically creates a single-folder workspace. At this point, VS Code automatically tracks configuration information, such as open files and editor layout. When you reopen the folder, the editor restores to its previous state.

When you begin modifying editor settings related to the current project, VS Code automatically creates a .vscode folder in the project root directory to store your changes. For example, if you modify settings that apply only to the current project, VS Code creates a settings.json file and stores the changes within it.

Multi-Root Workspaces

Multi-root workspaces are an advanced feature of VS Code that allow you to configure multiple distinct folders as part of the same workspace. In this case, you need to open a .code-workspace file that lists all folders of the workspace.

An example JSON structure for a multi-root workspace is as follows:

{
  "folders": [
    {
      "path": "my-folder-a"
    },
    {
      "path": "my-folder-b"
    }
  ]
}

Detailed Workspace Configuration

Workspace Settings

Workspace settings allow you to configure settings within the context of the opened workspace. Workspace settings always override global user settings. Their storage location depends on whether you opened a folder or a .code-workspace file.

For single-folder workspaces, workspace settings are stored in .vscode/settings.json. For multi-root workspaces, all workspace settings are added to the .code-workspace file.

Tasks and Launch Configurations

Similar to workspace settings, tasks and launch configurations can also be scoped to the workspace. Depending on whether you opened a folder or a .code-workspace file, the location of workspace tasks and launch configurations is either inside the .vscode folder or within the .code-workspace file.

Operations on Workspace Files

Creating .code-workspace Files

To create a .code-workspace file, go to the menu File → Save Workspace As...

Adding Root Folders to a Workspace

To add more folders to a workspace, go to the menu File → Add Folder to Workspace...

Opening .code-workspace Files

To open a workspace defined by a .code-workspace file, go to the menu File → Open Workspace..., or double-click the .code-workspace file.

Viewing .code-workspace File Contents

To view the actual content of a .code-workspace file, go to the menu File → Open... and select the target file, or use the command palette in the opened workspace to search for and select the Workspaces: Open Workspace Configuration File command.

Practical Application Scenarios of Workspaces

Team Collaboration

Workspace configurations are particularly valuable in team collaboration. By defining recommended extensions and project-specific settings within the workspace, you can ensure that team members use the same development environment, reducing issues caused by configuration differences.

Multi-Project Management

For developers who need to work on multiple related projects simultaneously, multi-root workspaces provide a centralized management solution. You can add project folders from different locations to the same workspace, achieving a unified project view and management.

Project Scenario Segmentation

Even when primarily working on single-folder projects, you can use .code-workspace files to create workspace views tailored to different scenarios. For example, you can create separate workspace files for client-side and server-side development, filtering out unrelated folders in the File Explorer.

Confusion in Workspace Terminology

It is worth noting that Visual Studio Code does not consistently use the term "workspace" in the user interface. Sometimes it refers to the workspace concept described above, while other times it specifically refers to projects associated with .code-workspace files.

A typical example is the recent files widget, where all projects are grouped under the same "workspaces" heading, indicating that everything there is a workspace. However, projects with .code-workspace files are given a "Workspace" suffix, contradicting the heading and suggesting that only those files are actual workspaces.

Untitled Multi-Root Workspaces

VS Code supports flexibly adding or removing folders in a workspace. When you add a second folder to a workspace for the first time (unless you have already opened a .code-workspace file), VS Code automatically creates an untitled workspace. In the background, VS Code automatically maintains an untitled .code-workspace file containing all folders and workspace settings from your current session.

There is no functional difference between untitled workspaces and saved workspaces, except that untitled workspaces are automatically created for convenience and will always restore until you save them. When you close a window containing an untitled workspace, VS Code automatically deletes the untitled workspace after asking for confirmation.

Best Practices for Workspaces

When to Use .code-workspace Files

You only need .code-workspace files when creating multi-root workspaces. In this case, you will have a single .code-workspace file that automatically restores all workspace settings and all root folders you want displayed in the File Explorer.

Automated Management for Single-Folder Projects

For single-folder projects, everything is automated. When you open a folder and begin making modifications related to the current project, VS Code automatically handles all configuration storage and management tasks.

Usage of Relative Paths

Since .code-workspace files support relative paths in the folders section, these workspace files are effective for everyone, regardless of where the folders are stored. This makes workspace configurations highly portable in team environments.

Conclusion

The workspace functionality in Visual Studio Code provides developers with powerful project management and environment configuration capabilities. Whether for simple single-folder projects or complex multi-root workspaces, the workspace mechanism helps developers maintain consistent working environments and improve development efficiency. Understanding the different types, configuration methods, and usage scenarios of workspaces is crucial for fully leveraging the powerful features of VS Code.