| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emacs has commands for passing single command lines to inferior shell processes; it can also run a shell interactively with input and output to an Emacs buffer named `*shell*' or run a shell inside a terminal emulator window.
Run the shell command line cmd and display the output
(shell-command).
Run the shell command line cmd with region contents as input;
optionally replace the region with the output
(shell-command-on-region).
Run a subshell with input and output through an Emacs buffer. You can then give commands interactively.
Run a subshell with input and output through an Emacs buffer. You can then give commands interactively. Full terminal emulation is available.
M-x eshell invokes a shell implemented entirely in Emacs. It is documented in a separate manual. See Eshell: (eshell)Top section `Eshell' in Eshell: The Emacs Shell.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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*', 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 shell-command returns.
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, 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
the gpg program. That program will ignore everything except
the encoded keys, and will output a list of the keys the buffer
contains.
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 `.emacs' file
can override either or both of these default initializations.
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
ignores the 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 section Coding Systems for Interprocess Communication.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To run a subshell interactively, putting its typescript in an Emacs buffer, use M-x shell. This creates (or reuses) a buffer named `*shell*' and runs a subshell with input coming from and output going to that buffer. That is to say, any "terminal output" from the subshell goes into the buffer, advancing point, and any "terminal input" for the subshell comes from text in the buffer. To give input to the subshell, go to the end of the buffer and type the input, terminated by RET.
Emacs does not wait for the subshell to do anything. You can switch windows or buffers and edit them while the shell is waiting, or while it is running a command. Output from the subshell waits until Emacs has time to process it; this happens whenever Emacs is waiting for keyboard input or for time to elapse.
Input lines, once you submit them, are displayed using the face
comint-highlight-input, and prompts are displayed using the
face comint-highlight-prompt. This makes it easier to see
previous input lines in the buffer. See section Using Multiple Typefaces.
To make multiple subshells, you can invoke M-x shell with a prefix argument (e.g. C-u M-x shell), which will read a buffer name and create (or reuse) a subshell in that buffer. You can also rename the `*shell*' buffer using M-x rename-uniquely, then create a new `*shell*' buffer using plain M-x shell. Subshells in different buffers run independently and in parallel.
The file name used to load the subshell is the value of the variable
explicit-shell-file-name, if that is non-nil. Otherwise,
the environment variable ESHELL is used, or the environment
variable SHELL if there is no ESHELL. If the file name
specified is relative, the directories in the list exec-path are
searched; this list is initialized based on the environment variable
PATH when Emacs is started. Your `.emacs' file can override
either or both of these default initializations.
Emacs sends the new shell the contents of the file `~/.emacs_shellname' as input, if it exists, where shellname is the name of the file that the shell was loaded from. For example, if you use bash, the file sent to it is `~/.emacs_bash'. If this file is not found, Emacs tries to fallback on `~/.emacs.d/init_shellname.sh'.
To specify a coding system for the shell, you can use the command C-x RET c immediately before M-x shell. You can also change the coding system for a running subshell by typing C-x RET p in the shell buffer. See section Coding Systems for Interprocess Communication.
Emacs sets the envitonment variable INSIDE_EMACS to t
in the subshell. Programs can check this variable to determine
whether they are running inside an Emacs subshell.
Emacs also sets the EMACS environment variable to t if
it is not already defined. Warning: This environment
variable is deprecated. Programs that check this variable should be
changed to check INSIDE_EMACS instead.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Shell buffers use Shell mode, which defines several special keys attached to the C-c prefix. They are chosen to resemble the usual editing and job control characters present in shells that are not under Emacs, except that you must type C-c first. Here is a complete list of the special key bindings of Shell mode:
At end of buffer send line as input; otherwise, copy current line to
end of buffer and send it (comint-send-input). Copying a line
in this way omits any prompt at the beginning of the line (text output
by programs preceding your input). See section Shell Prompts, for how
Shell mode recognizes prompts.
Complete the command name or file name before point in the shell buffer
(comint-dynamic-complete). TAB also completes history
references (see section Shell History References) and environment variable names.
The variable shell-completion-fignore specifies a list of file
name extensions to ignore in Shell mode completion. The default
setting is nil, but some users prefer ("~" "#" "%") to
ignore file names ending in `~', `#' or `%'. Other
related Comint modes use the variable comint-completion-fignore
instead.
Display temporarily a list of the possible completions of the file name
before point in the shell buffer
(comint-dynamic-list-filename-completions).
Either delete a character or send EOF
(comint-delchar-or-maybe-eof). Typed at the end of the shell
buffer, C-d sends EOF to the subshell. Typed at any other
position in the buffer, C-d deletes a character as usual.
Move to the beginning of the line, but after the prompt if any
(comint-bol-or-process-mark). If you repeat this command twice
in a row, the second time it moves back to the process mark, which is
the beginning of the input that you have not yet sent to the subshell.
(Normally that is the same place--the end of the prompt on this
line--but after C-c SPC the process mark may be in a
previous line.)
Accumulate multiple lines of input, then send them together. This command inserts a newline before point, but does not send the preceding text as input to the subshell--at least, not yet. Both lines, the one before this newline and the one after, will be sent together (along with the newline that separates them), when you type RET.
Kill all text pending at end of buffer to be sent as input
(comint-kill-input). If point is not at end of buffer,
this only kills the part of this text that precedes point.
Kill a word before point (backward-kill-word).
Interrupt the shell or its current subjob if any
(comint-interrupt-subjob). This command also kills
any shell input pending in the shell buffer and not yet sent.
Stop the shell or its current subjob if any (comint-stop-subjob).
This command also kills any shell input pending in the shell buffer and
not yet sent.
Send quit signal to the shell or its current subjob if any
(comint-quit-subjob). This command also kills any shell input
pending in the shell buffer and not yet sent.
Delete the last batch of output from a shell command
(comint-delete-output). This is useful if a shell command spews
out lots of output that just gets in the way. This command used to be
called comint-kill-output.
Write the last batch of output from a shell command to a file
(comint-write-output). With a prefix argument, the file is
appended to instead. Any prompt at the end of the output is not
written.
Scroll to display the beginning of the last batch of output at the top
of the window; also move the cursor there (comint-show-output).
Scroll to put the end of the buffer at the bottom of the window
(comint-show-maximum-output).
Move forward across one shell command, but not beyond the current line
(shell-forward-command). The variable shell-command-regexp
specifies how to recognize the end of a command.
Move backward across one shell command, but not beyond the current line
(shell-backward-command).
Ask the shell what its current directory is, so that Emacs can agree with the shell.
Send text as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password.
Please note that Emacs will not echo passwords by default. If you really want them to be echoed, evaluate the following Lisp expression:
(remove-hook 'comint-output-filter-functions
'comint-watch-for-password-prompt)
|
Continue the shell process. This is useful if you accidentally suspend the shell process.(18)
Discard all control-M characters from the current group of shell output. The most convenient way to use this command is to make it run automatically when you get output from the subshell. To do that, evaluate this Lisp expression:
(add-hook 'comint-output-filter-functions
'comint-strip-ctrl-m)
|
This command truncates the shell buffer to a certain maximum number of
lines, specified by the variable comint-buffer-maximum-size.
Here's how to do this automatically each time you get output from the
subshell:
(add-hook 'comint-output-filter-functions
'comint-truncate-buffer)
|
Shell mode is a derivative of Comint mode, a general-purpose mode for communicating with interactive subprocesses. Most of the features of Shell mode actually come from Comint mode, as you can see from the command names listed above. The special features of Shell mode include the directory tracking feature, and a few user commands.
Other Emacs features that use variants of Comint mode include GUD (see section Running Debuggers Under Emacs) and M-x run-lisp (see section Running an External Lisp).
You can use M-x comint-run to execute any program of your choice in a subprocess using unmodified Comint mode--without the specializations of Shell mode.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A prompt is text output by a program to show that it is ready to
accept new user input. Normally, Comint mode (and thus Shell mode)
considers the prompt to be any text output by a program at the
beginning of an input line. However, if the variable
comint-use-prompt-regexp is non-nil, then Comint mode
uses a regular expression to recognize prompts. In Shell mode,
shell-prompt-pattern specifies the regular expression.
The value of comint-use-prompt-regexp also affects many
motion and paragraph commands. If the value is non-nil, the
general Emacs motion commands behave as they normally do in buffers
without special text properties. However, if the value is nil,
the default, then Comint mode divides the buffer into two types of
"fields" (ranges of consecutive characters having the same
field text property): input and output. Prompts are part of
the output. Most Emacs motion commands do not cross field boundaries,
unless they move over multiple lines. For instance, when point is in
input on the same line as a prompt, C-a puts point at the
beginning of the input if comint-use-prompt-regexp is
nil and at the beginning of the line otherwise.
In Shell mode, only shell prompts start new paragraphs. Thus, a
paragraph consists of a prompt and the input and output that follow
it. However, if comint-use-prompt-regexp is nil, the
default, most paragraph commands do not cross field boundaries. This
means that prompts, ranges of input, and ranges of non-prompt output
behave mostly like separate paragraphs; with this setting, numeric
arguments to most paragraph commands yield essentially undefined
behavior. For the purpose of finding paragraph boundaries, Shell mode
uses shell-prompt-pattern, regardless of
comint-use-prompt-regexp.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Shell buffers support three ways of repeating earlier commands. You can use keys like those used for the minibuffer history; these work much as they do in the minibuffer, inserting text from prior commands while point remains always at the end of the buffer. You can move through the buffer to previous inputs in their original place, then resubmit them or copy them to the end. Or you can use a `!'-style history reference.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Fetch the next earlier old shell command.
Fetch the next later old shell command.
Search backwards or forwards for old shell commands that match regexp.
Fetch the next subsequent command from the history.
Fetch one argument from an old shell command.
Display the buffer's history of shell commands in another window
(comint-dynamic-list-input-ring).
Shell buffers provide a history of previously entered shell commands. To reuse shell commands from the history, use the editing commands M-p, M-n, M-r and M-s. These work just like the minibuffer history commands except that they operate on the text at the end of the shell buffer, where you would normally insert text to send to the shell.
M-p fetches an earlier shell command to the end of the shell buffer. Successive use of M-p fetches successively earlier shell commands, each replacing any text that was already present as potential shell input. M-n does likewise except that it finds successively more recent shell commands from the buffer. C-UP works like M-p, and C-DOWN like M-n.
The history search commands M-r and M-s read a regular expression and search through the history for a matching command. Aside from the choice of which command to fetch, they work just like M-p and M-n. If you enter an empty regexp, these commands reuse the same regexp used last time.
When you find the previous input you want, you can resubmit it by typing RET, or you can edit it first and then resubmit it if you wish. Any partial input you were composing before navigating the history list is restored when you go to the beginning or end of the history ring.
Often it is useful to reexecute several successive shell commands that were previously executed in sequence. To do this, first find and reexecute the first command of the sequence. Then type C-c C-x; that will fetch the following command--the one that follows the command you just repeated. Then type RET to reexecute this command. You can reexecute several successive commands by typing C-c C-x RET over and over.
The command C-c . (comint-input-previous-argument)
copies an individual argument from a previous command, like ESC
. in Bash. The simplest use copies the last argument from the
previous shell command. With a prefix argument n, it copies the
nth argument instead. Repeating C-c . copies from an
earlier shell command instead, always using the same value of n
(don't give a prefix argument when you repeat the C-c .
command).
These commands get the text of previous shell commands from a special history list, not from the shell buffer itself. Thus, editing the shell buffer, or even killing large parts of it, does not affect the history that these commands access.
Some shells store their command histories in files so that you can refer to commands from previous shell sessions. Emacs reads the command history file for your chosen shell, to initialize its own command history. The file name is `~/.bash_history' for bash, `~/.sh_history' for ksh, and `~/.history' for other shells.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Move point to the previous prompt (comint-previous-prompt).
Move point to the following prompt (comint-next-prompt).
Copy the input command which point is in, inserting the copy at the end
of the buffer (comint-copy-old-input). This is useful if you
move point back to a previous command. After you copy the command, you
can submit the copy as input with RET. If you wish, you can
edit the copy before resubmitting it. If you use this command on an
output line, it copies that line to the end of the buffer.
If comint-use-prompt-regexp is nil (the default), copy
the old input command that you click on, inserting the copy at the end
of the buffer (comint-insert-input). If
comint-use-prompt-regexp is non-nil, or if the click is
not over old input, just yank as usual.
Moving to a previous input and then copying it with C-c RET or Mouse-2 produces the same results--the same buffer contents--that you would get by using M-p enough times to fetch that previous input from the history list. However, C-c RET copies the text from the buffer, which can be different from what is in the history list if you edit the input text in the buffer after it has been sent.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Various shells including csh and bash support history references that begin with `!' and `^'. Shell mode recognizes these constructs, and can perform the history substitution for you.
If you insert a history reference and type TAB, this searches the input history for a matching command, performs substitution if necessary, and places the result in the buffer in place of the history reference. For example, you can fetch the most recent command beginning with `mv' with ! m v TAB. You can edit the command if you wish, and then resubmit the command to the shell by typing RET.
Shell mode can optionally expand history references in the buffer
when you send them to the shell. To request this, set the variable
comint-input-autoexpand to input. You can make
SPC perform history expansion by binding SPC to the
command comint-magic-space.
Shell mode recognizes history references when they follow a prompt. See section Shell Prompts, for how Shell mode recognizes prompts.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Shell mode keeps track of `cd', `pushd' and `popd' commands given to the inferior shell, so it can keep the `*shell*' buffer's default directory the same as the shell's working directory. It recognizes these commands syntactically, by examining lines of input that are sent.
If you use aliases for these commands, you can tell Emacs to
recognize them also. For example, if the value of the variable
shell-pushd-regexp matches the beginning of a shell command
line, that line is regarded as a pushd command. Change this
variable when you add aliases for `pushd'. Likewise,
shell-popd-regexp and shell-cd-regexp are used to
recognize commands with the meaning of `popd' and `cd'.
These commands are recognized only at the beginning of a shell command
line.
If Emacs gets confused about changes in the current directory of the subshell, use the command M-x dirs to ask the shell what its current directory is. This command works for shells that support the most common command syntax; it may not work for unusual shells.
You can also use M-x dirtrack-mode to enable (or disable) an alternative and more aggressive method of tracking changes in the current directory.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If the variable comint-scroll-to-bottom-on-input is
non-nil, insertion and yank commands scroll the selected window
to the bottom before inserting. The default is nil.
If comint-scroll-show-maximum-output is non-nil, then
arrival of output when point is at the end tries to scroll the last
line of text to the bottom line of the window, showing as much useful
text as possible. (This mimics the scrolling behavior of most
terminals.) The default is t.
By setting comint-move-point-for-output, you can opt for
having point jump to the end of the buffer whenever output arrives--no
matter where in the buffer point was before. If the value is
this, point jumps in the selected window. If the value is
all, point jumps in each window that shows the Comint buffer. If
the value is other, point jumps in all nonselected windows that
show the current buffer. The default value is nil, which means
point does not jump to the end.
If you set comint-prompt-read-only, the prompts in the Comint
buffer are read-only.
The variable comint-input-ignoredups controls whether successive
identical inputs are stored in the input history. A non-nil
value means to omit an input that is the same as the previous input.
The default is nil, which means to store each input even if it is
equal to the previous input.
Three variables customize file name completion. The variable
comint-completion-addsuffix controls whether completion inserts a
space or a slash to indicate a fully completed file or directory name
(non-nil means do insert a space or slash).
comint-completion-recexact, if non-nil, directs TAB
to choose the shortest possible completion if the usual Emacs completion
algorithm cannot add even a single character.
comint-completion-autolist, if non-nil, says to list all
the possible completions whenever completion is not exact.
Command completion normally considers only executable files.
If you set shell-completion-execonly to nil,
it considers nonexecutable files as well.
You can configure the behavior of `pushd'. Variables control
whether `pushd' behaves like `cd' if no argument is given
(shell-pushd-tohome), pop rather than rotate with a numeric
argument (shell-pushd-dextract), and only add directories to the
directory stack if they are not already on it
(shell-pushd-dunique). The values you choose should match the
underlying shell, of course.
If you want Shell mode to handle color output from shell commands, you can enable ANSI Color mode. Here is how to do this:
(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on) |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To run a subshell in a terminal emulator, putting its typescript in an Emacs buffer, use M-x term. This creates (or reuses) a buffer named `*terminal*', and runs a subshell with input coming from your keyboard, and output going to that buffer.
The terminal emulator uses Term mode, which has two input modes. In line mode, Term basically acts like Shell mode; see Shell Mode.
In char mode, each character is sent directly to the inferior subshell, as "terminal input." Any "echoing" of your input is the responsibility of the subshell. The sole exception is the terminal escape character, which by default is C-c (see section Term Mode). Any "terminal output" from the subshell goes into the buffer, advancing point.
Some programs (such as Emacs itself) need to control the appearance
on the terminal screen in detail. They do this by sending special
control codes. The exact control codes needed vary from terminal to
terminal, but nowadays most terminals and terminal emulators
(including xterm) understand the ANSI-standard (VT100-style)
escape sequences. Term mode recognizes these escape sequences, and
handles each one appropriately, changing the buffer so that the
appearance of the window matches what it would be on a real terminal.
You can actually run Emacs inside an Emacs Term window.
The file name used to load the subshell is determined the same way as for Shell mode. To make multiple terminal emulators, rename the buffer `*terminal*' to something different using M-x rename-uniquely, just as with Shell mode.
Unlike Shell mode, Term mode does not track the current directory by
examining your input. But some shells can tell Term what the current
directory is. This is done automatically by bash version 1.15
and later.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The terminal emulator uses Term mode, which has two input modes. In line mode, Term basically acts like Shell mode; see Shell Mode. In char mode, each character is sent directly to the inferior subshell, except for the Term escape character, normally C-c.
To switch between line and char mode, use these commands:
Switch to line mode. Do nothing if already in line mode.
Switch to char mode. Do nothing if already in char mode.
The following commands are only available in char mode:
Send a literal C-c to the sub-shell.
This is equivalent to C-x char in normal Emacs. For example, C-c o invokes the global binding of C-x o, which is normally `other-window'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Term mode has a page-at-a-time feature. When enabled it makes output pause at the end of each screenful.
Toggle the page-at-a-time feature. This command works in both line and char modes. When page-at-a-time is enabled, the mode-line displays the word `page'.
With page-at-a-time enabled, whenever Term receives more than a
screenful of output since your last input, it pauses, displaying
`**MORE**' in the mode-line. Type SPC to display the next
screenful of output. Type ? to see your other options. The
interface is similar to the more program.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can login to a remote computer, using whatever commands you
would from a regular terminal (e.g. using the telnet or
rlogin commands), from a Term window.
A program that asks you for a password will normally suppress echoing of the password, so the password will not show up in the buffer. This will happen just as if you were using a real terminal, if the buffer is in char mode. If it is in line mode, the password is temporarily visible, but will be erased when you hit return. (This happens automatically; there is no special password processing.)
When you log in to a different machine, you need to specify the type
of terminal you're using, by setting the TERM environment
variable in the environment for the remote login command. (If you use
bash, you do that by writing the variable assignment before the remote
login command, without separating comma.) Terminal types `ansi'
or `vt100' will work on most systems.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Mark Kaminski on July, 3 2008 using texi2html 1.70.