branch: externals/dtache
commit eefc2833b1956099d7cecbbe9fd17b4fe2ea4f3d
Author: Niklas Eklund <niklas.ekl...@posteo.net>
Commit: Niklas Eklund <niklas.ekl...@posteo.net>
Update README
---
README.md | 503 +++++++++++++++++++++-----------------------------------------
1 file changed, 171 insertions(+), 332 deletions(-)
diff --git a/README.md b/README.md
index 090a639d02..1ed2a32c7b 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,39 @@
-# Detach Emacs
+# detached.el
-<a href="http://elpa.gnu.org/packages/dtache.html";><img alt="GNU ELPA"
src="https://elpa.gnu.org/packages/dtache.svg"/></a>
-<a href="http://elpa.gnu.org/devel/dtache.html";><img alt="GNU-devel ELPA"
src="https://elpa.gnu.org/devel/dtache.svg"/></a>
-<a href="https://melpa.org/#/dtache";><img alt="MELPA"
src="https://melpa.org/packages/dtache-badge.svg"/></a>
-<a href="https://stable.melpa.org/#/dtache";><img alt="MELPA Stable"
src="https://stable.melpa.org/packages/dtache-badge.svg"/></a>
-<a
href="https://builds.sr.ht/~niklaseklund/dtache/commits/main/.build.yml";><img
alt="Build"
src="https://builds.sr.ht/~niklaseklund/dtache/commits/main/.build.yml.svg"/></a>
+<a href="http://elpa.gnu.org/packages/detached.html";><img alt="GNU ELPA"
src="https://elpa.gnu.org/packages/detached.svg"/></a>
+<a href="http://elpa.gnu.org/devel/detached.html";><img alt="GNU-devel ELPA"
src="https://elpa.gnu.org/devel/detached.svg"/></a>
+<a href="https://melpa.org/#/detached";><img alt="MELPA"
src="https://melpa.org/packages/detached-badge.svg"/></a>
+<a href="https://stable.melpa.org/#/detached";><img alt="MELPA Stable"
src="https://stable.melpa.org/packages/detached-badge.svg"/></a>
+<a
href="https://builds.sr.ht/~niklaseklund/detached.el/commits/main/.build.yml";><img
alt="Build"
src="https://builds.sr.ht/~niklaseklund/detached.el/commits/main/.build.yml.svg"/></a>
# Introduction
-Dtache is a package to run, and interact with, shell commands that are
completely detached from Emacs itself. The package achieves this functionality
by launching the commands with the program
[dtach](https://github.com/crigler/dtach). Even though the commands are run
decoupled, the package makes sure the integration to Emacs is seamless. The
advantage is that the processes are insensitive to Emacs being killed, and this
holds true for remote hosts as well, essentially making `dtache` a [...]
+`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](https://github.com/crigler/dtach), in order to
make this functionality possible.
-Another advantage of `dtache` is that in order to implement the detached
feature it actually represents the processes as text inside of Emacs. This
enables features such as history of all session outputs, possibility to diff
session outputs etc.
+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 following videos about `dtache`. They are currently a bit outdated but the
core concept is still true.
+The package supports integration with multiple packages, here is a list of the
built-in packages that are supported:
-- [Dtache - An Emacs package that provides detachable shell
commands](https://www.youtube.com/watch?v=if1W58SrClk)
-- [Dtache - Version 0.2](https://www.youtube.com/watch?v=De5oXdnY5hY)
+- `shell`
+- `eshell`
+- `compile`
+- `org`
+- `dired`
-## Features
+# Features
-The way `dtache` is designed with its `dtache-session` objects opens up the
possibilities for the following features.
+Since a `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:
-### Output
-
-The user always have access to the session's output. The user never needs to
fear that the output history of the terminal is not enough to capture all of
its output. Also its pretty handy to be able to go back in time and see the
output from a session you ran earlier today. Having access to the output as
well as the other information from the session makes it possible to compile a
session using Emacs built in functionality. This enables navigation between
errors in the output as well as [...]
-
-### Notifications
-
-Start a session and then focus on something else. `Dtache` will notify you
when the session has become inactive.
-
-### Metadata
-
-The session always contain metadata, such as when the session was started, for
how long it has been running (if it is active), how long it ran (if it is
inactive).
-
-### Annotations
-
-Arbitrary metadata can be captured when a session is started. An example
further down is how to leverage this feature to capture the git branch for a
session.
-
-### Remote
-
-Proper support for running session on a remote host. See the `Remote suppport`
section of the README for further details on how to configure `dtache` to work
for a remote host.
-
-### Actions
-
-The package provides commands that can act on a session. There is the
functionality to `kill` an active session, to `rerun` a session, or `diff` two
sessions.
-
-### Persistent
-
-The sessions are made persistent by writing the `dtache-session` objects to
file. This makes it possible for Emacs to resume the knowledge of prior
sessions when Emacs is restarted.
+- `Unlimited scrollback:` All the output from a `detached-session` is always
accessible
+- `Remote support:` Full support for running on remote hosts. See `Remote
support` section 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-env`
it 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:
+ + `kill` a an active session
+ + `rerun` a session
+ + `copy` the output of a session
+ + `diff` the output of two different sessions
# Installation
@@ -55,146 +41,118 @@ The package is available on [GNU
ELPA](https://elpa.gnu.org) and [MELPA](https:/
# Configuration
-The prerequisite for `dtache` is that the user has the program `dtach`
installed.
+The prerequisite for `detached.el` is that the user has the program `dtach`
installed.
## Use-package example
-A minimal configuration for `dtache`.
+A minimal `use-package` configuration.
``` emacs-lisp
-(use-package dtache
- :defer t
- :hook ((shell-mode . dtache-shell-mode))
- :bind (([remap async-shell-command] . dtache-shell-command))
- :custom ((dtache-show-output-on-attach t)))
+(use-package detached
+ :init
+ (detached-init)
+ :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>")
+ (detached-show-output-on-attach t)
+ (detached-shell-history-file "~/.bash_history")))
```
-# Commands
+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:
+
+- `compile`
+- `dired`
+- `dired-rsync`
+- `embark`
+- `eshell`
+- `org`
+- `projectile`
+- `shell`
+- `vterm`
-## Creating a session
+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.
-There are tree different ways to create a dtache session.
+However if you do want to disable the integration with a specific package, or
enable for a subset of the packages use the variables
`detached-init-allow-list` or `detached-init-block-list`.
-| Function | Description |
-|----------------------------|-------------------------------|
-| `dtache-shell-command` | Called from M-x |
-| `dtache-shell-send-input` | Called from inside M-x shell |
-| `dtache-eshell-send-input` | Called from inside eshell |
-| `dtache-compile` | Called from M-x |
-| `dtache-org` | Used in org-babel src blocks |
-| `dtache-start-session` | Called from within a function |
+# Usage
-The `dtache-shell-command` is for the Emacs users that are accustomed to
running shell commands from `M-x shell-command` or `M-x async-shell-command`.
The `dtache-shell-send-input` is for those that want to run a command through
`dtache` when inside a `shell` buffer. The `dtache-eshell-send-input` is the
equivalent for `eshell`. The `dtache-compile` is supposed to be used as a
replacement for `compile`. The `dtache-org` provides integration with
`org-babel` in order to execute shell sour [...]
+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
-To detach from a `dtache` session you should use the universal
`dtache-detach-session` command. The keybinding for this command is defined by
the `dtache-detach-key` variable, which by default has the value `C-c C-d`.
+In the integration of `detached.el` with other packages these commands are
always existent, with the exception for `org-mode`.
-## Interacting with a session
+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 `C-c C-d`.
-To interact with a session `dtache` provides the command
`dtache-open-session`. This provides a convenient completion interface,
enriched with annotations to provide useful information about the sessions. The
`dtache-open-session` command is implemented as a do what I mean command. This
results in `dtache` 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 se [...]
+## General
-The actions are controlled by the customizable variables named
`dtache-.*-session-action`. They come preconfigured but if you don't like the
behavior of `dtache-open-session` these variables allows for tweaking the
experience.
+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 configura [...]
+
+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.
- If the session is `active`, call the sessions `attach` function
- If the session is `inactive` call the sessions `view` function, which by
default performs a post-compile on the session if its status is `failure`
otherwise the sessions raw output is opened.
The package also provides additional commands to interact with a session.
-| Command (Keybinding) | Description
|
-|-----------------------------------|---------------------------------------------|
-| dtache-view-session (v) | View a session's output
|
-| dtache-attach-session (a) | Attach to a session
|
-| dtache-tail-session (t) | Tail the output of an active session
|
-| dtache-diff-session (=) | Diff a session with another session
|
-| dtache-compile-session (c) | Open the session output in compilation
mode |
-| dtache-rerun-session (r) | Rerun a session
|
-| dtache-insert-session-command (i) | Insert the session's command at point
|
-| dtache-copy-session-command (w) | Copy the session's shell command
|
-| dtache-copy-session (W) | Copy the session's output
|
-| dtache-kill-session (k) | Kill an active session
|
-| dtache-delete-session (d) | Delete an inactive session
|
-
-These commands are available through the `dtache-action-map`. The user can
bind the action map to a keybinding of choice. For example
+| 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
``` emacs-lisp
-(global-set-key (kbd "C-c d") dtache-action-map)
+(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. See further
down in the document how to integrate these bindings with `embark`.
-
-# Extensions
+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.
-## Shell
+## Shell command
-A `use-package` configuration of the `dtache-shell` extension, which provides
the integration with `M-x shell`.
+The `detached-shell-command` is for the Emacs users that are accustomed to
running shell commands from `M-x shell-command` or `M-x async-shell-command`.
-``` emacs-lisp
-(use-package dtache-shell
- :after shell
- :init
- (advice-add 'shell :around #'dtache-shell-override-history)
- (add-hook 'shell-mode-hook #'dtache-shell-save-history-on-kill)
- :custom (dtache-shell-history-file "~/.bash_history"))
-```
+## Shell
-A minor mode named `dtache-shell-mode` is provided, and will be enabled in
`shell`. The commands that are implemented are:
+A minor mode named `detached-shell-mode` is provided, and will be enabled in
`shell`. The commands that are implemented are:
-| Command | Description | Keybinding
|
-|-----------------------------|------------------------------|-------------------|
-| dtache-shell-send-input | Run command with dtache | <S-return>
|
-| dtache-shell-attach-session | Attach to a dtache session | <C-return>
|
-| dtache-detach-session | Detach from a dtache session |
dtache-detach-key |
+| Command | Description | Keybinding
|
+|-------------------------------|--------------------------------|---------------------|
+| detached-shell-send-input | Run command with detached | <S-return>
|
+| detached-shell-attach-session | Attach to a detached session | <C-return>
|
+| detached-detach-session | Detach from a detached session |
detached-detach-key |
## Eshell
-A `use-package` configuration of the `dtache-eshell` extension, which provides
the integration with `eshell`.
-
-``` emacs-lisp
-(use-package dtache-eshell
- :defer t
- :hook ((eshell-mode . dtache-eshell-mode)))
-```
-
-A minor mode named `dtache-eshell-mode` is provided, and will be enabled in
`eshell`. The commands that are implemented are:
-
-| Command | Description | Keybinding
|
-|------------------------------|------------------------------|-------------------|
-| dtache-eshell-send-input | Run command with dtache | <S-return>
|
-| dtache-eshell-attach-session | Attach to a dtache session | <C-return>
|
-| dtache-detach-session | Detach from a dtache session |
dtache-detach-key |
-
-In this [blog post](https://niklaseklund.gitlab.io/blog/posts/dtache_eshell/)
there are examples and more information about the extension.
-
-## Compile
-
-A `use-package` configuration of the `dtache-compile` extension, which
provides the integration with `compile`.
-
-``` emacs-lisp
-(use-package dtache-compile
- :defer t
- :bind (([remap compile] . dtache-compile)
- ([remap recompile] . dtache-compile-recompile))
- :hook ((compilation-start . dtache-compile-start)
- (compilation-shell-minor-mode . dtache-shell-mode)))
-```
-
-The package implements the commands `dtache-compile` and
`dtache-compile-recompile`, which are thin wrappers around the original
`compile` and `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 `detach`.
+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 | <S-return>
|
+| detached-eshell-attach-session | Attach to a detached session | <C-return>
|
+| detached-detach-session | Detach from a detached session |
detached-detach-key |
-## Org
-
-A `use-package` configuration of the `dtache-org` extension, which provides
the integration with `org-babel`.
-
-``` emacs-lisp
-(use-package dtache-org
- :after ob
- :init
- (advice-add #'org-babel-sh-evaluate :around #'dtache-org-babel-sh))
-```
+## Org babel
-The package implements an additional header argument for `ob-shell`. The
header argument is `:dtache t`. When provided it will enable the code inside a
src block to be run with `dtache`. Since org is not providing any live updates
on the output the session is created with `dtache-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 `dtache-org` works both
with and without the `: [...]
+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 wit [...]
```
-#+begin_src sh :dtache t
+#+begin_src sh :detached t
cd ~/code
ls -la
#+end_src
@@ -203,17 +161,13 @@ The package implements an additional header argument for
`ob-shell`. The header
: [detached]
```
-## Consult
+## Compile
-A `use-package` configuration of the `dtache-consult` extension, which
provides the integration with the [consult](https://github.com/minad/consult)
package.
+The package implements the commands `detached-compile` and
`detached-compile-recompile`, which are thin wrappers around the original
`compile` and `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 `detach`.
-``` emacs-lisp
-(use-package dtache-consult
- :after dtache
- :bind ([remap dtache-open-session] . dtache-consult-session))
-```
+## Consult
-The command `dtache-consult-session` is a replacement for
`dtache-open-session`. The difference is that the consult command provides
multiple session sources, which is defined in the `dtache-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:
+The command `detached-consult-session` is a replacement for
`detached-open-session` using the [consult](https://github.com/minad/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 [...]
| Type | Key |
|-----------------------+-----|
@@ -225,82 +179,80 @@ The command `dtache-consult-session` is a replacement for
`dtache-open-session`.
| Remote host sessions | r |
| Current host sessions | c |
-Examples of the different sources are featured in this [blog
post](https://niklaseklund.gitlab.io/blog/posts/dtache_consult/).
-
# Customization
## Customizable variables
The package provides the following customizable variables.
-| Name | Description
|
-|------------------------------------|---------------------------------------------------------------------------|
-| dtache-session-directory | A host specific directory to store
sessions in |
-| dtache-db-directory | A localhost specific directory to store
the database |
-| dtache-dtach-program | Name or path to the `dtach` program
|
-| dtache-shell-program | Name or path to the `shell` that
`dtache` should use |
-| dtache-timer-configuration | Configuration of the timer that runs on
remote hosts |
-| dtache-env | Name or path to the `dtache-env` script
|
-| dtache-annotation-format | A list of annotations that should be
present in completion |
-| dtache-command-format | A configuration for displaying a
session command |
-| dtache-tail-interval | How often `dtache` should refresh the
output when tailing |
-| dtache-nonattachable-commands | A list of commands that should be
considered nonattachable |
-| dtache-notification-function | Specifies which function to issue
notifications with |
-| dtache-detach-key | Specifies which keybinding to use to
detach from a session |
-| dtache-shell-command-initial-input | Enables latest value in history to be
used as initial input |
-| dtache-filter-ansi-sequences | Specifies if dtache will use ansi-color
to filter out escape sequences |
-| dtache-show-output-command | Specifies if dtache should show the
session's output when attaching to it |
+| 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 `shell` that
`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
|
-|-------------------------------------|---------------------------------------------------------------|
-| dtache-shell-command-session-action | Actions for sessions launched with
`dtache-shell-command` |
-| dtache-eshell-session-action | Actions for sessions launched with
`dtache-eshell-send-input` |
-| dtache-shell-session-action | Actions for sessions launched with
`dtache-shell-send-input` |
-| dtache-compile-session-action | Actions for sessions launched with
`dtache-compile` |
-| dtache-org-session-action | Actions for sessions launched with
`dtache-org` |
+| Name | Description
|
+|---------------------------------------|-----------------------------------------------------------------|
+| detached-shell-command-session-action | Actions for sessions launched with
`detached-shell-command` |
+| detached-eshell-session-action | Actions for sessions launched with
`detached-eshell-send-input` |
+| detached-shell-session-action | Actions for sessions launched with
`detached-shell-send-input` |
+| detached-compile-session-action | Actions for sessions launched with
`detached-compile` |
+| detached-org-session-action | Actions for sessions launched with
`detached-org` |
## Remote support
-The `dtache` package supports [Connection Local
Variables](https://www.gnu.org/software/emacs/manual/html_node/elisp/Connection-Local-Variables.html)
which allows the user to customize the variables used by `dtache` when running
on a remote host. This example shows how the following variables are customized
for all remote hosts.
+The `detached.el` supports [Connection Local
Variables](https://www.gnu.org/software/emacs/manual/html_node/elisp/Connection-Local-Variables.html)
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-dtache
- '((dtache-env . "~/bin/dtache-env")
- (dtache-shell-program . "/bin/bash")
- (dtache-shell-history-file . "~/.bash_history")
- (dtache-session-directory . "~/tmp")
- (dtache-dtach-program . "/home/user/.local/bin/dtach")))
+ '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-dtache)
+ '(:application tramp :protocol "ssh") 'remote-detached)
```
## Completion annotations
-Users can customize the appearance of annotations in `dtache-open-session` by
modifying the `dtache-annotation-format`. The default annotation format is the
following.
+Users can customize the appearance of annotations in `detached-open-session`
by modifying the `detached-annotation-format`. The default annotation format is
the following.
``` emacs-lisp
-(defvar dtache-annotation-format
- `((:width 3 :function dtache--state-str :face dtache-state-face)
- (:width 3 :function dtache--status-str :face dtache-failure-face)
- (:width 10 :function dtache--host-str :face dtache-host-face)
- (:width 40 :function dtache--working-dir-str :face dtache-working-dir-face)
- (:width 30 :function dtache--metadata-str :face dtache-metadata-face)
- (:width 10 :function dtache--duration-str :face dtache-duration-face)
- (:width 8 :function dtache--size-str :face dtache-size-face)
- (:width 12 :function dtache--creation-str :face dtache-creation-face))
+(defvar detached-annotation-format
+ `((: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.")
```
## Status deduction
-Users are encouraged to define the `dtache-env` variable. It should point to
the `dtache-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 `dtache` will be able to set the status of a
session to either `success` or `failure`.
+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 `success` or `failure`.
``` emacs-lisp
-(setq dtache-env "/path/to/repo/dtache-env")
+(setq detached-env "/path/to/repo/detached-env")
```
## Metadata annotators
@@ -308,7 +260,7 @@ Users are encouraged to define the `dtache-env` variable.
It should point to the
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.
``` emacs-lisp
-(defun my/dtache--session-git-branch ()
+(defun my/detached--session-git-branch ()
"Return current git branch."
(let ((git-directory (locate-dominating-file "." ".git")))
(when git-directory
@@ -318,183 +270,69 @@ The user can configure any number of annotators to run
upon creation of a sessio
(string-trim (buffer-string)))))))
```
-Next add the annotation function to the `dtache-metadata-annotators-alist`
together with a symbol describing the property.
+Next add the annotation function to the `detached-metadata-annotators-alist`
together with a symbol describing the property.
``` emacs-lisp
-(setq dtache-metadata-annotators-alist '((branch .
my/dtache--session-git-branch))
+(setq detached-metadata-annotators-alist '((branch .
my/detached--session-git-branch))
```
## Nonattachable commands
-To be able to both attach to a dtach session as well as logging its output
`dtache` 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.
+To be able to both attach to a dtach session as well as logging its output
`detached` 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 `dtache` provides the `dtache-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.
+For these situations `detached` 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.
``` emacs-lisp
-(setq dtache-nonattachable-commands '("^ls"))
+(setq detached-nonattachable-commands '("^ls"))
```
Here a command beginning with `ls` would from now on be considered
nonattachable.
## Colors in sessions
-Dtache needs to use a trick to get programs programs such as `git` or `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 `dtache-env` therefore has two different modes. The mode can be either
`plain-text` or `terminal-data`, the latter is now the default. The
`dtache-env` program then uses the `script` command to make programs run in
`dtache` think they are inside of a ful [...]
+The package needs to use a trick to get programs programs such as `git` or
`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 `plain-text` or `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 i [...]
-The drawback is that there can be commands which generates escape sequences
that `dtache` 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 `dtache-env-plain-text-commands`. By doing so `dtache`
will instruct `dtache-env` to run those commands in plain-text mode.
-
-``` emacs-lisp
-(setq dtache-env-plain-text-commands '(".*"))
-```
+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.
# Tips & Tricks
-## 3rd party extensions
-
-### Embark
+The `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.
-The user have the possibility to integrate `dtache` with the package
[embark](https://github.com/oantolin/embark/). The `dtache-action-map` can be
reused for this purpose, so the user doesn't need to bind it to any key.
Instead the user simply adds the following to their `dtache` configuration in
order to get embark actions for `dtache-open-session`.
+## Alert
-``` emacs-lisp
-(defvar embark-dtache-map (make-composed-keymap dtache-action-map
embark-general-map))
-(add-to-list 'embark-keymap-alist '(dtache . embark-dtache-map))
-```
-
-### Alert
-
-By default `dtache` 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 `dtache-notification-function` to
`dtache-state-transitionion-echo-message` to use the echo area instead. If that
doesn't suffice there is the possibility to use the
[alert](https://github.com/jwiegley/alert) package to get a system notification
instead.
+By default `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-notification-function` to
`detached-state-transition-echo-message` to use the echo area instead. If that
doesn't suffice there is the possibility to use the
[alert](https://github.com/jwiegley/alert) package to get a system notification
instead.
``` emacs-lisp
-(defun my/dtache-state-transition-alert-notification (session)
+(defun my/state-detached-transition-alert-notification (session)
"Send an `alert' notification when SESSION becomes inactive."
- (let ((status (car (dtache--session-status session)))
- (host (car (dtache--session-host session))))
- (alert (dtache--session-command session)
+ (let ((status (car (detached--session-status session)))
+ (host (car (detached--session-host session))))
+ (alert (detached--session-command session)
:title (pcase status
- ('success (format "Dtache finished [%s]" host))
- ('failure (format "Dtache failed [%s]" host)))
+ ('success (format "Detached finished [%s]" host))
+ ('failure (format "Detached failed [%s]" host)))
:severity (pcase status
('success 'moderate)
('failure 'high)))))
-(setq dtache-notification-function
#'my/dtache-state-transition-alert-notification)
-```
-
-### Projectile
-
-The package can be integrated with
[projectile](https://github.com/bbatsov/projectile), by overriding its
compilation command in the following fashion.
-
-``` emacs-lisp
-(defun my/dtache-projectile-run-compilation (cmd &optional use-comint-mode)
- "If CMD is a string execute it with `dtache-compile', optionally
USE-COMINT-MODE."
- (if (functionp cmd)
- (funcall cmd)
- (let ((dtache-session-origin 'projectile))
- (dtache-compile cmd use-comint-mode))))
-
-(advice-add 'projectile-run-compilation :override
#'my/dtache-projectile-run-compilation)
+(setq detached-notification-function
#'my/detached-state-transition-alert-notification)
```
-### Vterm
-
-The package can be integrated with the
[vterm](https://github.com/akermu/emacs-libvterm) package. This is for users
that want `dtache` to run in a terminal emulator.
-
-``` emacs-lisp
-(use-package vterm
- :defer t
- :bind (:map vterm-mode-map
- ("<S-return>" . #'dtache-vterm-send-input)
- ("<C-return>" . #'dtache-vterm-attach)
- ("C-c C-d" . #'dtache-vterm-detach))
- :config
-
- (defun dtache-vterm-send-input (&optional detach)
- "Create a `dtache' session."
- (interactive)
- (vterm-send-C-a)
- (let* ((input (buffer-substring-no-properties (point) (vterm-end-of-line)))
- (dtache-session-origin 'vterm)
- (dtache-session-action
- '(:attach dtache-shell-command-attach-session
- :view dtache-view-dwim
- :run dtache-shell-command))
- (dtache-session-mode
- (if detach 'create 'create-and-attach)))
- (vterm-send-C-k)
- (process-send-string vterm--process (dtache-dtach-command input t))
- (vterm-send-C-e)
- (vterm-send-return)))
-
- (defun dtache-vterm-attach (session)
- "Attach to an active `dtache' session."
- (interactive
- (list
- (let* ((host-name (car (dtache--host)))
- (sessions
- (thread-last (dtache-get-sessions)
- (seq-filter (lambda (it)
- (string= (car (dtache--session-host
it)) host-name)))
- (seq-filter (lambda (it) (eq 'active
(dtache--determine-session-state it)))))))
- (dtache-completing-read sessions))))
- (let ((dtache-session-mode 'attach))
- (process-send-string vterm--process (dtache-dtach-command session t))
- (vterm-send-return)))
-
- (defun dtache-vterm-detach ()
- "Detach from a `dtache' session."
- (interactive)
- (process-send-string vterm--process dtache--dtach-detach-character)))
-```
-
-### Dired
-
-Dtache can be used to run async commands in `dired`, with all of dired's
special features for inserting filenames an working with marked files.
-
-``` emacs-lisp
-(defun my/dtache-dired-do-shell-command (dired-do-shell-command &rest args)
- "Make sure `dtache' is used before running DIRED-DO-SHELL-COMMAND with ARGS."
- (cl-letf* ((dtache-session-origin 'dired)
- ((symbol-function #'dired-run-shell-command)
- (lambda (command)
- (dtache-start-session command)
- nil)))
- (apply dired-do-shell-command args)))
-
-(advice-add 'dired-do-shell-command :around #'my/dtache-dired-do-shell-command)
-```
-
-### Dired-rsync
-
-The [dired-rsync](https://github.com/stsquad/dired-rsync) is a package to run
[rsync](https://linux.die.net/man/1/rsync) commands from within `dired`. Its a
perfect package to integrate with `dtache` since it typically requires some
time to run and you don't want to have your Emacs limited by that process.
-
-``` emacs-lisp
-(defun my/dtache-dired-rsync (command _details)
- "Run COMMAND with `dtache'."
- (let ((dtache-local-session t)
- (dtache-session-origin 'rsync))
- (dtache-start-session command t)))
-
-(advice-add #'dired-rsync--do-run :override #'my/dtache-dired-rsync)
-```
-
-The above code block shows how to make `dired-rsync` use `dtache`.
-
# Versions
Information about larger changes that has been made between versions can be
found in the `CHANGELOG.org`
# Support
-The `dtache` package should work on `Linux` and `macOS`. It is regularly
tested on `Ubuntu` and `GNU Guix System`.
+The `detached.el` package should work on `Linux` and `macOS`. It is regularly
tested on `Ubuntu` and `GNU Guix System`.
# Contributions
The package is part of [ELPA](https://elpa.gnu.org/) which means that if you
want to contribute you must have a [copyright
assignment](https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html).
-
# Acknowledgments
This package wouldn't have been were it is today without these contributors.
-
## Code contributors
- [rosetail](https://gitlab.com/rosetail)
@@ -502,7 +340,8 @@ This package wouldn't have been were it is today without
these contributors.
## Idea contributors
-- [rosetail](https://gitlab.com/rosetail) for all the great ideas and
improvements to the package. Without those contributions `dtache` would be a
less sophisticated package.
-- [Troy de Freitas](https://gitlab.com/ntdef) for solving the problem of
getting `dtache` to work with `filenotify` on macOS.
-- [Daniel Mendler](https://gitlab.com/minad) for helping out in improving
`dtache`, among other things integration with other packages such as `embark`
and `consult`.
+- [rosetail](https://gitlab.com/rosetail) for all the great ideas and
improvements to the package. Without those contributions `detached.el` would be
a less sophisticated package.
+- [Troy de Freitas](https://gitlab.com/ntdef) for solving the problem of
getting `detached.el` to work with `filenotify` on macOS.
+- [Daniel Mendler](https://gitlab.com/minad) for helping out in improving
`detached.el`, among other things integration with other packages such as
`embark` and `consult`.
- [Ambrevar](https://gitlab.com/ambrevar) who indirectly contributed by
inspiring me with his [yes eshell is my main
shell](https://www.reddit.com/r/emacs/comments/6y3q4k/yes_eshell_is_my_main_shell/).
It was through that I discovered his
[package-eshell-detach](https://github.com/Ambrevar/dotfiles/blob/master/.emacs.d/lisp/package-eshell-detach.el)
which got me into the idea of using `dtach` as a base for detached shell
commands.
+
![https://elpa.gnu.org/packages/dtache.svg"/](https://elpa.gnu.org/packages/dtache.svg"/){kind=link}
![https://elpa.gnu.org/devel/dtache.svg"/](https://elpa.gnu.org/devel/dtache.svg"/){kind=link}
![https://melpa.org/packages/dtache-badge.svg"/](https://melpa.org/packages/dtache-badge.svg"/){kind=link}
![https://stable.melpa.org/packages/dtache-badge.svg"/](https://stable.melpa.org/packages/dtache-badge.svg"/){kind=link}
![https://builds.sr.ht/~niklaseklund/dtache/commits/main/.build.yml.svg"/](https://builds.sr.ht/~niklaseklund/dtache/commits/main/.build.yml.svg"/){kind=link}
![https://elpa.gnu.org/packages/detached.svg"/](https://elpa.gnu.org/packages/detached.svg"/){kind=link}
![https://elpa.gnu.org/devel/detached.svg"/](https://elpa.gnu.org/devel/detached.svg"/){kind=link}
![https://melpa.org/packages/detached-badge.svg"/](https://melpa.org/packages/detached-badge.svg"/){kind=link}
![https://stable.melpa.org/packages/detached-badge.svg"/](https://stable.melpa.org/packages/detached-badge.svg"/){kind=link}
![https://builds.sr.ht/~niklaseklund/detached.el/commits/main/.build.yml.svg"/](https://builds.sr.ht/~niklaseklund/detached.el/commits/main/.build.yml.svg"/){kind=link}