To install this package, run in Emacs:
M-x package-install RET detached RET
detached.el is a package to launch, and manage, detached processes. The idea is that these processes are detached from the Emacs process and the package can make Emacs seamlessly attach to these processes. This enables users to launch processes that can survive when Emacs itself is being shutdown. The package relies on the program dtach, in order to make this functionality possible.
Internally the package transforms the detached process into a
detached-session object, which essentially is a text-based representation of the process. All
detached-session objects are stored in a lisp file, and the output of all sessions are captured into individual logs.
The package supports integration with multiple packages, here is a list of the built-in packages that are supported:
detached-session contain all the output of the process as well as data such as,
what command was run,
which directory the process was launched etc, it opens up the possibility for the following features:
Unlimited scrollback:All the output from a
detached-sessionis always accessible
Remote support:Full support for running on remote hosts. See
Remote supportsection of the README
Notifications:The package will monitor all detached sessions and notify when a session has finished
Post compilation: If the package has been configured to use
detached-envit will know the exit status of a session. That enables the package to post compile the output of a session to enable Emacs's built-in functionality of navigating between errors in the output.
Annotations:When selecting a session all are presented with a rich set of annotations
Actions:The package provides actions to act on a session:
killa an active session
copythe output of a session
diffthe output of two different sessions
The prerequisite for
detached.el is that the user has the program
:bind (;; Replace `async-shell-command' with `detached-shell-command'
([remap async-shell-command] . detached-shell-command)
;; Replace `compile' with `detached-compile'
([remap compile] . detached-compile)
([remap recompile] . detached-compile-recompile)
;; Replace built in completion of sessions with `consult'
([remap detached-open-session] . detached-consult-session))
:custom ((detached-env "<path_to_detached-env>")
The users are required to call
detached-init. This function orchestrates the integration with all other internal and external packages that
detached.el supports. These are:
All of the integration are configured to enable lazy-loading. Meaning that if you are not a user of
projectile that code that handles the integration will never load.
However if you do want to disable the integration with a specific package, or enable for a subset of the packages use the variables
The idea is that users can choose to either:
create: a detached session and attach to it
detach: from a detached session
attach: to a detached session
In the integration of
detached.el with other packages these commands are always existent, with the exception for
To detach from a
detached-session in any of the modes, use the universal
detached-detach-session command. The keybinding for this command is defined by the
detached-detach-key variable, which by default has the value
To interact with a session the package provides the command
detached-open-session. This provides a convenient completion interface, enriched with annotations to provide useful information about the sessions. The
detached-open-session command is implemented as a do what I mean command. This results in
detached.el performing different actions depending on the state of a session. The actions can be configured based on the
origin of the session. The user can have one set of configurations for sessions started in
shell which is different from those started in
The actions are controlled by the customizable variables named
detached-.*-session-action. They come preconfigured but if you don't like the behavior of
detached-open-session these variables allows for tweaking the experience.
active, call the sessions
inactivecall the sessions
viewfunction, which by default performs a post-compile on the session if its status is
failureotherwise the sessions raw output is opened.
The package also provides additional commands to interact with a session.
| Command (Keybinding) | Description | |-------------------------------------|---------------------------------------------| | detached-view-session (v) | View a session's output | | detached-attach-session (a) | Attach to a session | | detached-tail-session (t) | Tail the output of an active session | | detached-diff-session (=) | Diff a session with another session | | detached-compile-session (c) | Open the session output in compilation mode | | detached-rerun-session (r) | Rerun a session | | detached-insert-session-command (i) | Insert the session's command at point | | detached-copy-session-command (w) | Copy the session's shell command | | detached-copy-session (W) | Copy the session's output | | detached-kill-session (k) | Kill an active session | | detached-delete-session (d) | Delete an inactive session |
These commands are available through the
detached-action-map. The user can bind the action map to a keybinding of choice. For example
(global-set-key (kbd "C-c d") detached-action-map)
Then upon invocation the user can choose an action, keybindings listed in the table above, and then choose a session to perform the action upon. For those using
embark this will not be necessary as
detached-init sets up integration with embark actions.
detached-shell-command is for the Emacs users that are accustomed to running shell commands from
M-x shell-command or
A minor mode named
detached-shell-mode is provided, and will be enabled in
shell. The commands that are implemented are:
| Command | Description | Keybinding |
| detached-shell-send-input | Run command with detached |
A minor mode named
detached-eshell-mode is provided, and will be enabled in
eshell. The commands that are implemented are:
| Command | Description | Keybinding |
| detached-eshell-send-input | Run command with detached |
The package implements an additional header argument for
ob-shell. The header argument is
:detached t. When provided it will enable the code inside a src block to be run with
detached.el. Since org is not providing any live updates on the output the session is created with
detached-sesion-mode set to
create. This means that if you want to access the output of the session you do that the same way you would for any other type of session. The
detached-org works both with and without the
:session header argument.
cd ~/code ls -la
: [detached] ```
The package implements the commands
detached-compile-recompile, which are thin wrappers around the original
recompile commands. The users should be able to use the former as replacements for the latter without noticing any difference except from the possibility to
detached-consult-session is a replacement for
detached-open-session using the consult package. The difference is that the consult command provides multiple session sources, which is defined in the
detached-consult-sources variable. Users can customize which sources to use, as well as use individual sources in other
consult commands, such as
consult-buffer. The users can also narrow the list of sessions by entering a key. The list of supported keys are:
| Type | Key | |-----------------------+-----| | Active sessions | a | | Inactive sessions | i | | Successful sessions | s | | Failed sessions | f | | Local host sessions | l | | Remote host sessions | r | | Current host sessions | c |
The package provides the following customizable variables.
| Name | Description |
| detached-session-directory | A host specific directory to store sessions in |
| detached-db-directory | A localhost specific directory to store the database |
| detached-dtach-program | Name or path to the
dtach program |
| detached-shell-program | Name or path to the
detached.el should use |
| detached-timer-configuration | Configuration of the timer that runs on remote hosts |
| detached-env | Name or path to the
detached-env script |
| detached-annotation-format | A list of annotations that should be present in completion |
| detached-command-format | A configuration for displaying a session command |
| detached-tail-interval | How often
detached.el should refresh the output when tailing |
| detached-nonattachable-commands | A list of commands that should be considered nonattachable |
| detached-notification-function | Specifies which function to issue notifications with |
| detached-detach-key | Specifies which keybinding to use to detach from a session |
| detached-shell-command-initial-input | Enables latest value in history to be used as initial input |
| detached-filter-ansi-sequences | Specifies if
detached.el will use ansi-color to filter out escape sequences |
| detached-show-output-command | Specifies if
detached.el should show the session's output when attaching to it |
Apart from those variables there is also the different
action variables, which can be configured differently depending on the origin of the session.
| Name | Description |
| detached-shell-command-session-action | Actions for sessions launched with
| detached-eshell-session-action | Actions for sessions launched with
| detached-shell-session-action | Actions for sessions launched with
| detached-compile-session-action | Actions for sessions launched with
| detached-org-session-action | Actions for sessions launched with
detached.el supports Connection Local Variables which allows the user to customize the variables used by
detached.el when running on a remote host. This example shows how the following variables are customized for all remote hosts.
``` emacs-lisp (connection-local-set-profile-variables 'remote-detached '((detached-env . "~/bin/detached-env") (detached-shell-program . "/bin/bash") (detached-shell-history-file . "~/.bash_history") (detached-session-directory . "~/tmp") (detached-dtach-program . "/home/user/.local/bin/dtach")))
(connection-local-set-profiles '(:application tramp :protocol "ssh") 'remote-detached) ```
Users can customize the appearance of annotations in
detached-open-session by modifying the
detached-annotation-format. The default annotation format is the following.
`((:width 3 :function detached--state-str :face detached-state-face)
(:width 3 :function detached--status-str :face detached-failure-face)
(:width 10 :function detached--host-str :face detached-host-face)
(:width 40 :function detached--working-dir-str :face detached-working-dir-face)
(:width 30 :function detached--metadata-str :face detached-metadata-face)
(:width 10 :function detached--duration-str :face detached-duration-face)
(:width 8 :function detached--size-str :face detached-size-face)
(:width 12 :function detached--creation-str :face detached-creation-face))
"The format of the annotations.")
Users are encouraged to define the
detached-env variable. It should point to the
detached-env script, which is provided in the repository. This script allows sessions to communicate the status of a session when it transitions to inactive. When configured properly
detached.el will be able to set the status of a session to either
(setq detached-env "/path/to/repo/detached-env")
The user can configure any number of annotators to run upon creation of a session. Here is an example of an annotator which captures the git branch name, if the session is started in a git repository.
(defun my/detached--session-git-branch ()
"Return current git branch."
(let ((git-directory (locate-dominating-file "." ".git")))
(let ((args '("name-rev" "--name-only" "HEAD")))
(apply #'process-file `("git" nil t nil ,@args))
Next add the annotation function to the
detached-metadata-annotators-alist together with a symbol describing the property.
(setq detached-metadata-annotators-alist '((branch . my/detached--session-git-branch))
To be able to both attach to a dtach session as well as logging its output
detached.el relies on the usage of
tee. However it is possible that the user tries to run a command which involves a program that doesn't integrate well with tee. In those situations the output could be delayed until the session ends, which is not preferable.
For these situations
detached.el provides the
detached-nonattachable-commands variable. This is a list of regular expressions. Any command that matches any of the strings will be getting the property
attachable set to false.
(setq detached-nonattachable-commands '("^ls"))
Here a command beginning with
ls would from now on be considered nonattachable.
The package needs to use a trick to get programs programs such as
grep to show color in their outputs. This is because these commands only use colors and ansi sequences if they are being run in a terminal, as opposed to a pipe. The
detached-env therefore has two different modes. The mode can be either
terminal-data, the latter is now the default. The
detached-env program then uses the
script command to make programs run in
detached.el think they are inside of a full-featured terminal, and therefore can log their raw terminal data.
The drawback is that there can be commands which generates escape sequences that the package supports and will therefore mess up the output for some commands. If you detect such an incompatible command you can add a regexp that matches that command to the list
detached-env-plain-text-commands. By doing so
detached.el will instruct
detached-env to run those commands in plain-text mode.
detached.el package integrates with core Emacs packages as well as 3rd party packages. Integration is orchestrated in the
detached-init.el. In this section you can find tips for integrations that are not supported in the package itself.
detached.el uses the built in
notifications library to issue a notification. This solution uses
dbus but if that doesn't work for the user there is the possibility to set the
detached-state-transition-echo-message to use the echo area instead. If that doesn't suffice there is the possibility to use the alert package to get a system notification instead.
(defun my/state-detached-transition-alert-notification (session)
"Send analert' notification when SESSION becomes inactive."
(let ((status (car (detached--session-status session)))
(host (car (detached--session-host session))))
(alert (detached--session-command session)
:title (pcase status
('success (format "Detached finished [%s]" host))
('failure (format "Detached failed [%s]" host)))
:severity (pcase status
(setq detached-notification-function #'my/detached-state-transition-alert-notification) ```
Information about larger changes that has been made between versions can be found in the
detached.el package should work on
macOS. It is regularly tested on
GNU Guix System.
This package wouldn't have been were it is today without these contributors.
detached.elwould be a less sophisticated package.
detached.elto work with
detached.el, among other things integration with other packages such as
dtachas a base for detached shell commands.
detached.el, source code has been moved to https://git.sr.ht/~niklaseklund/detached.el
dtache-init.eland move integration of other packages there. The integration now becomes even simpler for users of
dtacheto enable the package to lazy load and not force users to load it when starting Emacs.
dtache-command-formathas been added, this supersedes the
dtache-env. The package will now control which mode
dtache-envshould be run in. The mode is either
terminal-data. The latter is enabled by default and allows
dtacheto capture control sequences for e.g. colored output. This update will require users to update their
dtachewill no longer run if commands are
ansi-colorto handle ANSI escape sequences. This feature is enabled by default but can be turned of if
dtache-filter-ansi-sequencesis set to nil.
dtache-orgextension. This makes it possible to use
org-babel(shell) source code blocks.
dtachesession is created, it will now become visible in all active Emacs sessions.
dtachetakes care of setting up the keybindings for its users. The detach key can be customized through
dtachenow has full on macOS. The previous issue of not being able to utilize
filenotifyhas been resolved.
notificationslibrary to issue notifications by default.
filenotifyfor notifications except on local macOS hosts.
filenotifyfor both local and remote sessions. If run on
macOStimers are used both for local as well as remote sessions.
dtache-sessionobjects. This makes dtache not break whenever non-backwards compatible changes are made to the dtache-session object.
dtache-detach-session. This command is supposed to be used to detach from sessions in all supported modes.
dtache-compile.el. This library provides commands
dtache-compile-recompilewhich are supposed to be used instead of
dtache-shell-command, the command is now very similar to
async-shell-commandand can be considered a replacement of the latter.
dtache-open-session, the package is ready to harmonize the user interface. This means deprecating