Consistency with the use of "workspace"

[jabacchetta]

Problem

Developers don't know what a workspace is. Here's my recent attempt to clear up the confusion.

Confusion

• The recent list widget groups folder workspaces along with .code-workspace workspaces under a "workspace" heading, indicating that everything in that list is a workspace. Then it gives .code-workspace workspaces a "Workspace" suffix, contradicting the header, and indicating that only those workspaces that are associated with a .code-workspace file are true workspaces.

• The first interaction with the term "workspace" for most developers is going to be the workspace settings. This is setting up users for confusion right off the bat. Because a folder's .vscode settings is initially referred to as "Workspace" settings. But when a .code-workspace file is created, .vscode settings becomes "Folder" settings, while the .code-workspace settings becomes the new "Workspace" settings.

• "Open Workspace" is referring to a .code-workspace workspace (with the dialog only allowing a .code-workspace file to be selected). Same goes for "Add Folder to Workspace..." and "Save Workspace As...".

• An extension's "Disable (Workspace)" option is referring to workspace as defined by my definition in the SO post.

Suggestion

NOTE: Suggestions will be updated as discussion in this thread evolves.

• In the recent list widget, create two separate headings: "Workspace" and "Folder". Remove suffixes.
• In settings editor, always refer to specific settings with the same reference. "Workspace" tab for .code-workspace settings. "Folder" tab for .vscode settings.
• "Open Workspace", "Add Folder to Workspace...", and "Save Workspace As..." remain unchanged.
• An extension's context menu will show "Disable (Workspace)" or "Disable (Folder)" depending on which is currently active.
• Optionally, come up with another term when wanting to reference both definitions. Whether it's "Project" or something else. Then it would be acceptable to use "Disable (Project)" in the extension's context menu, for example.

[bpasero]

I think we have to be careful to call this "multi root workspace" because you can easily have just one (or actually no) folder in a workspace file. The use case is still that it allows you to store workspace settings for this folder without polluting the folder with a .vscode folder.

[jabacchetta]

Yeah, naming this will be tough. Although I do think that consistency across the UI is more important than the naming itself.

What about referring to everything as "Projects", and then in the recent list widget, for example, changing the heading to "Projects", and giving those projects a suffix "Workspace" for .code-workspace files and "Folders" for single folder projects?

Same goes for the settings... "Workspace" and "Folder" settings, with "Folder" always being used to refer to settings that exist inside a .vscode folder and "Workspace" always being used to refer to settings that exist in a .code-workspace file (as opposed to changing the naming and creating confusion when a .code-workspace file is created).

And then when enabling/disabling extensions, "enable for this project".

[bpasero]

But why would we introduce something new ("Project") that was never used in VSCode so far at all? I do not want to bring in the notion of projects because the next question will be, what kind of project systems we support etc.

[jabacchetta]

Another option:

In the recent list widget, separate them out into two different headings: "Workspace" and "Folder", and remove suffixes all together.

Again, "Workspace" and "Folder tabs in the settings, with "Folder" always being used for settings coming from the .vscode folder.

For enabling/disabling extensions, I suppose it would need to be dynamic. "Enable for this workspace" when a workspace is opened, and "Enable for this folder" otherwise.

At this point, I'm starting to confuse myself, lol.

[bpasero]

We decided to call both single folders and workspace file the "workspace" you are in. You could name the one "single-folder workspace" and the other "multi-root workspace", but then again, a multi-root workspace can have 0-1 roots too.

[jabacchetta]

What about the UI inconsistencies mentioned above?

• Will suffixes be removed in the recent list widget? If referring to both as "Workspaces", then the .code-workspace projects shouldn't have a "Workspace" suffix that would indicate that only those are workspaces.
• When opening a .code-workspace file, what will settings tabs look like? Will what was once referred to as "workspace" settings become "folder" settings still?
• What will "Open Workspace" menu item become? In other words, it wouldn't make sense to refer to both a single folder project with a .vscode folder and a project that's associated with a .code-workspace file as a Workspace, but then have an option for opening a workspace that only allows you to choose a .code-workspace file.

[bpasero]

"Open Workspace" and "Open Folder" are still there so that we can filter the dialog. With our custom dialog it would probably be possibly to be smarter here.

I refer to @sandy081 for settings.

[jabacchetta]

Yeah, I definitely understand the need to filter the dialog, but again, this is a UI inconsistency that is going to confuse users. At times, both are being referred to as a workspace. At other times, the UI is using the term workspace to refer only to projects associated with a .code-workspace file.

I think, looking through the forum posts that I linked to, it's clear that this has become a confusing issue. Even the answers to those questions are all over the map. And the UI inconsistencies are the biggest cause of this confusion.

[jabacchetta]

Expanding on earlier suggestion:

• In the recent list widget, create two separate headings: "Workspace" and "Folder". Remove suffixes.
• In settings editor, always refer to specific settings with the same reference. "Workspace" tab for .code-workspace settings. "Folder" tab for .vscode settings.
• "Open Workspace", "Add Folder to Workspace...", and "Save Workspace As..." remain unchanged.
• An extension's context menu will show either "Disable (Workspace)" or "Disable (Folder)" depending on which is currently open.
• Optionally, come up with another term when wanting to reference both definitions. Whether it's "Project" or something else. Then it would be acceptable to use "Disable (Project)" in the extension's context menu, for example.

[sandy081]

I agree it makes sense to call settings from a folder always Folder settings which makes it consistent across single folder and multi root folder workspace.

@roblourens FYI

[andrecasal]

I think it would make a lot of intuitive sense to explain that VS Code assumes that any opened folders are an implicit workspace and that we have the ability to create an explicit workspace as a .code-workspace file.

Something like this:
VS Code assumes any opened folders as an implicit workspace and settings for each root folder go inside each root's /.vscode folder. We can also create an explicit workspace as a .code-workspace file which can contain none or more root folders. An explicit workspace .code-workspace file without any root folders can be used to save custom settings, useful for remote development for example, or with multiple root folders where you might have a repository with your product's source code along with the product's documentation which you'd like to keep current. There is no advantage to an explicit workspace .code-workspace file with only one root folder over an implicit workspace that automatically reads settings from the /.vscode folder, however.

I suggest we use implicit workspace and explicit workspace to differentiate between the two use-cases.

[nemchik]

I wouldn't mind to see Project Folders added to Workspaces (where a workspace is the vscode workspace and a project folder gets added to your tree).

With that in mind, some people may choose to run a single project per workspace. That's up to each person to decide how they want their root.

[edburns]

I just submitted a PR to address the documentation side of this issue: microsoft/vscode-docs#3154 . Please consider it.

[vscodebot]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[vscodebot]

🙂 This feature request received a sufficient number of community upvotes and we moved it to our backlog. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[Spenhouet]

While reading the following, keep in mind that I write this to point out my confusion about VS codes "workspace" concept and the term they are using for it.

I just came across this since I opened our project (single folder project) as workspace and my extensions stopped working:

This setting cannot be applied in this workspace. It will be applied when you open the containing workspace folder directly.

That makes absolutely no sense to me.

Why is a single folder project not a workspace?

Why are extensions not working in a workspace?

If this "workspace" concept is so useless, then why is VS code trying to force users to save a workspace file for projects?

Every other IDE I worked with before had such a "workspace" file. But it was always referring to a single folder project. I intuitively expected that this is the same with the VS code workspace, but it is not. It only starts to make sense with multi-root workspaces.

Could someone explain to me how such a multi-root workspace is meant to work? Given multiple different Git projects that should all use the same VS code settings, extensions and launch configs.. how to combine this. Does the multi-root workspace with settings get an independent Git repository? Don't forget that extensions stop working as soon as we start using a workspace...

What a confusing mess.
After googling the above warning message and figuring out what VS code refers to as "workspace", I was sitting here like "what are they doing".

[yozachar]

At UI level I've a suggestion:

If folders could be switched like the servers in Discord (top tabs is also an alternative) I think it will be cool! A default workspace manages the root .code-workspace files.

[MarcosCalvi]

Well, obviously there is a lot of confussion around the concept of Workspace

The only thing that would make sense to me is a workspace has its own launch configurations, git configurations and the opened files you are working on in that workspace so you could have different independent projects in the same window. Switching the workspace in that window would switch the files you are viewing and the configurations you have available. It seems obvious, I don't understand all the confussion.

What do you think of that?

[tamuratak]

Related to microsoft/vscode-docs/issues/3547

[AlbertoFabbri93]

I agree that something should be done in order to clarify the difference between workspace settings and folder settings.

[bpasero]

As a first step I pushed the following changes:

• Windows taskbar will refer to "folders" or "folders & workspaces" when at least 1 workspace was opened
• Recently opened picker will refer to "folders" or "folders & workspaces" when at least 1 workspace was opened

If you never had a workspace open, you will just see this as a result:

In our UX discussion yesterday we feel that separating folders from workspaces in that list is not a good idea because this breaks the support for quickly jumping between the "thing" you had opened most recently.

There is still the question wether we should refer to "Folder" for setting related things or keep using "Workspace" even when a folder is opened. I think this needs a bit more discussion. While I find it easy to argue that the settings editor should talk about "Folder" and not "Workspace" when a folder is opened, I wonder if an action such as Enable All Extensions for this Workspace should really be renamed to Enable All Extensions for this Folder when you are in a folder.

I have similar problems with renaming "Go to symbol in workspace" to "Go to symbol in folder" depending on what is opened tbh.

[bpasero]

After discussing this more in the team, we feel that simply changing "Workspace" to "Folder" everywhere in our UI depending on wether you have folder or a workspace open is more confusing than helpful. For many users that don't care about multi-root workspaces or are simply new to VSCode and only feel comfortable opening folders, a folder really is their workspace.

Also, we cannot control how extensions refer to the workspace depending on context: many extensions already use the term "workspace" for when the user has a folder opened and we would introduce more inconsistency if we changed it in the core of VSCode.

In retrospect, I think we should have probably called "multi root workspaces" in VSCode something different that is not "workspace". We discussed calling it "Project" but then were afraid people would expect VSCode to have a full blown project system (which it does not have).

If there is still a very obvious issue with the use of "workspace" vs "folder", I am happy to fix that (e.g. as I outlined in #77718 (comment)).

Next plan of action:

• review https://stackoverflow.com/questions/44629890/what-is-a-workspace-in-visual-studio-code
• review suggested doc update #77718 Define the term "workspace" vscode-docs#3154
• add a topic to our docs trying to answer our concept of workspace

@jabacchetta as author of this issue, does that make sense?

[andrecasal]

In retrospect, I think we should have probably called "multi root workspaces" in VSCode something different that is not "workspace". We discussed calling it "Project" but then were afraid people would expect VSCode to have a full blown project system (which it does not have).

Making the best possible decisions based on past bad decisions is the path towards the descent to a bloated and poorly explained VS Code. I urge you to think from first principles and don't treat the symptom, but the cause. If, in retrospect, a "multi root workspace" should have been called something else, please call it something else - even if, for a few moments, users will be confused. This will be better for the future of VS Code.

[gjsjohnmurray]

I too would like VS Code core and its documentation to use the term "workspace" only for the thing that gets loaded from a .code-workspace file. The File menu (on Windows at least) already distinguishes well between Folder and Workspace.

If a user (even a new one) opens a folder, then that's what they're working in - a folder. I don't see any benefit in encouraging them to think of a simple folder as something called a workspace. Reserve that term for what were originally called multi-root workspaces.

Yes, there'll be a bit of confusion / pain for some as the terminology evolves, and some extensions might fail to keep up with the change, but I think the end result will be a lot easier to understand for future generations.

[Spenhouet]

I think we should have probably called "multi root workspaces" in VSCode something different that is not "workspace".

@bpasero How about "multi root workspace"?

[bpasero]

@andrecasal @gjsjohnmurray how do you suggest we fix all the extensions that are out there to call their user facing things "workspace" or "folder" depending on wether the user has opened a folder or a workspace? I think that will not be easily possible. If we change something in VSCode (either call it "Folder" or call workspaces "Projects"), we need extensions to update too, no?

@Spenhouet

@bpasero How about "multi root workspace"?

You can have a workspace file opened that has no folder in it, so in theory it is a 0-root workspace, as such "multi root" might be misleading.

[andrecasal]

@andrecasal @gjsjohnmurray how do you suggest we fix all the extensions that are out there to call their user facing things "workspace" or "folder" depending on wether the user has opened a folder or a workspace? I think that will not be easily possible. If we change something in VSCode (either call it "Folder" or call workspaces "Projects"), we need extensions to update too, no?

As developers of VS Code you should do your best to help extension developers, but it's our responsibility, as extension developers, to update according to VS Code, not the other way around.

[bpasero]

Our data shows that the majority of people use VSCode with folders and not with .code-workspace. So we can either make a change that impacts the majority of users (including new users that have not yet learned about .code-workspace) or make a change for the few "power" users that want to leverage .code-workspace.

What if we pushed for a change that only impacts the minority with the goal to make things clear. I.e. refer to .code-workspace workspaces with a different word (that can be a separate discussion) but preserve "Workspace" as the "thing" you open in VSCode. To give an example: imagine the file menu has "Open Folder" and "Open Xyz" and no matter what option you pick, both result in an experience where you have a "workspace" opened with "Workspace Settings" and "Workspace State". In the "folder" case all this state is associated with the ".vscode" folder inside and in the "Xyz" case the state is associated with the "Xyz configuration file".

I feel that route would still resolve the confusion and has minimal impact to the majority of users and/or new users. I also feel that the term "Workspace" is an accepted term for something you work on in VSCode. Imho the confusion only started to emerge when we gave .code-workspace the name "Workspace" too.

[gjsjohnmurray]

@bpasero in other words Folder and Xyz would both be types of Workspace. Yes, this makes sense to me. I think Project works. It's a sufficiently generic term to mean we can still push back if people start saying "but a VS Code Project should do A, B and C as well", with the response "that's not in scope for what we're calling a Project - it's a candidate for an extension".

[bersbersbers]

@bpasero

Imho the confusion only started to emerge when we gave .code-workspace the name "Workspace" too.

Personally, I can confirm this.

I also understand your objection to the "Multi-root workspace", and I can't stop think about calling the .code-workspace a "Workspace collection".

[bpasero]

One thing to keep in mind is that the file extension .code-workspace is something we can probably not change. So if we go with a word such as "Project" it would still be xyz.code-workspace files you open from the file system.

[andrecasal]

The current state of affairs is quite complicated and I believe this problem has been dragging for so long because there isn't a clear definition of what the problem actually is. Allow me to try and shed some light.

Let's clarify a few definitions.

Instance and Folder

Instance is the running VS Code instance where folders are opened.
Folder is the top-level folder opened in VS Code's file explorer.

Types of settings

User type settings apply to all running instances of VS Code.
Instance type settings apply to a running instance of VS Code.
Folder type settings apply to a particular folder.

Cascade of settings

The global settings.json file contains all user, instance and folder type settings.
The .code-workspace file contains instance and folder type settings. These override the global settings.json file.
The /.vscode/settings.json file contains instance and folder type settings. These override the global settings.json file and the .code-workspace file. Instance type settings here only apply if VS Code is in Single Folder Workspace mode - see below.

For example, "workbench.colorCustomizations": {} is an instance setting that makes sense inside /.vscode/settings.json because I might want to change the title bar color to easily distinguish the running instance of VS Code where the client folder is opened from the running instance of VS Code where the server folder is opened.

VS Code Modes

Single Folder Workspace mode is an instance of VS Code where a folder was opened directly (without adding it through the file explorer).

Settings cascade:

1. Global settings.json
2. /.vscode/settings.json. Instance type settings apply.

Implicit Workspace mode is an instance of VS Code where a folder was added/removed from the file explorer (without having opened it directly).

Settings cascade:

1. Global settings.json
2. /.vscode/settings.json. Instance type settings do not apply.

Explicit Workspace mode is an instance of VS Code with zero or more referenced folders in a .code-workspace file.

Settings cascade:

1. Global settings.json
2. .code-workspace
3. /.vscode/settings.json. Instance type settings do not apply.

An Implicit Workspace with a single opened folder and a Single Folder Workspace are essentially the same thing - an instance of VS Code with a single folder opened in the explorer. But they work differently. In the latter, instance type settings in /.vscode/settings.json no longer apply. And you have to be incredibly careful to not transform a Single Folder Workspace into an Implicit Workspace.

Suggestion

The global settings.json file can contain user, instance and folder type settings.
The .code-workspace file can contain instance and folder type settings. These override the global settings.json file.
Detect a new folder/settings.json file that can contain instance and folder type settings. These override the global settings.json file and the .code-workspace file.
The folder/.vscode/settings.json file can only contain folder type settings. These override all others.

Please notice that all this discussion was had without using the concept of "workspace" except to distinguish between VS Code modes - but those could have easily been called mode A, B and C. The reason for not using the concept of workspace is because it isn't a useful concept in this context.

I suggest we do away with the concept altogether.

[bpasero]

I think you don't have to explicitly distinguish Implicit Workspace mode and Explicit Workspace mode, for VSCode they are really the same. We call the former "Untitled Workspaces" (https://code.visualstudio.com/docs/editor/multi-root-workspaces#_workspace-file) and they work like any other workspace you open from a .code.workspace file. The only difference is that we keep the .code-workspace file in the user data directory automatically created for you. When you change workspace settings you will edit them into that .code-workspace file. When you "Save Workspace As..." the contents of this file can be written to a location anywhere on disk, but you are really just copying that untitled workspace to a different place. When you close the window without saving the untitled workspace, we delete it.

I am not sure the term Instance type settings is accurate, because you can have an empty VSCode window with files opened where settings apply and these settings can only come from the global settings.json file. I think the name "Workspace Setting" is very accurate because these settings are active whenever you open a workspace. If that workspace is a "Folder", the settings are defined in .vscode/settings.json and when you open a .code-workspace these settings are defined in that file.

Settings are more complicated than that actually, because individual settings can be folder or language overridable:

• folder: actual settings value is determined by the root folder (this only applies when a .code-workspace file is opened), for example files.exclude
• language: actual settings value is determined by the language mode of the file that is opened (e.g. all editor settings fall into this category)

[aisbergde]

@bpasero it is very useful to read what you write here. And I never would know this if not subscribing to this topic. I can't find this in the VSC documentation, but I think it would be great to find it also there. Could you consider in the team to explain this also in the documentation? Maybe not all details, but users could get a better understanding about settings, folders, untitled and explicit workspace.

[bpasero]

Yes I was planning to update our docs to make this clear.

[bpasero]

We now have a document explaining the concept of workspaces in VS Code: https://code.visualstudio.com/docs/editor/workspaces

If there are no objections, I will go ahead and close this issue. We will link to that document throughout our documentation so that people can easily find it. If you have feedback on the topic, feel free to open a PR for this site at https://github.com/microsoft/vscode-docs/blob/master/docs/editor/workspaces.md

Thanks!

[edburns]

Hello @bpasero thank you so much for this, and in particular for this text:

Note: It is also possible to open VS Code without a workspace. For example, when you open a new VS Code window by selecting a file from your platform's File menu, you will not be inside a workspace. In this mode, some of VS Code's capabilities are reduced but you can still open text files and edit them.

This text will clear up so much confusion and improve the day one experience of old school Java developers used to IDEs. I am also working on a PR to help those old school folks even more. I'll link it here.

[edburns]

@bpasero Here is the promised PR #4288.