Configuring single and multi root workspaces

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 defined in its devfile (for example, the dashboard’s built-in "Empty Workspace"), the editor opens with an empty Explorer. To automatically open the /projects folder instead, define the OPEN_PROJECTS_ROOT_ON_EMPTY environment variable in your devfile.

         env:
     - name: OPEN_PROJECTS_ROOT_ON_EMPTY
       value: "true"

      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.