Support Settings for Multi root workspaces

[sandy081]

This is an umbrella item for support Settings for Multi root workspaces

• Support reading configuration in multi root set up
• Support writing configuration in multi root set up
• Distinguish workspace and folder scoped settings
• Provisional API for reading configurations in multi root context

[sandy081]

Configuration editing (internal API) takes now scopes as an additional option. Scopes are -

• resource: Write configuration into resource scope
• overrideIdentifier - Write configuration into overrideIdentifier scope

Given a resource scope, following is the support

• Selecting WORKSPACE target, will write the configuration into appropriate root folder of the resource. Invalidates when there is no workspace.
• Selecting USER target, will write the configuration into User settings

[sandy081]

@Microsoft/vscode

Here is the strategy of how settings are applied in a Multi-root workspace.

Classification

In a multi root workspace, settings come from following locations

• Default
• User
• Workspace
• Folder

How does settings coming from a Folder are applied?

We cannot apply folder settings on a workbench level because, a setting can have a value in several root folders and it is not obvious to pick a value. Hence, we classified settings into following scopes

• Workspace: Applicable to Workspace. Eg: window.zoomLevel
• Folder: Applicable to Folder. Eg: editor.lineNumbers

Folder scoped settings are subset of Workspace scoped settings. It means editor.lineNumbers is available at Workspace and Folder levels where as window.zoomLevel is only available at Workspace.

Look up Strategy

We follow bubble-up strategy to fetch a value of a setting. Here is the bubble up walk through order we take for

Folder Scoped Setting

Folder -> Workspace -> User -> Default.

We first look for the setting in Folder settings, if found we take that value. Otherwise,
Look in Workspace Settings, if found we take that value. Otherwise,
Look in User Settings, if found we take that value. Otherwise,
Take from Default settings.

Workspace Scoped Setting

Workspace -> User -> Default.

We first look for the setting in Workspace Settings, if found we take that value. Otherwise,
Look in User Settings, if found we take that value. Otherwise,
Take from Default settings.

Merging Strategy

While looking for a value of a setting using bubble-up strategy, we merge following value types, if settings are defined at multiple locations. Other value types are just overridden (Implies, we take value as it is)

• Object

Object Merging Strategy

Explained by following example. Let's assume a setting files.exclude is defined in Workspace and Folder settings.

Workspace:

 "files.exclude": {
    "**/.vscode": true,
    "**/.git": true,
    "**/.svn": true
  }

Folder:

 "files.exclude": {
    "**/.vscode": false,
    "**/subFolder": true
  },

After merging

 "files.exclude": {
    "**/.vscode": false,
    "**/.git": true,
    "**/.svn": true,
    "**/subFolder": true
  }

Questions

1. Where are Workspace settings defined currently?
A. At present source of Workspace settings is the settings in first Root Folder. We exclude Folder scoped settings from the first Root Folder to generate them. But, in case of Single Root, all settings in Root Folder are considered.

2. What settings are scoped to Folder currently?
A. We started with ZERO settings supporting Folder scope. Planning to support following

editor.*
languageOverrides
files.trimTrailingWhitespace
files.insertFinalNewLine
files.encoding
files.autoGuessEncoding
files.exclude??

3. How to define a Folder Scoped setting?
A. Can be defined while registering a setting. Unsure about what property to use. Any ideas are welcome and appreciated.

4. How about Debug and Task configurations?
A. Debug and Tasks are by default considered Folder scoped configurations. As per our design and implementation, these cannot be overridden by Workspace and hence they are taken from the Root Folder as is.

5. Can we define a Folder scoped setting at Workspace level?
A. Yes and No. Conceptually YES, you can do it but be aware not to leak the semantics of folders in the workspace. Technically NO, as we do not yet have separate source for Workspace settings. This can be thought of.

6. What are the changes to Single Root Workspace scenario?
A. NO IMPACT. Because we take all settings in the first Root folder for Workspace settings.

7. Can you explain how an editor setting is applied when files from different root folders are opened?
A. Assume we have two Root folders Folder A (First Root Folder) and Folder B.

Default:

"editor.lineNumbers": "on"

Folder A:

"editor.lineNumbers": "relative"

Folder B:

"editor.lineNumbers": "off"

Line numbers are RELATIVE when a file from Folder A is opened.
Line numbers are OFF when a file from Folder B is opened.

Folder B:

// Nothing defined

Line numbers are ON when a file from Folder B is opened.

8. How about language overrides behave in different folders?
A. Language overrides are not special than other Folder Scoped Settings. So they should work similar to other Folder Scoped Settings as above.

Please provide your opinions and feedback. Thanks.

[roblourens]

At present source of Workspace settings is the settings in first Root Folder. We exclude Folder scoped settings from the first Root Folder to generate them.

So to expand on your example in 7,

Folder A:

"editor.lineNumbers": "relative",
"foo.bar": true // Not a Folder scoped setting

Folder B doesn't override either of these, so the result will be

"editor.lineNumbers": "on", // From Default
"foo.bar": true // Inherited from A

Will it be confusing for some settings to not be inherited? Do you know how a setting will be marked as folder scope for the user?

files.exclude should be folder scoped, also search.exclude.

[bpasero]

@sandy081 good write up 👍 . Your example in 7. makes sense to me but I am unsure how to implement that with our current setup of having a master folder containing the workspace settings.

Today we use the master folder as the container of workspace settings:

• all non-folder-scope settings apply to all root folders
• all folder-scope settings apply to all root folders unless overridden in a root folder

So, your example is not clear to me if Folder A is the first root folder containing workspace settings. In that case I would assume that Folder B is getting the following setting if it does not define it:

"editor.lineNumbers": "relative"

Because that is what Folder A ( = workspace settings) defines.

[bpasero]

After talking to Sandeep, I agree it makes sense to ignore folder settings for now if they appear in the first root folder. We need to think about a new concept of workspace settings when in multi root environment.

[sandy081]

@roblourens Yes agreed, that it is not easy for users to know what is folder scoped and what is not. We need a nice UX story to make it look simple for Users.