diff --git a/docs/getstarted/images/settings/activity-bar-hidden.png b/docs/getstarted/images/settings/activity-bar-hidden.png deleted file mode 100644 index a8a9c5a852..0000000000 --- a/docs/getstarted/images/settings/activity-bar-hidden.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:0754bc5ecac86111cd0b8840d5eaca2b325d7c19ebbf1a1ac5e54d20dbe28e7a -size 212680 diff --git a/docs/getstarted/images/settings/color-customization-example.png b/docs/getstarted/images/settings/color-customization-example.png deleted file mode 100644 index 3aacb725d5..0000000000 --- a/docs/getstarted/images/settings/color-customization-example.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:d460b8fc5780b4bffa1fc24abaaa14bbc4ca41ed569981e780e6bb20a455018e -size 74300 diff --git a/docs/getstarted/images/settings/search-for-activity.png b/docs/getstarted/images/settings/search-for-activity.png deleted file mode 100644 index 5291aeaff0..0000000000 --- a/docs/getstarted/images/settings/search-for-activity.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:bf738ca2123b7c61351e22665275ec13a76910fd01329c6e119440cec07667ab -size 192046 diff --git a/docs/getstarted/images/settings/settings-editor-user-tab.png b/docs/getstarted/images/settings/settings-editor-user-tab.png new file mode 100644 index 0000000000..5fbae70e0d --- /dev/null +++ b/docs/getstarted/images/settings/settings-editor-user-tab.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d5c5f90dc5531061e4a8f7316798e4c099f95fa05e4c66e2cfd1a6ab438008e0 +size 53618 diff --git a/docs/getstarted/images/settings/settings-editor-workspace-tab.png b/docs/getstarted/images/settings/settings-editor-workspace-tab.png index 396293128d..a98b82e03e 100644 --- a/docs/getstarted/images/settings/settings-editor-workspace-tab.png +++ b/docs/getstarted/images/settings/settings-editor-workspace-tab.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:624a143736c8db038f5098a07cae4b0b98cce3a45f3ee9f9516a34b44255583a -size 38689 +oid sha256:5d3b665dbbbfbaceefb3d5011bc0942b89b933c84e162e630b1b6fe40d659d06 +size 53833 diff --git a/docs/getstarted/images/settings/settings-modified.png b/docs/getstarted/images/settings/settings-modified.png index 52c5243dbf..69ff41d4a5 100644 --- a/docs/getstarted/images/settings/settings-modified.png +++ b/docs/getstarted/images/settings/settings-modified.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:04e1a344c96f6d3c0f750d3bbc20f1aa46347eaef596f913f678d635f1ed0a1c -size 253644 +oid sha256:88bddb0ce77d0d114e23b83b9ee029b81ebfdb5aac6f2e60e107c6509baa5836 +size 261571 diff --git a/docs/getstarted/settings.md b/docs/getstarted/settings.md index 199a5c1724..0107b4767d 100644 --- a/docs/getstarted/settings.md +++ b/docs/getstarted/settings.md @@ -16,65 +16,73 @@ VS Code provides different scopes for settings: * **User settings** - Settings that apply globally to any instance of VS Code you open. * **Workspace settings** - Settings stored inside your workspace and only apply when the workspace is opened. -In this article, we'll first describe user settings as these are your personal settings for customizing VS Code. Later we'll cover [Workspace settings](#workspace-settings), which will be specific to the project you're working on. +VS Code stores setting values in a settings JSON file. You can change settings values either by editing the settings JSON file or by using the [Settings editor](#settings-editor), which provides a graphical interface to manage settings. -## Settings editor +## User settings -Use the Settings editor to review and change VS Code settings. To open the Settings editor, navigate to **File** > **Preferences** > **Settings**. Alternately, open the Settings editor from the **Command Palette** (`kb(workbench.action.showCommands)`) with **Preferences: Open Settings** or use the keyboard shortcut (`kb(workbench.action.openSettings)`). +User settings are your personal settings for customizing VS Code. These settings apply globally to any instance of VS Code you open. For example, if you set the editor font size to 14 in your user settings, it will be 14 in all instances of VS Code on your computer. -When you open the Settings editor, you can search and discover the settings you are looking for. When you search using the search bar, it not only shows and highlights the settings matching your criteria, but also filter out those which are not matching. This makes finding settings quick and easy. +You can access your user settings in a few ways: -![Filtering settings by searching in the Settings editor](images/settings/settings-search.png) +* Select the **Preferences: Open User Settings** command in the Command Palette (`kb(workbench.action.showCommands)`) +* Select the **User** tab in the [Settings editor](#settings-editor) (`kb(workbench.action.openSettings)`) +* Select the **Preferences: Open User Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`) -Changes to settings are applied directly by VS Code, as you change them. Modified settings are indicated with a blue line, similar to modified lines in the editor. +![Settings editor with User tab highlighted](images/settings/settings-editor-user-tab.png) -In the example below, the Side Bar location and File Icon Theme were changed. +## Workspace settings -![Modified settings in the Settings editor showing blue vertical bars to the left of them](images/settings/settings-modified.png) +Workspace settings are specific to a project and override user settings. If you have specific settings that you want to apply to a specific project, you can use workspace settings. For example, for a backend server project, you might want to set the `files.exclude` setting to exclude the `node_modules` folder from the File Explorer. -The gear icon (**More Actions...** `kb(settings.action.showContextMenu)`) opens a context menu with options to reset a setting to its default value, and to copy the setting ID, copy a JSON name-value pair, or copy the settings URL. +>**Note**: A VS Code "workspace" is usually just your project root folder. You can also have more than one root folder in a VS Code workspace through a feature called [Multi-root workspaces](/docs/editor/multi-root-workspaces.md). Get more info about [VS Code workspaces](/docs/editor/workspaces.md). -![Settings edit gear context menu](images/settings/more-actions-context-menu.png) +VS Code stores workspace settings at the root of the project in a `.vscode` folder. This makes it easy to share settings with others in a version-controlled (for example, Git) project. -> **Tip**: A settings URL enables you to navigate directly to a specific setting in the Settings editor from the browser. The URL is in the format `vscode://settings/`, where `` is the ID of the setting you want to navigate to. For example, to navigate to the `workbench.colorTheme` setting, use the URL `vscode://settings/workbench.colorTheme`. +You can access the workspace settings in a few ways: -### Edit settings +* Select the **Preferences: Open Workspace Settings** command in the Command Palette (`kb(workbench.action.showCommands)`) +* Select the **Workspace** tab in the [Settings editor](#settings-editor) (`kb(workbench.action.openSettings)`) +* Select the **Preferences: Open Workspace Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`) -Each setting can be edited by either a checkbox, an text input field, or a dropdown. Edit the text or select the option you want to change to the desired settings. +![Settings editor with Workspace tab highlighted](images/settings/settings-editor-workspace-tab.png) -![An example setting with a dropdown](images/settings/settings-edit.png) +Not all user settings are available as workspace settings. For example, application-wide settings related to updates and security can not be overridden by Workspace settings. -### Settings groups +## Settings editor -Settings are represented in groups, so that you can navigate to them easily. There is a **Commonly Used** group at the top, which shows popular customizations. +The Settings editor provides a graphical interface to manage both user and workspace settings. To open the Settings editor, navigate to **File** > **Preferences** > **Settings**. Alternately, open the Settings editor from the **Command Palette** (`kb(workbench.action.showCommands)`) with **Preferences: Open Settings** or use the keyboard shortcut (`kb(workbench.action.openSettings)`). -In the following example, the source control settings are focused by selecting **Source Control** in the tree view. +When you open the Settings editor, you can search and discover the settings you are looking for. When you search using the search bar, the Settings editor filters the settings to only show those that match your criteria. This makes finding settings quick and easy. -![Settings editor with the Source Control section of the table of contents selected](images/settings/settings-groups.png) +![Filtering settings by searching in the Settings editor](images/settings/settings-search.png) -> **Note**: VS Code extensions can also add their own custom settings, and those settings are visible under an **Extensions** section. +VS Code applies changes to settings directly as you change them. You can identify settings that you modified by the colored bar on the left of the setting, similar to modified lines in the editor. -## Changing a setting +In the example below, the Side Bar location and File Icon Theme were changed. -As an example, let's hide the [Activity Bar](/docs/getstarted/userinterface.md#basic-layout) from VS Code. You might want to hide the Activity Bar to give the editor a little more room, or if you prefer to open views via the **View** menu or Command Palette. +![Modified settings in the Settings editor showing blue vertical bars to the left of them](images/settings/settings-modified.png) -1. Open the Settings Editor (`kb(workbench.action.openSettings)`) and type "activity" in the search bar. +The gear icon alongside the setting (`kb(settings.action.showContextMenu)`) opens a context menu with options to reset a setting to its default value, and to copy the setting ID, copy a JSON name-value pair, or copy the settings URL. -![Settings editor with 'activity' in the search bar with at least five settings](images/settings/search-for-activity.png) +![Settings edit gear context menu](images/settings/more-actions-context-menu.png) -1. You can further limit the scope to just those settings under the **Appearance** group in the table of contents on the left. There should now be just three settings. +> **Tip**: A settings URL enables you to navigate directly to a specific setting in the Settings editor from the browser. The URL is in the format `vscode://settings/`, where `` is the ID of the setting you want to navigate to. For example, to navigate to the `workbench.colorTheme` setting, use the URL `vscode://settings/workbench.colorTheme`. -1. You can now check and uncheck the **Workbench** > **Activity Bar: Visible** setting to hide and unhide the Activity Bar. Notice that when you have changed the setting value to be different than the default value, you see a blue line to the left. +### Settings groups -![Activity Bar: Visible unchecked and Activity Bar is hidden](images/settings/activity-bar-hidden.png) +Settings are represented in groups, so that you can navigate to related settings quickly. There is a **Commonly Used** group at the top, which shows popular customization settings. -You can always reset a setting to the default value by hovering over a setting to show the gear icon, clicking on the gear icon, and then selecting the **Reset Setting** action. +In the following example, the source control settings are focused by selecting **Source Control** in the tree view. -## Settings editor filters +![Settings editor with the Source Control section of the table of contents selected](images/settings/settings-groups.png) + +> **Note**: VS Code extensions can also add their own custom settings, and those settings are visible under an **Extensions** section. + +### Settings editor filters The Settings editor search bar has several filters to make it easier to manage your settings. To the right of the search bar is a filter button with a funnel icon that provides options to easily add a filter to the search bar. -### Modified settings +#### Modified settings To check which settings you have configured, there is a `@modified` filter in the search bar. A setting shows up under this filter if its value differs from the default value, or if its value is explicitly set in the respective settings JSON file. @@ -82,7 +90,7 @@ This filter can be useful if you have forgotten whether you configured a setting ![Settings editor with @modified filter showing changed settings](images/settings/modified-filter-settings.png) -### Other filters +#### Other filters There are several other handy filters to help with searching through settings. Type the `@` symbol in the search bar to discover the different filters. @@ -112,9 +120,13 @@ You can also review an extension's settings from the Extensions view (`kb(workbe Extension authors can learn more about adding custom settings in the [configuration contribution point documentation](/api/references/contribution-points.md#contributes.configuration). -## settings.json +## Settings JSON file -VS Code stores setting values in a `settings.json` file. The Settings editor is the user interface that enables you to review and modify setting values that are stored in a `settings.json` file. You can also review and edit this file directly by opening it in the editor with the **Preferences: Open User Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`). Settings are written as JSON by specifying the setting ID and value. +VS Code stores setting values in a `settings.json` file. The Settings editor is the user interface that enables you to review and modify setting values that are stored in a `settings.json` file. + +You can also review and edit the `settings.json` file directly by opening it in the editor with the **Preferences: Open User Settings (JSON)** or **Preferences: Open Workspace Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`). + +Settings are written as JSON by specifying the setting ID and value. You can quickly copy the corresponding JSON name-value pair for a setting by selecting the setting's gear icon in the Settings editor, and then selecting the **Copy Setting as JSON** action. ![User settings.json open in the editor](images/settings/settings-json-in-editor.png) @@ -126,61 +138,31 @@ Some settings can only be edited in `settings.json` such as **Workbench: Color C ![Workbench: Color Customizations setting with Edit in settings.json link](images/settings/edit-in-settings-json-link.png) -### Changing settings.json - -As an example, lets change the editor line number color. Select the **Edit in settings.json** link and add the following JSON: - -```json - "workbench.colorCustomizations": { - "editorLineNumber.foreground": "#00ff00" - } -``` - -Notice that the line numbers in the editor for the `settings.json` file are now green. - -![settings.json editor with green line numbers](images/settings/color-customization-example.png) - -Remove the `setting(workbench.colorCustomizations)` setting code block to return the line number color to the default. - ->**Note**: The example above changes the editor line number for all [Color Themes](/docs/getstarted/themes.md), but you can tune colors per [specific Color Theme](/docs/getstarted/themes.md#customizing-a-color-theme) or even [create your own Color Theme](/api/extension-guides/color-theme.md#create-a-new-color-theme) extension. - -If you prefer to always work directly with `settings.json`, you can set `"workbench.settings.editor": "json"` so that **File** > **Preferences** > **Settings** and the keybinding `kb(workbench.action.openSettings)` always opens the `settings.json` file and not the Setting editor UI. +> **Tip**: If you prefer to always work directly with `settings.json`, you can set `setting(workbench.settings.editor)` to `json`. Then, **File** > **Preferences** > **Settings** and the keybinding `kb(workbench.action.openSettings)` always open the `settings.json` file and not the Setting editor UI. ### Settings file locations +#### User settings.json location + Depending on your platform, the user settings file is located here: * **Windows** `%APPDATA%\Code\User\settings.json` * **macOS** `$HOME/Library/Application\ Support/Code/User/settings.json` * **Linux** `$HOME/.config/Code/User/settings.json` -### Reset all settings - -While you can reset settings individually via the Settings editor **Reset Setting** command, you can reset all changed settings by opening `settings.json` and deleting the entries between the braces `{}`. Be careful since there is no way to recover your previous setting values. - -## Workspace settings - -Workspace settings are specific to a project and can be shared across developers on a project. Workspace settings override user settings. - ->**Note**: A VS Code "workspace" is usually just your project root folder. Workspace settings as well as [debugging](/docs/editor/debugging.md) and [task](/docs/editor/tasks.md) configurations are stored at the root in a `.vscode` folder. You can also have more than one root folder in a VS Code workspace through a feature called [Multi-root workspaces](/docs/editor/multi-root-workspaces.md). You can learn more in the [What is a VS Code "workspace"?](/docs/editor/workspaces.md) article. +#### Workspace settings.json location -You can edit via the Settings editor **Workspace** tab or open that tab directly with the **Preferences: Open Workspace Settings** command. +The workspace settings file is located under the `.vscode` folder in your root folder. When you add a Workspace Settings `settings.json` file to your project or source control, the settings for the project will be shared by all users of that project. -![Settings editor with Workspace tab highlighted](images/settings/settings-editor-workspace-tab.png) - -All features of the Settings editor such as settings groups, search, and filtering behave the same for Workspace settings. Not all User settings are available as Workspace settings. For example, application-wide settings related to updates and security can not be overridden by Workspace settings. - -### Workspace settings.json location - -Similar to User Settings, Workspace Settings are also stored in a `settings.json` file, which you can edit directly via the **Preferences: Open Workspace Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`). +![The File Explorer displaying settings.json under the .vscode folder](images/settings/settings-json-under-vscode.png) -The workspace settings file is located under the `.vscode` folder in your root folder. +> **Note:** For a [Multi-root Workspace](/docs/editor/multi-root-workspaces.md#settings), workspace settings are located inside the workspace configuration file. -![The File Explorer displaying settings.json under the .vscode folder](images/settings/settings-json-under-vscode.png) +## Reset settings ->**Note:** For a [Multi-root Workspace](/docs/editor/multi-root-workspaces.md#settings), workspace settings are located inside the workspace configuration file. +You can always reset a setting to the default value by hovering over a setting to show the gear icon, clicking on the gear icon, and then selecting the **Reset Setting** action. -When you add a Workspace Settings `settings.json` file to your project or source control, the settings for the project will be shared by all users of that project. +While you can reset settings individually via the Settings editor, you can reset all changed settings by opening `settings.json` and deleting the entries between the braces `{}`. Be careful since there is no way to recover your previous setting values. ## Language specific editor settings @@ -245,6 +227,20 @@ You can configure language specific editor settings for multiple languages at on } ``` +## Profile settings + +You can use [profiles in VS Code](/docs/editor/profiles.md) to create sets of customizations and quickly switch between them. For example, they are a great way to customize VS Code for a specific programming language. + +When you switch to a profile, the user settings are scoped to only that profile. When you switch to another profile, the user settings of that other profile are applied. This way, you can have different settings for different profiles. + +If you're using a non-default profile, you notice that there is a **Preferences: Open Application Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`). This command opens the user `settings.json` file that is associated with default profile. + +The user settings JSON file for a profile is located in the following directory: + +* **Windows** `%APPDATA%\Code\User\profiles\\settings.json` +* **macOS** `$HOME/Library/Application\ Support/Code/User/profiles//settings.json` +* **Linux** `$HOME/.config/Code/User/profiles//settings.json` + ## Settings precedence Configurations can be overridden at multiple levels by the different setting scopes. In the following list, **later scopes override earlier scopes**: @@ -303,7 +299,7 @@ If there are conflicting values, such as `editor.selectionBackground` in the exa ### Note about multiple language specific settings -If you are using [multiple language-specific settings](#multiple-languagespecific-editor-settings), be aware that language-specific settings are merged and precedence is set based on the full language string (for example `"[typescript][javascript]"`) and not the individual language IDs (`typescript` and `javascript`). This means that for example, a `"[typescript][javascript]"` workspace setting will not override a `"[javascript]"` user setting. +If you are using [multiple language-specific settings](#multiple-language-specific-editor-settings), be aware that language-specific settings are merged and precedence is set based on the full language string (for example `"[typescript][javascript]"`) and not the individual language IDs (`typescript` and `javascript`). This means that for example, a `"[typescript][javascript]"` workspace setting will not override a `"[javascript]"` user setting. ## Settings and security