| TMUX(1) | General Commands Manual | TMUX(1) |
tmux —
tmux |
[-28dqUuv]
[-f file]
[-L socket-name]
[-S socket-path]
[command [flags]] |
tmux is a terminal multiplexer: it enables a number of
terminals to be accessed and controlled from a single terminal.
The options are as follows:
-2tmux to assume the terminal supports 256
colours.-8-2, but indicates that the terminal supports
88 colours.-dtmux to assume the terminal supports default
colours.-f
filetmux loads the system configuration file from
/etc/tmux.conf, if present, then looks for a user
configuration file at ~/.tmux.conf. The
configuration file is a set of tmux commands which
are executed in sequence when the server is first started.-L
socket-nametmux stores the server socket in a directory under
/tmp; the default socket is named
default. This option allows a different socket name to
be specified, allowing several independent tmux
servers to be run. Unlike -S a full path is not
necessary: the sockets are all created in the same directory.
If the socket is accidentally removed, the
SIGUSR1 signal may be sent to the
tmux server process to recreate it.
-q-S
socket-path-S is specified, the default socket directory is
not used and any -L flag is ignored.-U-utmux attempts to guess if the terminal is likely
to support UTF-8 by checking the first of the
LC_ALL, LC_CTYPE and
LANG environment variables to be set for the
string "UTF-8". This is not always correct: the
-u flag explicitly informs
tmux that UTF-8 is supported.
If the server is started from a client passed
-u or where UTF-8 is detected, the
utf8 and status-utf8
options are enabled in the global window and session options
respectively.
-vtmux, as described in the following sections. If
no command and flags are specified, the
new-session command is assumed.tmux runs as a server-client system. A server holds a
number of sessions, each of which may have a number of
windows linked to it. A server is started automatically when
the first session is created and exits when all the sessions it contains are
destroyed. A window may be split on screen into one or more
panes, each of which is a separate terminal. Any number of
clients may connect to a session, or the server may be
controlled by issuing commands with tmux.
Communication takes place through a socket, by default placed in
/tmp.
This is an overview of the sections in this manual page:
tmux commands work.tmux.tmux. Most commands accept the optional
-t argument with one of
target-client, target-session
target-window, or target-pane.
These specify the client, session, window or pane which a command should
affect. target-client is the name of the
pty(4) file to which the client is connected, for example
either of /dev/ttyp1 or ttyp1
for the client attached to /dev/ttyp1. If no client is
specified, the current client is chosen, if possible, or an error is reported.
Clients may be listed with the list-clients command.
target-session is either the name of a
session (as listed by the list-sessions command) or
the name of a client with the same syntax as
target-client, in which case the session attached to
the client is used. When looking for the session name,
tmux initially searches for an exact match; if none
is found, the session names are checked for any for which
target-session is a prefix or for which it matches as
an fnmatch(3) pattern. If a single match is found, it is
used as the target session; multiple matches produce an error. If a session
is omitted, the current session is used if available; if no current session
is available, the most recently created is chosen.
target-window specifies a window in the form
session:window.
session follows the same rules as for
target-session, and window is looked
for in order: as a window index, for example mysession:1; as an exact window
name, such as mysession:mywindow; then as an fnmatch(3)
pattern or the start of a window name, such as mysession:mywin* or
mysession:mywin. An empty window name specifies the next unused index if
appropriate (for example the new-window and
link-window commands) otherwise the current window
in session is chosen. When the argument does not contain a
colon, tmux first attempts to parse it as window; if
that fails, an attempt is made to match a session.
target-pane takes a similar form to
target-window but with the optional addition of a
period followed by a pane index, for example: mysession:mywindow.1. If the
pane index is omitted, the currently active pane in the specified window is
used. If neither a colon nor period appears, tmux
first attempts to use the argument as a pane index; if that fails, it is
looked up as for target-window.
Multiple commands may be specified together as part of a
command sequence. Each command should be separated by
spaces and a semicolon; commands are executed sequentially from left to
right. A literal semicolon may be included by escaping it with a backslash
(for example, when specifying a command sequence to
bind-key).
Examples include:
refresh-client -t/dev/ttyp2 rename-session -tfirst newname set-window-option -t:0 monitor-activity on new-window ; split-window -d bind-key D detach-client \; lock-server
attach-session
[-d] [-t
target-session]attach)tmux, create a new client in the
current terminal and attach it to target-session. If
used from inside, switch the current client. If -d
is specified, any other clients attached to the session are detached.
If no server is started,
attach-session will attempt to start it; this
will fail unless sessions are created in the configuration file.
detach-client
[-t target-client]detach)-t.has-session
[-t target-session]has)kill-servertmux server and clients and destroy all
sessions.kill-session
[-t target-session]list-clientslsc)list-commandslscm)tmux.list-sessionsls)new-session
[-d] [-n
window-name] [-s
session-name] [command]new)-d is given. window-name and
command are the name of and command to execute in
the initial window.refresh-client
[-t target-client]refresh)-t.rename-session
[-t target-session]
new-namerename)source-file
pathsource)start-serverstart)tmux server, if not already running,
without creating any sessions.suspend-client
[-c target-client]suspendc)SIGTSTP (tty stop).switch-client
[-c target-client]
[-t target-session]switchc)tmux window may be in one of several modes. The
default permits direct access to the terminal attached to the window. The
others are:
list-keys, is executed from a key binding.scroll-mode command
(bound to ‘=’ by default) and
permits the window history buffer to be inspected.copy-mode command,
bound to [‘The keys available depend on whether emacs or vi mode is selected
(see the mode-keys option). The following keys are
supported as appropriate for the mode:
| Function | vi | emacs |
Start
of line |
0 | C-a |
Back
to indentation |
^ | M-m |
Clear
selection |
Escape | C-g |
Copy
selection |
Enter | M-w |
Cursor
down |
j | Down |
End
of line |
$ | C-e |
Cursor
left |
h | Left |
Next
page |
C-f | Page down |
Next
word |
w | M-f |
Previous
page |
C-u | Page up |
Previous
word |
b | M-b |
Quit
mode |
q | Escape |
Cursor
right |
l | Right |
Start
selection |
Space | C-Space |
Cursor
up |
k | Up |
Delete
to end of line |
D | C-k |
Paste
buffer |
p | C-y |
These key bindings are defined in a set of named tables:
vi-edit and emacs-edit for keys used
when line editing at the command prompt; vi-choice and
emacs-choice for keys used when choosing from lists (such
as produced by the window-choose command) or in
output mode; and vi-copy and emacs-copy
used in copy and scroll modes. The tables may be viewed with the
list-keys command and keys modified or removed with
bind-key and unbind-key.
The paste buffer key pastes the first line from the top paste buffer on the stack.
The mode commands are as follows:
copy-mode
[-u] [-t
target-window]-u option scrolls one page
up.scroll-mode
[-u] [-t
target-window]-u has the same meaning as
in the copy-mode command.Each window displayed by tmux may be split
into one or more panes; each pane takes up a certain area
of the display and is a separate terminal. A window may be split into panes
using the split-window command. Windows may be split
horizontally (with the -h flag) or vertically. Panes
may be resized with the resize-pane command (bound
to ‘C-up’,
‘C-down’
‘C-left’ and
‘C-right’ by default), the current
pane may be changed with the up-pane and
down-pane commands and the
rotate-window and swap-pane
commands may be used to swap panes without changing their position. Panes
are numbered beginning from zero in the order they are created.
A number of preset layouts are available. These
may be selected with the select-layout command or
cycled with next-layout (bound to
‘C-space’ by default); once a layout
is chosen, panes within it may be moved and resized as normal.
The following layouts are supported:
even-horizontaleven-verticalmain-horizontalmain-verticalmain-horizontal but the large pane is
placed on the left and the others spread from top to bottom along the
right. See the main-pane-width window option.Commands related to windows and panes are as follows:
break-pane
[-d] [-t
target-pane]breakp)-d is
given, the new window does not become the current window.choose-session
[-t target-window]tmux.choose-window
[-t target-window]tmux.down-pane
[-t target-pane]downp)find-window
[-t target-window]
match-stringfindw)tmux.kill-pane
[-t target-pane]killp)kill-window
[-t target-window]killw)last-window
[-t target-session]last)link-window
[-dk] [-s
src-window] [-t
dst-window]linkw)-k is given and
dst-window exists, it is killed, otherwise an error
is generated. If -d is given, the newly linked
window is not selected.list-windows
[-t target-session]lsw)move-window
[-d] [-s
src-window] [-t
dst-window]movew)link-window, except the window at
src-window is moved to
dst-window.new-window
[-dk] [-n
window-name] [-t
target-window] [command]neww)-d is given, the session
does not make the new window the current window.
target-window represents the window to be created;
if the target already exists an error is shown, unless the
-k flag is used, in which case it is destroyed.
command is the command to execute. If
command is not specified, the default command is
used.
The TERM environment variable must be
set to “screen” for all programs running
inside tmux. New windows will
automatically have “TERM=screen” added to their
environment, but care must be taken not to reset this in shell start-up
files.
next-layout
[-t target-window]nextl)next-window
[-a] [-t
target-session]next)-a is
used, move to the next window with a bell, activity or content alert.previous-window
[-a] [-t
target-session]prev)-a,
move to the previous window with a bell, activity or content alert.rename-window
[-t target-window]
new-namerenamew)resize-pane
[-DLRU] [-t
target-pane] [adjustment]resizep)-U (the default),
downward with -D, to the left with
-L and to the right with
-R. The adjustment is given
in lines or cells (the default is 1).respawn-window
[-k] [-t
target-window] [command]respawnw)remain-on-exit window option). If
command is not given, the command used when the
window was created is executed. The window must be already inactive,
unless -k is given, in which case any existing
command is killed.rotate-window
[-DU] [-t
target-window]rotatew)-U or downward
(numerically higher).select-layout
[-t target-window]
[layout-name]select-pane
[-t target-pane]selectp)select-window
[-t target-window]selectw)split-window
[-dhv] [-l
size | -p
percentage] [-t
target-window] [command]-h
does a horizontal split and -v a vertical split;
if neither is specified, -v is assumed. The
-l and -p options specify
the size of the new window in lines (for vertical split) or in cells (for
horizontal split), or as a percentage, respectively. All other options
have the same meaning as in the new-window
command.swap-pane
[-dDU] [-s
src-pane] [-t
dst-pane]swapp)-U is used and no source pane is
specified with -s, dst-pane
is swapped with the previous pane (before it numerically);
-D swaps with the next pane (after it
numerically).swap-window
[-d] [-s
src-window] [-t
dst-window]swapw)link-window, except the source
and destination windows are swapped. It is an error if no window exists at
src-window.unlink-window
[-k] [-t
target-window]unlinkw)-k is given, a window may be unlinked only if it
is linked to multiple sessions - windows may not be linked to no sessions;
if -k is specified and the window is linked to
only one session, it is unlinked and destroyed.up-pane
[-t target-pane]upp)tmux may be controlled from an attached client by using
a key combination of a prefix key, ‘C-b’
(Ctrl-b) by default, followed by a command key.
Some of the default key bindings include:
A complete list may be obtained with the
list-keys command (bound to
‘?’ by default). Key bindings may be
changed with the bind-key and
unbind-key commands.
Commands related to key bindings are as follows:
bind-key
[-cnr] [-t
key-table] key
command [arguments]bind)C-’
or ‘^’ for Ctrl keys, or
‘M-’ for Alt (meta) keys.
By default (without -t) the primary
key bindings are modified (those normally activated with the prefix
key); in this case, if -n is specified, it is
not necessary to use the prefix key, command is
bound to key alone. The -r
flag indicates this key may repeat, see the
repeat-time option.
If -t is present,
key is bound in key-table:
the binding for command mode with -c or for
normal mode without. To view the default bindings and possible commands,
see the list-keys command.
list-keys
[-t key-table]lsk)-t the primary key
bindings - those executed when preceded by the prefix key - are printed.
Keys bound without the prefix key (see bind-key
-n) are enclosed in square brackets.
With -t, the key bindings in
key-table are listed; this may be one of:
vi-edit, emacs-edit,
vi-choice, emacs-choice,
vi-copy or emacs-copy.
send-keys
[-t target-window]
key ...send)C-a’
or ‘npage’ ) to send; if the string
is not recognised as a key, it is sent as a series of characters. All
arguments are sent sequentially from first to last.send-prefix
[-t target-window]unbind-key
[-cn] [-t
key-table] keyunbind)-t the primary key bindings are modified; in this
case, if -n is specified, the command bound to
key without a prefix (if any) is removed.
If -t is present,
key in key-table is unbound:
the binding for command mode with -c or for
normal mode without.
tmux may be modified by
changing the value of various options. There are two types of option:
session options and window options.
Each individual session may have a set of session options, and
there is a separate set of global session options. Sessions which do not
have a particular option configured inherit the value from the global
session options. Session options are set or unset with the
set-option command and may be listed with the
show-options command. The available session options
are listed under the set-option command.
Similarly, a set of window options is attached to each window, and
there is a set of global window options from which any unset options are
inherited. Window options are altered with the
set-window-option command and can be listed with the
show-window-options command. All window options are
documented with the set-window-option command.
Commands which set options are as follows:
set-option
[-agu] [-t
target-session] option
valueset)-a, and if the option
expects a string, value is appended to the existing
setting. If -g is specified, the global session
option is set. The -u flag unsets an option, so a
session inherits the option from the global options - it is not possible
to unset a global option.
Available session options are:
bell-action
[any | none |
current]any means a bell in
any window linked to a session causes a bell in the current window of
that session, none means all bells are ignored
and current means only bell in windows other
than the current window are ignored.buffer-limit
numberdefault-command
commandtmux to create a login
shell using the SHELL environment variable or,
if it is unset, the user's shell returned by
getpwuid(3).default-path
pathdefault-terminal
terminalTERM environment
variable. For tmux to work correctly, this
must be set to
‘screen’ or a derivative of
it.display-time
timehistory-limit
lineslock-after-time
number-g.message-attr
attributesdefault or a comma-delimited list of one or
more of: bright (or
bold), dim,
underscore, blink,
reverse, hidden, or
italics.message-bg
colourblack,
red, green,
yellow, blue,
magenta, cyan,
white or default.message-fg
colourprefix
keyrepeat-time
time-r flag to
bind-key. Repeat is enabled for the default
keys bound to the resize-pane command.set-remain-on-exit
[on | off]remain-on-exit window option for any
windows first created in this session.set-titles
[on | off]status
[on | off]status-attr
attributesstatus-bg
colourstatus-fg
colourstatus-interval
intervalstatus-justify
[left | centre |
right]status-keys
[vi | emacs]status-left
string| Character pair | Replaced with |
#(command) |
First line of command's output |
#H |
Hostname of local host |
#I |
Current window index |
#P |
Current pane index |
#S |
Session name |
#T |
Current window title |
#W |
Current window name |
## |
A literal ‘#’ |
Where appropriate, these may be prefixed with a number to
specify the maximum length, for example
‘#24T’.
By default, UTF-8 in string is not
interpreted, to enable UTF-8, use the
status-utf8 option.
status-left-length
lengthstatus-right
stringstatus-left, string will
be passed to strftime(3), character pairs are
replaced, and UTF-8 is dependent on the
status-utf8 option.status-right-length
lengthstatus-utf8
[on | off]tmux to treat top-bit-set characters
in the status-left and
status-right strings as UTF-8; notably, this
is important for wide characters. This option defaults to off.terminal-overrides
stringFor example, to set the
‘clear’
terminfo(5) entry to
‘\e[H\e[2J’ for all terminal
types and the ‘dch1’ entry to
‘\e[P’ for the
‘rxvt’ terminal type, the
option could be set to the string:
"*:clear=\e[H\e[2J,rxvt:dch1=\e[P"
The terminal entry value is passed through
strunvis(3) before interpretation. The default
value forcibly corrects the
‘colors’ entry for terminals
which support 88 or 256 colours:
"*88col*:colors=88,*256col*:colors=256"
visual-activity
[on | off]monitor-activity window option
is enabled.visual-bell
[on | off]bell-action option.visual-content
[on | off]visual-activity, display a message when
content is present in a window for which the
monitor-content window option is enabled.set-window-option
[-agu] [-t
target-window] option
valuesetw)-a,
-g and -u flags work
similarly to the set-option command.
Supported window options are:
aggressive-resize
[on | off]tmux will resize the window to the size of the
smallest session for which it is the current window, rather than the
smallest session to which it is attached. The window may resize when
the current window is changed on another sessions; this option is good
for full-screen programs which support
SIGWINCH and poor for interactive programs
such as shells.
automatic-rename
[on | off]tmux will attempt - on supported platforms -
to rename the window to reflect the command currently running in it.
This flag is automatically disabled for an individual window when a
name is specified at creation with new-window
or new-session, or later with
rename-window. It may be switched off globally
with:
set-window-option -g automatic-rename off
clock-mode-colour
colourclock-mode-style
[12 | 24]force-height
heightforce-width
widthtmux from resizing a window to greater
than width or height. A
value of zero restores the default unlimited setting.
main-pane-width
widthmain-pane-height
heightmain-horizontal or
main-vertical layouts.
mode-attr
attributesmode-bg
colourmode-fg
colourmode-keys
[vi | emacs]mode-mouse
[on | off]tmux will respond
to mouse clicks by moving the cursor in copy mode or selecting an
option in choice mode.
monitor-activity
[on | off]monitor-content
match-stringremain-on-exit
[on | off]respawn-window command.
utf8
[on | off]tmux to expect UTF-8 sequences to
appear in this window.
window-status-attr
attributeswindow-status-bg
colourwindow-status-fg
colourwindow-status-current-attr
attributeswindow-status-current-bg
colourwindow-status-current-fg
colourxterm-keys
[on | off]tmux will generate
xterm(1) -style function key sequences; these have a
number included to indicate modifiers such as Shift, Alt or Ctrl.show-options
[-g] [-t
target-session]show)-g.show-window-options
[-g] [-t
target-window]showw)-g is used.tmux includes an optional status line which is displayed
in the bottom line of each terminal. By default, the status line is enabled
(it may be disabled with the status session option)
and contains, from left-to-right: the name of the current session in square
brackets; the window list; the current window title in double quotes; and the
time and date.
The status line is made of three parts: configurable left and
right sections (which may contain dynamic content such as the time or output
from a shell command, see the status-left,
status-left-length,
status-right, and
status-right-length options below), and a central
window list. The window list shows the index, name and (if any) flag of the
windows present in the current session in ascending numerical order. The
flag is one of the following symbols appended to the window name:
| Symbol | Meaning |
* |
Denotes the current window. |
- |
Marks the last window (previously selected). |
# |
Window is monitored and activity has been detected. |
| ! | A bell has occurred in the window. |
+ |
Window is monitored for content and it has appeared. |
The # symbol relates to the
monitor-activity and + to the
monitor-content window options. The window name is
printed in inverted colours if an alert (bell, activity or content) is
present.
The colour and attributes of the status line may be configured,
the entire status line using the status-attr,
status-fg and status-bg
session options and individual windows using the
window-status-attr,
window-status-fg and
window-status-bg window options.
The status line is automatically refreshed at interval if it has
changed, the interval may be controlled with the
status-interval session option.
Commands related to the status line are as follows:
command-prompt
[-t target-client]
[template]tmux to execute commands interactively. If
template is specified, it is used as the command;
any %% in the template will be replaced by what is entered at the
prompt.confirm-before
[-t target-client]
commandconfirm)tmux.display-message
[-t target-client]
[message]display)status-left option below)
in the status line.select-prompt
[-t target-client]tmux maintains a stack of paste
buffers for each session. Up to the value of the
buffer-limit option are kept; when a new buffer is
added, the buffer at the bottom of the stack is removed. Buffers may be added
using copy-mode or the
set-buffer command, and pasted into a window using the
paste-buffer command.
A configurable history buffer is also maintained for each window.
By default, up to 2000 lines are kept; this can be altered with the
history-limit option (see the
set-option command above).
The buffer commands are as follows:
clear-history
[-t target-pane]clearhist)copy-buffer
[-a src-index]
[-b dst-index]
[-s src-session]
[-t dst-session]copyb)delete-buffer
[-b buffer-index]
[-t target-session]deleteb)list-buffers
[-t target-session]lsb)load-buffer
[-b buffer-index]
[-t target-session]
pathloadb)paste-buffer
[-dr] [-b
buffer-index] [-t
target-window]pasteb)-d, also delete the paste buffer from the stack.
When output, any linefeed (LF) characters in the paste buffer are replaced
with carriage returns (CR). This translation may be disabled with the
-r flag.save-buffer
[-a] [-b
buffer-index] [-t
target-session] pathsaveb)-a option appends
to rather than overwriting the file.set-buffer
[-b buffer-index]
[-t target-session]
datasetb)show-buffer
[-b buffer-index]
[-t target-session]showb)clock-mode
[-t target-window]if-shell
shell-command commandif)lock-serverlock)server-infoinfo)set-password
[-c] passwordpass)-c option is given,
a pre-encrypted password may be specified. By default, the password is
blank, thus any entered password will be accepted when unlocking the
server (see the lock-server command). To prevent
variable expansion when an encrypted password is read from a configuration
file, enclose it in single quotes (').tmux configuration file.tmux session running
vi(1):
$ tmux new-session viMost commands have a shorter form, known as an alias. For
new-session, this is new:
$ tmux new viAlternatively, the shortest unambiguous form of a command is accepted. If there are several options, they are listed:
$ tmux n ambiguous command: n, could be: new-session, new-window, next-window
Within an active session, a new window may be created by typing
‘C-b c’ (Ctrl followed by the
‘b’ key followed by the
‘c’ key).
Windows may be navigated with: ‘C-b
0’ (to select window 0), ‘C-b
1’ (to select window 1), and so on;
‘C-b n’ to select the next window; and
‘C-b p’ to select the previous
window.
A session may be detached using ‘C-b
d’ and reattached with:
$ tmux attach-sessionTyping ‘C-b ?’ lists the
current key bindings in the current window; up and down may be used to
navigate the list or ‘q’ to exit from
it.
Commands to be run when the tmux server is
started may be placed in the ~/.tmux.conf
configuration file. Common examples include:
Changing the default prefix key:
set-option -g prefix C-a unbind-key C-b bind-key C-a send-prefix
Turning the status line off, or changing its colour:
set-option -g status off set-option -g status-bg blue
Setting other options, such as the default command, or locking after 30 minutes of inactivity:
set-option -g default-command "exec /bin/ksh" set-option -g lock-after-time 1800
Creating new key bindings:
bind-key b set-option status bind-key / command-prompt "split-window 'exec man %%'"
| August 4, 2009 | BSD |