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 the ‘ "*Shell Command Output*"’ ( shell-command-buffer-name) buffer (if the
output is long). The variables resize-mini-windows and
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 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 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
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
buffer whose name is the value of shell-command-buffer-name.
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).
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 Per-Connection Local Variables).
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 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.