Eshell

1.1 What is Eshell?

Eshell is a command shell written in Emacs Lisp. Everything it does, it uses Emacs’s facilities to do. This means that Eshell is as portable as Emacs itself. It also means that cooperation with Lisp code is natural and seamless.

What is a command shell? To properly understand the role of a shell, it’s necessary to visualize what a computer does for you. Basically, a computer is a tool; in order to use that tool, you must tell it what to do—or give it “commands.” These commands take many forms, such as clicking with a mouse on certain parts of the screen. But that is only one form of command input.

By far the most versatile way to express what you want the computer to do is by using an abbreviated language called script. In script, instead of telling the computer, “list my files, please”, one writes a standard abbreviated command word—‘ls’. Typing ‘ls’ in a command shell is a script way of telling the computer to list your files.²

The real flexibility of this approach is apparent only when you realize that there are many, many different ways to list files. Perhaps you want them sorted by name, sorted by date, in reverse order, or grouped by type. Most graphical browsers have simple ways to express this. But what about showing only a few files, or only files that meet a certain criteria? In very complex and specific situations, the request becomes too difficult to express using a mouse or pointing device. It is just these kinds of requests that are easily solved using a command shell.

For example, what if you want to list every Word file on your hard drive, larger than 100 kilobytes in size, and which hasn’t been looked at in over six months? That is a good candidate list for deletion, when you go to clean up your hard drive. But have you ever tried asking your computer for such a list? There is no way to do it! At least, not without using a command shell.

The role of a command shell is to give you more control over what your computer does for you. Not everyone needs this amount of control, and it does come at a cost: Learning the necessary script commands to express what you want done. A complicated query, such as the example above, takes time to learn. But if you find yourself using your computer frequently enough, it is more than worthwhile in the long run. Any tool you use often deserves the time spent learning to master it. ³

1.2 Contributors to Eshell

Contributions to Eshell are welcome. I have limited time to work on this project, but I will gladly add any code you contribute to me to this package.

The following persons have made contributions to Eshell.

• John Wiegley is the original author of Eshell.
• Eli Zaretskii made it possible for Eshell to run without requiring asynchronous subprocess support. This is important for MS-DOS, which does not have such support.
• Miles Bader contributed many fixes during the port to Emacs 21.
• Stefan Monnier fixed the things which bothered him, which of course made things better for all.
• Gerd Moellmann also helped to contribute bug fixes during the initial integration with Emacs 21.
• Alex Schroeder contributed code for interactively querying the user before overwriting files.

Apart from these, a lot of people have sent suggestions, ideas, requests, bug reports and encouragement. Thanks a lot! Without you there would be no new releases of Eshell.

2.1 Invocation

Eshell is both a command shell and an Emacs Lisp REPL. As a result, you can invoke commands in two different ways: in command form or in Lisp form.

You can use the semicolon (;) to separate multiple command invocations on a single line, executing each in turn. You can also separate commands with && or ||. When using &&, Eshell will execute the second command only if the first succeeds (i.e. has an exit status of 0); with ||, Eshell will execute the second command only if the first fails.

A command invocation followed by an ampersand (&) will be run in the background. Eshell has no job control, so you can not suspend or background the current process, or bring a background process into the foreground. That said, background processes invoked from Eshell can be controlled the same way as any other background process in Emacs.

• Command form
• Lisp form

~ $ echo hello
hello

~ $ echo {echo hello; echo there}
hellothere

~ $ (format "hello, %s" user-login-name)
hello, user

~ $ ls *.patch > (format-time-string "%F.log")

2.2 Arguments

Ordinarily, Eshell parses arguments in command form as either strings or numbers, depending on what the parser thinks they look like. To specify an argument of some other data type, you can use a Lisp form (see Invocation):

~ $ echo (list 1 2 3)
(1 2 3)

Additionally, many built-in Eshell commands (see Built-in commands) will flatten the arguments they receive, so passing a list as an argument will “spread” the elements into multiple arguments:

~ $ printnl (list 1 2) 3
1
2
3

• Quoting and escaping
• Special argument types

~ $ echo "foo\
bar"
foobar

2.3 Built-in commands

Eshell provides a number of built-in commands, many of them implementing common command-line utilities, but enhanced for Eshell. (These built-in commands are just ordinary Lisp functions whose names begin with eshell/.) In order to call the external variant of a built-in command foo, you could call *foo. Usually, this should not be necessary. You can check what will be applied by the which command:

~ $ which ls
eshell/ls is a compiled Lisp function in `em-ls.el'
~ $ which *ls
/bin/ls

If you want to discard a given built-in command, you could declare an alias (see Aliases). Example:

~ $ which sudo
eshell/sudo is a compiled Lisp function in `em-tramp.el'.
~ $ alias sudo '*sudo $*'
~ $ which sudo
sudo is an alias, defined as "*sudo $*"

Some of the built-in commands have different behavior from their external counterparts, and some have no external counterpart. Most of these will print a usage message when given the --help option.

In some cases, a built-in command’s behavior can be configured via user settings, some of which are mentioned below. For example, certain commands have two user settings to allow them to overwrite files without warning and to ensure that they always prompt before overwriting files. If both settings are non-nil, the commands always prompt. If both settings are nil (the default), the commands signal an error.

Several commands observe the value of eshell-default-target-is-dot. If non-nil, then the default target for the commands cp, mv, and ln is the current directory.

A few commands are wrappers for more niche Emacs features, and can be loaded as part of the eshell-xtra module. See Extension modules.

. ¶

Source an Eshell file in the current environment. This is not to be confused with the command source, which sources a file in a subshell environment.

addpath ¶

Adds a given path or set of paths to the PATH environment variable, or, with no arguments, prints the current paths in this variable.

alias ¶

Define an alias (see Aliases). This adds it to the aliases file.

basename ¶

Return a file name without its directory.

cat ¶

Concatenate file contents into standard output. If in a pipeline, or if the file is not a regular file, directory, or symlink, then this command reverts to the system’s definition of cat.

cd ¶

This command changes the current working directory. Usually, it is invoked as cd dir where dir is the new working directory. But cd knows about a few special arguments:

• - When it receives no argument at all, it changes to the home directory.
• - Giving the command cd - changes back to the previous working directory (this is the same as cd $-).
• - The command cd = shows the directory ring. Each line is numbered.
• - With cd =foo, Eshell searches the directory ring for a directory matching the regular expression ‘foo’, and changes to that directory.
• - With cd -42, you can access the directory stack slots by number.
• - If eshell-cd-shows-directory is non-nil, cd will report the directory it changes to. If eshell-list-files-after-cd is non-nil, then ls is called with any remaining arguments after changing directories.

clear ¶

Scrolls the contents of the Eshell window out of sight, leaving a blank window. If provided with an optional non-nil argument, the scrollback contents are cleared instead.

clear-scrollback ¶

Clear the scrollback contents of the Eshell window. Unlike the command clear, this command deletes content in the Eshell buffer.

cp ¶

Copy a file to a new location or copy multiple files to the same directory.

If eshell-cp-overwrite-files is non-nil, then cp will overwrite files without warning. If eshell-cp-interactive-query is non-nil, then cp will ask before overwriting anything.

date ¶

Print the current local time as a human-readable string. This command is similar to, but slightly different from, the GNU Coreutils date command.

diff ¶

Compare files using Emacs’s internal diff (not to be confused with ediff). See Comparing Files in The GNU Emacs Manual.

If eshell-plain-diff-behavior is non-nil, then this command does not use Emacs’s internal diff. This is the same as using ‘alias diff '*diff $*'’.

dirname ¶

Return the directory component of a file name.

dirs ¶

Prints the directory stack. Directories can be added or removed from the stack using the commands pushd and popd, respectively.

du ¶

Summarize disk usage for each file.

echo ¶

Echoes its input. By default, this prints in a Lisp-friendly fashion (so that the value is useful to a Lisp command using the result of echo as an argument). If a single argument is passed, echo prints that; if multiple arguments are passed, it prints a list of all the arguments; otherwise, it prints the empty string.

If eshell-plain-echo-behavior is non-nil, echo will try to behave more like a plain shell’s echo, printing each argument as a string, separated by a space.

env ¶

Prints the current environment variables. Unlike in Bash, this command does not yet support running commands with a modified environment.

eshell-debug ¶

Toggle debugging information for Eshell itself. You can pass this command the argument errors to enable/disable Eshell trapping errors when evaluating commands, or the argument commands to show/hide command execution progress in the buffer *eshell last cmd*.

exit ¶

Exit Eshell and save the history. By default, this command kills the Eshell buffer, but if eshell-kill-on-exit is nil, then the buffer is merely buried instead.

export ¶

Set environment variables using input like Bash’s export, as in ‘export var1=val1 var2=val2 …’.

grep ¶

agrep

egrep

fgrep

glimpse

The grep commands are compatible with GNU grep, but use Emacs’s internal grep instead. See Grep Searching in The GNU Emacs Manual.

If eshell-plain-grep-behavior is non-nil, then these commands do not use Emacs’s internal grep. This is the same as using ‘alias grep '*grep $*'’, though this setting applies to all of the built-in commands for which you would need to create a separate alias.

history ¶

Prints Eshell’s input history. With a numeric argument N, this command prints the N most recent items in the history.

info ¶

Browse the available Info documentation. This command is the same as the external info command, but uses Emacs’s internal Info reader. See Misc Help in The GNU Emacs Manual.

jobs ¶

List subprocesses of the Emacs process, if any, using the function list-processes.

kill ¶

Kill processes. Takes a PID or a process object and an optional signal specifier which can either be a number or a signal name.

listify ¶

Eshell version of list. Allows you to create a list using Eshell syntax, rather than Elisp syntax. For example, ‘listify foo bar’ and ("foo" "bar") both evaluate to ("foo" "bar").

ln ¶

Create links to files.

If eshell-ln-overwrite-files is non-nil, ln will overwrite files without warning. If eshell-ln-interactive-query is non-nil, then ln will ask before overwriting files.

locate ¶

Alias to Emacs’s locate function, which simply runs the external locate command and parses the results. See Dired and Find in The GNU Emacs Manual.

If eshell-plain-locate-behavior is non-nil, then Emacs’s internal locate is not used. This is the same as using ‘alias locate '*locate $*'’.

ls ¶

Lists the contents of directories.

If eshell-ls-use-colors is non-nil, the contents of a directory is color-coded according to file type and status. These colors and the regexps used to identify their corresponding files can be customized via M-x customize-group RET eshell-ls RET.

The user option eshell-ls-date-format determines how the date is displayed when using the -l option. The date is produced using the function format-time-string (see Time Parsing in GNU Emacs Lisp Reference Manual).

The user option eshell-ls-initial-args contains a list of arguments to include with any call to ls. For example, you can include the option -h to always use a more human-readable format.

The user option eshell-ls-default-blocksize determines the default blocksize used when displaying file sizes with the option -s.

make ¶

Run make through compile when run asynchronously (e.g., ‘make &’). See Compilation in The GNU Emacs Manual. Otherwise call the external make command.

man ¶

Display Man pages using the Emacs man command. See Man Page in The GNU Emacs Manual.

mkdir ¶

Make new directories.

mv ¶

Move or rename files.

If eshell-mv-overwrite-files is non-nil, mv will overwrite files without warning. If eshell-mv-interactive-query is non-nil, mv will prompt before overwriting anything.

occur ¶

Alias to Emacs’s occur. See Other Repeating Search in The GNU Emacs Manual.

popd ¶

Pop a directory from the directory stack and switch to a another place in the stack.

printnl ¶

Print the arguments separated by newlines.

pushd ¶

Push the current directory onto the directory stack, then change to another directory.

If eshell-pushd-dunique is non-nil, then only unique directories will be added to the stack. If eshell-pushd-dextract is non-nil, then ‘pushd +n’ will pop the nth directory to the top of the stack.

pwd ¶

Prints the current working directory.

rm ¶

Removes files, buffers, processes, or Emacs Lisp symbols, depending on the argument.

If eshell-rm-interactive-query is non-nil, rm will prompt before removing anything. If eshell-rm-removes-directories is non-nil, then rm can also remove directories. Otherwise, rmdir is required.

rmdir ¶

Removes directories if they are empty.

set ¶

Set variable values, using the function set like a command (see Setting Variables in GNU Emacs Lisp Reference Manual). A variable name can be a symbol, in which case it refers to a Lisp variable, or a string, referring to an environment variable (see Arguments).

setq ¶

Set variable values, using the function setq like a command (see Setting Variables in GNU Emacs Lisp Reference Manual).

source ¶

Source an Eshell file in a subshell environment. This is not to be confused with the command ., which sources a file in the current environment.

time ¶

Show the time elapsed during a command’s execution.

umask ¶

Set or view the default file permissions for newly created files and directories.

unset ¶

Unset one or more variables. As with set, a variable name can be a symbol, in which case it refers to a Lisp variable, or a string, referring to an environment variable.

wait ¶

Wait until a process has successfully completed.

which ¶

Identify a command and its location.

whoami ¶

Print the current user. This Eshell version of whoami supports Tramp.

• Defining new built-in commands

2.4 Variables

Since Eshell is a combination of an Emacs REPL and a command shell, it can refer to variables from two different sources: ordinary Emacs Lisp variables, as well as environment variables. By default, when using a variable in Eshell, it will first look in the list of built-in variables, then in the list of environment variables, and finally in the list of Lisp variables. If you would prefer to use Lisp variables over environment variables, you can set eshell-prefer-lisp-variables to t.

You can set variables in a few different ways. To set a Lisp variable, you can use the command ‘setq name value’, which works much like its Lisp counterpart (see Setting Variables in The Emacs Lisp Reference Manual). To set an environment variable, use ‘export name=value’. You can also use ‘set variable value’, which sets a Lisp variable if variable is a symbol, or an environment variable if it’s a string (see Arguments). Finally, you can temporarily set environment variables for a single command with ‘name=value command …’. This is equivalent to:

{
  export name=value
  command …
}

• Built-in variables

2.5 Aliases

Aliases are commands that expand to a longer input line. For example, ll is a common alias for ls -l, and would be defined with the command invocation alias ll 'ls -l $*'; with this defined, running ‘ll foo’ in Eshell will actually run ‘ls -l foo’. Aliases defined (or deleted) by the alias command are automatically written to the file named by eshell-aliases-file, which you can also edit directly (although you will have to manually reload it).

Note that unlike aliases in Bash, arguments must be handled explicitly. Typically the alias definition would end in ‘$*’ to pass all arguments along. More selective use of arguments via ‘$1’, ‘$2’, etc., is also possible. For example, alias mcd 'mkdir $1 && cd $1' would cause mcd foo to create and switch to a directory called ‘foo’.

2.6 Remote Access

Since Eshell uses Emacs facilities for most of its functionality, you can access remote hosts transparently. To connect to a remote host, simply cd into it:

~ $ cd /ssh:user@remote:
/ssh:user@remote:~ $

Additionally, built-in Eshell commands (see Built-in commands) and ordinary Lisp functions accept remote file names, so you can access them even without explicitly connecting first. For example, to print the contents of a remote file, you could type ‘cat /ssh:user@remote:~/output.log’. However, this means that when using built-in commands or Lisp functions from a remote directory, you must be careful about specifying absolute file names: ‘cat /var/output.log’ will always print the contents of your local /var/output.log, even from a remote directory. If you find this behavior annoying, you can enable the optional electric forward slash module (see Electric forward slash).

2.7 History

The ‘history’ command shows all commands kept in the history ring as numbered list. If the history ring contains eshell-history-size commands, those numbers change after every command invocation, therefore the ‘history’ command shall be applied before using the expansion mechanism with history numbers.

The n-th entry of the history ring can be applied with the ‘!n’ command. If n is negative, the entry is counted from the end of the history ring.

When history event designators are enabled (by adding eshell-expand-history-references to eshell-expand-input-functions), ‘!foo’ expands to the last command beginning with foo, and ‘!?foo’ to the last command containing foo. The n-th argument of the last command beginning with foo is accessible by !foo:n.

The history ring is loaded from a file at the start of every session, and written back to the file at the end of every session. The file path is specified in eshell-history-file-name. Unlike other shells, such as Bash, Eshell can not be configured to keep a history ring of a different size than that of the history file.

Since the default buffer navigation and searching key-bindings are still present in the Eshell buffer, the commands for history navigation and searching are bound to different keys:

M-r

M-s

History I-search.

M-p

M-n

Previous and next history line. If there is anything on the input line when you run these commands, they will instead jump to the previous or next line that begins with that string.

2.8 Completion

Eshell uses the pcomplete package for programmable completion, similar to that of other command shells. Argument completion differs depending on the preceding command: for example, possible completions for rmdir are only directories, while rm completions can be directories and files. Eshell provides predefined completions for the built-in functions and some common external commands, and you can define your own for any command.

Eshell completion also works for Lisp forms and glob patterns. If the point is on a Lisp form, then TAB will behave similarly to completion in elisp-mode and lisp-interaction-mode. For glob patterns, the pattern will be removed from the input line, and replaced by the completion.

If you want to see the entire list of possible completions (e.g. when it’s below the completion-cycle-threshold), press M-?.

• pcomplete

2.9 Control Flow

Because Eshell commands can not (easily) be combined with Lisp forms, Eshell provides command-oriented control flow statements for convenience.

Most of Eshell’s control flow statements accept a conditional. This can take a few different forms. If conditional is a dollar expansion, the condition is satisfied if the result is a non-nil value. If conditional is a ‘{ subcommand }’ or ‘(lisp form)’, the condition is satisfied if the command’s exit status is 0.

if conditional { true-commands }

if conditional { true-commands } { false-commands }

Evaluate true-commands if conditional is satisfied; otherwise, evaluate false-commands.

unless conditional { false-commands }

unless conditional { false-commands } { true-commands }

Evaluate false-commands if conditional is not satisfied; otherwise, evaluate true-commands.

while conditional { commands }

Repeatedly evaluate commands so long as conditional is satisfied.

until conditional { commands }

Repeatedly evaluate commands until conditional is satisfied.

for var in list… { commands }

Iterate over each element of list, storing the element in var and evaluating commands. If list is not a list, treat it as a list of one element. If you specify multiple lists, this will iterate over each of them in turn.

2.10 Scripts

You can run Eshell scripts much like scripts for other shells; the main difference is that since Eshell is not a system command, you have to run it from within Emacs. An Eshell script is simply a file containing a sequence of commands, as with almost any other shell script. Scripts are invoked from Eshell with source, or from anywhere in Emacs with eshell-source-file.

If you wish to load a script into your current environment, rather than in a subshell, use the . command.

3.1 Dollars Expansion

Eshell has different $ expansion syntax from other shells. There are some similarities, but don’t let these lull you into a false sense of familiarity.

$var

Expands to the value bound to var. This is the main way to use variables in command invocations.

$"var"

$'var'

Expands to the value bound to var. This is useful to disambiguate the variable name when concatenating it with another value, such as ‘$"var"-suffix’.

$(lisp)

Expands to the result of evaluating the S-expression (lisp). On its own, this is identical to just (lisp), but with the $, it can be used inside double quotes or within a longer string, such as ‘/some/path/$(lisp).txt’.

${command}

Returns the output of command, which can be any valid Eshell command invocation, and may even contain expansions. Similar to $(lisp), this is identical to {command} when on its own, but the $ allows it to be used inside double quotes or as part of a string.

Normally, the output is split line-by-line, returning a list (or the first element if there’s only one line of output); if eshell-convert-numeric-arguments is non-nil and every line of output looks like a number, convert each line to a number. However, when this expansion is surrounded by double quotes, it returns the output as a single string instead.

$<command>

As with ‘${command}’, evaluates the Eshell command invocation command, but writes the output to a temporary file and returns the file name.

$expr[i...]

Expands to the ith element of the result of expr, an expression in one of the above forms listed here. If multiple indices are supplied, this will return a list containing the elements for each index. The exact behavior depends on the type of expr’s value:

a sequence

Expands to the element at the (zero-based) index i of the sequence (see Sequences Arrays Vectors in The Emacs Lisp Reference Manual).

a string

Split the string at whitespace, and then expand to the ith element of the resulting sequence.

an alist

If i is a non-numeric value, expand to the value associated with the key "i" in the alist. For example, if var is ‘(("dog" . "fido") ("cat" . "felix"))’, then ‘$var[dog]’ expands to "fido". Otherwise, this behaves as with sequences; e.g., ‘$var[0]’ expands to ("dog" . "fido"). See Association Lists in The Emacs Lisp Reference Manual.

anything else

Signals an error.

Multiple sets of indices can also be specified. For example, if var is ‘((1 2) (3 4))’, then ‘$var[0][1]’ will expand to 2, i.e. the second element of the first list member (all indices are zero-based).

$expr[regexp i...]

As above (when expr expands to a string), but use regexp to split the string. regexp can be any form other than a number. For example, ‘$var[: 0]’ will return the first element of a colon-delimited string.

$#expr

Expands to the length of the result of expr, an expression in one of the above forms. For example, ‘$#var’ returns the length of the variable var and ‘$#var[0]’ returns the length of the first element of var. Again, signals an error if the result of expr is not a string or a sequence.

3.2 Globbing

Eshell’s globbing syntax is very similar to that of Zsh (see Filename Generation in The Z Shell Manual). Users coming from Bash can still use Bash-style globbing, as there are no incompatibilities.

By default, globs are case sensitive, except on MS-DOS/MS-Windows systems. You can control this behavior via the eshell-glob-case-insensitive option. You can further customize the syntax and behavior of globbing in Eshell via the Customize group eshell-glob (see Easy Customization in The GNU Emacs Manual).

‘*’

Matches any string (including the empty string). For example, ‘*.el’ matches any file with the .el extension.

‘?’

Matches any single character. For example, ‘?at’ matches cat and bat, but not goat.

‘**/’

Matches zero or more subdirectories in a file name. For example, ‘**/foo.el’ matches foo.el, bar/foo.el, bar/baz/foo.el, etc. Note that this cannot be combined with any other patterns in the same file name segment, so while ‘foo/**/bar.el’ is allowed, ‘foo**/bar.el’ is not.

‘***/’

Like ‘**/’, but follows symlinks as well.

‘[ … ]’

Defines a character set (see Regexps in The GNU Emacs Manual). A character set matches characters between the two brackets; for example, ‘[ad]’ matches a and d. You can also include ranges of characters in the set by separating the start and end with ‘-’. Thus, ‘[a-z]’ matches any lower-case ASCII letter. Note that, unlike in Zsh, character ranges are interpreted in the Unicode codepoint order, not in the locale-dependent collation order.

Additionally, you can include character classes in a character set. A ‘[:’ and balancing ‘:]’ enclose a character class inside a character set. For instance, ‘[[:alnum:]]’ matches any letter or digit. See Char Classes in The Emacs Lisp Reference Manual, for a list of character classes.

‘[^ … ]’

Defines a complemented character set. This behaves just like a character set, but matches any character except the ones specified.

‘( … )’

Defines a group. A group matches the pattern between ‘(’ and ‘)’. Note that a group can only match a single file name component, so a ‘/’ inside a group will signal an error.

‘x|y’

Inside of a group, matches either x or y. For example, ‘e(m|sh)-*’ matches any file beginning with em- or esh-.

‘x#’

Matches zero or more copies of the glob pattern x. For example, ‘fo#.el’ matches f.el, fo.el, foo.el, etc.

‘x##’

Matches one or more copies of the glob pattern x. Thus, ‘fo#.el’ matches fo.el, foo.el, fooo.el, etc.

‘x~y’

Matches anything that matches the pattern x but not y. For example, ‘[[:digit:]]#~4?’ matches 1 and 12, but not 42. Note that unlike in Zsh, only a single ‘~’ operator can be used in a pattern, and it cannot be inside of a group like ‘(x~y)’.

3.3 Argument Predication and Modification

Eshell supports argument predication, to filter elements of a glob, and argument modification, to manipulate argument values. These are similar to glob qualifiers in Zsh (see Glob Qualifiers in The Z Shell Manual).

Predicates and modifiers are introduced with ‘(filters)’ after any list argument, where filters is a list of predicates or modifiers. For example, ‘*(.)’ expands to all regular files in the current directory and ‘*(^@:U^u0)’ expands to all non-symlinks not owned by root, upper-cased.

Some predicates and modifiers accept string parameters, such as ‘*(u'user')’, which matches all files owned by user. These parameters must be surrounded by delimiters; you can use any of the following pairs of delimiters: "…", '…', /…/, |…|, (…), […], <…>, or {…}.

You can customize the syntax and behavior of predicates and modifiers in Eshell via the Customize group eshell-pred (see Easy Customization in The GNU Emacs Manual).

• Argument Predicates
• Argument Modifiers

4.1 Visual Commands

If you try to run programs from within Eshell that are not line-oriented, such as programs that use ncurses, you will just get garbage output, since the Eshell buffer is not a terminal emulator. Eshell solves this problem by running such programs in Emacs’s terminal emulator.

Programs that need a terminal to display output properly are referred to in this manual as “visual commands”, because they are not simply line-oriented. You must tell Eshell which commands are visual, by adding them to eshell-visual-commands; for commands that are visual for only certain sub-commands – e.g., ‘git log’ but not ‘git status’ – use eshell-visual-subcommands; and for commands that are visual only when passed certain options, use eshell-visual-options.

Caution: Some tools such as Git use the pager ‘less’ by default to paginate their output but call it with its ‘-F’ option. This option causes ‘less’ to echo the output instead of paginating it if the output is less than one page long. This causes undesirable behavior if, e.g., ‘git diff’, is defined as a visual subcommand. It’ll work if the output is big enough and fail if it is less than one page long. If that occurs to you, search for configuration options for calling ‘less’ without the ‘-F’ option. For Git, you can do that using ‘git config --global core.pager 'less -+F'’.

If you want the buffers created by visual programs killed when the program exits, customize the variable eshell-destroy-buffer-when-process-dies to a non-nil value; the default is nil.

4.2 Redirection

Redirection in Eshell is similar to that of other command shells. You can use the output redirection operators > and >>, but there is not yet any support for input redirection. In the cases below, fd specifies the file descriptor to redirect; if not specified, file descriptor 1 (standard output) will be used by default.

> dest

fd> dest

Redirect output to dest, overwriting its contents with the new output.

>> dest

fd>> dest

Redirect output to dest, appending it to the existing contents of dest.

>>> dest

fd>>> dest

Redirect output to dest, inserting it at the current mark if dest is a buffer, at the beginning of the file if dest is a file, or otherwise behaving the same as >>.

&> dest

>& dest

Redirect both standard output and standard error to dest, overwriting its contents with the new output.

&>> dest

>>& dest

Redirect both standard output and standard error to dest, appending it to the existing contents of dest.

&>>> dest

>>>& dest

Redirect both standard output and standard error to dest, inserting it like with >>> dest.

>&other-fd

fd>&other-fd

Duplicate the file descriptor other-fd to fd (or 1 if unspecified). The order in which this is used is significant, so

command > file 2>&1

redirects both standard output and standard error to file, whereas

command 2>&1 > file

only redirects standard output to file (and sends standard error to the display via standard output’s original handle).

Eshell supports redirecting output to several different types of targets:

• files, including virtual targets (see below);
• buffers (see Buffers in GNU Emacs Lisp Reference Manual);
• markers (see Markers in GNU Emacs Lisp Reference Manual);
• processes (see Processes in GNU Emacs Lisp Reference Manual); and
• symbols (see Symbols in GNU Emacs Lisp Reference Manual).

• Virtual Targets

4.3 Pipelines

As with most other shells, Eshell supports pipelines to pass the output of one command the input of the next command. You can send the standard output of one command to the standard input of another using the | operator. For example,

~ $ echo hello | rev
olleh

To send both the standard output and standard error of a command to another command’s input, you can use the |& operator.

• Running Shell Pipelines Natively

 cat *.ogg *| my-cool-decoder >file

 foo *| baz >#<buffer quux>

 sh -c "foo | baz" >#<buffer quux>

5.1 Optional modules

In addition to the various modules enabled by default (documented above), Eshell provides several other modules which are not enabled by default. If you want to enable these, you can add them to eshell-modules-list.

• Key rebinding
• Smart scrolling
• Electric forward slash
• Tramp extensions
• Extra built-in commands

 cd /ssh:root@example.com:
 find /etc -name "*gnu*"

 mv /etc/gnugnu /tmp

 mv /ssh:root@example.com:/etc/gnugnu /ssh:root@example.com:/tmp

5.2 Writing a module

An Eshell module is defined the same as any other library but with two additional requirements: first, the module’s source file should be named em-name.el; second, the module must define an autoloaded Customize group (see Customization in The Emacs Lisp Reference Manual) with eshell-module as the parent group. In order to properly autoload this group, you should wrap its definition with progn as follows:

;;;###autoload
(progn
(defgroup eshell-my-module nil
  "My module lets you do very cool things in Eshell."
  :tag "My module"
  :group 'eshell-module))

Even if you don’t have any Customize options in your module, you should still define the group so that Eshell can include your module in the Customize interface for eshell-modules-list.