The em script runs emacs(1) and/or emacsclient(1) as appropriate per
given command-line arguments. For interactive sessions, emacs(1) is
started in daemon mode as necessary prior to running emacsclient(1).
When running Emacs in multiple virtual/pseudo terminals (e.g., via ssh(1)), each terminal requires a separate Emacs daemon for I/O. The em script attempts to address this via a heuristic by setting a unique server name for each terminal.
Invoking em with multiple FILE arguments opens, by default,
FILEs in the top-most frame either sequentially, via the
server-edit (C-x #) command, or randomly, via switch-to-buffer
(C-x b).
In addition to command-line options from either emacs(1) or emacsclient(1),
the following options are recognized:
| OPTION | DESCRIPTION |
|---|---|
| --buffer[=BUF] | Visit buffer BUF if given, otherwise *scratch*. |
| --dired[=DIR] | Visit directory DIR if given, otherwise .. |
| --markdown, -md=FILE | Visit FILE in mode markdown-live-preview-mode. |
| --new-frame | Visit FILEs in a new frame. |
| --preload-files | Load FILEs in parallel, but visit one at a time. |
| --many-frames | Visit FILEs in parallel, each in its own frame. |
| --save-kill | Save buffers and kill Emacs and Emacs server. |
| --ssh=[USER@]HOST[:PATH] | Visit PATH on remote HOST via SSH. |
| --ssu=[USER@]HOST[:PATH] | Visit PATH with SUDO on remote HOST via SSH. |
| --super-user | Visit FILEs with root privileges via tramp. |
| --trace | Trace execution of em script. |
| --two-way-merge=F1,F2[,OUT] | Call emerge-files with file args F1 and F2. |
| --update-loaddefs[=DIR] | Build autoload file DIR-loaddefs.el. |
| --wait | Run emacsclient(1) in foreground. |
Options may be abbreviated (e.g., -new instead of --new-frame)
provided they are unambiguous.
If em is invoked with either no command-line options or
emacsclient options only, then it runs as a background process and
switches focus to the Emacs server. Otherwise, Emacs-specific
command-line options (see emacs --help) force a new Emacs process
to be run in the foreground, allowing this script to be invoked,
e.g., in batch mode within a Makefile.
If the environment variable SSH_TTY is set and the SSH client and server
differ, then the command-line option--tty is enabled by default.
Similarly, if environment variable SUDO_USER is set and not equal to
USER, then command-line option --tty is enabled by default. Rather
than override this behavior, generally a better solution is to use
tramp mode. For example, if not logged in as user root, to edit
file /etc/hosts, use em -su /etc/hosts.
To kill the Emacs server, use em --save-kill, which can be shortened
to em -sa.
See also FAQ for troubleshooting.