List of Built-ins (Eshell: The Emacs Shell)

3.3.1 List of Built-in Commands

. file [argument]…

Source an Eshell script named file in the current environment, passing any arguments to the script (see Scripts). This is not to be confused with the command source, which sources a file in a subshell environment.

addpath

addpath [-b] directory…

Adds each specified directory to the $PATH environment variable. By default, this adds the directories to the end of $PATH, in the order they were passed on the command line; by passing -b or --begin, Eshell will instead add the directories to the beginning.

With no directories, print the list of directories currently stored in $PATH.

alias

alias name [command]

Define an alias named name and expanding to command, adding it to the aliases file (see Aliases). If command is omitted, delete the alias named name. With no arguments at all, list all the currently-defined aliases.

basename filename

Return filename without its directory.

cat file…

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

cd

cd directory

cd -[n]

cd =[regexp]

Change the current working directory. This command can take several forms:

cd: Change to the user’s home directory.
cd directory: Change to the specified directory.
cd -: Change back to the previous working directory (this is the same as cd $-).
cd -n: Change to the directory in the nth slot of the directory stack.
cd =: Show the directory ring. Each line is numbered.
cd =regexp: Search the directory ring for a directory matching the regular expression regexp and change to that directory.

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 [scrollback]

Scrolls the contents of the Eshell window out of sight, leaving a blank window. If scrollback is non-nil, the scrollback contents are cleared instead, as with clear-scrollback.

clear-scrollback

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

compile [-p | -i] [-m mode-name] command…

Run an external command, sending its output to a compilation buffer if the command would output to the screen and is not part of a pipeline or subcommand.

With the -p or --plain options, always send the output to the Eshell buffer; similarly, with -i or --interactive, always send the output to a compilation buffer. You can also set the mode of the compilation buffer with -m mode-name or --mode mode-name.

compile is particularly useful when defining aliases, so that interactively, the output shows up in a compilation buffer, but you can still pipe the output elsewhere if desired. For example, if you have a grep-like command on your system, you might define an alias for it like so: ‘alias mygrep 'compile --mode=grep-mode -- mygrep $*'’.

cp [option…] source dest

cp [option…] source… directory

Copy the file source to dest or source into 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.

cp accepts the following options:

-a, --archive: Equivalent to --no-dereference --preserve --recursive.
-d, --no-dereference: Don’t dereference symbolic links when copying; instead, copy the link itself.
-f, --force: Never prompt for confirmation before copying a file.
-i, --interactive: Prompt for confirmation before copying a file if the target already exists.
-n, --preview: Run the command, but don’t copy anything. This is useful if you want to preview what would be removed when calling cp.
-p, --preserve: Attempt to preserve file attributes when copying.
-r, -R, --recursive: Copy any specified directories and their contents recursively.
-v, --verbose: Print the name of each file before copying it.

date [specified-time [zone]]

Print the current local time as a human-readable string. This command is an alias to the Emacs Lisp function current-time-string (see Time of Day in GNU Emacs Lisp Reference Manual).

diff [option]… old new

Compare the files old and new 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 filename

Return the directory component of filename.

dirs

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

du [option]… file…

Summarize disk usage for each file, recursing into directories.

du accepts the following options:

-a, --all: Print sizes for files, not just directories.
--block-size=size: Print sizes as number of blocks of size size.
-b, --bytes: Print file sizes in bytes.
-c, --total: Print a grand total of the sizes at the end.
-d, --max-depth=depth: Only print sizes for directories (or files with --all) that are depth or fewer levels below the command line arguments.
-h, --human-readable: Print sizes in human-readable format, with binary prefixes (so 1 KB is 1024 bytes).
-H, --si: Print sizes in human-readable format, with decimal prefixes (so 1 KB is 1000 bytes).
-k, --kilobytes: Print file sizes in kilobytes (like --block-size=1024).
-L, --dereference: Follow symbolic links when traversing files.
-m, --megabytes: Print file sizes in megabytes (like --block-size=1048576).
-s, --summarize: Don’t recurse into subdirectories (like --max-depth=0).
-x, --one-file-system: Skip any directories that reside on different filesystems.

echo [-n | -N] [arg]…

Prints the value of each arg. 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.

You can control whether echo outputs a trailing newline using -n to disable the trailing newline (the default behavior) or -N to enable it (the default when eshell-plain-echo-behavior is non-nil).

env [var=value]… [command]…

With no arguments, print the current environment variables. If you pass arguments to this command, then env will execute the arguments as a command. If you pass any initial arguments of the form ‘var=value’, env will first set var to value before running the command.

eshell-debug [error | form | process]…

Toggle debugging information for Eshell itself. You can pass this command one or more of the following arguments:

error, to enable/disable Eshell trapping errors when evaluating commands;
form, to show/hide Eshell command form manipulation in the buffer *eshell last cmd*; or
process, to show/hide external process events 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 [name=value]…

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

funcall function [arg]…

Call function with the specified arguments (function may be a symbol or a string naming a Lisp function). This command is useful when you want to call an ordinary Lisp function using Eshell’s command form (see Invocation), even if there may be an external program of the same name.

grep [arg]…

agrep [arg]…

egrep [arg]…

fgrep [arg]…

rgrep [arg]…

glimpse [arg]…

The grep commands are compatible with GNU grep, but open a compilation buffer in grep-mode instead. See Grep Searching in The GNU Emacs Manual.

If eshell-plain-grep-behavior is non-nil, then these commands do not use open a compilation buffer, instead printing output to Eshell’s buffer. 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 [n]

history [-arw] [filename]

Prints Eshell’s input history. With a numeric argument n, this command prints the n most recent items in the history. Alternately, you can specify the following options:

-a, --append: Append new history items to the history file.
-r, --read: Read history items from the history file and append them to the current shell’s history.
-w, --write: Write the current history list to the history file.

info [manual [item]…]

Browse the available Info documentation. With no arguments, browse the top-level menu. Otherwise, show the manual for manual, selecting the menu entry for item.

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 [-signal] [pid | process]

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 [arg]…

Return the arguments as a single list. With a single argument, return it as-is if it’s already a list, or otherwise wrap it in a list. With multiple arguments, return a list of all of them.

ln [option]… target [link-name]

ln [option]… target… directory

Create a link to the specified target named link-name or create links to multiple targets in directory.

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.

ln accepts the following options:

-f, --force: Never prompt for confirmation before linking a target.
-i, --interactive: Prompt for confirmation before linking to an item if the source already exists.
-n, --preview: Run the command, but don’t move anything. This is useful if you want to preview what would be linked when calling ln.
-s, --symbolic: Make symbolic links instead of hard links.
-v, --verbose: Print the name of each file before linking it.

locate arg…

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 [option]… [file]…

List information about each file, including the contents of any specified directories. If file is unspecified, list the contents of the current directory.

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.

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.

ls supports the following options:

-a, --all: List all files, including ones starting with ‘.’.
-A, --almost-all: Like --all, but don’t list the current directory (.) or the parent directory (..).
-c, --by-ctime: Sort files by last status change time, with newest files first.
-C: List entries by columns.
-d, --directory: List directory entries instead of their contents.
-h, --human-readable: Print sizes in human-readable format, with binary prefixes (so 1 KB is 1024 bytes).
-H, --si: Print sizes in human-readable format, with decimal prefixes (so 1 KB is 1000 bytes).
-Ipattern, --ignore=pattern: Don’t list directory entries matching pattern.
-k, --kilobytes: Print sizes as 1024-byte kilobytes.
-l: Use a long listing format showing details for each file. The user option eshell-ls-date-format determines how the date is displayed when using this option. The date is produced using the function format-time-string (see Time Parsing in GNU Emacs Lisp Reference Manual).
-L, --dereference: Follow symbolic links when listing entries.
-n, --numeric-uid-gid: Show UIDs and GIDs numerically, instead of using their names.
-r, --reverse: Reverse order when sorting.
-R, --recursive: List subdirectories recursively.
-s, --size: Show the size of each file in blocks.
-S: Sort by file size, with largest files first. The user option eshell-ls-default-blocksize determines the default blocksize used when displaying file sizes with this option.
-t: Sort by modification time, with newest files first.
-u: Sort by last access time, with newest files first.
-U: Do not sort results. Instead, list entries in their directory order.
-x: List entries by lines instead of by columns.
-X: Sort alphabetically by file extension.
-1: List one file per line.

make [arg]…

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

man [arg]…

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

mkdir [-p] directory…

Make new directories. With -p or --parents, automatically make any necessary parent directories as well.

mv [option]… source dest

mv [option]… source… directory

Rename the file source to dest or move source into directory.

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.

mv accepts the following options:

-f, --force: Never prompt for confirmation before moving an item.
-i, --interactive: Prompt for confirmation before moving an item if the target already exists.
-n, --preview: Run the command, but don’t move anything. This is useful if you want to preview what would be moved when calling mv.
-v, --verbose: Print the name of each item before moving it.

occur regexp [nlines]

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

popd

popd +n

Pop a directory from the directory stack and switch to a another place in the stack. This command can take the following forms:

popd: Remove the current directory from the directory stack and change to the directory beneath it.
popd +n: Remove the current directory from the directory stack and change to the nth directory in the stack (counting from zero).

printnl [arg]…

Print all the args separated by newlines.

pushd

pushd directory

pushd +n

Push the current directory onto the directory stack, then change to another directory. This command can take the following forms:

pushd: Swap the current directory with the directory on the top of the stack. If eshell-pushd-tohome is non-nil, push the current directory onto the stack and change to the user’s home directory (like ‘pushd ~’).
pushd directory: Push the current directory onto the stack and change to directory. If eshell-pushd-dunique is non-nil, then only unique directories will be added to the stack.
pushd +n: Change to the nth directory in the directory stack (counting from zero), and “rotate” the stack by moving any elements before the nth to the bottom. If eshell-pushd-dextract is non-nil, then ‘pushd +n’ will instead pop the nth directory to the top of the stack.

pwd

Prints the current working directory.

rm [option]… item…

Removes files, buffers, processes, or Emacs Lisp symbols, depending on the type of each item.

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.

rm accepts the following options:

-f, --force: Never prompt for confirmation before removing an item.
-i, --interactive: Prompt for confirmation before removing each item.
-n, --preview: Run the command, but don’t remove anything. This is useful if you want to preview what would be removed when calling rm.
-r, -R, --recursive: Remove any specified directories and their contents recursively.
-v, --verbose: Print the name of each item before removing it.

rmdir directory…

Removes directories if they are empty.

set [var value]…

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

setq [symbol value]…

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

source file [argument]…

Source an Eshell script named file in a subshell environment, passing any arguments to the script (see Scripts). This is not to be confused with the command ., which sources a file in the current environment.

time command…

Show the time elapsed during the execution of command.

umask [-S]

umask mode

View the default file permissions for newly created files and directories. If you pass -S or --symbolic, view the mode symbolically. With mode, set the default permissions to this value.

unset [var]…

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

wait [process]…

Wait until each specified process has exited.

which command…

For each command, identify what kind of command it is and its location.

whoami

Print the current user. This Eshell version of whoami is connection-aware, so for remote directories, it will print the user associated with that connection.