Workspace Config+

Provides additional capabilities to manage your "workspace" configuration settings, including the ability to utilize shared and local versions of the VS Code workspace configuration files.

Note: A VS Code "workspace" is usually just your project root folder. This extension can be immediately used in standard, single root/projects, as well as more advanced, multi-root workspaces. See the VS Code docs What is a VS Code "Workspace"? and Workspace Settings for more information.

Functional, but still in Beta !!!!

Current Features

Adds support for shared and local configuration files (.vscode/*.shared.json, and .vscode/*.local.json)

Shared and Local Configuration Files

With this extension you can now split your project's workspace configuration between shared files that can be checked into version control and shared with other team members, as well as local configuration overrides/extension that are excluded from version control.

It currently supports:

settings.json - (settings.shared.json, settings.local.json)
tasks.json - (tasks.shared.json, tasks.local.json)
launch.json - (launch.shared.json, launch.local.json)

Setup

Be sure your *.local.json files and the main VS Code files are excluded from version control by adding the corresponding entries to your project's ignore file (e.g. .gitignore, .hgignore). For example:

# .gitignore
.vscode/*
!.vscode/*.shared.json

Then just add your desired *.shared.json and/or *.local.json files to your .vscode directory in your workspace folder(s). The extension works with both standard (single root) workspace projects and multi root workspaces.

Enter the values that you want to share with other contributors into the *.shared.json file, and any personal/local overrides and additional settings to the corresponding *.local.json file. The configuration values defined in a *.local.json file will take precedence over any conflicting values defined in the corresponding *.shared.json file.

The extension will re-evaluate and, if necessary, automatically apply any configuration updates any time any supported *.shared.json or *.local.json files are added, modified, or removed, as well as when additional folders are added to a workspace. As such you never have to worry about running any commands!

This extension is not an all-or-nothing proposition. Team members and contributors that want to take advantage of the shared configuration defined in the *.shared.json files only need to have this extension installed and enabled. Any contributor that doesn't want to pull in any of the project's shared configuration can either not install or disable this extension, or they can create a corresponding *.local.json file to override the shared settings.

Settings

Note that currently Workspace Config+ requires you to specify any of the below settings in your "workspace" files, and it doesn't yet support setting them at the user/machine global level.

If you'd like to use these settings to modify the behavior of Workspace Config+ ,then you'll need to add the setting to either settings.local.json or settings.shared.json

`arrayMerge`

Allows you to specify how the extension should handle array-type keys that are defined in multiple places (i.e. in both the *.shared.json and *.local.json))

Default: combine
Supported values: [ combine, overwrite ]

When set to combine, the two array values will be combined in the final result.

For example, if you have the following:

tasks.local.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "My awesome personal task",
      ...
    }
  ]
}

and tasks.shared.json

{
  "version": "0.1.0",
  "foo": "bar",
  "configurations": [
    {
      "name": "Shared Team task [#1](https://github.com/swellaby/vscode-workspace-config-plus/issues/1)",
      ...
    }
  ]
}

The end result in tasks.json that VS Code will see and honor will have both of the tasks defined under the configurations arrays in the shared and local files:

tasks.json

{
  "version": "0.2.0",
  "foo": "bar",
  "configurations": [
    {
      "name": "My awesome personal task",
      ...
    },
    {
      "name": "Shared Team task [#1](https://github.com/swellaby/vscode-workspace-config-plus/issues/1)",
      ...
    }
  ]
}

However, if you change the value of the setting to overwrite, then the overlapping configurations array value in *.local.json will be used instead, producing the below for tasks.json:

{
  "version": "0.2.0",
  "foo": "bar",
  "configurations": [
    {
      "name": "Shared Team task [#1](https://github.com/swellaby/vscode-workspace-config-plus/issues/1)",
      ...
    }
  ]
}

Limitations

All configuration setting values are ultimately stored and persisted in the native VS Code workspace configuration files (e.g. .vscode/settings.json). However, because these features are added via an extension there are some associated limitations and accordingly we'd strongly advise against manually modifying those native files when using the extension, and instead advise managing your configuration in the shared/local files.

You can utilize inline comments in the *.local.json and *.shared.json files, but any comments from those files are not persisted into the native VS Code configuration file.
Any comments added to the native VS Code configuration file (e.g. settings.json) will be lost when any configuration updates are applied based on changes to the local/shared files.
- Some other extensions may automatically add configuration values to the native files with comments, so we'd advise moving any such configuration values to the corresponding *.local.json or *.shared.json file if you'd like to maintain the comments.
The extension does not monitor any changes made to the native VS Code configuration files (e.g. settings.json), so if you manually modify a value in one of those files then that takes precedence with VS Code.
- If you mistakenly modify the native file, the easiest way to trigger this extension to correct the configuration is to modify the corresponding shared or local file (e.g. add a blank line and then save).
This extension only works with the workspace configuration files, and doesn't allow for configuration values to be edited in the VS Code Settings Editor interface.
We've tested and validated the extension with both single and multi-root workspace projects. We have not had a chance to test with VS Code Remote SSH based workspaces, nor browser-based workspaces like GitHub Codespaces. We don't necessarily expect any particular issues in those types of projects, but just haven't been able to test and validate (if you do, and want to test, please let us know!)
Our understanding is that you will not be able to sync your *.local.json files if you are a user of the native VS Code Settings Sync feature. However, the Settings Sync Extension may support synchronizing the *.local.json configuration files too.

Background

VS Code is highly configurable, and allows you to configure specific workspaces in addition to your global user settings.. This includes things like general settings, such as the zoom level, as well as [tasks and launch configurations] amongst others. These configurations are stored in various respective files within the .vscode directory in the workspace. For example, the workspace task configuration is stored in .vscode/tasks.json.

This works fantastically, but unfortunately often poses a challenging question for teams or projects that have more than one author since they have to determine whether or not to track the configuration file(s) in version control. If they include the files in version control then they'll often run into conflicting opinions or even conflicting settings, such as those from extensions which are specific to the developer's local file system. However, if they exclude the files from version control then they give up the ability to share elements that are helpful for other developers and force contributors to manually duplicate part of their setup.

There are some longstanding requests from the VS Code community (microsoft/vscode#40233, microsoft/vscode#37519, microsoft/vscode#15909) to extend the product to address these concerns, and we hope to see a resolution natively within VS Code some day. This extension should help fill the gap in the interim however.

Feedback

Found a bug, have an idea for a new feature, or a question? Please reach out to us on the project GitHub repository by opening an Issue or starting a Discussion!

Like this extension? Please consider starring the repo on GitHub!

You can also share feedback by rating the extension and/or leaving a review on the Marketplace.

Contributing

All contributions are welcomed and appreciated! See the Contributing guide for more information.

License

MIT - see license details here

Code of Conduct

This project follows the standard Code of Conduct as other Swellaby projects, which is the Contributor Covenant