doomemacs/modules/os/tty/README.org

os/tty

• Description
  • Maintainers
  • Module Flags
  • Plugins
• Prerequisites
• Configuration
  • True-color and italic support
• Troubleshooting

Description

This module configures Emacs for terminal usage.

• System clipboard integration (through an external clipboard program or OSC-52 escape codes in supported terminals).
• Fixes cursor-shape changing across evil states in terminal that support it.
• Mouse support in the terminal.

Maintainers

This module has no dedicated maintainers.

Module Flags

• +osc Instead of piping your kill ring through external programs, like xclip or pbcopy, have Emacs emit OSC-52 escape codes instead, allowing Emacs to communicate to your clipboard through your terminal. This allows for clipboard communication over SSH connections or tmux. However, this requires a supported terminal.

Plugins

• clipetty
• evil-terminal-cursor-changer
• xclip

Prerequisites

This module has no hard prerequisites, but in order for its features to work you need

• For system clipboard integration:

  • A supported clipboard program, such as:

    • Linux: xclip, xsel, or wl-clibpoard (Wayland)
    • macOS: pbcopy and pbpaste (included with macOS)
    • Windows: getclip and putclip (cygwin)
  • A terminal that supports OSC 52 escape codes, such as: xterm (unix), iTerm2 (macOS), alacritty (cross platform), kitty (macOS, linux), mintty (Windows), hterm (javascript), st (unix), mlterm (cross platform)

• For cursor shape changing:

  • A terminal that supports VT's DECSCUSR sequence, such as: Gnome Terminal, xterm, iTerm (macOS), Konsole, or mintty (Windows). Terminal.app (macOS) is supported to, but requires SIMBL and MouseTerm Plus to work.

Configuration

True-color and italic support

This advice only applies to Emacs 26.x. True color support is built into 27.1+ and newer.

(credit goes to the spacemacs wiki for this information)

Create a xterm-24bit.terminfo file with the following contents:

xterm-24bit|xterm with 24-bit direct color mode,
   use=xterm-256color,
   sitm=\E[3m,
   ritm=\E[23m,
   setb24=\E[48;2;%p1%{65536}%/%d;%p1%{256}%/%{255}%&%d;%p1%{255}%&%dm,
   setf24=\E[38;2;%p1%{65536}%/%d;%p1%{256}%/%{255}%&%d;%p1%{255}%&%dm,

WARNING: Make sure you have a newline at end of file otherwise you will get errors!

Execute the following command on the command line:

tic -x -o ~/.terminfo xterm-24bit.terminfo

Now set your $TERM variable to xterm-24bit:

export TERM=xterm-24bit

SSH might break if your remote machine does not have the same setup, you can work around this with the following alias.

alias ssh="TERM=xterm-256color ssh"

If you use tmux, you need to make sure you installed a version with truecolor support, then add the following lines to your `.tmux.conf`:

set -g default-terminal "xterm-24bit"
set -g terminal-overrides ',xterm-24bit:Tc'

Also, make sure you have utf8 language variables if you want all characters to display correctly. For example:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
export LANGUAGE=en_US.UTF-8

Troubleshooting