Eshell

https://www.gnu.org/software/emacs/manual/html_node/eshell/
Admin
Eshell is an Emacs Lisp command shell that provides an interactive command interpreter and REPL with...
Tokens:32,820
Snippets:425
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### Execute a basic command in command form

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Invocation.html

A simple example of running the echo command in command form.

```shell
~ $ echo hello
hello
```

--------------------------------

### Example: cd and find with remote directory

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Electric-forward-slash.html

Shows a typical remote command sequence: cd to a remote host and then find for files. This is the context for the electric forward slash behavior.

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

```

--------------------------------

### Splice operator example with echo

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Dollars-Expansion.html

Demonstrates the difference between standard variable expansion and the splice operator ($@) when passing a list to a command.

```text
~ $ echo 0 $numbers
(0
 (1 2 3))
```

```text
~ $ echo 0 $@numbers
(0 1 2 3)
```

--------------------------------

### Redirection order example: command > file 2>&1

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Redirection.html

Shows the order of redirection operators. Redirecting standard output to file first, then duplicating standard error to standard output's new handle, sends both to file.

```shell
command > file 2>&1

```

--------------------------------

### Bash-compatible alias and function syntax

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Bugs-and-ideas.html

Proposed syntax for Eshell to support Bash-compatible aliases and functions. The example shows an alias definition and a function definition using $@* for arguments.

```bash
alias arg=blah
function arg () { blah $@* }

```

--------------------------------

### Example: mv command without electric slash

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Electric-forward-slash.html

Shows the mv command as typed by the user, which would operate on local files because mv is a Lisp function.

```shell
 mv /etc/gnugnu /tmp

```

--------------------------------

### Example: mv command with electric slash inserted

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Electric-forward-slash.html

Shows the mv command after the electric forward slash module automatically inserts the Tramp prefix, making it operate on remote files.

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

```

--------------------------------

### eshell-eval-using-options example for ls command

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Defining-New-Built_002dins.html

Shows how to use the eshell-eval-using-options macro to handle a subset of options for the 'ls' command. The macro processes command-line arguments, binds option values to symbols, and executes the body with remaining arguments in 'args'. Unknown options trigger an external command.

```lisp
(eshell-eval-using-options
 "ls" macro-args
 '((?a  nil      nil show-all       "show all files")
   (?I  "ignore" t   ignore-pattern "ignore files matching pattern")
   (nil "help"   nil nil            "show this help message")
 :external "ls"
 :usage "[OPTION]... [FILE]...
  List information about FILEs (the current directory by default).")
 ;; List the files in ARGS somehow...
 )
```

--------------------------------

### Chained if/else example in Eshell

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Control-Flow.html

Shows how to chain if/else forms in Eshell. The conditionals use subcommands in command form, and the condition is satisfied if the subcommand's exit status is 0.

```eshell
if {[ -f file.txt ]} {
  echo found file
} else if {[ -f alternate.txt ]} {
  echo found alternate
} else {
  echo not found!
}
```

--------------------------------

### eshell-eval-using-options

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Defining-New-Built_002dins.html

Macro to process command-line options for an Eshell built-in command. It parses arguments, binds option values to symbols, and executes the body with remaining arguments in 'args'. If an unknown option is encountered and an external command is specified, it starts that command and throws 'eshell-external'.

```APIDOC
## eshell-eval-using-options

### Description
Macro to process command-line options for an Eshell built-in command. It parses arguments, binds option values to symbols, and executes the body with remaining arguments in 'args'. If an unknown option is encountered and an external command is specified, it starts that command and throws 'eshell-external'.

### Syntax
(eshell-eval-using-options name macro-args options body...)

### Parameters
- **name** (string) - Required - The command name used for usage messages.
- **macro-args** (list) - Required - The list of arguments to parse.
- **options** (list) - Required - A list of option specifications and keyword arguments.
- **body** (forms) - Required - Lisp forms to execute after successful parsing.

### Options Specification
Each option element is a list: (short long value symbol help-string)
- **short** (character or nil) - Optional - Short switch character (e.g., ?a for -a). At least one of short or long must be non-nil.
- **long** (string or nil) - Optional - Long switch string (e.g., "ignore" for --ignore).
- **value** - Required - Value associated with the option: t (requires a value), nil (option given value t), or any other value (option given that value).
- **symbol** (symbol or nil) - Required - Lisp symbol to bind the value to. If nil, specifying the switch calls eshell-show-usage (useful for --help).
- **help-string** (string) - Required - Documentation string for the option, shown when eshell-show-usage is invoked.

### Keyword Arguments
- **:external string** - Optional - External command to run if unknown switches are present.
- **:usage string** - Optional - Initial part of the command's documentation string.
- **:post-usage string** - Optional - Trailing part of the command's documentation string.
- **:show-usage** - Optional - Show usage message if called with no arguments.
- **:preserve-args** - Optional - Preserve original arguments instead of flattening and converting to strings.
- **:parse-leading-options-only** - Optional - Do not parse dash or switch arguments after the first positional argument.

### Example
(eshell-eval-using-options
 "ls" macro-args
 '((?a  nil      nil show-all       "show all files")
   (?I  "ignore" t   ignore-pattern "ignore files matching pattern")
   (nil "help"   nil nil            "show this help message")
 :external "ls"
 :usage "[OPTION]... [FILE]...\n  List information about FILEs (the current directory by default).")
 ;; List the files in ARGS somehow...
 )

### Return Value
The value of the last form in body.
```

--------------------------------

### Redirection order example: command 2>&1 > file

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Redirection.html

Shows the opposite order. Duplicating standard error to standard output's original handle first, then redirecting standard output to file, only sends standard output to file; standard error goes to the display.

```shell
command 2>&1 > file

```

--------------------------------

### Native shell pipeline redirection

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Pipelines.html

Demonstrates how Eshell interprets native shell pipeline syntax compared to its equivalent sh -c command.

```shell
 foo *| baz >#<buffer quux>
```

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

--------------------------------

### Invalid regexp error with argument predicates

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Bugs-and-ideas.html

An example command that triggers an 'Invalid regexp' error when using argument predicates and modifiers in a path. The command attempts to use globbing with predicates.

```shell
/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)  Invalid regexp:
"Unmatched ( or \\("

```

--------------------------------

### Connect to a remote host with cd

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Remote-Access.html

Use cd to connect to a remote host via TRAMP. The prompt changes to show the remote directory.

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

```

--------------------------------

### Define autoloaded Customize group for Eshell module

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Writing-a-module.html

Wrap the defgroup in progn with ;;;###autoload to ensure the Customize group is autoloaded. The group must have :group 'eshell-module as parent. Even without Customize options, define the group so Eshell can include the module in eshell-modules-list.

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

```

--------------------------------

### eshell-command

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/One_002dOff-Commands.html

Executes an Eshell command string and shows the output in a buffer. Supports output and error targets, and asynchronous execution when the command ends with '&'.

```APIDOC
## eshell-command

### Description
Execute the Eshell command string command and show the output in a buffer. If output-target is t (interactively, with the prefix argument), write the command's standard output to the current buffer at point. If nil, write the output to a new output buffer. For any other value, output to that Eshell target. error-target controls where to write standard error; a nil value means to write standard error to the same place as standard output. When the command ends with '&', Eshell will evaluate the command asynchronously. Otherwise, it will wait until the command has finished execution.

### Method
Function call

### Signature
(eshell-command command &optional output-target error-target)

### Parameters
- **command** (string) - Required - The Eshell command string to execute.
- **output-target** (optional) - Optional - If t, write standard output to the current buffer at point. If nil, write to a new output buffer. For any other value, output to that Eshell target.
- **error-target** (optional) - Optional - Controls where to write standard error. If nil, write standard error to the same place as standard output. To suppress standard error, write to the Eshell virtual target /dev/null.

### Notes
- When the command ends with '&', the command is evaluated asynchronously.
- Otherwise, Eshell waits until the command has finished execution.
```

--------------------------------

### eshell-execute-file

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Scripts.html

Executes the Eshell commands contained in a file, with optional arguments and output/error targets.

```APIDOC
## eshell-execute-file

### Description
Execute the Eshell commands contained in a file, passing an optional list of arguments to the script. The output and error targets control where the command output and standard error are written.

### Method
Command

### Endpoint
eshell-execute-file file &optional args output-target error-target

### Parameters
#### Arguments
- **file** (string) - Required - The path to the file containing Eshell commands.
- **args** (list) - Optional - A list of arguments to pass to the script.
- **output-target** - Optional - If `t`, write the command output to the current buffer. If `nil`, don't write the output anywhere. For any other value, output to the corresponding Eshell target (see Redirection).
- **error-target** - Optional - Controls where to write standard error. If `nil`, write standard error to the same place as standard output. To suppress standard error, write to the Eshell virtual target /dev/null.

### Response
No explicit response is documented. The command executes the script and writes output according to the specified targets.
```

--------------------------------

### Execute Lisp form

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Invocation.html

Run standard Emacs Lisp code directly within the Eshell prompt.

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

--------------------------------

### Combine command and Lisp forms

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Invocation.html

Use a Lisp form to dynamically generate an argument for a command form.

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

--------------------------------

### substitute new old seq [option]...

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Extra-built_002din-commands.html

A wrapper around the function cl-substitute. This command can be used for comparing lists of strings.

```APIDOC
## substitute new old seq [option]...

### Description
A wrapper around the function cl-substitute. This command can be used for comparing lists of strings.

### Method
Eshell command

### Endpoint
substitute new old seq [option]...

### Parameters
- **new** - Required - The new element to substitute.
- **old** - Required - The old element to replace.
- **seq** - Required - The sequence to modify.
- **option**... - Optional - Additional options as accepted by cl-substitute.
```

--------------------------------

### Temporarily set environment variables for a single command

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Variables.html

Shows the equivalent of 'name=value command ...' in Eshell, which temporarily sets an environment variable for a single command by wrapping it in a block that exports the variable and then runs the command.

```eshell
{
  export name=value
  command ...
}
```

--------------------------------

### Pipe standard output with |

Source: https://www.gnu.org/software/emacs/manual/html_node/eshell/Pipelines.html

Sends the standard output of the echo command to the input of the rev command.

```shell
~ $ echo hello | rev
olleh
```
Tokens:
Raw