What is a 'workspace' in Visual Studio Code?
What is a workspace?
A project that consists of one or more root folders, along with all of the Visual Studio Code configurations that belong to that project. These configurations include:
- settings that should be applied when that project is open
- recommended extensions for the project (useful when sharing the configuration files with colleagues)
- project-specific debugging configurations
Why is a workspace so confusing?
Visual Studio Code does not use the term consistently across the UI (I've opened a GitHub issue to address this). Sometimes it refers to a workspace as described above, and other times it refers to a workspace as a project that is specifically associated with a .code-workspace file.
A good example being the recent files widget. Notice in the linked screenshot that all projects are grouped under the same "workspaces" heading, which would indicate that everything there is a workspace. But then projects with a .code-workspace file are given a "Workspace" suffix, contradicting the heading and indicating that only those files are actually workspaces.
What is a .code-workspace file?
It is a JSON file with comments that stores all of the configuration data mentioned above, in addition to the location of all root folders belonging to a workspace.
Do I need a .code-workspace file?
Only if you're creating a multi-root workspace, in which case you'll have a single .code-workspace file that automatically restores all of the workspace settings, in addition to all of the root folders that you want to be displayed in the Explorer.
What about single folder projects?
Everything is automated.
When you open a folder in Visual Studio Code and start making modifications to the editor that are specifically related to the project you're currently working on, Visual Studio Code automatically creates a .vscode folder and stores it in the root of the project folder that you're working on. This .vscode folder has files that store the changes you made.
For example, if you change Visual Studio Code settings that you want to apply only to your current project, Visual Studio Code creates a settings.json file with those updates, and that file is stored in the .vscode folder.
You can create a .code-workspace file that includes just a single root folder if you really want to. You'd then be able to either open the project folder directly, or open the workspace file. But I can't think of any reason why this would be beneficial.
How do I create a .code-workspace file?
Go to menu File → Save Workspace As...
How do I add root folders to a workspace?
Go to menu File → Add Folder to Workspace....
How do I open a workspace that is defined by a .code-workspace file?
Go to menu File → Open Workspace....
Alternatively, double click the .code-workspace file. Visual Studio Code won't open the actual file. Instead, it will read that file and open the folders that belong to that workspace.
How do I view the actual .code-workspace file?
Go to menu File → Open... and select the target .code-workspace file.
Alternatively, open the workspace associated with that file. Then open the command palette, search for, and select the Workspaces: Open Workspace Configuration File command.
You can save settings at the workspace level and you can open multiple folders in a workspace. If you want to do either of those things, use a workspace, otherwise, just open a folder.
A Visual Studio Code workspace is a list of a project's folders and files. A workspace can contain multiple folders. You can customize the settings and preferences of a workspace.
A workspace is just a text file with a (.code-workspace) extension. You can look at it by opening it with a text editor. I too was frustrated by the idea of a workspace and how it is implemented in Visual Studio Code. I found a method that suits me.
Start with a single "project" folder.
Open Visual Studio Code and close any open workspaces or files or folders. You should see only "OPEN EDITORS" and "NO FOLDER OPENED" in the EXPLORER.
From the menu bar → File → Open Folder.... Navigate to where you want to put your folder and right click to open a new folder. Name it whatever you want, then click on "Select Folder". It will appear in the *Visual Studio Code explorer.
Now from menu File → Save Workspace As.... Name the workspace and save it wherever you want to keep all your workspaces, (not necessarily where your project folders are). I put all mine in a folder called "Visual Studio Code workspace".
It will be saved as a (.code-workspace) file and is just an index to all the files and folders it contains (or points to) wherever they may be on your hard drive. You can look at it by opening it with a text editor. Close the folder you created and close Visual Studio Code.
Now find your workspace "file" and double click on it. This will open Visual Studio Code with the folder you created in your workspace. Or you can open Visual Studio Code and use "Open Workspace".
Any folders you create from within your Visual Studio Code workspace will be inside your first folder. If you want to add any more top level folders, create them first wherever you want them and then use "Add To Workspace.." from Visual Studio Code.
The title and subsequent question in the OP seem to boil down to:
- What is a workspace in Visual Studio Code?
- How do workspace settings work?
Short answer:
A workspace is a virtual collection of folders opened simultaneously in Visual Studio Code and defined in a .code-workspace file. Opening this file will open the collection of folders automatically. This is called a "multi-root" workspace.
The .code-workspace file also defines workspace settings that are used by the instance of Visual Studio Code where the workspace is opened.
When a workspace is not defined, i.e. you open a folder on its own, you can create "workspace settings" that are saved in a .vscode\settings.json file in the root of that folder structure.
In more detail:
Visual Studio Code uses the word "workspace" a little ambiguously in places. The first use to consider is in what is calls a multi-root workspace.
A multi-root workspace is a set of folders (the "roots") that are opened collectively in an instance of Visual Studio Code. There is no need for these folders to share parent folders; indeed that is the point since Visual Studio Code normally uses a single folder in the Explorer side-bar.
A multi-root workspace is defined by a .code-workspace (JSON) file which contains both the list of folders to be included in the workspace and Visual Studio Code settings.
- Multi-root Workspaces
Regarding those workspace settings...
When you open menu File → Preferences → Settings the settings editor is shown. At the very least you should see a USER SETTINGS tab. These are the Visual Studio Code settings that are universal for your user account on your local machine. In Windows these are saved in %APPDATA%\Code\User\settings.json.
- Visual Studio Code Settings File Locations
Individual folders (often each of the "root" folders in a workspace) might have a .vscode folder with their own settings.json file. When opened individually, i.e. not as part of a workspace, the content of these settings.json files is presented under the WORKSPACE SETTINGS tab, and all the settings in that file are used by the running Visual Studio Code instance.
When opening a multi-root workspace things behave differently. Firstly, the WORKSPACE SETTINGS tab shows the options set in the .code-workspace file. Secondly, any folder with a settings.json file will appear under a new FOLDER SETTINGS tab. Be aware that, when in a multi-root workspace, only a limited number of settings from each folder's settings.json are used. I suggest you open the link above to read further.
The main utility of a workspace (and maybe the only one) is to allow to add multiple independent folders that compounds a project. For example:
- WorkspaceProjectX
-- ApiFolder (maybe /usr/share/www/api)
-- DocsFolder (maybe /home/user/projx/html/docs)
-- WebFolder (maybe /usr/share/www/web)
So you can group those in a workspace for a specific project instead of have to open multiple folders windows.
You can learn more here.