38.1 Single Shell Commands
M-! (shell-command) reads a line of text using the minibuffer and executes it as a shell command, in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output appears either in the echo area (if it is short), or in an Emacs buffer named *Shell Command Output*, displayed in another window (if the output is long). The variables resize-mini-windows and max-mini-window-height (see Minibuffer Edit) control when Emacs should consider the output to be too long for the echo area.
For instance, one way to decompress a file named foo.gz is to type M-! gunzip foo.gz RET. That shell command normally creates the file foo and produces no terminal output.
A numeric argument to shell-command, e.g., M-1 M-!, causes it to insert terminal output into the current buffer instead of a separate buffer. By default, it puts point before the output, and sets the mark after the output (but a non-default value of shell-command-dont-erase-buffer can change that, see below). For instance, M-1 M-! gunzip < foo.gz RET would insert the uncompressed form of the file foo.gz into the current buffer.
Provided the specified shell command does not end with ‘&’, it runs synchronously, and you must wait for it to exit before continuing to use Emacs. To stop waiting, type C-g to quit; this sends a SIGINT signal to terminate the shell command (this is the same signal that C-c normally generates in the shell). Emacs then waits until the command actually terminates. If the shell command doesn’t stop (because it ignores the SIGINT signal), type C-g again; this sends the command a SIGKILL signal, which is impossible to ignore.
A shell command that ends in ‘&’ is executed asynchronously, and you can continue to use Emacs as it runs. You can also type M-& (async-shell-command) to execute a shell command asynchronously; this is exactly like calling M-! with a trailing ‘&’, except that you do not need the ‘&’. The default output buffer for asynchronous shell commands is named ‘*Async Shell Command*’. Emacs inserts the output into this buffer as it comes in, whether or not the buffer is visible in a window.
If you want to run more than one asynchronous shell command at the same time, they could end up competing for the output buffer. The option async-shell-command-buffer specifies what to do about this; e.g., whether to rename the pre-existing output buffer, or to use a different buffer for the new command. Consult the variable’s documentation for more possibilities.
If you want the output buffer for asynchronous shell commands to be displayed only when the command generates output, set async-shell-command-display-buffer to nil.
The option async-shell-command-width defines the number of display columns available for output of asynchronous shell commands. A positive integer tells the shell to use that number of columns for command output. The default value is nil that means to use the same number of columns as provided by the shell.
To make the above commands show the current directory in their prompts, customize the variable shell-command-prompt-show-cwd to a non-nil value.
M-| (shell-command-on-region) is like M-!, but passes the contents of the region as the standard input to the shell command, instead of no input. With a numeric argument, it deletes the old region and replaces it with the output from the shell command.
For example, you can use M-| with the gpg program to see what keys are in the buffer. If the buffer contains a GnuPG key, type C-x h M-| gpg RET to feed the entire buffer contents to gpg. This will output the list of keys to the *Shell Command Output* buffer.
The above commands use the shell specified by the variable shell-file-name. Its default value is determined by the SHELL environment variable when Emacs is started. If the file name is relative, Emacs searches the directories listed in exec-path (see Shell).
If the default directory is remote (see Remote Files), the default value is /bin/sh. This can be changed by declaring shell-file-name connection-local (see Connection Variables).
To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. See Communication Coding.
By default, error output is intermixed with the regular output in the output buffer. But if you change the value of the variable shell-command-default-error-buffer to a string, error output is inserted into a buffer of that name.
By default, the output buffer is erased between shell commands, except when the output goes to the current buffer. If you change the value of the option shell-command-dont-erase-buffer to erase, then the output buffer is always erased. Other non-nil values prevent erasing of the output buffer, and—if the output buffer is not the current buffer—also control where to put point after inserting the output of the shell command:
beg-last-out​
Puts point at the beginning of the last shell-command output.
end-last-out​
Puts point at the end of the last shell-command output, i.e. at the end of the output buffer.
save-point​
Restores the position of point as it was before inserting the shell-command output.