tmux (1) Linux Manual Page

NAME

tmux – terminal multiplexer

SYNOPSIS

tmux -words [-28lCquvV ] [-c shell-command ] [-f file ] [-L socket-name ] [-S socket-path ] [command [flags ] ]

DESCRIPTION

tmux is a terminal multiplexer: it enables a number of terminals 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.

When tmux is started it creates a new session with a single window and displays it on screen. A status line at the bottom of the screen shows information on the current session and is used to enter interactive commands.

A session is a single collection of pseudo terminals under the management of . Each session has one or more windows linked to it. A window occupies the entire screen and may be split into rectangular panes, each of which is a separate pseudo terminal (the pty(4) manual page documents the technical details of pseudo terminals). Any number of tmux instances may connect to the same session, and any number of windows may be present in the same session. Once all sessions are killed, tmux exits.

Each session is persistent and will survive accidental disconnection (such as ssh(1) connection timeout) or intentional detaching (with the `C-b’ d key strokes). tmux may be reattached using:

$ tmux attach

In , a session is displayed on screen by a client and all sessions are managed by a single server The server and each client are separate processes which communicate through a socket in /tmp

The options are as follows:

-2

Force tmux to assume the terminal supports 256 colours.

-8

Like –2 but indicates that the terminal supports 88 colours.

-C

Start in control mode. Given twice ( Fl CC ) Xc disables echo.

-c shell-command

Execute shell-command using the default shell. If necessary, the tmux server will be started to retrieve the default-shell option. This option is for compatibility with sh(1) when tmux is used as a login shell.

-f file

Specify an alternative configuration file. By default, tmux 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. tmux loads configuration files once when the server process has started. The source-file command may be used to load a file later.

tmux shows any error messages from commands in configuration files in the first session created, and continues to process the rest of the configuration file.

-L socket-name tmux

stores the server socket in a directory under /tmp (or TMPDIR if set); 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.

-l

Behave as a login shell. This flag currently has no effect and is for compatibility with other shells when using tmux as a login shell.

-q

Set the quiet server option to prevent the server sending various informational messages.

-S socket-path

Specify a full alternative path to the server socket. If –S is specified, the default socket directory is not used and any –L flag is ignored.

-u tmux

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.

-v

Request verbose logging. This option may be specified multiple times for increasing verbosity. Log messages will be saved into tmux-client-PID.log and tmux-server-PID.log files in the current directory, where PID is the PID of the server or client process.

-V

Report the tmux version.

command [flags ]

This specifies one of a set of commands used to control , as described in the following sections. If no commands are specified, the new-session command is assumed.

KEY BINDINGS

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.

The default command key bindings are:

C-b

Send the prefix key (C-b) through to the application.

C-o

Rotate the panes in the current window forwards.

C-z

Suspend the tmux client.

!

Break the current pane out of the window.

"

Split the current pane into two, top and bottom.

#

List all paste buffers.

$

Rename the current session.

%

Split the current pane into two, left and right.

&

Kill the current window.

‘

Prompt for a window index to select.

,

Rename the current window.

–

Delete the most recently copied buffer of text.

.

Prompt for an index to move the current window.

0 to 9

Select windows 0 to 9.

:

Enter the tmux command prompt.

;

Move to the previously active pane.

=

Choose which buffer to paste interactively from a list.

?

List all key bindings.

D

Choose a client to detach.

[

Enter copy mode to copy text or view the history.

]

Paste the most recently copied buffer of text.

c

Create a new window.

d

Detach the current client.

f

Prompt to search for text in open windows.

i

Display some information about the current window.

l

Move to the previously selected window.

n

Change to the next window.

o

Select the next pane in the current window.

p

Change to the previous window.

q

Briefly display pane indexes.

r

Force redraw of the attached client.

s

Select a new session for the attached client interactively.

L

Switch the attached client back to the last session.

t

Show the time.

w

Choose the current window interactively.

x

Kill the current pane.

{

Swap the current pane with the previous pane.

}

Swap the current pane with the next pane.

~

Show previous messages from , if any.

Page Up Enter copy mode and scroll one page up.

Up, Down

Left, Right

Change to the pane above, below, to the left, or to the right of the current pane.

M-1 to M-5

Arrange panes in one of the five preset layouts: even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled.

M-n

Move to the next window with a bell or activity marker.

M-o

Rotate the panes in the current window backwards.

M-p

Move to the previous window with a bell or activity marker.

C-Up, C-Down

C-Left, C-Right

Resize the current pane in steps of one cell.

M-Up, M-Down

M-Left, M-Right

Resize the current pane in steps of five cells.

Key bindings may be changed with the bind-key and unbind-key commands.

COMMANDS

This section contains a list of the commands supported by . 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 the session id prefixed with a $, 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 used 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 a window ID, such as @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. The special character `!’ uses the last (previously current) window, `^’ selects the highest numbered window, `$’ selects the lowest numbered window, and `+’ and `-‘ select the next window or the previous window by number. 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 A `+’ or `-‘ indicate the next or previous pane index, respectively. One of the strings top bottom left right top-left top-right bottom-left or bottom-right may be used instead of a pane index.

The special characters `+’ and `-‘ may be followed by an offset, for example:

select-window -t:+2

When dealing with a session that doesn’t contain sequential window indexes, they will be correctly skipped.

tmux also gives each pane created in a server an identifier consisting of a `%’ and a number, starting from zero. A pane’s identifier is unique for the life of the tmux server and is passed to the child process of the pane in the TMUX_PANE environment variable. It may be used alone to target a pane or the window containing it.

shell-command arguments are sh(1) commands. These must be passed as a single item, which typically means quoting them, for example:

new-window 'vi /etc/passwd'

command [arguments ] refers to a tmux command, passed with the command and arguments separately, for example:

bind-key F1 set-window-option force-width 81

Or if using sh(1):

$ tmux bind-key F1 set-window-option force-width 81

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 and lines ending with a backslash continue on to the next line, except when escaped by another backslash. A literal semicolon may be included by escaping it with a backslash (for example, when specifying a command sequence to bind-key )

Example tmux commands 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 R source-file ~/.tmux.conf \; \
        display-message "source-file done"

Or from sh(1):

$ tmux kill-window -t :1
$ tmux new-window \; split-window -d
$ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach

CLIENTS AND SESSIONS

The tmux server manages clients, sessions, windows and panes. Clients are attached to sessions to interact with them, either when they are created with the new-session command, or later with the attach-session command. Each session has one or more windows linked into it. Windows may be linked to multiple sessions and are made up of one or more panes, each of which contains a pseudo terminal. Commands for creating, linking and otherwise manipulating windows are covered in the Sx WINDOWS AND PANES section.

The following commands are available to manage clients and sessions:

attach-session [-dr ] [-t target-session ]

If run from outside , 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. –r signifies the client is read-only (only keys bound to the detach-client or switch-client commands have any effect)

If no server is started, attach-session will attempt to start it; this will fail unless sessions are created in the configuration file.

The target-session rules for attach-session are slightly adjusted: if tmux needs to select the most recently used session, it will prefer the most recently used unattached session.

detach-client [-P ] [-a ] [-s target-session ] [-t target-client ]

Detach the current client if bound to a key, the client specified with –t or all clients currently attached to the session specified by –s The –a option kills all but the client given with –t If –P is given, send SIGHUP to the parent process of the client, typically causing it to exit.

has-session [-t target-session ]

Report an error and exit with 1 if the specified session does not exist. If it does exist, exit with 0.

kill-server

Kill the tmux server and clients and destroy all sessions.

kill-session

[-a ] [-t target-session ] Destroy the given session, closing any windows linked to it and no other sessions, and detaching all clients attached to it. If –a is given, all sessions but the specified one is killed.

list-clients [-F format ] [-t target-session ]

List all clients attached to the server. For the meaning of the –F flag, see the Sx FORMATS section. If target-session is specified, list only clients connected to that session.

list-commands

List the syntax of all commands supported by .

list-sessions [-F format ]

List all sessions managed by the server. For the meaning of the –F flag, see the Sx FORMATS section.

lock-client [-t target-client ]

Lock target-client see the lock-server command.

lock-session [-t target-session ]

Lock all clients attached to target-session

new-session [-AdDP ] [-F format ] [-n window-name ] [-s session-name ] [-t target-session ] [-x width ] [-y height ] [shell-command ]

Create a new session with name session-name

The new session is attached to the current terminal unless –d is given. window-name and shell-command are the name of and shell command to execute in the initial window. If –d is used, –x and –y specify the size of the initial window (80 by 24 if not given).

If run from a terminal, any termios(4) special characters are saved and used for new windows in the new session.

The –A flag makes new-session behave like attach-session if session-name already exists; in the case, –D behaves like –d to attach-session

If –t is given, the new session is grouped with target-session This means they share the same set of windows – all windows from target-session are linked to the new session and any subsequent new windows or windows being closed are applied to both sessions. The current and previous window and any session options remain independent and either session may be killed without affecting the other. Giving –n or shell-command are invalid if –t is used.

The –P option prints information about the new session after it has been created. By default, it uses the format `#{session_name}:’ but a different format may be specified with –F

refresh-client [-S ] [-t target-client ]

Refresh the current client if bound to a key, or a single client if one is given with –t If –S is specified, only update the client’s status bar.

rename-session [-t target-session ] new-name

Rename the session to new-name

show-messages [-t target-client ]

Any messages displayed on the status line are saved in a per-client message log, up to a maximum of the limit set by the message-limit session option for the session attached to that client. This command displays the log for target-client

source-file path

Execute commands from path

start-server

Start the tmux server, if not already running, without creating any sessions.

suspend-client [-t target-client ]

Suspend a client by sending SIGTSTP (tty stop).

switch-client [-lnpr ] [-c target-client ] [-t target-session ]

Switch the current session for client target-client to target-session If –l –n or –p is used, the client is moved to the last, next or previous session respectively. –r toggles whether a client is read-only (see the attach-session command).

WINDOWS AND PANES

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, which permits a section of a window or its history to be copied to a paste buffer for later insertion into another window. This mode is entered with the copy-mode command, bound to `[‘ by default. It is also entered when a command that produces output, such as list-keys is executed from a key binding.

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 Ta vi Ta emacs

Back to indentation Ta ^ Ta M-m

Bottom of history Ta G Ta M-<

Clear selection Ta Escape Ta C-g

Copy selection Ta Enter Ta M-w

Cursor down Ta j Ta Down

Cursor left Ta h Ta Left

Cursor right Ta l Ta Right

Cursor to bottom line Ta L Ta

Cursor to middle line Ta M Ta M-r

Cursor to top line Ta H Ta M-R

Cursor up Ta k Ta Up

Delete entire line Ta d Ta C-u

Delete/Copy to end of line Ta D Ta C-k

End of line Ta $ Ta C-e

Go to line Ta : Ta g

Half page down Ta C-d Ta M-Down

Half page up Ta C-u Ta M-Up

Jump forward Ta f Ta f

Jump to forward Ta t Ta

Jump backward Ta F Ta F

Jump to backward Ta T Ta

Jump again Ta ; Ta ;

Jump again in reverse Ta , Ta ,

Next page Ta C-f Ta Page down

Next space Ta W Ta

Next space, end of word Ta E Ta

Next word Ta w Ta

Next word end Ta e Ta M-f

Paste buffer Ta p Ta C-y

Previous page Ta C-b Ta Page up

Previous word Ta b Ta M-b

Previous space Ta B Ta

Quit mode Ta q Ta Escape

Rectangle toggle Ta v Ta R

Scroll down Ta C-Down or C-e Ta C-Down

Scroll up Ta C-Up or C-y Ta C-Up

Search again Ta n Ta n

Search again in reverse Ta N Ta N

Search backward Ta ? Ta C-r

Search forward Ta / Ta C-s

Start of line Ta 0 Ta C-a

Start selection Ta Space Ta C-Space

Top of history Ta g Ta M->

Transpose characters Ta Ta C-t

The next and previous word keys use space and the `-‘ , `_’ and `@’ characters as word delimiters by default, but this can be adjusted by setting the word-separators session option. Next word moves to the start of the next word, next word end to the end of the next word and previous word to the start of the previous word. The three next and previous space keys work similarly but use a space alone as the word separator.

The jump commands enable quick movement within a line. For instance, typing `f’ followed by `/’ will move the cursor to the next `/’ character on the current line. A `;’ will then jump to the next occurrence.

Commands in copy mode may be prefaced by an optional repeat count. With vi key bindings, a prefix is entered using the number keys; with emacs, the Alt (meta) key and a number begins prefix entry. For example, to move the cursor forward by ten words, use `M-1′ 0 M-f in emacs mode, and `10w’ in vi.

When copying the selection, the repeat count indicates the buffer index to replace, if used.

Mode 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 choose-window command); and vi-copy and emacs-copy used in copy mode. The tables may be viewed with the list-keys command and keys modified or removed with bind-key and unbind-key One command accepts an argument, copy-pipe which copies the selection and pipes it to a command. For example the following will bind `C-q’ to copy the selection into /tmp as well as the paste buffer:

bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out"

The paste buffer key pastes the first line from the top paste buffer on the stack.

The synopsis for the copy-mode command is:

copy-mode [-u ] [-t target-pane ]

Enter copy mode. The –u option scrolls one page up.

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 select-pane command 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 `Space’ by default); once a layout is chosen, panes within it may be moved and resized as normal.

The following layouts are supported:

even-horizontal

Panes are spread out evenly from left to right across the window.

even-vertical

Panes are spread evenly from top to bottom.

main-horizontal

A large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom. Use the main-pane-height window option to specify the height of the top pane.

main-vertical

Similar to main-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.

tiled

Panes are spread out as evenly as possible over the window in both rows and columns.

In addition, select-layout may be used to apply a previously used layout – the list-windows command displays the layout of each window in a form suitable for use with select-layout For example:

$ tmux list - windows 0 : ksh[159x48] layout : bb62, 159x48, 0, 0 {79x48, 0, 0, 79x48, 80, 0} $ tmux select - layout bb62, 159x48, 0, 0
{
    79x48, 0, 0, 79x48, 80, 0
}

tmux automatically adjusts the size of the layout for the current window size. Note that a layout cannot be applied to a window with more panes than that from which the layout was originally defined.

Commands related to windows and panes are as follows:

break-pane [-dP ] [-F format ] [-t target-pane ]

Break target-pane off from its containing window to make it the only pane in a new window. If –d is given, the new window does not become the current window. The –P option prints information about the new window after it has been created. By default, it uses the format `#{session_name}:#{window_index}’ but a different format may be specified with –F

capture-pane [-aep([-b buffer-index ] ) ] [-E end-line ] [-S start-line ] [-t target-pane ]

Capture the contents of a pane. If –p is given, the output goes to stdout, otherwise to the buffer specified with –b or a new buffer if omitted. If –a is given, the alternate screen is used, and the history is not accessible. If no alternate screen exists, an error will be returned unless –q is given. If –e is given, the output includes escape sequences for text and background attributes. –C also escapes non-printable characters as octal