ShellCommand
The ShellCommand plugin allows arbitrary shell commands to be run and their output to be sent to buffers or panels. The output can have a syntax associated with it, which makes it possible to build 'modes' that provide complex interactions.
Details
Installs
- Total 22K
- Win 9K
- Mac 7K
- Linux 6K
Dec 6 | Dec 5 | Dec 4 | Dec 3 | Dec 2 | Dec 1 | Nov 30 | Nov 29 | Nov 28 | Nov 27 | Nov 26 | Nov 25 | Nov 24 | Nov 23 | Nov 22 | Nov 21 | Nov 20 | Nov 19 | Nov 18 | Nov 17 | Nov 16 | Nov 15 | Nov 14 | Nov 13 | Nov 12 | Nov 11 | Nov 10 | Nov 9 | Nov 8 | Nov 7 | Nov 6 | Nov 5 | Nov 4 | Nov 3 | Nov 2 | Nov 1 | Oct 31 | Oct 30 | Oct 29 | Oct 28 | Oct 27 | Oct 26 | Oct 25 | Oct 24 | Oct 23 | Oct 22 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Windows | 1 | 0 | 1 | 1 | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 3 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 3 | 2 | 1 | 0 | 1 | 1 | 2 | 1 | 2 |
Mac | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 2 | 0 | 0 | 0 | 0 | 1 | 3 | 0 | 0 | 1 | 2 | 1 | 0 | 0 | 0 | 1 | 0 |
Linux | 0 | 0 | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 1 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 0 | 0 | 1 | 0 |
Readme
- Source
- raw.githubusercontent.com
Introduction
The ShellCommand
plugin allows arbitrary shell commands to be run and their output to be sent to buffers or panels.
It can:
- run pretty much any shell command, either typed into a prompt or configured in key bindings and commands;
- the output from a command is directable to either a new buffer or a panel;
- subsequent commands can cause other panels to re-run their commands, i.e., to 'refresh' themselves;
- the output of a shell command can be controlled by any syntax definition.
These features can be combined together to create apps or modes. To see a full example of how this can be done, see the Git Mode plugin, which provides an interface to Git, entirely implemented using key bindings, syntax definitions and calls to ShellCommand
.
Motivation
Whilst working on a number of Emacs-style extensions for Sublime it became clear that much of the functionality of extensions such as dired
and magit
required little more than the ability to move from one buffer to another, invoking commands based on context on the way.
For example, dired
shows a list of files and directories, and then allows users to interact with those files by selecting items in the buffer and pressing some key combinations. This way files and directories can be opened, renamed, deleted, zipped up, compared, and so on.
Similarly, the incredibly useful magit
firstly shows the status of a Git repo and then allows files to be staged, unstaged, committed and diffed, whilst branches can be switched between, rebased, merged, pushed, pulled and more.
So this extension is the factoring out of the core functionality on top of which tools like dired
and magit
can be built. A Sublime-style version of magit
should be available shortly.
Installation
The package is available on Package Control.
Key bindings
The built-in bindings are based on similar functionality for Emacs (see Execute External Command):
alt+!
will show a prompt into which a shell command can be typed;alt+|
will also show a prompt, but will use any selections or text under the cursor (or the current file if nothing is selected) as standard input to the shell command (i.e.,stdin
);ctrl+alt+!
will do the same asalt+!
but instead of sending the result to a new buffer, the result will be placed in the current document at the cursor position;ctrl+alt+|
will do the same asalt+|
but instead of sending the result to a new buffer, the result will overwrite the selected text in the current document (i.e., the text that was used as input to the command);g
in a view that is showing the output of a shell command will cause the command to be run again.
In addition to this it's possible to customise the behaviour for many different scenarios.
Shell Configuration Files
For detailed information about using your shell configuration options see Using a Shell Configuration File.
Commands
There is one command provided in the Command Pallette, which is ShellCommand
. This provides a prompt into which a shell command can be entered. Any selections in the active view will be fed to the command as standard input. If there are no selections then the entire buffer will be passed through.
Configuration Settings
NOTE: Some variable names have hyphens and some underscores. This is because I'm still uncertain about how much to align with the Emacs functionality that this module is based on.
comint-scroll-show-maximum-output
If comint-scroll-show-maximum-output is True
, then scrolling due to arrival of output tries to place the last line of text at the bottom line of the window, so as to show as much useful text as possible. (This mimics the scrolling behavior of many terminals.) The default is False
.
shell-file-name
shell-file-name
provides the name of the shell to use when executing commands. If this value is not set then either the SHELL
or COMSPEC
environment variable is used, depending on whether Sublime Text is running on a Posix or Windows system. If none of these is set then the behaviour is defined by subprocess.Popen()
.
show_success_but_no_output_message
Indicates whether to show a message when the shell command returns no output, or the output is just whitespace. The default value is False
, i.e., no window is created if the command doesn't return anything.
success_but_no_output_message
This is the message to show in the window or panel if the show_success_but_no_output_message
value is set to True
. The default value copies the equivalent from Emacs, i.e., “Shell command succeeded with no output”.
Examples
Note that the following key bindings are for illustrative purposes only.
Prompt for a command on ctrl+enter
[
{
"keys": ["ctrl+enter"],
"command": "shell_command"
}
]
This is the most basic use of the plugin, and will result in a prompt being provided to the user, into which any string can be typed. On pressing [ENTER]
the string will be processed as a shell command and the output will be rendered in a new view. The buffer in the view is read only.
Change the prompt caption and the output window title
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"prompt": "Enter a command",
"title": "My Command"
}
}
]
Using these arguments the caption next to the prompt can be changed, as well as the title of the output view.
Capturing output in a panel
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"prompt": "Enter a command",
"title": "My Command",
"panel": true
}
}
]
Often the output of a command is only required for a short amount of time, in which case a panel might be more appropriate.
Capturing output in the current buffer
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"prompt": "Enter a command",
"title": "My Command",
"target": "point"
}
}
]
Sometimes the output of a command should be inserted into the document being edited. Setting the target
argument to point
achieves this. If there is a region selected then this is overwritten.
Run a specific command
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command": "git status"
}
}
]
To run a particular shell command use the command
parameter.
Prompt the user for parameters
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command": "git checkout -b feature/${branch::Feature Branch} develop"
}
}
]
The branch
variable has a prompt (the string 'Feature Branch'), so the user is asked to provide its value.
If a default value is provided (the second value after the variable name) then this will be placed into the prompt: “json [ { "keys”: [“ctrl+enter”], “command”: “shell_command”, “args”: { “command”: “git checkout -b feature/${branch:new feature:Feature Branch} develop” } } ]
## Predefined variables
There are a number of predefined variables that you can pass to command (eg. current file name, project dir etc.).
|Variable|Value example|
|---|---|
|${file}|/var/www/index.html|
|${file_path}|/var/www|
|${file_name}|index.html|
|${file_extension}|.html|
|${file_base_name}|index|
|${packages}|/home/andrew/.config/sublime-text-3/Packages|
|${project}|/var/www/my-project.sublime-project|
|${project_path}|/var/www|
|${project_name}|my-project.sublime-project|
|${project_extension}|.sublime-project|
|${project_base_name}|my-project|
|${project_folders}|/var/www|
```json
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command": "cat ${file}"
}
}
]
Use cursor selection for input
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command": "ls -al",
"region": "arg"
}
}
]
If the region
option is set to 'arg' then any active selections are appended to the command as arguments. If there are no active selections then the word under the cursor is used. In this example if there were no selections, and no word under the cursor then the ls -al
command would be run as is, most likely giving the contents of the project directory. But if a directory name were under the cursor, or was selected, then its contents would be listed.
[
{
"caption": "Word Count",
"command": "shell_command",
"args": {
"command": "wc -w",
"region": "stdin"
}
}
]
If the region
option is set to 'stdin' then any active selections are piped to the command as standard input (stdin). If there are no active selections then the entire buffer is used. In this example if there were no selections, and no word under the cursor then the wc -w
command would count the number of words in the current buffer.
Providing a common command prefix
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command_prefix": "git",
"prompt": "Git Command"
}
}
]
Sometimes it's useful to provide a command prompt that relates to a specific shell command, and the user would then only need to provide the parameters. This example creates a prompt labelled 'Git Command', into which the user need only type the Git command itself, and any parameters. For example, to run git status
, only status
would need to be entered into the prompt.
Feeding a string of text to a command
[
{
"caption": "Word Count",
"command": "shell_command",
"args": {
"stdin": "A contrived example. The output should be 8",
"command": "wc -w"
}
}
]
To pass a string of text to a command use the stdin
argument.
Applying a syntax definition to the output
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command": "git diff",
"syntax": "Diff",
"title": "Diff"
},
}
]
This will run git diff
against whatever file is selected, and then use the Diff
syntax file (Packages/Diff/Diff.sublime-syntax
) to format the output.
The value of the syntax
property can be a full path to a syntax file, a file name without a path, but with a file extension, or a syntax name without a file extension (as in the above example). If the value specified is not found when treated as a path then ShellCommand
will append a suffix of .sublime-syntax
and try again. If there is still no match, a suffix of .tmLanguage
will be tried, before finally, an error is reported.
Restricting key bindings to a shell command view
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"command": "git diff",
"syntax": "Diff",
"title": "Diff"
},
"context": [{ "key": "setting.ShellCommand" }]
}
]
This is the same command as before – running git diff
on the file that the cursor is pointing at – but this time the command will only work if the view is a ShellCommand
window.
Refreshing the current view
If a shell command is executed whilst in the context of the output of another shell command and the action would affect the first view, then a refresh can be sent after the command has run. This uses the refresh
argument. For example, say a view contains a listing of the working directory created with the following shell command:
[
{
"keys": ["ctrl+enter", "1"],
"command": "shell_command",
"args": {
"command": "ls -al"
}
}
]
If we then have two further shell commands – one that creates a new file, and one that deletes the file whose name is under the cursor – we would want to ensure that the ls
view updates after either of these commands is run. The settings for the two add and delete commands might look like this:
[
{
"keys": ["ctrl+enter", "2"],
"command": "shell_command",
"args": {
"command": "cp README.md tmp",
"refresh": true
}
},
{
"keys": ["ctrl+enter", "3"],
"command": "shell_command",
"args": {
"command": "rm",
"arg_required": true,
"region": "arg",
"refresh": true
}
},
]
Whether to wait for the command to complete
By default long-running commands will update the buffer as and when data is available. For some short commands this can look a little jerky and it might be best to wait for the command to complete before updating the buffer. This can be achieved with the 'wait for completion' flag:
[
{
"keys": ["ctrl+enter"],
"command": "shell_command",
"args": {
"wait_for_completion": true
}
}
]
Changelog
Moved to CHANGELOG.