Usage

Installation

To use MisTTY, first install its package,

from MELPA or MELPA Stable, using M-x package-install mistty

from source using M-x package-vc-install https://github.com/szermatt/mistty

You can then call it, as described in Launching.

However, you’ll likely want to configure it and add some key bindings you use often in shells, for example:

(use-package mistty
  :bind (("C-c s" . mistty) ;; or mistty-in-project

         ;; bind here the shortcuts you'd like the
         ;; shell to handle instead of Emacs.
         :map mistty-prompt-map

         ;; fish: dir history, more history manipulation
         ("M-<up>" . mistty-send-key)
         ("M-<down>" . mistty-send-key)
         ("M-<left>" . mistty-send-key)
         ("M-<right>" . mistty-send-key)))

Read on for details on the commands and key bindings configured above.

Launching

To create a new interactive shell buffer in MisTTY mode, call M-x mistty or M-x mistty-create. If you use MisTTY regularly, you’ll want to bind some of these to global shortcuts:

M-x mistty-create launches a new interactive shell in a MisTTY buffer. The shell that is launched is the one that’s configured on M-x configure-option explicit-shell-file-name

If explicit-shell-file-name is unset, MisTTY falls back to shell-file-name, then the environment variables ESHELL and SHELL.

M-x customize-option display-comint-buffer-action lets you configure how the buffer is displayed.

M-x mistty-create-other-window does the same, but opens the buffer in another window.

M-x mistty creates a new MisTTY buffer the first time it is called. Afterwards, it’ll try to guess what’s most appropriate, displaying an existing MisTTY buffer or creating a new one.

With a prefix argument, this command always creates a new buffer.

M-x mistty-other-window does the same, but opens the buffer in another window.

M-x mistty-in-project creates a new MisTTY buffer in the root directory of the current project the first time it is called. Afterwards, it’ll try to guess what’s most appropriate, displaying an existing MisTTY buffer or creating a new one.

With a prefix argument, this command always creates a new buffer.

Note that if you want M-x project-kill-buffers to kill such buffers, you’ll want to execute mistty-project-init-kill-buffer somewhere in your configuration or tell M-x configure-option project-kill-buffer-conditions about MisTTY.

Terminal vs. Scrollback

MisTTY buffers are split into two zones, with different behaviors:

The scrollback zone, is where you can see commands that have been executed and their output.

The terminal zone, marked by a purple line on the left of the window, is where you can type command and interact with the terminal. In this zone, TAB triggers the shell completion, if available. With some shells, you’ll see autosuggestions as you type.

The scrollback zone behaves as a normal Emacs buffer. You can modify it as you see fit.

The terminal zone, on the other hand, limits what you can do: When a shell is attached to the terminal, you can edit the command you’re about to run, but you can’t edit the prompt itself - or rather, if you do change the prompt, your change will be undone by the shell.

The terminal zone is where the magic happens: this is where you can use a mix of Emacs and shell key bindings to edit the command line. The trickiest part is choosing which key bindings you want Emacs to handle and which key bindings you want the shell to handle.

By default, Emacs handles everything but a few key bindings are sent directly to the terminal, bypassing Emacs:

RET, to ask the shell to run the command
TAB, to ask the shell to run command completion,
C-a to ask it to move the cursor to the beginning of the line, and
C-e to ask it to move the cursor to the end of the line.
C-d to ask it to either delete the next character or exit the program.
M-p to ask it to go up, or up the command history, sending C-p to the terminal.
M-n to ask it to go down, or down the command history, sending C-n to the terminal.
M-r to ask it to do backward history search, sending C-r to the terminal.
M-. to ask the shell to insert the last history argument.

In addition, C-c C-c sends the TERM signal to the terminal.

The program attached to the terminal decides what the actual effect of these shortcuts is. Most shells and command-line editing tools supports the shortcuts above by default, but they might not work everywhere as expected.

Warning

MisTTY will not work if you’ve configured your shell to turn on VI mode by default. Please turn it off before trying out MisTTY, for details on how to turn off VI mode only of MisTTY buffers and leave it on otherwise, check out the instructions in Shells for details. VI mode must be turned off even if you just end up controlling it with VI commands using Evil.

To get the most out of MisTTY, it’s worth it to take the time to configure it to send to the terminal the shell key bindings that you actually use and keep everything else behaving as usual for your Emacs configuration.

To bind keys only in the terminal zone, bind them to mistty-prompt-map. To bind keys in both zones, bind them to mistty-mode-map. See examples below.

The following commands are useful to send key sequences to the current shell or program controlling the terminal:

The command mistty-send-key, called interactively, forwards the key it was called from. It is meant to be bound to the shell key bindings you want to work in the terminal zone map, mistty-prompt-map.

For example, searching in the shell command history is usually bound to C-r, MisTTY binds that to M-r, like comint does, but if you’d like it to be accessible using the original key binding, you can do:
(keymap-set mistty-prompt-map "C-r" #'mistty-send-key)
If you’d prefer to have the key available in both the scrollback and terminal zones, bind it mistty-mode-map instead.

You can also pass arbitrary keys to mistty-send-key, for example:
(defun my-mistty-M-s (n)
  (interactive "p")
  (mistty-send-key n (kbd "M-s")))
(keymap-set mistty-prompt-map "C-c a" #'my-mistty-M-s)
The command mistty-send-last-key forwards the last key combination of a sequence it was called from to the terminal. For example, C-c C-c is bound to mistty-send-last-key so that the terminal eventually just gets C-c.

To just try things out, or for shell shortcuts you don’t use regularly, you can use the C-q prefix to bypass Emacs key bindings and send keys directly to the terminal. For example, C-q <right> sends a right arrow key press to the terminal instead of moving the cursor.

If that’s not enough,

C-c C-q, M-x mistty-send-key-sequence sends all keys you press to the terminal until you press C-g.

Navigating the scrollback zone

C-e C-e moves the point back inside the prompt. This is handled by the interactive function mistty-end-of-line-or-goto-cursor

M-x mistty-goto-cursor also moves the point back inside the prompt. You can bind it to a custom shortcut if you don’t like overloading C-e.

C-c C-p or M-x mistty-goto-previous-output goes to the beginning of the previous command output. This is useful to if the buffer has scrolled too far and you want to see it from the beginning.

C-c C-n or M-x mistty-goto-next-output does the reverse, that is, it goes to the next command output.

C-c C-r or M-x mistty-create-buffer-with-output creates a new buffer containing the last command output.

M-x mistty-goto-previous-input goes to the beginning of the previous command input, that is, the previous prompt. While this is a way of going back the command you’ve previously input, it’s best to use the shell native command history, as discussed in Command History.

M-x mistty-goto-next-input goes to the next command input.

Fullscreen Mode

MisTTY detects when a program such as less or vi asks to run full screen and splits the MisTTY buffers into:

a terminal buffer, which shows the program output and lets you interact with it. This is a term-mode buffer.
a scrollback buffer, which shows the previous command lines and their output.

C-c C-j or M-x mistty-toggle-buffers switches between these two.

When the program exits, the two buffers are again merged. Note that the output of the full screen app isn’t available in the scrollback.

Command History

MisTTY doesn’t track command history. It relies instead on being able to access the history of the different interactive command-line tools.

The command history available in most shells and command-line editing tools is available in MisTTY using the following shortcuts:

M-p moves up command history
M-n moves down command history
M-r triggers a backward search in command history
M-. insert the last argument from command history

To get the same key bindings you’d get in a normal terminal, you can bind C-p, C-n, or C-r to mistty-send-key in the terminal zone of the MisTTY buffer. For example:

(keymap-set mistty-prompt-map "C-p" #'mistty-send-key)
(keymap-set mistty-prompt-map "C-n" #'mistty-send-key)
(keymap-set mistty-prompt-map "C-r" #'mistty-send-key)

Directory tracking and TRAMP

In order for Emacs to know your shell’s current directory, the shell has to tell MisTTY about it. This is usually done from the prompt.

Bash does it by default, for local shells, when it detects a terminal of type TERM=eterm-color run from inside Emacs.

Other shells need to be configured to do the same. For more details, see Shells.

If you have configured TRAMP and know that the hosts you ssh into are accessible with the default TRAMP method, you might consider allowing MisTTY to report remote paths on M-x configure-option mistty-allow-tramp-paths.

Completion-at-point

When in a MisTTY buffer, it’s best to rely on the completion or autosuggestions provided by the shell or other command-line tool currently running, as they’re more up-to-date and context-sensitive than what Emacs can provide.

However, some form of Emacs-based completion can still be useful from inside of a MisTTY buffer, to complete abbreviations, expand templates or add emojis.

The following completion packages are known to work with MisTTY out of the box, including auto-completion, if enabled:

Emacs builtin complete-in-region
corfu
company-mode

Emacs hippie-expand also works. That’s not completion, but it’s close.

Other packages might work or might be made to work with some efforts. Auto-completion is usually the main challenge. See Auto-complete for some pointers. Please file a bug if you encounter issues with other completion packages.

Autosuggestions

completion-at-point completes the text around the point. This is generally convenient, but gets confused by shell autosuggestions, available in Fish or ZSH.

What if you typed “com” and the shell helpfully suggests “completion”? The buffer would look like: “com<>pletion”, with <> representing the point. completion-at-point would then think you typed “completion” and not suggest anything else.

To avoid that problem MisTTY modifies the functions it finds in completion-at-point-functions so that they just won’t see anything after the point when in the terminal region. In the example above, they’d only complete “com”, not “completion”.

That is, completion-at-point in the MisTTY terminal region completes the text before the point.

If you don’t like that or don’t use a shell that supports autosuggestions, you can turn this off with M-x customize-option mistty-wrap-capf-functions

Template Expansion

Template expansion and other form of long-running editing command might be confused by the way MisTTY work in the terminal region. See Long-running commands for details.

The following template expansion packages are known to work with MisTTY out of the box, if enabled:

Emacs built-in tempo package
tempel
yasnippet

Other packages might work or might be made to work with some efforts. Please file a bug if you encounter issues with other packages.

Fancy prompts

MisTTY is known to work with powerline-shell prompts or Tide, on Fish. This includes right prompts, for the most part - though there might be temporary artifacts and troublesome corner cases left.

If you suspect your shell prompt is causing issues, please first try setting a traditional prompt to confirm, then file a bug, whatever the outcome.