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 the ‘"*Shell
Command Output*"’ (
shell-command-buffer-name) buffer (if the
output is long). The variables
max-mini-window-height (see Editing in the Minibuffer) 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
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 output from asynchronous shell commands, by default, goes into the
‘"*Async Shell Command*"’ buffer
shell-command-buffer-name-async). 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
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-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
to a non-
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
gpg. This will output the list of keys to the
buffer whose name is the value of
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 Running Shell Commands from Emacs).
To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. See Coding Systems for Interprocess Communication.
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
then the output buffer is always erased. Other non-
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:
Puts point at the beginning of the last shell-command output.
Puts point at the end of the last shell-command output, i.e. at the end of the output buffer.
Restores the position of point as it was before inserting the shell-command output.