You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/reference/variables-reference.md
+76-68Lines changed: 76 additions & 68 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,63 +7,66 @@ PageTitle: Visual Studio Code Variables Reference
7
7
DateApproved: 02/06/2025
8
8
MetaDescription: Visual Studio Code variable substitution reference
9
9
---
10
-
# Variables Reference
10
+
# Variables reference
11
11
12
-
Visual Studio Code supports variable substitution in [Debugging](/docs/editor/debugging.md) and [Task](/docs/editor/tasks.md) configuration files as well as some select settings. Variable substitution is supported inside some key and value strings in `launch.json` and `tasks.json` files using **${variableName}** syntax.
12
+
Visual Studio Code supports variable substitution in [Debugging](/docs/editor/debugging.md) and [Task](/docs/editor/tasks.md) configuration files, and for some select settings. Variable substitution is supported inside some key and value strings in `launch.json` and `tasks.json` files by using the**${variableName}** syntax.
13
13
14
14
## Predefined variables
15
15
16
16
The following predefined variables are supported:
17
17
18
-
-**${userHome}** - the path of the user's home folder
19
-
-**${workspaceFolder}** - the path of the folder opened in VS Code
20
-
-**${workspaceFolderBasename}** - the name of the folder opened in VS Code without any slashes (/)
21
-
-**${file}** - the current opened file
22
-
-**${fileWorkspaceFolder}** - the current opened file's workspace folder
23
-
-**${relativeFile}** - the current opened file relative to `workspaceFolder`
24
-
-**${relativeFileDirname}** - the current opened file's dirname relative to `workspaceFolder`
25
-
-**${fileBasename}** - the current opened file's basename
26
-
-**${fileBasenameNoExtension}** - the current opened file's basename with no file extension
27
-
-**${fileExtname}** - the current opened file's extension
28
-
-**${fileDirname}** - the current opened file's folder path
29
-
-**${fileDirnameBasename}** - the current opened file's folder name
30
-
-**${cwd}** - the task runner's current working directory upon the startup of VS Code
31
-
-**${lineNumber}** - the current selected line number in the active file
32
-
-**${columnNumber}** - the current selected column number in the active file
33
-
-**${selectedText}** - the current selected text in the active file
34
-
-**${execPath}** - the path to the running VS Code executable
35
-
-**${defaultBuildTask}** - the name of the default build task
36
-
-**${pathSeparator}** - the character used by the operating system to separate components in file paths
37
-
-**${/}** - shorthand for **${pathSeparator}**
38
-
39
-
### Predefined variables examples
40
-
41
-
Supposing that you have the following requirements:
-**${selectedText}**: text selected in your code editor
65
+
-**${execPath}**: location of Code.exe
66
+
-**${pathSeparator}**: `/` on macOS or linux, `\` on Windows
67
+
68
+
> [!TIP]
69
+
> Use IntelliSense inside string values for `tasks.json` and `launch.json` to get a full list of predefined variables.
67
70
68
71
### Variables scoped per workspace folder
69
72
@@ -73,7 +76,7 @@ For example, in a multi root workspace with folders `Server` and `Client`, a `${
73
76
74
77
## Environment variables
75
78
76
-
You can also reference environment variables through the **${env:Name}** syntax (for example, `${env:USERNAME}`).
79
+
You can reference environment variables with the **${env:Name}** syntax. For example, **${env:USERNAME}** references the `USERNAME` environment variable.
77
80
78
81
```json
79
82
{
@@ -88,11 +91,11 @@ You can also reference environment variables through the **${env:Name}** syntax
88
91
89
92
## Configuration variables
90
93
91
-
You can reference VS Code settings ("configurations") through **${config:Name}** syntax (for example, `${config:editor.fontSize}`).
94
+
To reference VS Code settings (_configurations_), use the **${config:Name}** syntax. For example, **${config:editor.fontSize}** references the `editor.fontSize` setting.
92
95
93
96
## Command variables
94
97
95
-
If the predefined variables from above are not sufficient, you can use any VS Code command as a variable through the **${command:commandID}** syntax.
98
+
You can use any VS Code command as a variable with the **${command:commandID}** syntax.
96
99
97
100
A command variable is replaced with the (string) result from the command evaluation. The implementation of a command can range from a simple calculation with no UI, to some sophisticated functionality based on the UI features available via VS Code's extension API. If the command returns anything other than a string, then the variable replacement will not complete. Command variables **must** return a string.
98
101
@@ -111,13 +114,13 @@ An example of this functionality is in VS Code's Node.js debugger extension, whi
111
114
}
112
115
```
113
116
114
-
When using a command variable in a `launch.json` configuration, the enclosing `launch.json` configuration is passed as an object to the command via an argument. This allows commands to know the context and parameters of the specific `launch.json` configuration when they are called.
117
+
When using a command variable in a `launch.json` configuration, the enclosing `launch.json` configuration is passed as an object to the command via an argument. This enables commands to know the context and parameters of the specific `launch.json` configuration when they are called.
115
118
116
119
## Input variables
117
120
118
121
Command variables are already powerful but they lack a mechanism to configure the command being run for a specific use case. For example, it is not possible to pass a **prompt message** or a **default value** to a generic "user input prompt".
119
122
120
-
This limitation is solved with **input variables** which have the syntax: `${input:variableID}`. The `variableID` refers to entries in the `inputs` section of `launch.json` and `tasks.json`, where additional configuration attributes are specified. Nesting of input variables is not supported.
123
+
This limitation is solved with **input variables**, which have the syntax**${input:variableID}**. The `variableID` refers to entries in the `inputs` section of `launch.json` and `tasks.json`, where additional configuration attributes are specified. Nesting of input variables is not supported.
121
124
122
125
The following example shows the overall structure of a `tasks.json` that makes use of input variables:
123
126
@@ -143,30 +146,30 @@ The following example shows the overall structure of a `tasks.json` that makes u
143
146
144
147
Currently VS Code supports three types of input variables:
145
148
146
-
-**promptString**: Shows an input box to get a string from the user.
147
-
-**pickString**: Shows a Quick Pick dropdown to let the user select from several options.
148
-
-**command**: Runs an arbitrary command.
149
+
-**promptString**: shows an input box to get a string from the user.
150
+
-**pickString**: shows a Quick Pick dropdown to let the user select from several options.
151
+
-**command**: runs an arbitrary command.
149
152
150
153
Each type requires additional configuration attributes:
151
154
152
155
`promptString`:
153
156
154
-
-**description**: Shown in the quick input, provides context for the input.
155
-
-**default**: Default value that will be used if the user doesn't enter something else.
156
-
-**password**: Set to true to input with a password prompt that will not show the typed value.
157
+
-**description**: shown in the quick input, provides context for the input.
158
+
-**default**: default value that will be used if the user doesn't enter something else.
159
+
-**password**: set to true to input with a password prompt that will not show the typed value.
157
160
158
161
`pickString`:
159
162
160
-
-**description**: Shown in the quick pick, provides context for the input.
161
-
-**options**: An array of options for the user to pick from.
162
-
-**default**: Default value that will be used if the user doesn't enter something else. It must be one of the option values.
163
+
-**description**: shown in the quick pick, provides context for the input.
164
+
-**options**: an array of options for the user to pick from.
165
+
-**default**: default value that will be used if the user doesn't enter something else. It must be one of the option values.
163
166
164
167
An option can be a string value or an object with both a label and value. The dropdown will display **label: value**.
165
168
166
169
`command`:
167
170
168
-
-**command**: Command being run on variable interpolation.
169
-
-**args**: Optional option bag passed to the command's implementation.
171
+
-**command**: runs a command on variable interpolation.
172
+
-**args**: optional option bag passed to the command's implementation.
170
173
171
174
Below is an example of a `tasks.json` that illustrates the use of `inputs` using Angular CLI:
172
175
@@ -205,7 +208,7 @@ Below is an example of a `tasks.json` that illustrates the use of `inputs` using
The following example shows how to use a user input variable of type `command` in a debug configuration that lets the user pick a test case from a list of all test cases found in a specific folder. It is assumed that some extension provides an `extension.mochaSupport.testPicker` command that locates all test cases in a configurable location and shows a picker UI to pick one of them. The arguments for a command input are defined by the command itself.
211
214
@@ -269,13 +272,13 @@ A consequence of this is that the evaluation of a variable (for example, a comma
269
272
270
273
### Is variable substitution supported in User and Workspace settings?
271
274
272
-
The predefined variables are supported in a select number of setting keys in `settings.json` files such as the terminal `cwd`, `env`, `shell` and `shellArgs` values. Some [settings](/docs/editor/settings.md) like `setting(window.title)` have their own variables:
275
+
The predefined variables are supported in a select number of setting keys in `settings.json` files such as the terminal `cwd`, `env`, `shell` and `shellArgs` values. Some settings like `setting(window.title)` have their own variables:
0 commit comments