Emacs-libvterm (vterm) is fully-fledged terminal emulator inside GNU Emacs based on libvterm, a C library. As a result of using compiled code (instead of elisp), emacs-libvterm is fully capable, fast, and it can seamlessly handle large outputs.
This package is in active development and, while being stable enough to be used as a daily-driver, it is currently in early alpha stage. This means that occasionally the public interface will change (for example names of options or functions). A list of recent breaking changes is in appendix. Moreover, emacs-libvterm deals directly with some low-level operations, hence, bugs in the code can lead to segmentation faults and crashes. If that happens, please report the problem.
Before installing emacs-libvterm, you need to make sure you have installed
- GNU Emacs (>= 25.1) with module
support.
You can check that, by verifying that
module-file-suffix
is notnil
. - cmake (>= 3.11)
- libtool-bin (related issues: #66 #85)
- OPTIONAL: libvterm. This library can be found in the official repositories of most distributions (e.g., Arch, Debian, Fedora, Gentoo, openSUSE, Ubuntu). If not available, it will be downloaded during the compilation process.
vterm
is available on MELPA, and it can be installed as
a normal package. If the requirements are satisfied (mainly, Emacs was built
with support for modules), vterm
will compile the module the first time it is
run. This is the recommended way to install vterm
.
vterm
can be install from MELPA with use-package
by adding the following
lines to your init.el
:
(use-package vterm
:ensure t)
To take full advantage of the capabilities of vterm
, you should configure your
shell too. Read about this in the section shell-side
configuration.
Clone the repository:
git clone https://github.com/akermu/emacs-libvterm.git
By default, vterm will try to find if libvterm is installed. If it is not found,
emacs-libvterm will download the latest version available of libvterm (from
here), compile it, and use it. If you
always want to use the vendored version as opposed to the one on you system, set
USE_SYSTEM_LIBVTERM
to Off
. To do this, change cmake ..
with cmake -DUSE_SYSTEM_LIBVTERM=Off ..
in the following instructions.
Build the module with:
cd emacs-libvterm
mkdir -p build
cd build
cmake ..
make
And add this to your init.el
:
(add-to-list 'load-path "path/to/emacs-libvterm")
(require 'vterm)
Or, with use-package
:
(use-package vterm
:load-path "path/to/emacs-libvterm/")
Using vterm
on Ubuntu requires additional steps. The latest LTS version
(18.04) ships with a version of CMake that is too old for vterm
and GNU
Emacs is not compiled with support for dynamical module loading.
It is possible to install GNU Emacs with module support from Kevin Kelley's PPA. The binary in Ubuntu Emacs Lisp PPA is currently broken and leads to segmentation faults (see #185). In case Emacs is already on the system, you need to purge it before proceeding with the following commands.
sudo add-apt-repository ppa:kelleyk/emacs
sudo apt update
sudo apt-get install emacs26
A way to install a recent version of CMake (>= 3.11) is with linuxbrew.
brew install cmake
In some cases, /bin/sh
needs to be relinked to /bin/bash
for the compilation
to work (see,
#216).
Pull requests to improve support for Ubuntu are welcome (e.g., simplyfing the installation).
vterm
and its dependencies are available in GNU Guix as
emacs-vterm.
The package can be installed with guix package -i emacs-vterm
.
Some of the most useful features in vterm
(e.g.,
directory-tracking and prompt-tracking or
message passing) require shell-side configurations. The main goal of
these additional functions is to enable the shell to send information to vterm
via properly escaped sequences. A function that helps in this task,
vterm_printf
, is defined below. This function is widely used throughout this
readme.
For bash
or zsh
, put this in your .zshrc
or .bashrc
function vterm_printf(){
if [ -n "$TMUX" ]; then
# Tell tmux to pass the escape sequences through
# (Source: http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1324)
printf "\ePtmux;\e\e]%s\007\e\\" "$1"
elif [ "${TERM%%-*}" = "screen" ]; then
# GNU screen (screen, screen-256color, screen-256color-bce)
printf "\eP\e]%s\007\e\\" "$1"
else
printf "\e]%s\e\\" "$1"
fi
}
For fish
put this in your ~/.config/fish/config.fish
:
function vterm_printf;
if [ -n "$TMUX" ]
# tell tmux to pass the escape sequences through
# (Source: http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1324)
printf "\ePtmux;\e\e]%s\007\e\\" "$argv"
else if string match -q -- "screen*" "$TERM"
# GNU screen (screen, screen-256color, screen-256color-bce)
printf "\eP\e]%s\007\e\\" "$argv"
else
printf "\e]%s\e\\" "$argv"
end
end
If you have successfully built the module, you can test it by executing the
following command in the build
directory:
make run
Open a terminal in the current window.
Open a terminal in another window.
When you enable vterm-copy-mode
, the terminal buffer behaves like a normal
read-only
text buffer: you can search, copy text, etc. The default keybinding
to toggle vterm-copy-mode
is C-c C-t
. When a region is selected, it is
possible to copy the text and leave vterm-copy-mode
with the enter key.
If no region is selected when the enter key is pressed it will copy the current
line from start to end. If vterm-copy-exclude-prompt
is true it will skip
the prompt and not include it in the copy.
vterm-clear-scrollback
does exactly what the name suggests: it clears the
current buffer from the data that it is not currently visible.
vterm-clear-scrollback
is bound to C-c C-l
. This function is typically used
with the clear
function provided by the shell to clear both screen and
scrollback. In order to achieve this behavior, you need to add a new shell alias.
For zsh
, put this in your .zshrc
:
if [[ "$INSIDE_EMACS" = 'vterm' ]]; then
alias clear='vterm_printf "51;Evterm-clear-scrollback";tput clear'
fi
For bash
, put this in your .bashrc
:
if [[ "$INSIDE_EMACS" = 'vterm' ]]; then
function clear(){
vterm_printf "51;Evterm-clear-scrollback";
tput clear;
}
fi
These aliases take advantage of the fact that vterm
can execute elisp
commands, as explained below.
If it possible to automatically clear the scrollback when the screen is cleared
by setting the variable vterm-clear-scrollback-when-clearing
: When
vterm-clear-scrollback-when-clearing
is non nil, C-l
clears both the screen
and the scrollback. When is nil, C-l
only clears the screen. The opposite
behavior can be achieved by using the universal prefix (ie, calling C-u C-l
).
Shell to run in a new vterm. It defaults to $SHELL
.
Value for the TERM
environment variable. It defaults to xterm-256color
. If
eterm-256color is installed,
setting vterm-term-environment-variable
to eterm-color
improves the
rendering of colors in some systems.
If set to t
, buffers are killed when the associated process is terminated
(for example, by logging out the shell).
Compilation flags and arguments to be given to CMake when compiling the module.
This string is directly passed to CMake, so it uses the same syntax. At the
moment, it main use is for compiling vterm using the system libvterm instead of
the one downloaded from GitHub. You can find all the arguments and flags
available with cmake -LA
in the build directory.
Controls whether or not to exclude the prompt when copying a line in
vterm-copy-mode
. Using the universal prefix before calling
vterm-copy-mode-done
will invert the value for that call, allowing you to
temporarily override the setting.
The variable vterm-copy-use-vterm-prompt
determines whether to use the vterm
prompt tracking, if false it use the regexp in vterm-copy-prompt-regexp
to
search for the prompt. If not found, it copies the whole line.
When vterm-buffer-name-string
is not nil, vterm renames automatically its own
buffers with vterm-buffer-name-string
. This string can contain the character
%s
, which is substituted with the title (as defined by the shell, see
below). A possible value for vterm-buffer-name-string
is vterm %s
, according
to which all the vterm buffers will be named "vterm TITLE".
This requires some shell-side configuration to print the title. For example to set the name "HOSTNAME:PWD", use can you the following:
For zsh
autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ print -Pn "\e]2;%m:%2~\a" }
For bash
,
PROMPT_COMMAND='echo -ne "\033]0;\h:\w\007"'
For fish
,
function fish_title
hostname
echo ":"
pwd
end
See zsh and bash and (fish documentations)[https://fishshell.com/docs/current/#programmable-title].
Vterm needs vterm-module
to work. This can be compiled externally, or vterm
will ask the user whether to build the module when vterm
is first called. To
avoid this question and always compile the module, set
vterm-always-compile-module
to t
.
If you want a key to be sent to the terminal, bind it to vterm--self-insert
,
or remove it from vterm-mode-map
. By default, vterm.el
binds most of the
C-<char>
and M-<char>
keys, <f1>
through <f12>
and some special keys
like <backspace>
and <return>
. Sending a keyboard interrupt is bound to C-c C-c
.
If you would like to change the font or face used in a vterm, use the following code:
(add-hook 'vterm-mode-hook
(lambda ()
(set (make-local-variable 'buffer-face-mode-face) 'fixed-pitch)
(buffer-face-mode t)))
The above would change change the font in vterm buffers to a mono-spaced font
(the fixed-pitch
face) if your default font in Emacs is a proportional font.
Set the :foreground
and :background
attributes of the following faces to a
color you like. The :foreground
is ansi color 0-7, the :background
attribute
is ansi color 8-15.
- vterm-color-default
- vterm-color-black
- vterm-color-red
- vterm-color-green
- vterm-color-yellow
- vterm-color-blue
- vterm-color-magenta
- vterm-color-cyan
- vterm-color-white
vterm
supports directory tracking. If this feature is enabled, the default
directory in Emacs and the current working directory in vterm
are synced. As a
result, interactive functions that ask for a path or a file (e.g., dired
or
find-file
) will do so starting from the current location.
And vterm
supports prompt tracking. If this feature is enabled, Emacs knows
where the prompt ends, you needn't customize term-prompt-regexp
any more.
Then you can use vterm-next-prompt
and vterm-previous-prompt
moving to end of next/previous prompt. The default keybinding is C-c C-n
and C-c C-p
.
And vterm-beginning-of-line
would move the point to the first character after the
shell prompt on this line. If the point is already there, move to the beginning of the line.
The default keybinding is C-a
in vterm-copy-mode
.
And vterm--at-prompt-p
would check whether the cursor is at the point just after
the shell prompt.
Directory tracking and Prompt tracking requires some configuration, as the shell has to be
instructed to share the relevant information with Emacs. The following pieces of
code assume that you have the function vterm_printf
as defined in section
shell-side configuration.
For zsh
, put this at the end of your .zshrc
:
vterm_prompt_end() {
vterm_printf "51;A$(whoami)@$(hostname):$(pwd)";
}
setopt PROMPT_SUBST
PROMPT=$PROMPT'%{$(vterm_prompt_end)%}'
For bash
, put this at the end of your .bashrc
:
vterm_prompt_end(){
vterm_printf "51;A$(whoami)@$(hostname):$(pwd)"
}
PS1=$PS1'\[$(vterm_prompt_end)\]'
For fish
, put this in your ~/.config/fish/config.fish
:
function vterm_prompt_end;
vterm_printf '51;A'(whoami)'@'(hostname)':'(pwd)
end
functions -c fish_prompt vterm_old_fish_prompt
function fish_prompt --description 'Write out the prompt; do not replace this. Instead, put this at end of your file.'
# Remove the trailing newline from the original prompt. This is done
# using the string builtin from fish, but to make sure any escape codes
# are correctly interpreted, use %b for printf.
printf "%b" (string join "\n" (vterm_old_fish_prompt))
vterm_prompt_end
end
Directory tracking works on remote servers too. In case the hostname of your
remote machine does not match the actual hostname needed to connect to that
server, change $(hostname)
with the correct one. For example, if the correct
hostname is foo
and the username is bar
, you should have something like
HOSTNAME=foo
USER=baz
vterm_printf "51;A$USER@$HOSTNAME:$(pwd)"
vterm
can read and execute commands. At the moment, a command is
passed by providing a specific escape sequence. For example, to evaluate
(message "Hello!")
use
printf "\e]51;Emessage \"Hello\!\"\e\\"
# or
vterm_printf "51;Emessage \"Hello\!\""
The commands that are understood are defined in the setting vterm-eval-cmds
.
As split-string-and-unquote
is used the parse the passed string, double quotes
and backslashes need to be escaped via backslash. For instance, bash can replace
strings internally.
vterm_cmd() {
if [ -n "$TMUX" ]; then
# tell tmux to pass the escape sequences through
# (Source: http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1324)
printf "\ePtmux;\e\e]51;E"
elif [ "${TERM%%-*}" = "screen" ]; then
# GNU screen (screen, screen-256color, screen-256color-bce)
printf "\eP\e]51;E"
else
printf "\e]51;E"
fi
printf "\e]51;E"
local r
while [[ $# -gt 0 ]]; do
r="${1//\\/\\\\}"
r="${r//\"/\\\"}"
printf '"%s" ' "$r"
shift
done
if [ -n "$TMUX" ]; then
# tell tmux to pass the escape sequences through
# (Source: http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1324)
printf "\007\e\\"
elif [ "${TERM%%-*}" = "screen" ]; then
# GNU screen (screen, screen-256color, screen-256color-bce)
printf "\007\e\\"
else
printf "\e\\"
fi
}
However if you are using dash and need a pure POSIX implementation:
vterm_cmd() {
if [ -n "$TMUX" ]; then
# tell tmux to pass the escape sequences through
# (Source: http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1324)
printf "\ePtmux;\e\e]51;E"
elif [ "${TERM%%-*}" = "screen" ]; then
# GNU screen (screen, screen-256color, screen-256color-bce)
printf "\eP\e]51;E"
else
printf "\e]51;E"
fi
while [ $# -gt 0 ]; do
printf '"%s" ' "$(printf "%s" "$1" | sed -e 's|\\|\\\\|g' -e 's|"|\\"|g')"
shift
done
if [ -n "$TMUX" ]; then
# tell tmux to pass the escape sequences through
# (Source: http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1324)
printf "\007\e\\"
elif [ "${TERM%%-*}" = "screen" ]; then
# GNU screen (screen, screen-256color, screen-256color-bce)
printf "\007\e\\"
else
printf "\e\\"
fi
}
Now we can write shell functions to call the ones defined in vterm-eval-cmds
.
find_file() {
vterm_cmd find-file "$(realpath "$@")"
}
say() {
vterm_cmd message "%s" "$*"
}
This can be used inside vterm
as
find_file name_of_file_in_local_directory
As an example, say you like having files opened below the current window. You could add the command to do it on the lisp side like so:
(push (list "find-file-below"
(lambda (path)
(if-let* ((buf (find-file-noselect path))
(window (display-buffer-below-selected buf nil)))
(select-window window)
(message "Failed to open file: %s" path))))
vterm-eval-cmds)
Then add the command in your .bashrc
file.
open_file_below() {
vterm_cmd find-file-below "$(realpath "$@")"
}
Then you can open any file from inside your shell.
open_file_below ~/Documents
This can be fixed by rebinding the key to what C-w
does:
(define-key vterm-mode-map (kbd "<C-backspace>")
(lambda () (interactive) (vterm-send-key (kbd "C-w"))))
Add this piece of code to your configuration file to make counsel
use
the correct function to yank in vterm buffers.
(defun vterm-counsel-yank-pop-action (orig-fun &rest args)
(if (equal major-mode 'vterm-mode)
(let ((inhibit-read-only t)
(yank-undo-function (lambda (_start _end) (vterm-undo))))
(cl-letf (((symbol-function 'insert-for-yank)
(lambda (str) (vterm-send-string str t))))
(apply orig-fun args)))
(apply orig-fun args)))
(advice-add 'counsel-yank-pop-action :around #'vterm-counsel-yank-pop-action)
- vterm-toggle: Toggles between a vterm and the current buffer
- multi-libvterm: Multiterm for emacs-libvterm
vterm-clear-scrollback
was renamed tovterm-clear-scrollback-when-clearning
.vterm-set-title-functions
was removed. In its place, there is a new custom optionvterm-buffer-name-string
. See vterm-buffer-name-string for documentation.