Work with multiple projects in one workspace

With the multi-root workspace feature, you can work with multiple project folders in the same workspace. This is useful when you are working on several related projects at once, such as product documentation and product code repositories.

See What is a VS Code workspace for better understanding and authoring the workspace files.

The workspace is set to open in multi-root mode by default.

Once workspace is started, the /projects/.code-workspace workspace file is generated. The workspace file will contain all the projects described in the devfile.

{
	"folders": [
		{
			"name": "project-1",
			"path": "/projects/project-1"
		},
		{
			"name": "project-2",
			"path": "/projects/project-2"
		}
	]
}

If the workspace file already exist, it will be updated and all missing projects will be taken from the devfile. If you remove a project from the devfile, it will be left in the workspace file.

You can change the default behavior and provide your own workspace file or switch to a single-root workspace.

Procedure

  • Provide your own workspace file.

    • Put a workspace file with the name .code-workspace into the root of your repository. After workspace creation, the Visual Studio Code - Open Source ("Code - OSS") will use the workspace file as it is.

      {
	"folders": [
		{
			"name": "project-name",
			"path": "."
		}
	]
}

      Be careful when creating a workspace file. In case of errors, an empty Visual Studio Code - Open Source ("Code - OSS") will be opened instead.

      If you have several projects, the workspace file will be taken from the first project. If the workspace file does not exist in the first project, a new one will be created and placed in the /projects directory.

  • Specify alternative workspace file.

    • Define the VSCODE_DEFAULT_WORKSPACE environment variable in your devfile and specify the right location to the workspace file.

         env:
     - name: VSCODE_DEFAULT_WORKSPACE
       value: "/projects/project-name/workspace-file"

  • Open a workspace in a single-root mode.

    • Define VSCODE_DEFAULT_WORKSPACE environment variable and set it to the root.

         env:
     - name: VSCODE_DEFAULT_WORKSPACE
       value: "/"

  • Open the projects root folder in empty workspaces.

    • By default, when a workspace has no projects, dependent projects, or starter projects defined in its devfile and no workspace folders are configured (for example, the dashboard’s built-in "Empty Workspace"), the editor opens with an empty Explorer. To automatically open the /projects folder instead, set the workspace.openProjectsRootOnEmpty setting to true in the vscode-editor-configurations ConfigMap.

      Prerequisites

      • You must have an active session with permissions to create ConfigMaps in user namespaces.

      apiVersion: v1
kind: ConfigMap
metadata:
  name: vscode-editor-configurations
data:
  configurations.json: |
    {
      "workspace.openProjectsRootOnEmpty": true
    }

      If the vscode-editor-configurations ConfigMap already exists in your namespace, merge the workspace.openProjectsRootOnEmpty key into the existing configurations.json entry instead of applying this manifest as-is, which would overwrite other settings.

      See Editor configurations for Microsoft Visual Studio Code for details on how to configure the vscode-editor-configurations ConfigMap.

      This setting only applies when the workspace has no projects, dependent projects, or starter projects defined. Workspaces that already have folders configured are not affected.
      Verification

      Restart the workspace and confirm that the Explorer opens the /projects folder.