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*’, which is displayed in another window
but not selected (if the output is long).
For instance, one way to decompress a file foo.gz from Emacs is to type M-! gunzip foo.gz <RET>. That shell command normally creates the file foo and produces no terminal output.
A numeric argument, as in M-1 M-!, says 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 equivalent of foo.gz into the current buffer.
If the shell command line ends in ‘&’, it runs asynchronously.
For a synchronous shell command,
shell-command returns the
command's exit status (0 means success), when it is called from a Lisp
program. You do not get any status information for an asynchronous
command, since it hasn't finished yet when
You can also type M-& (
async-shell-command) to execute
a shell command asynchronously. This behaves exactly like calling
shell-command with ‘&’, except that you do not need to add
the ‘&’ to the shell command line.
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, meaning insert
the output in the current buffer, it deletes the old region and the
output replaces it as the contents of the region. It returns the
command's exit status, like M-!.
One use for M-| is to run
gpg to see what keys are in
the buffer. For instance, if the buffer contains a GPG key, type
C-x h M-| gpg <RET> to feed the entire buffer contents to
gpg program. That program will ignore everything except
the encoded keys, and will output a list of the keys the buffer
Both M-! and M-| use
shell-file-name to specify
the shell to use. This variable is initialized based on your
SHELL environment variable when Emacs is started. If the file
name is relative, Emacs searches the directories in the list
exec-path; this list is initialized based on the environment
variable PATH when Emacs is started. Your init file can
override either or both of these default initializations (see Init File).
Both M-! and M-| wait for the shell command to complete,
unless you end the command with ‘&’ to make it asynchronous. To
stop waiting, type C-g to quit; that terminates the shell
command with the signal
SIGINT—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
SIGINT signal), type C-g again; this sends
the command a
SIGKILL signal which is impossible to ignore.
Asynchronous commands ending in ‘&’ feed their output into the buffer ‘*Async Shell Command*’. Output arrives in that buffer regardless of whether it is visible in a window.
To specify a coding system for M-! or M-|, use the command C-x <RET> c immediately beforehand. See Communication Coding.
Error output from these commands is normally intermixed with the
regular output. But if the variable
shell-command-default-error-buffer has a string as value, and
it's the name of a buffer, M-! and M-| insert error output
before point in that buffer.