Status Buttons for Visual Studio Code

A maintained fork of a fork of a VSCode extension to add customizable buttons to the statusline.

Basic features

The following is the list of core features retained from the original extension:

Execute shell commands
- Predefined variables like ${file} are available for shell commands.
ExecuteVS Code commands
- Any command that can be activated via a keyboard shortcut can be activated via a button.
Customize buttons' text color
Buttons with icons
- Icons can be added to buttons by using the Markdown icons-in-labels syntax. For example, to add an alert icon you include $(alert) in the button name. See https://code.visualstudio.com/api/references/icons-in-labels for more info.

Extended features

The following is the list of core features retained from the fork of the original repository:

Execute commands in an existing terminal without having to spawn a new one for each command.
- Define the terminal name in command option, so that the command will be executed in the existing terminal. If a terminal with that name does not exist it will be created.
Send one or more commands to a terminal with buttons
Optionally clear the terminal before running a command.
Define variables in config options and use them in commands.
- Use these variables in form like ${var}.

Extended Extended features

The following is the list of features added by this fork of the previous fork of this extension:

More icon possibilities (all nerd font symbols are available)
Automatic detection of some icons (NodeJS scripts, VSCode scripts, etc.)
Language-specific buttons; i.e., cargo run only present in Rust projects, gradlew build only present in Gradle projects, etc.
Automatic formatting of NPM scripts (build-local displays as Build Local, etc.)
Default (disableable) buttons for certain projects, such as cargo run, cargo build, etc.
Run all commands in the same terminal by default with no configuration

Configuration

Example

	"actionButtons": {
		"reloadButton": "♻️", // Show a "refresh button"
		"defaultColor": "#ff0034", // CSS-compliant color name or hex
		"loadNpmCommands": false, // Don't generate Node buttons
		"commands": [
			{
				"cwd": "/home/custom_folder",
				"name": "Run Cargo",
				"color": "green",
				"singleInstance": true,
				"command": "cargo run ${file}",
			},
			{
				/* example for esp-idf oriented command */
				"name": "Flash",
				"terminalName": "ESP-IDF 4.4 CMD",
				"color": "red",
				"useVsCodeApi": false,
				"ignoreCwd": true,
				"ignoreClear": true,
				"command": "idf.py -p ${port} flash",
				"extraCommands": [
					"idf.py -p ${port} monitor"
				]
			}
		]
		"customVars": {
			"port": "COM4" /* Can be used in command as `${port}`*/
		}
	}

Options

reloadButton
- Text for reload actions button. Defaults to ↻. Set to null value to enable automatic reload on configuration change, in this case the reload button is disabled.
defaultColor
- Default text color of action buttons. Defaults to white.
loadNpmCommands
- Whether or not to automatically generate action buttons from commands specified in package.json. Defaults to false.
commands
- List of action buttons to add to the status bar. Defaults to []. See Command Options for a list of valid options for each command.
customVars
- List of user defined config options. Defaults to {}. Can be used in commands for terminal in form like ${var}.

Command Options

Required:

name
- Name of the action button. This field is required.
command
- Command to execute when action is activated. This field is required.
- If useVsCodeApi is true, this is the VS Code command to execute. Otherwise, this specifies the command to execute in the terminal.
- Predefined vars like ${file} can be used in commands for terminal. See Config Vars for a list of valid vars.
- User defined config options can be used in commands for terminal. Use these variables in form like ${var}.

Optional:

projectTypes:
- An array of project types for which this button should be present. Defaults to all project types.
color
- Specifies the action button text color. Defaults to defaultColor.
tooltip
- Tooltip text to display when hovering over the button. Defaults to command.
cwd
- Start directory when executing terminal command. Defaults to ${workspaceFolder}. Only valid when useVsCodeApi is false.
- If ignoreCwd is true, the terminal does not receive cmd nor ${workspaceFolder} as start directory and opens in its own start directory.
singleInstance
- Reopen associated terminal each time this action is activated. Defaults to false. Only valid when useVsCodeApi is false.
focus
- Focus the terminal after executing the command. Defaults to false. Only valid when useVsCodeApi is false.
useVsCodeApi
- Specifies whether to execute a VS Code command or terminal command. Defaults to false.
args
- Specifies additional arguments to pass to VS Code command. Only valid when useVsCodeApi is true.
ignoreCwd
- Specifies whether to ignore cwd parameter while creating a terminal. Defaults to false that means cwd is not ignored.
ignoreClear
- Specifies whether to send builtin clear command to the terminal before the user defined command. Defaults to false that means builtin clear is sent before the user defined command.
extraCommands
- Specifies additional commands to be sent to the terminal just after the user defined command. Defaults to [].
- Predefined vars like ${file} can also be used in commands.
- User defined config options can also be used in commands in form like ${var}.
terminalName
- Specifies the terminal name in which the command(s) to be executed. If there is no runnnig terminal with such name than new terminal with name terminalName will be created. Defaults to empty string.
timeoutAfterCreate
- Specifies timeout in milliseconds between creating a new terminal and sending the command(s) to it. If terminal already exists no timeout inserted.

Config Variables

As seen in the previous example, vars such as ${file} can be used. Below is a list of each of them and what they do.

workspaceFolder - the path of the folder opened in VS Code.
workspaceFolderBasename - the name of the folder opened in VS Code without any slashes (/).
file - the current opened file.
relativeFile - the current opened file relative to workspaceFolder.
fileBasename - the current opened file's basename.
fileBasenameNoExtension - the current opened file's basename with no file extension.
fileDirname - the current opened file's dirname.
fileExtname - the current opened file's extension.
cwd - the task runner's current working directory on startup.
lineNumber - the current selected line number in the active file.
selectedText - the current selected text in the active file.
execPath - the path to the running VS Code executable.

vi013t/vscode-status-bar-buttons