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 …
}

2.4.1 Built-in variables

Eshell knows a few built-in variables:

$PWD
$+

This variable always contains the current working directory.

$OLDPWD
$-

This variable always contains the previous working directory (the current working directory from before the last cd command). When using $-, you can also access older directories in the directory ring via subscripting, e.g. ‘$-[1]’ refers to the working directory before the previous one.

$PATH

This specifies the directories to search for executable programs. Its value is a string, separated by ":" for Unix and GNU systems, and ";" for MS systems. This variable is connection-aware, so whenever you change the current directory to a different host (see Remote Files in The GNU Emacs Manual), the value will automatically update to reflect the search path on that host.

$_

This refers to the last argument of the last command. With a subscript, you can access any argument of the last command. For example, ‘$_[1]’ refers to the second argument of the last command (excluding the command name itself).

$$

This is the result of the last command. For external commands, it is t if the exit code was 0 or nil otherwise.

$?

This variable contains the exit code of the last command. If the last command was a Lisp function, it is 0 for successful completion or 1 otherwise. If eshell-lisp-form-nil-is-failure is non-nil, then a command with a Lisp form, like ‘(command args…)’, that returns nil will set this variable to 2.

$COLUMNS
$LINES

These variables tell the number of columns and lines, respectively, that are currently visible in the Eshell window. They are both copied to the environment, so external commands invoked from Eshell can consult them to do the right thing.

$INSIDE_EMACS

This variable indicates to external commands that they are being invoked from within Emacs so they can adjust their behavior if necessary. By default, its value is emacs-version,eshell. Other parts of Emacs, such as Tramp, may add extra information to this value.

See Aliases, for the built-in variables ‘$*’, ‘$1’, ‘$2’, …, in alias definitions.