mistty.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename mistty.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx.@*
@end ifinfo
@settitle MisTTY
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory Emacs
@direntry
* MisTTY: (mistty.info). Shell/comint alternative with a fully-functional
                        terminal
@end direntry

@c %**end of header

@copying
@quotation
MisTTY 1.3.1snapshot

Stephane Zermatten

Copyright @copyright{} 2023-2024, Stephane Zermatten
@end quotation

@end copying

@titlepage
@title MisTTY
@insertcopying
@end titlepage
@contents

@c %** start of user preamble

@c %** end of user preamble

@ifnottex
@node Top
@top MisTTY
@insertcopying
@end ifnottex

@c %**start of body
@anchor{index doc}@anchor{0}
`MisTTY' is a major mode for @code{Emacs} 29.1 and up that runs
a shell inside of a buffer, similarly to comint mode. It is built on
top of @code{term.el}. Check out its project page at
@indicateurl{https://github.com/szermatt/mistty}.

@code{M-x mistty} creates a buffer with an interactive shell. See
@ref{1,,Launching} for details.

MisTTY feels very much like comint mode: you can move around freely
and run any Emacs command you want - until you press TAB and end up
with the native completion or notice the shell autosuggestions. With
MisTTY you have access to both Emacs and the shell commands and
editing tools.

Additionally, commands that take over the @ref{2,,entire screen}, such as @code{less} or @code{vi} also
work, temporarily taking over the window, while scrollback remains
available in another buffer.


MisTTY is known to work on Linux and MacOS. It also supports non-shell
command-line programs, such as @code{python}.

The latest version of this documentation is available at
@indicateurl{https://mistty.readthedocs.io/en/latest/}.  Once MisTTY is installed,
this documentation can be accessed from inside Emacs using @code{M-x
info gmistty}

@cartouche
@quotation Note 
If you encounter issues, please take the time to file a bug. See
@ref{3,,Reporting issues} for details.
@end quotation
@end cartouche

@menu
* Comparison with other packages:: 
* Contents:: 
* Index:: 

@end menu

@node Comparison with other packages,Contents,Top,Top
@anchor{index comparison-with-other-packages}@anchor{4}@anchor{index mistty}@anchor{5}
@chapter Comparison with other packages


MisTTY isn’t a terminal emulator, but rather a frontend to an existing
terminal emulator, the built-in @code{term.el}. Its goal is to make
it more convenient to use while inside of Emacs and better integrate
with Emacs itself. In theory, other terminal emulators than
@code{term.el} might be used as engine for MisTTY, such as
@code{vterm} and @code{eat}.

MisTTY has some similarities with @code{coterm}; it offers the
same switch between full-screen and line mode.

@code{Coterm}, @code{ansi-term} and @code{eat} all have a
line mode, just like @code{comint} does, which allows you to edit
a command line as a whole before sending it to the shell. While in
line mode, rendering is done by Emacs and editing commands are Emacs
commands. In constrast, with MisTTY, all rendering is done by the
shell through the terminal. This is why native shell completion and
autosuggestion is available with MisTTY and not in line modes and why
you can freely mix shell commands with Emacs commands while editing
the command line.

@code{ansi-term} and @code{eat} also have a char mode, where
rendering and command execution is handled by the shell, and editing
with Emacs isn’t available. The difference with MisTTY is then that
MisTTY makes Emacs editing commands available when possible.

@code{eat} also has a semi-char mode, which is the closest there
is to MisTTY. In that mode, Emacs movements commands are available.
However, Emacs commands that modify the buffer, aren’t available to
edit the command line. In contrast, MisTTY allows Emacs to navigate to
and edit the whole buffer, then replays changes made to the
command-line.

@node Contents,Index,Comparison with other packages,Top
@anchor{index contents}@anchor{6}
@chapter Contents


@menu
* Usage:: 
* Shells:: 
* Extending MisTTY:: 
* FAQ:: 
* Contributing:: 

@end menu

@node Usage,Shells,,Contents
@anchor{usage doc}@anchor{7}@anchor{usage usage}@anchor{8}
@section Usage


@menu
* Installation:: 
* Launching:: 
* Terminal vs. Scrollback: Terminal vs Scrollback. 
* Navigating the scrollback zone:: 
* Fullscreen Mode:: 
* Command History:: 
* Backward Search:: 
* Completion-at-point:: 
* Template Expansion:: 
* Directory Tracking:: 
* Remote Shells with TRAMP:: 
* Directory tracking and TRAMP:: 
* Fancy prompts:: 

@end menu

@node Installation,Launching,,Usage
@anchor{usage id1}@anchor{9}@anchor{usage installation}@anchor{a}
@subsection Installation


To use MisTTY, first install its package,

@quotation


@itemize -

@item 
from MELPA or MELPA Stable@footnote{https://melpa.org/#/getting-started}, using @code{M-x
package-install mistty}

@item 
from source using @code{M-x package-vc-install https://github.com/szermatt/mistty}
@end itemize
@end quotation

And then launch it with @code{M-x mistty}, as described in @ref{1,,Launching}.

You’ll likely want to eventually bind that to some shortcut:

@example
(use-package mistty
  :bind (("C-c s" . mistty)))
@end example

and, unless you’re using @code{Bash}, configure your shell for
@ref{b,,Directory Tracking}, but read on for more details.

@node Launching,Terminal vs Scrollback,Installation,Usage
@anchor{usage id2}@anchor{c}@anchor{usage launching}@anchor{1}
@subsection Launching


To create a new interactive shell buffer in MisTTY mode, call
@code{M-x mistty}, which either creates a new shell or goes to an
existing MisTTY buffer, or @code{M-x mistty-create}, which creates a
new MisTTY buffer.

Here’s a quick list of the commands defined by the MisTTY package,
their behavior and arguments:

@quotation

@geindex command; mistty-create
@geindex command; mistty
@geindex command; mistty-create-other-window
@geindex command; mistty-other-window
@geindex variable; mistty-shell-command
@geindex variable; explicit-shell-file-name
@geindex variable; shell-file-name
@geindex variable; mistty-buffer-name


@itemize -

@item 
@code{M-x mistty-create} launches a new interactive shell in a
MisTTY buffer in the current buffer’s @code{default-directory}.

The shell that is launched is the one that’s configured on
@code{M-x configure-option mistty-shell-command}. If
@code{mistty-shell-command} is not set, MisTTY falls back to
@code{explicit-shell-file-name}, @code{shell-file-name}, then
the environment variables 
@geindex ESHELL
@geindex environment variable; ESHELL
@code{ESHELL} and 
@geindex SHELL
@geindex environment variable; SHELL
@code{SHELL}.

With a prefix argument, this command asks for a directory for the
new shell, instead of using the current buffer’s current
directory. This is particularly useful if you want to run a
@ref{d,,Remote Shells with TRAMP}.

By default, new buffers are called “*mistty*”, or, if you use
TRAMP “*mistty@@hostname*”. You can configure this on @code{M-x
customize-option mistty-buffer-name}.

@item 
@code{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.
@end itemize

@geindex command; mistty-other-window


@itemize -

@item 
@code{M-x mistty-other-window} does the same as @code{mistty},
but opens the buffer in another window.

@item 
@code{M-x mistty-create-other-window} does the same as
@code{mistty-create}, but opens the buffer in another window.

@quotation

If you need more control on how MisTTY windows are handled
than what’s provided by the @code{-other-window} variants,
you can configure it using @code{M-x customize-option
display-comint-buffer-action} or @code{M-x customize-option
display-buffer-alist}. In the latter case, note that MisTTY
buffers belong to the @code{comint} category, just like shell
buffers.

See the section “Window Choice” of the Emacs manual for
details.
@end quotation
@end itemize

@geindex command; mistty-in-project
@geindex command; mistty-ssh
@geindex command; mistty-docker


@itemize -

@item 
@code{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 @code{M-x project-kill-buffers} to kill such
buffers, you’ll want to execute
@code{mistty-project-init-kill-buffer} somewhere in your
configuration or tell @code{M-x configure-option
project-kill-buffer-conditions} about MisTTY.

@item 
@code{M-x mistty-ssh} creates a new MisTTY buffer connected to
another host using SSH. This is just a shortcut that uses TRAMP to
connect to a remote host. See @ref{d,,Remote Shells with TRAMP} for details.

@item 
@code{M-x mistty-docker} creates a new MisTTY buffer connected to
a docker instance. This requires the docker command-line tool to
be installed. This is just a shortcut that uses TRAMP to connect
to a remote host. See @ref{d,,Remote Shells with TRAMP} for details.
@end itemize
@end quotation

@node Terminal vs Scrollback,Navigating the scrollback zone,Launching,Usage
@anchor{usage term-vs-scroll}@anchor{e}@anchor{usage terminal-vs-scrollback}@anchor{f}
@subsection 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, @code{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:


@itemize -

@item 
@code{RET}, to ask the shell to run the command

@item 
@code{TAB}, to ask the shell to run command completion,

@item 
@code{C-a} to ask it to move the cursor to the beginning of the
line, and

@item 
@code{C-e} to ask it to move the cursor to the end of the line.

@item 
@code{C-d} to ask it to either delete the next character or exit the
program.

@item 
@code{M-p} to ask it to go up, or up the command history, sending
@code{C-p} to the terminal.

@item 
@code{M-n} to ask it to go down, or down the command history,
sending @code{C-n} to the terminal.

@item 
@code{M-r} to ask it to do @ref{10,,Backward Search}, sending @code{C-r} to the terminal.

@item 
@code{M-.} to ask the shell to insert the last history argument.
@end itemize

In addition, @code{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.

@cartouche
@quotation 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
@ref{11,,Shells} for details. VI mode must be turned off even if you
just end up controlling it with VI commands using Evil.
@end quotation
@end cartouche

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.

@geindex map; mistty-prompt-map
@geindex map; mistty-mode-map

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

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

@quotation

@geindex command; mistty-send-key


@itemize -

@item 
The command @code{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,
@code{mistty-prompt-map}.

For example, searching in the shell command history is usually
bound to @code{C-r}, MisTTY binds that to @code{M-r}, like comint
does, but if you’d like it to be accessible using the original key
binding, you can do:

@example
(keymap-set mistty-prompt-map "C-r" #'mistty-send-key)
@end example

If you’d prefer to have the key available in both the scrollback
and terminal zones, bind it @code{mistty-mode-map} instead.

You can also pass arbitrary keys to @code{mistty-send-key}, for
example:

@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)
@end example
@end itemize

@geindex command; mistty-send-last-key


@itemize -

@item 
The command @code{mistty-send-last-key} forwards the last key
combination of a sequence it was called from to the terminal. For
example, @code{C-c C-c} is bound to @code{mistty-send-last-key}
so that the terminal eventually just gets @code{C-c}.
@end itemize
@end quotation

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

If that’s not enough,

@quotation

@geindex command; mistty-send-key-sequence


@itemize -

@item 
@code{C-c C-q}, @code{M-x mistty-send-key-sequence} sends all keys
you press to the terminal until you press @code{C-g}.
@end itemize
@end quotation

@node Navigating the scrollback zone,Fullscreen Mode,Terminal vs Scrollback,Usage
@anchor{usage navigating-the-scrollback-zone}@anchor{12}@anchor{usage navigation}@anchor{13}
@subsection Navigating the scrollback zone


@quotation

@geindex command; mistty-end-of-line-goto-cursor


@itemize -

@item 
@code{C-e C-e} moves the point back inside the prompt. This is
handled by the interactive function
@code{mistty-end-of-line-or-goto-cursor}
@end itemize

@geindex command; mistty-goto-cursor


@itemize -

@item 
@code{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.
@end itemize

@geindex command; mistty-previous-output


@itemize -

@item 
@code{C-c C-p} or @code{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.
@end itemize

@geindex command; mistty-next-output


@itemize -

@item 
@code{C-c C-n} or @code{M-x mistty-goto-next-output} does the
reverse, that is, it goes to the next command output.
@end itemize

@geindex command; mistty-select-output


@itemize -

@item 
@code{C-c C-o} or @code{M-x mistty-select-output} selects the
command output at or before point. With an argument, selects the
Nth previous command output.
@end itemize

@geindex command; mistty-create-buffer-with-output


@itemize -

@item 
@code{C-c C-r} or @code{M-x mistty-create-buffer-with-output}
creates a new buffer containing the command output at or before
point. With an argument, creates a buffer containing the Nth
previous command output.
@end itemize

@geindex command; mistty-goto-previous-input


@itemize -

@item 
@code{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
@ref{14,,Command History}.
@end itemize

@geindex command; mistty-goto-next-input


@itemize -

@item 
@code{M-x mistty-goto-next-input} goes to the next command input.
@end itemize
@end quotation

@node Fullscreen Mode,Command History,Navigating the scrollback zone,Usage
@anchor{usage fullscreen}@anchor{2}@anchor{usage fullscreen-mode}@anchor{15}
@subsection Fullscreen Mode


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


@itemize -

@item 
a terminal buffer, which shows the program output and lets you
interact with it. This is a term-mode buffer.

@item 
a scrollback buffer, which shows the previous command lines and
their output.
@end itemize

@geindex command; mistty-toggle-buffers

@code{C-c C-j} or @code{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.

@node Command History,Backward Search,Fullscreen Mode,Usage
@anchor{usage command-history}@anchor{16}@anchor{usage history}@anchor{14}
@subsection 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:


@itemize -

@item 
@code{M-p} moves up command history

@item 
@code{M-n} moves down command history

@item 
@code{M-r} triggers a @ref{10,,Backward Search} in command history

@item 
@code{M-.} insert the last argument from command history
@end itemize

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

@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)
@end example

@node Backward Search,Completion-at-point,Command History,Usage
@anchor{usage backward-search}@anchor{17}@anchor{usage bs}@anchor{10}
@subsection Backward Search


@geindex map; mistty-forbid-edit-map
@geindex variable; mistty-forbid-edit-regexps
@geindex variable; mistty-forbid-edit-map

Within the different shells @code{C-r} or @code{M-r} triggers a
special backward search mode, during which edition is very limited.
MisTTY detects this mode based on the regular expressions configured
in @code{M-x customize-option mistty-forbid-edit-regexps}.

While this mode is active:


@itemize -

@item 
text can be appended or deleted, but not modified. While it is still
possible to yank text or delete a word in this mode, most Emacs
edition command will not work.

@item 
the status modeline shows “FE:run”, for Forbid Edit mode

@item 
arrow keys are sent directly to the terminal. This is useful when
the shell offers multiple choices that can be selected, as the Fish
shell does. To customize this behavior, add or remove key bindings
from @code{mistty-forbid-edit-map}, which extends
@code{mistty-prompt-map} while this mode is active.

@item 
C-g is forwarded to the terminal. It normally exits the backward
search mode without selecting anything.
@end itemize

@node Completion-at-point,Template Expansion,Backward Search,Usage
@anchor{usage cap}@anchor{18}@anchor{usage completion-at-point}@anchor{19}
@subsection 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:


@itemize -

@item 
Emacs builtin @cite{complete-in-region}

@item 
corfu@footnote{https://github.com/minad/corfu}

@item 
company-mode@footnote{http://company-mode.github.io}
@end itemize

Emacs @cite{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 @ref{1a,,Auto-complete}
for some pointers. Please @ref{3,,file a bug} if you
encounter issues with other completion packages.

@menu
* Autosuggestions:: 

@end menu

@node Autosuggestions,,,Completion-at-point
@anchor{usage autosuggestions}@anchor{1b}
@subsubsection Autosuggestions


@geindex variable; mistty-wrap-capf-functions

@code{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. @code{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
@code{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, @code{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 @code{M-x customize-option
mistty-wrap-capf-functions}

@node Template Expansion,Directory Tracking,Completion-at-point,Usage
@anchor{usage template-expansion}@anchor{1c}
@subsection 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
@ref{1d,,Long-running commands} for details.

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


@itemize -

@item 
Emacs built-in @cite{tempo} package

@item 
tempel@footnote{https://github.com/minad/tempel}

@item 
yasnippet@footnote{https://github.com/joaotavora/yasnippet}
@end itemize

Other packages might work or might be made to work with some efforts.
Please @ref{3,,file a bug} if you encounter issues with
other packages.

@node Directory Tracking,Remote Shells with TRAMP,Template Expansion,Usage
@anchor{usage directory-tracking}@anchor{1e}@anchor{usage dirtrack}@anchor{b}
@subsection Directory Tracking


If you’re using @code{Bash} as a shell, you’ll discover that Emacs
keeps track of the shell’s current directory, so commands like
@code{M-x find-file} know where to start from.

If you’re using another shell, however, you’ll need to configure it to
tell Emacs about its current directory, as described in the sections
@ref{1f,,Directory Tracking for Fish} and @ref{20,,Directory Tracking for Zsh}.

@code{Bash} out-of-the-box directory tracking also doesn’t work in
shells you start using @code{ssh} or @code{docker}. For that
to work, the simplest solution is to start @ref{d,,remote shells with TRAMP}.

@node Remote Shells with TRAMP,Directory tracking and TRAMP,Directory Tracking,Usage
@anchor{usage remote-shells}@anchor{d}@anchor{usage remote-shells-with-tramp}@anchor{21}
@subsection Remote Shells with TRAMP


If the @cite{default-directory} that is current when a new MisTTY buffer is
created contains a TRAMP path whose method supports it, MisTTY runs
the shell with the method, user and host `of that path'.

@cartouche
@quotation Tip 
@code{C-u M-x mistty-create} asks for a directory instead of using
the default one. This makes it possible to open a remote shell on a
host that no buffer is visiting. See @ref{1,,Launching}.
@end quotation
@end cartouche

For this to work, MisTTY needs to know the shell executable to use on
that host. The value of @code{mistty-shell-command} or
@code{explicit-shell-file-name} is interpreted as a local file within
that host, which might not always work.

To run different shells on different hosts, define different
connection local profiles that set @code{mistty-shell-command} and
bind them to the TRAMP host, machine or user you want, as shown in the
example below. This is described in details in the `Emacs Lisp'
manual, in the section `Connection Local Variables'.

Example:

@example
(connection-local-set-profile-variables
 'profile-usr-local-fish
 '((mistty-shell-command . ("/usr/local/bin/fish" "-i"))))

(connection-local-set-profiles '(:machine "myhost.example")
 'profile-usr-local-fish)
@end example

By default, the name of TRAMP shells include the user and hostname, if
different from the current one. If you don’t want that, configure it
on @code{M-x customize-option mistty-buffer-name}.

@node Directory tracking and TRAMP,Fancy prompts,Remote Shells with TRAMP,Usage
@anchor{usage directory-tracking-and-tramp}@anchor{22}@anchor{usage tramp-dirtrack}@anchor{23}
@subsection Directory tracking and TRAMP


@geindex variable; mistty-allow-tramp-path
@geindex variable; mistty-host-to-tramp-path-alist

@ref{b,,Directory tracking} normally just works in TRAMP
shells started described in the previous section.

This isn’t necessarily true of shells started from a MisTTY buffers,
by calling @code{ssh}, @code{docker} or @code{sudo}, but
it is possible to make that work, as described below.

@cartouche
@quotation Tip 
The simplest way to connect a host or docker instance you don’t
want to configure is to just start it as described in
@ref{d,,Remote Shells with TRAMP} and use @code{Bash} as your shell.
Everything then just work out of the box, at least for @ref{24,,Bash 4.4 and later}.
@end quotation
@end cartouche

If you haven’t already, configure your shell to tell Emacs about
directory changes, even @code{Bash}. This is described in
@ref{24,,Directory Tracking for Bash}, @ref{1f,,Directory Tracking for Fish} or @ref{20,,Directory Tracking for Zsh}.

Once this is done, the shell sends out file: URLs that include the
host name. By default, MisTTY will then use that to set the default
directory to remote file paths that include that hostname using the
default TRAMP method. For example, given the file: URL
@code{file:/example.com/var/log} reported by the shell, MisTTY will
set the directory of its buffer to @code{/-:example.com:/var/log}.

If you always connect to hosts using SSH, this is likely all you need,
if not, you can still make it work as follows:


@itemize -

@item 
If you’re using some other way of connecting to your host, configure
it in @code{M-x configure-option tramp-default-method}. You can also
configure that on a per-host basis using @code{M-x configure-option
tramp-default-method-alist}

@item 
If you’re connecting to hosts in more diverse ways, you can
configure the TRAMP path MisTTY should generate using @code{M-x
configure-option mistty-host-to-tramp-path-alist}

@item 
If you want to configure the TRAMP path on the hosts, you can send
it from the prompt as Emacs-specific @code{\032/...\n} code
containing a TRAMP path instead of the standard file: URL
recommended in @ref{24,,Directory Tracking for Bash},
@ref{1f,,Directory Tracking for Fish} or
@ref{20,,Directory Tracking for Zsh}. Here’s an example
of such a code for @code{Bash} that tells TRAMP to connect to
the current docker instance:

@example
if [ "$TERM" = "eterm-color" ]; then
    PS1='\032//docker:$HOSTNAME:/$PWD\n'$PS1
fi
@end example
@end itemize

That said, if you need more than just SSH to connect to other hosts,
it might be overall just easier to start @ref{d,,remote shells with TRAMP} instead of the command line, because directory
tracking just works in that case.

If everything fails, TRAMP is causing you too much trouble and you
just don’t want MisTTY to generate remote paths at all, unset the
option @code{M-x configure-option mistty-allow-tramp-paths}.

@node Fancy prompts,,Directory tracking and TRAMP,Usage
@anchor{usage fancy-prompts}@anchor{25}
@subsection Fancy prompts


MisTTY is known to work with powerline-shell prompts or Tide@comma{} on Fish@footnote{https://github.com/IlanCosman/tide}. 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 @ref{3,,file a bug}, whatever the outcome.

@node Shells,Extending MisTTY,Usage,Contents
@anchor{shells doc}@anchor{26}@anchor{shells id1}@anchor{27}@anchor{shells shells}@anchor{11}
@section Shells


@menu
* Bash:: 
* Fish:: 
* Zsh:: 
* IPython:: 

@end menu

@node Bash,Fish,,Shells
@anchor{shells bash}@anchor{28}@anchor{shells id2}@anchor{29}
@subsection Bash


A recent version of Bash is preferable. Bash 5.1 or later is
recommended.

MisTTY works best with shells that support bracketed paste. Without
bracketed paste support, MisTTY will still work, but might behaves
unexpectedly when yanking text containing special characters.

Bash 4.5 to 5.0 supports bracketed paste, but it must be turned
on in your @code{.inputrc}, as follows:

@example
set enable-bracketed-paste on
@end example

Bash versions older than 4.5 don’t support bracketed paste.

Additionally, Bash versions older than 4.4 require extra setup to
enable directory tracking, as documented in @ref{24,,Directory tracking}.

@menu
* Multi-line prompts:: 
* Directory tracking:: 
* VI mode:: 

@end menu

@node Multi-line prompts,Directory tracking,,Bash
@anchor{shells multi-line-prompts}@anchor{2a}
@subsubsection Multi-line prompts


When you press @code{RET} on an incomplete command, @code{bash}
has the annoying habit of starting a secondary prompt which doesn’t
let you go back to the previous line with the default keybindings.

To work around that, type @code{S-<return>} instead of @code{RET}
while on the terminal zone of a MisTTY buffer. This sends a newline
without running the command. You’ll then end up with one multi-line
prompt that you can edit normally. This requires Bash 5.1 or an
earlier version with bracketed paste mode turned on.

You’ll get the same effect if you yank a multi-line command while in a
prompt or go up the command history to a previous multi-line command.

@node Directory tracking,VI mode,Multi-line prompts,Bash
@anchor{shells bash-dirtrack}@anchor{24}@anchor{shells directory-tracking}@anchor{2b}
@subsubsection Directory tracking


@geindex variable; mistty-set-EMACS

Recent versions of @code{bash} already send the current directory
when they detects that it’s called from Emacs with
@code{TERM=eterm-color}. This works fine for local shell as well as remote
shells run with TRAMP.

If you ssh into a host from an existing MisTTY buffer, however,
@code{bash} will not send the remote directory. If you want this
use case to work, extend your prompt to send out an OSC7 sequence to
have @code{bash} send the current directory and hostname to
MisTTY.

To do that, you might add the following to @code{~/.bashrc}:

@example
if [ "$TERM" = "eterm-color" ]; then
  PS1='\e]7;file://$HOSTNAME$PWD\e\\\\'$PS1
fi
@end example

Such sequence are either ignored or understood by most terminals, so
you don’t absolutely need to check TERM.

Versions of @code{bash} older than 4.4 only enable directory
tracking if the env variable EMACS is set. You can have MisTTY set
this env variable when it starts a shell by going to @cite{M-x customize-option mistty-set-EMACS}. @code{mistty-set-EMACS} also
works as a connection-local variable, to set the EMACS env variable
only on some hosts that use an old version of @code{bash}.

For example:

@example
(connection-local-set-profile-variables
 'profile-old-bash
 '((mistty-set-EMACS . t)
   (mistty-shell-command . ("/bin/bash" "-i"))))

(connection-local-set-profiles '(:machine "oldhost.example.com")
 'profile-old-bash)
(connection-local-set-profiles '(:protocol "docker")
 'profile-old-bash)"
@end example

@node VI mode,,Directory tracking,Bash
@anchor{shells vi-mode}@anchor{2c}
@subsubsection VI mode


To communicate with @code{bash}, MisTTY requires the shell to be
in its default editing mode, that is, the emacs mode. `Please make
sure you haven’t put readline or bash in vi mode before trying out
MisTTY.'

To turn on vi mode in readline everywhere but MisTTY, you can add
something like the following into @code{~/.inputrc}:

@example
$if term=eterm
  set editing-mode emacs
$else
  set editing-mode vi
$endif
@end example

Or, in bash @code{~/.bashrc}:

@example
if [ "$TERM" != "eterm-color" ]; then
  set -o vi
fi
@end example

@node Fish,Zsh,Bash,Shells
@anchor{shells fish}@anchor{2d}@anchor{shells id3}@anchor{2e}
@subsection Fish


A recent version of Fish is preferable. MisTTY relies on bracketed
paste mode, on by default, so it should not be turned off.

@menu
* Autosuggestions: Autosuggestions<2>. 
* Command History: Command History<2>. 
* Directory tracking: Directory tracking<2>. 
* Multi-line prompts: Multi-line prompts<2>. 
* VI mode: VI mode<2>. 

@end menu

@node Autosuggestions<2>,Command History<2>,,Fish
@anchor{shells autosuggestions}@anchor{2f}
@subsubsection Autosuggestions


@code{fish} autosuggestions work normally in MisTTY. However, the
usual way of accepting an autosuggestion, pressing the right arrow
key, is very inconvenient as this is bound to an Emacs point movement.

The recommended way of accepting an autosuggestion in MisTTY is to
type @code{C-e}. This works in normal terminals as well.

@node Command History<2>,Directory tracking<2>,Autosuggestions<2>,Fish
@anchor{shells command-history}@anchor{30}
@subsubsection Command History


To make full use of @code{fish} command history, you’ll want to
forward some additional shortcuts to fish:

@example
(keymap-set mistty-prompt-map "M-<up>" #'mistty-send-key)
(keymap-set mistty-prompt-map "M-<down>" #'mistty-send-key)
(keymap-set mistty-prompt-map "M-<left>" #'mistty-send-key)
(keymap-set mistty-prompt-map "M-<right>" #'mistty-send-key)
@end example

This can also be done by calling @code{use-package} as shown in
@ref{a,,Installation}.

When in reverse history search mode, @code{fish} enters a mode
that lets you select an option using the arrow keys. To send
up/down/left/right directly to @code{fish}, you can:


@itemize -

@item 
use @code{M-p} to go up and @code{M-n} to go down, or, if you prefer

@item 
use @code{C-q <up>} @code{C-q <down>} @code{C-q <left>} @code{C-q <right>}, or even

@item 
@code{C-c C-q} to temporarily send all send key presses to @code{fish}
@end itemize

@node Directory tracking<2>,Multi-line prompts<2>,Command History<2>,Fish
@anchor{shells fish-dirtrack}@anchor{1f}@anchor{shells id4}@anchor{31}
@subsubsection Directory tracking


Extend your prompt to send out an OSC7 sequence to have
@code{fish} send the current directory and hostname to MisTTY. To
do that, you might add the following to
@code{~/.local/config/fish/config.fish}:

@example
if [ "$TERM" = "eterm-color" ]
  function osc7_send_pwd --on-event fish_prompt
    printf "\e]7;file://%s%s\e\\\\" (hostname) "$PWD"
  end
end
@end example

such sequence are either ignored or understood by most terminals. You
might already have it set up.

@node Multi-line prompts<2>,VI mode<2>,Directory tracking<2>,Fish
@anchor{shells id5}@anchor{32}
@subsubsection Multi-line prompts


@code{fish} automatically detects when a command is incomplete
when you type @code{RET} and launches a multi-line prompt, which
MisTTY knows to navigate.

@geindex variable; mistty-skip-empty-spaces

The cursor jumps over indent space while on such a prompt, just like
in a normal terminal. @code{M-x customize-option
mistty-skip-empty-spaces} allows you to turn that on or off in a
MisTTY buffer.

@node VI mode<2>,,Multi-line prompts<2>,Fish
@anchor{shells id6}@anchor{33}
@subsubsection VI mode


To communicate with @code{fish}, MisTTY requires the shell to be
in its default editing mode, that is, the emacs mode. `Please make
sure you haven’t put readline or bash in vi mode before trying out
MisTTY.'

To turn on vi mode in readline everywhere but in MisTTY, you can add
something like the following in @code{~/.zshrc}:

@example
if [ "$TERM" != "eterm-color" ]
  fish_vi_key_bindings
end
@end example

@node Zsh,IPython,Fish,Shells
@anchor{shells id7}@anchor{34}@anchor{shells zsh}@anchor{35}
@subsection Zsh


A recent version of Zsh is preferable.

Zsh supports bracketed paste, which MisTTY relies on, since version
5.1. Older versions will work, but with limitations, and you might get
unexpected results if you yank text containing special characters.

@menu
* Autosuggestions: Autosuggestions<3>. 
* Directory tracking: Directory tracking<3>. 
* Multi-line prompts: Multi-line prompts<3>. 
* VI mode: VI mode<3>. 

@end menu

@node Autosuggestions<3>,Directory tracking<3>,,Zsh
@anchor{shells id8}@anchor{36}
@subsubsection Autosuggestions


Fish-like @code{zsh} autosuggestions work normally in MisTTY, if
you’ve turned these on. However, the usual way of accepting an
autosuggestion, pressing the right arrow key, is very inconvenient as
this is normally bound to an Emacs point movement.

The recommended way of accepting an autosuggestion in MisTTY is to
type @code{C-e}. This works in normal terminals as well.

@node Directory tracking<3>,Multi-line prompts<3>,Autosuggestions<3>,Zsh
@anchor{shells id9}@anchor{37}@anchor{shells zsh-dirtrack}@anchor{20}
@subsubsection Directory tracking


Extend your prompt to send out an OSC7 sequence to have
@code{zsh} send the current directory and hostname to MisTTY. To
do that, you might add the following to @code{~/.zshrc}:

@example
if [ "$TERM" = "eterm-color" ]; then
    PS1='\e]7;file://$HOSTNAME$PWD\e\\\\'$PS1
fi
@end example

such sequence are either ignored or understood by most terminals.

@node Multi-line prompts<3>,VI mode<3>,Directory tracking<3>,Zsh
@anchor{shells id10}@anchor{38}
@subsubsection Multi-line prompts


When you press @code{RET} on an incomplete command, @code{zsh}
has the annoying habit of starting a secondary prompt. MisTTY doesn’t
know how to go back to the previous prompt from such a prompt.

To work around that, type @code{S-<return>} instead of @code{RET}
while on the terminal zone of a MisTTY buffer. This sends a newline
without running the command. You’ll then end up with one multi-line
prompt that you can edit normally. This requires a version of Zsh that
supports bracketed paste mode, 5.1 or later.

You’ll get the same effect if you yank a multi-line command while in a
prompt or go up the command history to a previous multi-line command.

@node VI mode<3>,,Multi-line prompts<3>,Zsh
@anchor{shells id11}@anchor{39}
@subsubsection VI mode


To communicate with @code{zsh}, MisTTY requires the shell to be in
its default editing mode, that is, the emacs mode. `Please make sure
you haven’t put readline or bash in vi mode before trying out
MisTTY.'

To turn on vi mode in readline everywhere but in MisTTY, you can add
something like the following in @code{~/.zshrc}:

@example
if [ "$TERM" != "eterm-color" ]; then
  bindkey -v
fi
@end example

@node IPython,,Zsh,Shells
@anchor{shells id12}@anchor{3a}@anchor{shells ipython}@anchor{3b}
@subsection IPython


Editing, and cursor movements should work out of the box with
@code{ipython}, even in multi-line commands, `provided you use the
default prompts'.

@geindex variable; mistty-move-vertically-regexps
@geindex variable; mistty-multi-line-continue-prompts

If you modified the @code{ipython} prompts, you’ll need to teach
MisTTY about these prompts for multi-line movement and editing to
work.

Go to @code{M-x configure-option mistty-move-vertically-regexps} and
add to the list a regular expression that matches your prompt. Make
sure that your regular expression is specific to your IPython prompt,
as mistakenly matching with @code{bash} or @code{zsh} would
have rather catastrophic results.

Go to @code{M-x configure-option mistty-multi-line-continue-prompts}
and add to the list a regular expression that matches your IPython
continue prompt, that is, the prompt that IPython adds to the second
and later lines of input. Again, be specific. The regular expression
shouldn’t match any other prompts. You don’t need to do anything here
if you configured IPython to not output any continue prompt.

@node Extending MisTTY,FAQ,Shells,Contents
@anchor{extensions doc}@anchor{3c}@anchor{extensions extending-mistty}@anchor{3d}
@section Extending MisTTY


@menu
* Hooks:: 
* OSC Sequences:: 
* Writing Your Own Commands:: 
* Terminal Keymap:: 
* Auto-complete:: 
* Long-running commands:: 

@end menu

@node Hooks,OSC Sequences,,Extending MisTTY
@anchor{extensions hooks}@anchor{3e}@anchor{extensions id1}@anchor{3f}
@subsection Hooks


@menu
* mistty-mode-hook:: 
* mistty-interactive-insert-hook:: 
* mistty-after-process-start-hook:: 
* mistty-after-process-end-hook:: 
* mistty-entered-fullscreen-hook:: 
* mistty-left-fullscreen-hook:: 

@end menu

@node mistty-mode-hook,mistty-interactive-insert-hook,,Hooks
@anchor{extensions mistty-mode-hook}@anchor{40}
@subsubsection mistty-mode-hook


@geindex variable; mistty-mode-hook
@geindex hook; mistty-mode-hook

The hook @code{mistty-mode-hook} is called on every MisTTY buffer
just after creating the buffer and selecting a window for it but
before executing the shell, with the buffer selected.

If you have enabled autocomplete or autosuggestion globally, you might
want to disable it for MisTTY buffers from a function called by
@code{mistty-mode-hook}.

This hook also provides a good time to rename the buffer, change its
directory or change environment variables, to be inherited by the
process.

For example, if you wanted a more generic name for the MisTTY buffers,
you could do:

@example
(defun my-lets-call-it-shell ()
  (rename-buffer (generate-new-buffer-name "*shell*")))
(add-hook 'mistty-mode-hook #'my-lets-call-it-shell)
@end example

@geindex variable; mistty-interactive-insert-hook
@geindex hook; mistty-interactive-interactive

@node mistty-interactive-insert-hook,mistty-after-process-start-hook,mistty-mode-hook,Hooks
@anchor{extensions mistty-interactive-insert-hook}@anchor{41}
@subsubsection mistty-interactive-insert-hook


@code{mistty-interactive-insert-hook} is a hook that is called when
text is typed in the terminal region. It’s not called, for example,
for text that is inserted or displayed by the shell.

This hook provides an appropriate time to trigger auto-completion UI,
which, by default, doesn’t work in the terminal region, as discussed
in @ref{1a,,Auto-complete}.

Auto-completion doesn’t work in the terminal region because it often
requires calling a post-command function. To work around that, in most
case, it’s enough to just turn on the option @code{M-x
customize-option mistty-simulate-self-insert-command}, which enables
the function @code{mistty-self-insert-command}, called by this hook
by default.

This might not always work and have unintended effects, so you might
prefer to trigger the auto-completion UI yourself by adding your own
function to this hook and turning the above option off.

@node mistty-after-process-start-hook,mistty-after-process-end-hook,mistty-interactive-insert-hook,Hooks
@anchor{extensions mistty-after-process-start-hook}@anchor{42}
@subsubsection mistty-after-process-start-hook


@code{mistty-after-process-start-hook} is a normal hook called from
within a new MisTTY work buffer just after starting the process,
usually a shell. The process itself is available as
@code{mistty-proc}. At the time this hook is called, the buffer is
typically empty, as no output from the process has been processed.

@node mistty-after-process-end-hook,mistty-entered-fullscreen-hook,mistty-after-process-start-hook,Hooks
@anchor{extensions mistty-after-process-end-hook}@anchor{43}
@subsubsection mistty-after-process-end-hook


@code{mistty-after-process-end-hook} is called from within a MisTTY
work buffer just after the process ended. The process is passed as an
argument to the hook and its status can be accessed using
@code{process-status}.

This can be used to, for example, kill the MisTTY work buffer after
the shell exits successfully, with @code{mistty-kill-buffer} or
@code{mistty-kill-buffer-and-window}.

@example
(add-hook 'mistty-after-process-end-hook
          'mistty-kill-buffer-and-window)
@end example

@node mistty-entered-fullscreen-hook,mistty-left-fullscreen-hook,mistty-after-process-end-hook,Hooks
@anchor{extensions mistty-entered-fullscreen-hook}@anchor{44}
@subsubsection mistty-entered-fullscreen-hook


@code{mistty-entered-fullscreen-hook} is a normal hook called from
within a MisTTY work buffer just after switching to fullscreen mode.

In this mode, @code{mistty-fullscreen} is non-nil and user commands
run within the terminal buffer, available as
@code{mistty-term-buffer}. The work buffer is kept, but usually
buried until @code{mistty-toggle-buffers} is called.

@node mistty-left-fullscreen-hook,,mistty-entered-fullscreen-hook,Hooks
@anchor{extensions mistty-left-fullscreen-hook}@anchor{45}
@subsubsection mistty-left-fullscreen-hook


@code{mistty-left-fullscreen-hook} is a normal hook called from
within a MisTTY work buffer just after switching back to normal mode.

In this mode, @code{mistty-fullscreen} is nil and user commands run
in the work buffer.

@node OSC Sequences,Writing Your Own Commands,Hooks,Extending MisTTY
@anchor{extensions osc}@anchor{46}@anchor{extensions osc-sequences}@anchor{47}
@subsection OSC Sequences


OSC are “operating system command” control sequences. MisTTY supports
some of these sequences and ignores the others.

By default, the supported sequences are OSC 2 (set window title), 7
(directory tracking, already mentioned in @ref{b,,Directory Tracking}) and 8
(hyperlinks), thanks to @code{ansi-osc.el}.

@geindex variable; mistty-osc-handlers

To add more, register handlers to @code{mistty-osc-handlers}. The
format is the same as the handlers supported for
@code{ansi-osc-handlers} and can usually be used interchangeably.

When working on OSC handlers for MisTTY, it’s important to keep the
following in mind: MisTTY separate buffers for the terminal (a
@code{term-mode} buffer) and for MisTTY itself. The OSC handlers run
in the term-mode buffer.

@geindex variable; mistty-variables-to-copy

One consequence of this is that if you set a buffer-local variable in
a handler, it won’t be available in the MisTTY buffer unless you
register it to @code{M-x configure-option mistty-variables-to-copy}

MisTTY provides helpers for writing OSC handlers that set text
properties:

@geindex command; mistty-register-text-properties
@geindex command; mistty-unregister-text-properties


@itemize -

@item 
The function @code{mistty-register-text-properties} registers a set
of text properties to set on any text written to the terminal until
@code{mistty-unregister-text-properties} is called with the
same argument.
@end itemize

@node Writing Your Own Commands,Terminal Keymap,OSC Sequences,Extending MisTTY
@anchor{extensions custom-commands}@anchor{48}@anchor{extensions writing-your-own-commands}@anchor{49}
@subsection Writing Your Own Commands


You might find the following functions useful if you’d like to write
commands that extend MisTTY’s behavior:

@geindex function; mistty-send-string


@itemize -

@item 
@code{mistty-send-string} sends a string to the terminal,
unmodified. The string that is sent appear only after the function
return - and it might not ever appear at all depending on the
application attached to the terminal. This is used to implement
@code{mistty-sudo} for example.
@end itemize

@geindex function; mistty-on-prompt-p


@itemize -

@item 
@code{mistty-on-prompt-p} returns non-nil if the given position is
inside of a prompt MisTTY is aware of. This is useful for writing
commands that behave differently on a prompt than on program output,
even while inside of the terminal zone. It is used to implement
@code{mistty-beginning-of-line} for example.
@end itemize

@geindex function; mistty-maybe-realize-possible-prompt


@itemize -

@item 
@code{mistty-maybe-realize-possible-prompt} might be useful to call
in your commands to tell MisTTY that there’s likely a prompt at the
current pointer position.
@end itemize

@geindex function; mistty-before-position


@itemize -

@item 
@code{mistty-before-position} not only check whether there’s a
prompt at the position, but also attempt to move the terminal cursor
to that position.
@end itemize

@node Terminal Keymap,Auto-complete,Writing Your Own Commands,Extending MisTTY
@anchor{extensions term-keymap}@anchor{4a}@anchor{extensions terminal-keymap}@anchor{4b}
@subsection Terminal Keymap


@geindex function; mistty-translate-key
@geindex map; mistty-term-key-map

To forward a key binding to the application attached to the terminal
@cite{mistty-send-key} first needs to convert that key binding to something
applications will understand. The translation is done by
@code{mistty-translate-key}.

@quotation

The function @code{mistty-translate-key} takes an Emacs key
binding, as returned by @cite{kbd} and returns a string containing the
sequence of characters that correspond to that key to send to the
application tied to the terminal.
@end quotation

The default terminal keymap used by MisTTY mimics @code{xterm} key
bindings. You might extend it or change it by changing the map
@code{mistty-term-key-map}.

For example, you can change the string that correspond to the first
function keys from their default (”\eOP” - “\eOS”) as follows:

@example
(define-key mistty-term-key-map (kbd "<f1>") "\e[11~")
(define-key mistty-term-key-map (kbd "<f2>") "\e[12~")
(define-key mistty-term-key-map (kbd "<f3>") "\e[13~")
(define-key mistty-term-key-map (kbd "<f4>") "\e[14~")
@end example

@geindex function; mistty-reverse-input-decode-map

@code{M-x mistty-reverse-input-decode-map} generates alternative
values for @code{mistty-term-key-map} for you if you’d like mimic
another set of key bindings than xterm, for example, to generate a
keymap that simulates rxvt, you might do:

@example
(load-library "term/rxvt.el")
(mistty-reverse-input-decode-map rxvt-function-map)
@end example

@code{mistty-reverse-input-decode-map.el} is not included into the
distribution; it’s only available on github@footnote{https://github.com/szermatt/mistty/tree/master/extras}.

@node Auto-complete,Long-running commands,Terminal Keymap,Extending MisTTY
@anchor{extensions auto-complete}@anchor{4c}@anchor{extensions autocomplete}@anchor{1a}
@subsection Auto-complete


@geindex variable; mistty-simulate-self-insert-command

Auto-complete is a completion UI that shows up automatically after
some delay, without having to call @cite{completion-at-point}. This used
not to work in MisTTY terminal region. The hook
@code{mistty-simulates-self-insert-command} was introduced to fix
that. See @code{mistty-interactive-insert-hook} in @ref{3e,,Hooks}.

By default this hook calls the buffer @code{pre-command-hook} and
@code{post-command-hook} with @code{this-command} set to
@code{self-insert-command}, as this is the way auto-complete is
normally triggered. This can be turned off if necessary using the
option on @code{M-x customize-option
mistty-simulate-self-insert-command}.

If the behavior described above doesn’t work for some packages, it
should be possible to build a custom bridge between this hook and the
auto-completion package.

@node Long-running commands,,Auto-complete,Extending MisTTY
@anchor{extensions long-running-commands}@anchor{4d}@anchor{extensions lrc}@anchor{1d}
@subsection Long-running commands


In Emacs, most editing tools are run as a single Emacs command, but
some tools span multiple Emacs command, for example, when you expand a
snippet with yasnippet@footnote{https://github.com/joaotavora/yasnippet},
the snippet template is inserted into the buffer, together with
placeholders for you to fill some missing information.

Filling in a template is a series of Emacs commands, that, together,
have a single effect: to insert a snippet of text. MisTTY calls this a
long-running command.

When run in the terminal region, such long-running commands fail as
MisTTY sends the initial text to the shell, which echoes it back to be
redisplayed, possibly jumbling things and definitely destroying any
overlays.

To avoid such situations, MisTTY holds back sending text to the shell
until long-running commands are done. For that to work, MisTTY needs
to know when such command start and end.

You can tell whether MisTTY thinks a long-running command is active,
as it displays `CMD' in the modeline. You can also do it
programmatically:

@quotation

@geindex function; mistty-long-running-command-p

The function @code{mistty-long-running-command-p} returns non-nil
if MisTTY thinks a long-running command is active.
@end quotation

@geindex variable; mistty-detect-foreign-overlays
@geindex option; mistty-detect-foreign-overlays
@geindex variable; mistty-foreign-overlay-properties
@geindex option; mistty-foreign-overlay-properties

MisTTY detects some long-running commands by looking for overlays they
typically add to the buffer. This can be extended with @code{M-x
customize-option mistty-foreign-overlay-properties} or turned off with
@code{M-x customize-option mistty-detect-foreign-overlays}.

To add a new property to @cite{mistty-foreign-overlay-properties}, start
the interactive command, look for overlays with @cite{overlays-in} then get
their properties with @cite{overlay-properties}. You can then choose, on
that list, a property or face that identifies the feature or package.

If you find yourself extending @cite{mistty-foreign-overlay-properties},
please add an issue to @indicateurl{https://github.com/szermatt/mistty/issues/new}
so it can be integrated into the next version.

Alternatively, as not all long-running commands that can be confused
by MisTTY use overlays, you might need to tell MisTTY about them.
MisTTY does it already for @code{completion-in-region}.

@quotation

@geindex function; mistty-report-long-running-command

The function @code{mistty-report-long-running-command} can be
called to tell MisTTY when a long-running command start and end.
It’s typically called from hooks provided by the package of the
long-running command.
@end quotation

Here’s an example of code that would detect
@code{completion-in-region-mode} if MisTTY didn’t already do it:

@example
(defun my-completion-in-region ()
  (mistty-report-long-running-command
    'my-completion-in-region completion-in-region-mode))
(defun my-detect-completion-in-region ()
   (add-hook 'completion-in-region-mode-hook
             #'my-completion-in-region nil t))
(add-hook 'mistty-mode-hook #'my-detect-completion-in-region)
@end example

@node FAQ,Contributing,Extending MisTTY,Contents
@anchor{faq doc}@anchor{4e}@anchor{faq faq}@anchor{4f}
@section FAQ


`The display is all messed up'

@quotation

First, check the value of the environment variable @code{TERM}.
It MUST be @code{eterm-color} or @code{eterm-direct}; nothing
else will work reliably.

If that still doesn’t work, please file a bug as described on
@ref{3,,Reporting issues}.
@end quotation

`warning: Could not set up terminal'

@quotation

If you’re getting errors such as the following from programs such
as @code{less} or @code{vi}, this means that the
@code{TERM} environment variable is set properly, but the host
doesn’t know about the terminal @code{eterm-color} or
@code{eterm-direct}.

@example
warning: Could not set up terminal.
warning: TERM environment variable set to 'eterm-color'.
warning: Check that this terminal type is supported on this system.
@end example

This might easily happen if you ssh into another host from inside
a MisTTY buffer. SSH typically forwards the value of the
@code{TERM} environment variable, which contains the terminal
name, but not @code{TERMCAP} environment variable, which contains
the terminal definition.

To fix this issue, you can do any one of the following:


@itemize -

@item 
Connect using TRAMP, as described in @ref{d,,Remote Shells with TRAMP}. TRAMP takes
care of setting all necessary environment variables.

@item 
Add the definition of @code{eterm-color} to all hosts you
regularly log into. To do that, follow the instructions in
@code{<data-directory>/e/README}, where
@code{<data-directory>} is the “etc” directory of your Emacs
installation, as shown by @cite{M-x describe-variable data-directory} - usually, that’s
@code{/usr/share/emacs/<emacs version>/etc/e/README}

@item 
Tell ssh to forward the @code{TERMCAP} environment variable. This
requires changing `both' the server and client configuration. On the
server @code{sshd_config}, add @code{AcceptEnv TERMCAP}. On the
client, add @code{SendEnv TERMCAP} to @code{ssh_config} or to
@code{~/.ssh/config}
@end itemize
@end quotation

`What are all those OCOCOCO or ODODODO that appear on the screen?'

@quotation

@geindex variable; mistty-forbid-edit-regexps

These are the terminal sequences that MisTTY sends to a program
to move the cursor left or right. If you see these printed on the
terminal, it means that the program that’s currently controlling
the terminal doesn’t support these.

In such situation, you can:


@itemize -

@item 
Only type self-inserting characters and @code{DEL}.

@item 
Press @code{C-c C-q} or @code{M-x mistty-send-key-sequence} to
send what you type directly to the terminal until you turn it
off with @code{C-g}.

@item 
Write a regexp that identifies the situation and add it to
@code{M-x customize-option mistty-forbid-edit-regexps} so MisTTY
knows it should not attempt to move the cursor. The default value
identifies most shell backward search prompts.
@end itemize

See the section @ref{e,,Terminal vs. Scrollback} for more details.
@end quotation

`The shell isn’t answering!'

@quotation

Press @code{C-g}. If this is just a one-time thing, this will do
the trick.

If this keeps happening, check the modeline. Does it contain CMD?
It might look like this: `misTTY CMD:run'. In that case, MisTTY is
stuck in long-running command mode. This is likely due to some
package leaving overlays to the buffer that confuse MisTTY. To fix
that, turn off the option @code{M-x customize-option
mistty-detect-foreign-overlays} or, if you know which package is
causing trouble, remove the corresponding property in in @code{M-x
customize-option mistty-foreign-overlay-properties}.

For details, see @ref{1d,,Long-running commands}

If this keeps happening and the modeline does not contain CMD,
this is likely a bug. Please see @ref{3,,Reporting issues} for details on
filing a bug report.
@end quotation

`Why is the cursor jumping around when I move it?'

@quotation

MisTTY jumps over spaces which just “aren’t there”, such as the
spaces between the command and the right prompt, spaces added by
@code{fish} for indentation in multi-line prompts.

If it doesn’t work with your shell or setup, or if you find it
confusing, type @code{M-x customize-option
mistty-skip-empty-spaces} to turn it off.
@end quotation

`What’s with the purple line?'

@quotation

This line indicates the region of the buffer that works as a
terminal, meaning that it is not fully editable and that some
shortcuts, such as @code{TAB} are sent directly to the program
controlling the terminal.

This is covered in depth in the section @ref{e,,Terminal vs. Scrollback}.

If you just don’t want to see that line, turn it off with
@code{M-x customize-option mistty-fring-enabled}
@end quotation

`Why doesn’t <insert package here> work in the terminal region?'

@quotation

The terminal region of MisTTY behaves very differently from a
normal buffer; many things can go wrong with commands that do more
than just editing text.

One such issue is with interactivly editing the buffer over
multiple Emacs command, which MisTTY calls a long-running command.
There are ways of making such commands work if they don’t already,
described in @ref{1d,,Long-running commands}.

Another such issue is with autocomplete, with can also be made to
work as described in @ref{1a,,Auto-complete}.

While this works with some packages, it might not necessarily work
with the package you want - it might even not be possible to make
it work, but we can always try. Please file a bug@footnote{https://github.com/szermatt/mistty/issues} if you encounter
such a package you’d like to work with MisTTY.
@end quotation

`… but it used to work!'

@quotation

Older versions used to detect any unknown overlay as a
long-running command, described in @ref{1d,,Long-running commands}. Unfortunately, this
caused problems with many packages which, leaving overlays around
for a long time, prevented MisTTY from working at all.

The good news is that it’s likely easy to make it work again by
detecting the specific kind of overlays the package is using.
Please see @ref{1d,,Long-running commands} or file a bug@footnote{https://github.com/szermatt/mistty/issues} mentioning the
package you’re using, its version and how you installed it.
@end quotation

`Why am I getting connection errors from TRAMP?'

@quotation

MisTTY tries to track the current directory whenever possible,
including from remote shells. You might get connection errors if
you connect to a remote or special shell from an existing MisTTY
that Emacs cannot access through TRAMP and then Emacs tries to
access a nonexisting remote file.

The best solution in such case is to configure TRAMP to connect to
that host, adding an entry to @code{M-x configure-option
mistty-host-to-tramp-path-alist}, if that’s necessary.

If that’s not possible or if you don’t want to bother, you might
find it convenient to just disable the generation of TRAMP paths
using @code{M-x configure-option mistty-allow-tramp-paths}.

For more details, see @ref{b,,Directory Tracking}.
@end quotation

@node Contributing,,FAQ,Contents
@anchor{contrib doc}@anchor{50}@anchor{contrib contributing}@anchor{51}
@section Contributing


@menu
* Reporting issues:: 
* Suggesting features:: 
* Asking questions:: 
* Code contributions:: 
* Documentation contributions:: 

@end menu

@node Reporting issues,Suggesting features,,Contributing
@anchor{contrib reporting}@anchor{3}@anchor{contrib reporting-issues}@anchor{52}
@subsection Reporting issues


At this time, the most useful thing you can do to help is and useful
bug reports to the Issue Tracker@footnote{https://github.com/szermatt/mistty/issues}

In your report, please discuss what you wanted to happen as well as
what happened. Also, please include enough information to reproduce
the issue. Such as:


@itemize -

@item 
the name and version of the program you were running - usually a shell

@item 
the version of Emacs you’re running, taken, for example, from @code{M-x about-emacs}

@item 
whether you’re running Emacs in a window environment or a terminal

@item 
what kind of prompt you’re using, that is, what it looks like, what
character it ends with, how many lines it has and whether you’re
using any kind of right prompt
@end itemize

@geindex command; mistty-start-log
@geindex command; mistty-stop-log

If you can reproduce reliably, please include the content of the
buffer @code{*mistty-log*} into your report, as follows:


@itemize -

@item 
Enable logging by calling @code{M-x mistty-start-log}

@item 
Reproduce the issue

@item 
Go to the buffer @code{*mistty-log*}

@item 
Call @code{M-x mistty-stop-log} to avoid getting more log entries

@item 
Copy the buffer content and paste it into the issue. The log
includes everything that you write to the terminal and everything
that you get back from the terminal. Please make sure you’re not
including any private information, such as password - remove them if
necessary…
@end itemize

If you cannot reproduce reliably,


@itemize -

@item 
go to @code{M-x customize-option mistty-backlog-size} to set the
backlog size to a large value, such as 50

@item 
use MisTTY normally, until the issue comes back

@item 
once it has happened again, immediately call @code{M-x
mistty-start-log}. The log will then contain entries for events that
happened just `before' you called the command.

@item 
call @code{M-x mistty-stop-log}

@item 
copy the content of the @code{*mistty-log*} buffer, strip out
anything private, and include it into the issue.
@end itemize

@node Suggesting features,Asking questions,Reporting issues,Contributing
@anchor{contrib issue-tracker}@anchor{53}@anchor{contrib suggesting-features}@anchor{54}
@subsection Suggesting features


Please add feature suggestions to the Issue Tracker@footnote{https://github.com/szermatt/mistty/issues}.

@node Asking questions,Code contributions,Suggesting features,Contributing
@anchor{contrib asking-questions}@anchor{55}
@subsection Asking questions


Open an issue on the Issue Tracker@footnote{https://github.com/szermatt/mistty/issues} with your question.

@node Code contributions,Documentation contributions,Asking questions,Contributing
@anchor{contrib code-contributions}@anchor{56}
@subsection Code contributions


To contribute code to the project, open a Pull Request@footnote{https://github.com/szermatt/mistty/pulls}.

Before you do that, please make sure the any new features is covered
by tests and that the tests pass.

To run the tests, install and setup eldev@footnote{https://github.com/emacs-eldev/eldev}, then run @code{eldev
test}.

Tests can also be run from inside of Emacs, using @cite{M-x ert-run-tests-interactively} but when you do so, be aware that there
might be unexpected interaction with your Emacs configurations. The
tests passing reliably when run using @code{eldev test} is what
matters.

@node Documentation contributions,,Code contributions,Contributing
@anchor{contrib documentation-contributions}@anchor{57}@anchor{contrib eldev}@anchor{58}
@subsection Documentation contributions


You don’t need to be a developer to contribute! Contribution to the
documentation or code comments are very welcome. Please open a Pull Request@footnote{https://github.com/szermatt/mistty/pulls} with your proposed modifications.

The documentation is written in reStructuredText. You’ll need to
install Sphinx@footnote{https://www.sphinx-doc.org} to build it:

@example
python3 -m venv venv
. venv/bin/activate # or activate.fish on fish
pip3 install -r docs/requirements.txt
@end example

Then run @code{eldev html} to build the documentation.

@node Index,,Contents,Top
@unnumbered Index


@printindex ge


@c %**end of body
@bye