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.
There is a shell implemented entirely in Emacs, documented in a separate manual. .
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.
Start the Emacs shell.
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 goes into an Emacs buffer named *Shell Command Output*, which is displayed in another window but not selected. A numeric argument, as in M-1 M-!, directs this command to insert any output into the current buffer. In that case, point is left before the output and the mark is set after the output.
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.
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. If a numeric argument is used, meaning insert the output in the current buffer, then the old region is deleted first and the output replaces it as the contents of the region. It returns the command's exit status when it is called from a Lisp program.
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 does not specify a directory, 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.
Both M-! and M-| wait for the shell command to complete. 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 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.
To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. Section 20.8.
Error output from the command is normally intermixed with the regular output. If you set the variable shell-command-default-error-buffer to a string, which is a buffer name, error output is inserted before point in the buffer of that name.
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. Section 13.1.
To make multiple subshells, rename the buffer *shell* to something different using M-x rename-uniquely. Then type M-x shell again to create a new buffer *shell* with its own subshell. If you rename this buffer as well, you can create a third one, and so on. All the subshells 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.
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 specify a coding system after starting the shell by using C-x RET p in the shell buffer. Section 20.8.
Emacs defines the environment variable EMACS in the subshell, with value t. A shell script can check this variable to determine whether it has been run from an Emacs subshell.
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). When a line is copied, any prompt at the beginning if the line (text output by programs preceding your input) is omitted. See also comint-use-prompt-regexp-instead-of-fields).
Complete the command name or file name before point in the shell buffer (comint-dynamic-complete). TAB also completes history references (Section 31.15.4.3) 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 ignores 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). 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).
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).
Display the buffer's history of shell commands in another window (comint-dynamic-list-input-ring).
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.
Alternatively, you can arrange for Emacs to notice password prompts and turn off echoing for them, as follows:
(add-hook 'comint-output-filter-functions
'comint-watch-for-password-prompt) |
Continue the shell process. This is useful if you accidentally suspend the shell process.[1]
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 also customizes the paragraph commands so that only shell prompts start new paragraphs. Thus, a paragraph consists of an input command plus the output that follows it in the 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 (Section 25.5) and M-x run-lisp (Section 25.10).
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.
Shell buffers support three ways of repeating earlier commands. You can use the same keys used in the minibuffer; 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.
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.
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.
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-r. 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.
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.
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 previous 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.
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.
Moving to a previous input and then copying it with C-c RET 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.
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. Normally, any text output by a program at the beginning of an input line is considered a prompt. However, if the variable comint-use-prompt-regexp-instead-of-fields is non-nil, then Comint mode uses a regular expression to recognize prompts. In general, the variable comint-prompt-regexp specifies the regular expression; Shell mode uses the variable shell-prompt-pattern to set up comint-prompt-regexp in the shell buffer.
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 an error while trying to handle what it believes is a cd, pushd or popd command, it runs the hook shell-set-directory-error-hook (Section 32.2.3).
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.
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.
If comint-scroll-show-maximum-output is non-nil, then scrolling due to arrival of output tries to place the last line of text at the bottom line of the window, so as to show as much useful text as possible. (This mimics the scrolling behavior of many terminals.) The default is nil.
By setting comint-scroll-to-bottom-on-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.
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.
The command comint-dynamic-complete-variable does variable-name completion using the environment variables as set within Emacs. The variables controlling file name completion apply to variable-name completion too. This command is normally available through the menu bar.
Command completion normally considers only executable files. If you set shell-command-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.
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 *term*, 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 Section 31.15.3.
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 (Section 31.15.8). 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 *term* 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.
The terminal emulator uses Term mode, which has two input modes. In line mode, Term basically acts like Shell mode; see Section 31.15.3. 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.
A prefix command to access the global C-x commands conveniently. For example, C-c C-x o invokes the global binding of C-x o, which is normally other-window.
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 Unix more program.
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 your using. Terminal types ansi or vt100 will work on most systems.
| [1] | You should not suspend the shell process. Suspending a subjob of the shell is a completely different matter--that is normal practice, but you must use the shell to continue the subjob; this command won't do it. |