eshell-atuin

Integrate eshell with atuin.

atuin stores shell history in a database, which allows for having the same history across multiple shells, sessions, and optionally across different machines. See the project page for the complete list of features.

This package provides functionality to store and browse eshell history in atuin.

Installation

The package is available on MELPA. Install it however you normally install packages, I prefer use-package and straight.el:

(use-package eshell-atuin
  :straight t
  :after eshell
  :config
  (eshell-atuin-mode))

Alternatively, clone the repository, add it to the load-path, and require the package.

If your version of atuin is less than 18, turn off saving command durations:

(setq eshell-atuin-save-duration nil)

Configuration

If your atuin binary is located in a place unknown to executable-find, set the atuin-executable variable.

If you are using a vertical completion system such as Ivy, Selectrum, etc., you can configure the completion interface, e.g.:

(setq eshell-atuin-search-fields '(time duration command))
(setq eshell-atuin-history-format "%-160c %t + %d")

The available flags are:

Flag	atuin field (see `help atuin search`)	Required
%t	`time`	+
%c	`command`	+
%e	`exit`
%d	`duration`
%i	`directory`
%u	`user`
%h	`host`
%r	`relativetime`

See (emacs) Custom Format Strings for information on the general format-spec syntax.

I suspect the package might be slow if your history has a lot of records (I haven’t checked yet). In this case, it might be worth setting a limit:

(setq eshell-atuin-search-options '("--exit" "0" "--limit" "10000"))

Usage

Enable eshell-atuin-mode to turn on storing eshell commands in atuin.

Run eshell-atuin-history inside an eshell buffer to browse the saved history. Accepting the completion will insert the command.

Filter mode

atuin supports 4 filter modes: global (default), host, session, directory. Default filter mode for eshell-atuin can be set as follows:

(setq eshell-atuin-filter-mode 'global)

In order to switch the mode at runtime, run M-x eshell-atuin-history with the prefix argument:

C-u 0 M-x eshell-atuin-history for global
C-u 1 M-x eshell-atuin-history for host
C-u 2 M-x eshell-atuin-history for session
C-u 3 M-x eshell-atuin-history for directory

Implementation notes

I may have overengineered the package a bit to scale on lots of records.

The package caches the results of atuin search in eshell-atuin--history-cache (which see on the algorithm), and updates the cache incrementally. A formatted string for each entry is created at the moment of addition; entries are additionally “indexed” by a hashmap to lookup “raw” commands by their formatted versions.

So, the only places I see with the computational complexity of O(N), where N is the number of unique commands in atuin, are:

populating the cache at the first run of M-x eshell-atuin-history;
feeding the entirety of the cache to completing-read on each run of M-x eshell-atuin-history.

Table of Contents