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
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. It puts point before the output, and sets the mark
after the output. 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
type C-g again; this sends the command a
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
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
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
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).
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.
If you change the value of the variable
shell-command-dont-erase-buffer to a non-
the output buffer is not erased. This variable also controls where to
set the point in the output buffer after the command completes; see the
documentation of the variable for details.