[http://tmux.github.io/ tmux] is a "terminal multiplexer: it enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached."

[http://tmux.github.io/ tmux] is a "terminal multiplexer: it enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached."

Revision as of 04:17, 10 April 2018

tmux is a "terminal multiplexer: it enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached."

tmux is an ISC-licensed alternative to GNU Screen. Although similar, there are many differences between the programs, as noted on the tmux FAQ page.

Installation

Configuration

A user-specific configuration file should be located at ~/.tmux.conf, while a global configuration file should be located at /etc/tmux.conf.

Key bindings

By default, command key bindings are prefixed by Ctrl-b. For example, to vertically split a window type Ctrl-b+%.

After splitting a window into multiple panes, a pane can be resized by the hitting prefix key (e.g. Ctrl-b) and, while continuing to hold Ctrl, press Left/Right/Up/Down. Swapping panes is achieved in the same manner, but by hitting o instead of a directional key.

Key bindings may be changed with the bind and unbind commands in tmux.conf. For example, the default prefix binding of Ctrl-b can be changed to Ctrl-a by adding the following commands in your configuration file:

unbind C-b
set -g prefix C-a
bind C-a send-prefix

Tip: Quote special characters to use them as prefix. You may also use Alt (called Meta) instead of Ctrl. For example: set -g prefix m-'\'

Additional ways to move between windows include the following:

Ctrl-b l (Move to the previously selected window)
Ctrl-b w (List all windows / window numbers)
Ctrl-b <window number> (Move to the specified window number, the default bindings are from 0 – 9)
Ctrl-b q (Show pane numbers, when the numbers show up type the key to goto that pane)

tmux has a find-window option & key binding to ease navigation of many windows:

Copy Mode

A tmux window may be in one of several modes. The default permits direct access to the terminal attached to the window; the other is copy mode. Once in copy mode you can navigate the buffer including scrolling the history. Use vi or emacs-style key bindings in copy mode. The default is emacs, unless VISUAL or EDITOR contains ‘vi’

To enter copy mode do the following:

Ctrl-b [

You can navigate the buffer as you would in your default editor.

To quit copy mode, use one of the following keybindings:

vi mode:

q

emacs mode:

Esc

Browsing URLs

To browse URLs inside tmux you must have urlviewAUR installed and configured.

Setting the correct term

256 colors

If you are using a 256 colour terminal, you will need to set the correct term in tmux. As of tmux 2.1, this is now tmux, or tmux-256color. You can do this in tmux.conf:

set -g default-terminal "tmux-256color"

Other, older alternatives, include screen, or screen-256color:

set -g default-terminal "screen-256color"

Also, if tmux messes up, you can force tmux to assume that the terminal support 256 colors, by adding this in your .bashrc:

alias tmux="tmux -2"

24-bit color

tmux supports 24-bit color as of version 2.2 ([1]). If your terminal supports 24-bit color (see this gist), add your terminal to the terminal-overrides setting. For example, if you use Termite, you would add:

set -ga terminal-overrides ",xterm-termite:Tc"

For other terminals, replace xterm-termite with the relevant terminal type (stored in $TERM). See the tmux(1) man page for details about the Tc terminfo extension.

xterm-keys

To enable xterm-keys in your tmux.conf, you have to add the following line

set-option -g xterm-keys on

If you enable xterm-keys in your tmux.conf, then you need to build a custom terminfo to declare the new escape codes or applications will not know about them. Compile the following with tic and you can use "xterm-screen-256color" as your TERM:

# A screen- based TERMINFO that declares the escape sequences
# enabled by the tmux config "set-window-option -g xterm-keys".
#
# Prefix the name with xterm- since some applications inspect
# the TERM *name* in addition to the terminal capabilities advertised.
xterm-screen-256color|GNU Screen with 256 colors bce and tmux xterm-keys,
# As of Nov'11, the below keys are picked up by
# .../tmux/blob/master/trunk/xterm-keys.c:
kDC=\E[3;2~, kEND=\E[1;2F, kHOM=\E[1;2H,
kIC=\E[2;2~, kLFT=\E[1;2D, kNXT=\E[6;2~, kPRV=\E[5;2~,
kRIT=\E[1;2C,
# Change this to screen-256color if the terminal you run tmux in
# doesn't support bce:
use=screen-256color-bce,

Autostart with systemd

There are some notable advantages to starting a tmux server at startup.
Notably, when you start a new tmux session, having the service already running reduces any delays in the startup.

Furthermore, any customization attached to your tmux session will be retained and your tmux session can be made to persist even if you have never logged in, if you have some reason to do that (like a heavily scripted tmux configuration or shared user tmux sessions).

The service below starts tmux for the specified user (i.e. start with tmux@username.service):

X clipboard integration

It is possible to copy tmux selection to X clipboard (and to X primary/secondary selection) and in reverse direction. The following tmux config file snippet effectively integrates X clipboard/selection with the current tmux selection using the program xsel:

xclip could also be used for that purpose, unlike xsel it works better on printing raw bitstream that doesn't fit the current locale. Nevertheless, it is neater to use xsel instead of xclip, because xclip does not close STDOUT after it has read from tmux's buffer. As such, tmux doesn't know that the copy task has completed, and continues to wait for xclip's termination, thereby rendering tmux unresponsive. A workaround is to redirect STDOUT of xclip to /dev/null, like in the following:

That's it. Be sure to end all instances of tmux before trying the new MiddleClick functionality.

While in tmux, Shift+MiddleMouseClick will paste the clipboard selection while just MiddleMouseClick will paste your tmux buffer.
Outside of tmux, just use MiddleMouseClick to paste your tmux buffer and your standard Ctrl-c to copy.

Tips and tricks

Start tmux with default session layout

Session managers like tmuxinator and tmuxp make it easy to manage common session configurations.

For tmuxinator, install tmuxinatorAUR from AUR. Test your installation with

tmuxinator doctor

Get the default layout values

Start tmux as usual and configure your windows and panes layout as you like. When finished, get the current layout values by executing (while you are still within the current tmux session)

tmux list-windows

The output may look like this (two windows with 3 panes and 2 panes layout)

The Interesting part you need to copy for later use begins after [layout... and excludes ... ] @2 (active). For the first window layout you need to copy e.g. 20a0,274x83,0,0{137x83,0,0,3,136x83,138,0[136x41,138,0,5,136x41,138,42,6]}

Define the default tmux layout

Knowing this, you can exit the current tmux session. Following this, you create your default tmux session layout by editing tmuxinator's config file (Don't copy the example, get your layout values as described above)

The example defines two windows named "default" and "remote". With your determined layout values. For each pane you have to use at least one - line. Within the first window panes you start the commandline "clear" in pane one, "vim" in pane two and "clear && emacs -nw" executes two commands in pane three on each tmux start. The second window layout has two panes without defining any start commmands.

Test the new default layout with (yes, it is "mux"):

mux default

Autostart tmux with default tmux layout

If you like to start your terminal session with your default tmux session layout edit

~/.bashrc

if [ -z "$TMUX" ]; then
mux default
fi

Alternate approach for default session

Instead of using the above method, one can just write a bash script that when run, will create the default session and attach to it.
Then you can execute it from a terminal to get the pre-designed configuration in that terminal

Note: This snippet ensures that tmux is not launched inside of itself (something tmux usually already checks for anyway). tmux sets $TMUX to the socket it is using whenever it runs, so if $TMUX isn't set or is length 0, we know we aren't already running tmux.

Add the following snippet to start only one session (unless you start some manually), on login, try attach at first, only create a session if no tmux is running.

# TMUX
if which tmux >/dev/null 2>&1; then
#if not inside a tmux session, and if no session is started, start a new session
test -z "$TMUX" && (tmux attach || tmux new-session)
fi

The following snippet does the same thing, but also checks tmux is installed before trying to launch it. It also tries to reattach you to an existing tmux session at logout, so that you can shut down every tmux session quickly from the same terminal at logout.

Start a non-login shell

Users of fortune may notice that quotes are printed when creating a new panel.

The configuration files for login shells such as ~/.profile are interpreted each time a new panel is created, so commands intended to be run on session initialization (e.g. setting audio level) are executed.

To disable this behaviour, add to ~/.tmux.conf:

set -g default-command "${SHELL}"

Use tmux windows like tabs

The following settings added to ~/.tmux.conf allow to use tmux windows like tabs, such as those provided by the reference of these hotkeys — urxvt's tabbing extensions[broken link: invalid section]. An advantage thereof is that these virtual “tabs” are independent of the terminal emulator.

Clients simultaneously interacting with various windows of a session

Screen and tmux's behaviour for when multiple clients are attached to one session differs slightly. In Screen, each client can be connected to the session but view different windows within it, but in tmux, all clients connected to one session must view the same window.

This problem can be solved in tmux by spawning two separate sessions and synchronizing the second one to the windows of the first, then pointing a second new session to the first.

The script “tmx” below implements this — the version here is slightly modified to execute “tmux new-window” if “1” is its second parameter. Invoked as tmx <base session name> [1] it launches the base session if necessary. Otherwise a new “client” session linked to the base, optionally add a new window and attach, setting it to kill itself once it turns “zombie”.

"mksc foo" creates a always detached permanent client named "foo". It also calls "rsc foo" to create a client to newly created session. "rsc foo" creates a new client grouped by "foo" name. It has destroy-unattached turned on so when I leave it, it kills client.

Therefore, when my computer looses network connectivity, all "foo.something" clients are killed while "foo" remains. I can then call "rsc foo" to continue work from where I stopped.

Reload an updated configuration without restarting tmux

By default tmux reads ~/.tmux.conf only if it was not already running. To have tmux load a configuration file afterwards, execute:

tmux source-file <path>

This can be added to ~/.tmux.conf as e. g.:

bind r source-file <path>

You can also do ^: and type :

source .tmux.conf

Template script to run program in new session resp. attach to existing one

This script checks for a program presumed to have been started by a previous run of itself. Unless found it creates a new tmux session and attaches to a window named after and running the program. If however the program was found it merely attaches to the session and selects the window.

A derived version to run irssi with the nicklist plugin can be found on its ArchWiki page.

Terminal emulator window titles

If you SSH into a host in a tmux window, you'll notice the window title of your terminal emulator remains to be user@localhost rather than user@server. To allow the title bar to adapt to whatever host you connect to, set the following in ~/.tmux.conf

set -g set-titles on
set -g set-titles-string "#T"

For set-titles-string, #T will display user@host:~ and change accordingly as you connect to different hosts.

Automatic layouting

When creating new splits or destroying older ones the currently selected layout isn't applied. To fix that, add following binds which will apply the currently selected layout to new or remaining panes:

Troubleshooting

Scrolling issues

If you have issues scrolling with Shift-Page Up/Down in your terminal, the following will remove the smcup and rmcup capabilities for any term that reports itself as anything beginning with xterm:

set -ga terminal-overrides ',xterm*:smcup@:rmcup@'

This tricks the terminal emulator into thinking tmux is a full screen application like pico or mutt[4], which will make the scrollback be recorded properly. Beware however, it will get a bit messed up when switching between windows/panes. Consider using tmux's native scrollback instead.

Mouse scrolling

Note: This interferes with selection buffer copying and pasting. To copy/paste to/from the selection buffer hold the shift key.

If you want to scroll with your mouse wheel, ensure mode-mouse is on in .tmux.conf

set -g mouse on

You can set scroll History with:

set -g history-limit 30000

For mouse wheel scrolling as from tmux 2.1 try adding one or both of these to ~/.tmux.conf