TMUX
Table of Contents
printf '\033[2J\033[3J\033[1;1H';
MISC
C-b C-z Suspend the tmux client.
C-b ~ Show previous messages from tmux, if any.
C-b : Enter the tmux command prompt.
C-b ? List all key bindings.
C-b t Show the time.
SESSION MANAGEMENT
$ tmux launch session
$ tmux a attach to session
$ tmux ls list sessions
C-b $ Rename the current session.
C-b D Choose a client to detach.
C-b d Detach the current client.
C-b r Force redraw of the attached client.
C-b s Select a new session for the attached client interactively.
C-b L Switch the attached client back to the last session.
WINDOWS MANAGEMENT
C-b c Create a new window.
C-b & Kill the current window.
C-b n Change to the next window.
C-b p Change to the previous window.
C-b l Move to the previously selected window.
C-b [0..9] Select windows 0 to 9.
C-b ' Prompt for a window index to select.
C-b . Prompt for an index to move the current window.
C-b , Rename the current window.
C-b w Choose the current window interactively.
C-b M-n Move to the next window with a bell or activity marker.
C-b M-p Move to the previous window with a bell or activity marker.
C-b f Prompt to search for text in open windows.
C-b i Display some information about the current window.
PANE MANAGEMENT
C-b x Kill the current pane.
C-b % Split the current pane into two, left and right.
C-b " Split the current pane into two, top and bottom.
C-b ! Break the current pane out of the window.
C-b q Briefly display pane indexes.
C-b o Select the next pane in the current window.
C-b Up
C-b Down
C-b Left
C-b Right Change to the pane above, below, to the left, or to the right
of the current pane.
C-b ; Move to the previously active pane.
LAYOUT
C-b : swap-window -s N -t M
Swap window N with M
C-b { Swap the current pane with the previous pane.
C-b } Swap the current pane with the next pane.
C-b C-o Rotate the panes in the current window forwards.
C-b M-o Rotate the panes in the current window backwards.
C-b <space> Switch to next layout
C-b M-1 to M-5 Arrange panes in one of the five preset layouts:
even-horizontal, even-vertical, main-horizontal, main-vertical,
or tiled.
C-b C-Up,
C-b C-Down
C-b C-Left,
C-b C-Right Resize the current pane in steps of one cell.
C-b M-Up,
C-b M-Down
C-b M-Left,
C-b M-Right Resize the current pane in steps of five cells.
paste buffers
C-b # List all paste buffers.
C-b - Delete the most recently copied buffer of text.
C-b = Choose which buffer to paste interactively from a list.
C-b [ Enter copy mode to copy text or view the history.
C-b ] Paste the most recently copied buffer of text.
C-b Page Up Enter copy mode and scroll one page up.
How do I use tmux?
The first step is to run tmux:
$ tmux
This starts a new tmux with a single new session (called "0") and creates a
client displaying it on screen. Most of the screen will show a window containing
a shell prompt, and you will notice the last line is occupied by a status line.
This shows the name of the session in square brackets on the left, the window
title (normally empty for shells) and the time on the right, and a summary of
the current open windows in the middle. In your new session, the currently open
windows will contain one entry, for example:
0:ksh*
Returning to the status line, the number "0" is the window index, "ksh" the name
of the window, and the "*" indicates this is the current window displayed above
the status line. Any typing is passed on to the shell and any output displayed.
For example, if you start "top":
$ top
It will run as normal, occupying the part of the screen above the status line.
You may also notice that the window name in the status line has changed from
"ksh" to "top" - tmux renames windows to reflect the program currently running
in them.
Now, let's say you want to detach tmux from the screen and return to the
original shell from which you started it. A tmux session may be detached by
first pressing the Ctrl and b keys together, and then the d key. The Ctrl-b key
combination (shortened in tmux and its man page to "C-b") is known as the prefix
key and is used to tell tmux that the next key pressed is an instruction that it
should perform some action, rather than passing the key through to the program
in the window.
After pressing Ctrl-b d and returning to the shell prompt, reattach the tmux
session using the "attach" command:
$ tmux attach
The tmux session will reappear, with the status line and "top" still happily
running. (If you instead run tmux again without arguments, a second session will
be created, named "1".)
Next, let's create a second window. This is done using the "c" key: press the
prefix key, Ctrl-b, then the "c" key. A new window will be created and again a
shell prompt displayed on screen. The status line will be updated to show the
new window:
0:top- 1:ksh*
The "-" after "top" shows the previously current window (the last window).
Pressing Ctrl-b c again creates another new shell:
0:top 1:ksh- 2:ksh*
There are several commands for moving between windows. From window 2, you can
move the previous window, number 1, by typing Ctrl-b p. Ctrl-b n moves to the
next window: in this case, there is no window 3 so the current window wraps to
window 0. You can also press Ctrl-b w to get an interactive menu of open
windows, Ctrl-b l to move to the last window (the one marked with "-"), or
Ctrl-b 0 to move to window 0, Ctrl-b 1 for window 1 and so on up to Ctrl-b 9 for
window 9. So, to get back to "top" in window 0, you can press Ctrl-b 0 to go
directly to window 0, Ctrl-b p twice to move via window 1, Ctrl-b n to wrap from
window 2 to window 0, or press Ctrl-b w and select window 0 from the list.
Sometimes you may want to create a window running a program directly, without
using a shell first. This can be done from the tmux command prompt. Pressing the
Ctrl-b : key sequence changes the status line to display a ":" prompt at which
commands may be entered. All the tmux commands are documented in the man page.
In this case the "new-window" command is needed. Each command has a shorthand
alias which may be used instead of typing the full name, for "new-window" this
is "neww". So, to create a new window running tetris(6), type:
neww tetris
The new window will close when tetris exits, or may be forcibly killed using the
Ctrl-b & key binding. This will first prompt for confirmation and if given,
close the window and terminate the program running in it.
Another common requirement is renaming a window. This can be done with the
Ctrl-b , key binding. The status line will change to display a "(rename-window)"
prompt at which the new name may be entered. Renaming a window turns off
automatic renaming for that window, to reenable that feature, press Ctrl-b : to
get to the command prompt and enter the following (more on what this means is in
the next section):
setw -u automatic-rename
One other important key is worth remembering: Ctrl-b ?. This will show a list of
all the tmux keys and the commands they execute. For example, Ctrl-b ? shows
that the c key is bound to the "new-window" command and the n key to the "next-
window" command.
## Configuring tmux
Many users want to customise the way tmux looks or behaves. This is done through
the configuration file, ~/.tmux.conf. This file is a list of tmux commands which
are executed when tmux is initially started, before the first session is
created. All tmux commands are documented in the man page, but a few common
examples you might want to put in your configuration file are discussed below.
The most common requirement is setting options. There are two types of option in
tmux: session options and window options. Session options control the behaviour
of a session and window options of an individual window. For both there is a set
of global options. When tmux comes to decide on an options value for a
particular session or window, it looks first at the options local to that
window; if the option has not been set, the global option value is used.
Session options are set with the "set-option" (alias "set") command and window
options with the "set-window-option" command (alias "setw"). To set a global
option, use the "-g" flag, if this is left out the option is set for the current
window or session. These commands also accept a few other flags, such as "-u" to
unset a local option and allow a window or session to inherit the global option
again.
In the configuration file, it is usual to set global options. Let's look at some
examples customising the status line:
set -g status-bg blue
set -g status-right '#(sysctl vm.loadavg)'
setw -g window-status-current-attr underscore
Putting these three commands in .tmux.conf and restarting tmux changes the
status line background to blue, puts the current load average on the right side
and underlines the current window. The status line may be turned off entirely
with:
set -g status off
There are a large number of other options; another handy one is changing to
vi(1)-style key bindings at the command prompt and in the window list and other
tmux interactive modes:
set -g status-keys vi
setw -g mode-keys vi
The current options and their values may be listed with the "show-options" and
"show-window-options" commands. Like the set commands these accept "-g" to show
the global options.
Another common task for the configuration file is adding or modifying tmux
command key bindings, that is the commands that are executed after you press
Ctrl-b with another key. These are added or changed with the "bind-key" command
(alias "bind") and removed with the "unbind-key" command (alias "unbind"). Two
examples of using "bind-key" are:
bind C-d detach
bind / neww 'exec top'
The first line creates a binding for Ctrl-b Ctrl-d to detach tmux, the same as
the default Ctrl-b d, and the second binds Ctrl-b / to create a new window
running top.
Many people like to use a different prefix key than Ctrl-b. This can be achieved
using both the "set-option" and key binding commands to alter the prefix key
option and change so that pressing the prefix twice continues to pass the same
key through to the window. To change the prefix key to Ctrl-a:
set -g prefix C-a
unbind C-b
bind C-a send-prefix
The final useful thing to do in the configuration file is to create an initial
set of windows when tmux starts. This is slightly more complicated than the
previous examples. In tmux, a session cannot have no windows, and you cannot
create windows without a session. So, to have windows created by the
configuration file you must first create a session to contain them. For example
(note that "new" is the alias for the "new-session" command):
new -d 'exec top'
neww -d
neww -d
These commands create a new session with "top" running in the first window, then
create two additional windows. The "-d" flags instruct tmux not to try to attach
the new session or to make the new windows the current window. Before putting
these lines into .tmux.conf, there is one other issue. When executed without
arguments, tmux runs the "new-session" command, so when starting tmux with
"tmux" from the shell, the configuration file tells tmux to create one session,
then the command from the shell tells it to create another, so you end up with
two sessions. To avoid this, tmux should be started with "tmux attach" when
creating a session from the configuration file - this means it will create the
session from .tmux.conf then immediately attach to it without creating a second
session.
## Advanced tmux usage
This section briefly covers some of the more advanced features available in
tmux. See the man page for more information.
In tmux, you can copy and paste text between windows. This is done by copying
the text in copy mode and then pasting it with the paste command. To enter copy
mode, press Ctrl-b [. In copy mode (with the "mode-keys" window option set to
emacs, for vi keys see the man page) the arrow keys may be used to position the
cursor, Ctrl-Space starts the selection and Ctrl-w copies. You can also use Page
Up, Page Down, Ctrl-a and Ctrl-e to move the cursor around. Press q or Escape to
exit copy mode. After that, Ctrl-b ] will paste the copied text into the current
window as if you had typed it directly.
tmux is quite scriptable, and most commands that may be entered from the command
prompt or bound to a key may be executed from the shell. Almost all tmux
commands accept an optional "-t" argument which specifies the session or window
on which to act. For example, this command:
$ tmux kill-window -t0:1
will kill window 1 in session 0. And:
$ tmux new-window -tmysession
creates a new window in the session named "mysession". Many commands accept
other arguments, for example the "new-window" command accepts a "-n" option to
give the name of the new window, and "new-session" accepts several arguments to
specify the attributes of the initial window created with the session. These
arguments may naturally be used when a command is bound to a key or executed
from the command prompt as well.
Another useful feature is the ability to split a single window into several
sections, called panes. You can split a window vertically (top to bottom) with
the Ctrl-b " key combination. A pane can be resized up or down with Ctrl-b Alt-
Up and Ctrl-b Alt-Down and the active pane changed with Ctrl-b o. In addition, a
window split in that way may be changed into one of a number of fixed layouts,
these are cycled through with Ctrl-b Space but panes in one of these layouts may
not be resized. In -current, splitting has been extended to support horizontal
splitting (Ctrl-b %) and the fixed layouts changed so they are applied once
(with the same Ctrl-b Space key strokes) but then may be freely resized and
modified both horizontally and vertically.