diff options
Diffstat (limited to 'tmux.1')
| -rw-r--r-- | tmux.1 | 6830 |
1 files changed, 6830 insertions, 0 deletions
@@ -0,0 +1,6830 @@ +.\" $OpenBSD$ +.\" +.\" Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER +.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING +.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt TMUX 1 +.Os +.Sh NAME +.Nm tmux +.Nd terminal multiplexer +.Sh SYNOPSIS +.Nm tmux +.Bk -words +.Op Fl 2CDluvV +.Op Fl c Ar shell-command +.Op Fl f Ar file +.Op Fl L Ar socket-name +.Op Fl S Ar socket-path +.Op Fl T Ar features +.Op Ar command Op Ar flags +.Ek +.Sh DESCRIPTION +.Nm +is a terminal multiplexer: +it enables a number of terminals to be created, accessed, and +controlled from a single screen. +.Nm +may be detached from a screen +and continue running in the background, +then later reattached. +.Pp +When +.Nm +is started, it creates a new +.Em session +with a single +.Em 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. +.Pp +A session is a single collection of +.Em pseudo terminals +under the management of +.Nm . +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 +.Xr pty 4 +manual page documents the technical details of pseudo terminals). +Any number of +.Nm +instances may connect to the same session, +and any number of windows may be present in the same session. +Once all sessions are killed, +.Nm +exits. +.Pp +Each session is persistent and will survive accidental disconnection +(such as +.Xr ssh 1 +connection timeout) or intentional detaching (with the +.Ql C-b d +key strokes). +.Nm +may be reattached using: +.Pp +.Dl $ tmux attach +.Pp +In +.Nm , +a session is displayed on screen by a +.Em client +and all sessions are managed by a single +.Em server . +The server and each client are separate processes which communicate through a +socket in +.Pa /tmp . +.Pp +The options are as follows: +.Bl -tag -width "XXXXXXXXXXXX" +.It Fl 2 +Force +.Nm +to assume the terminal supports 256 colours. +This is equivalent to +.Fl T Ar 256 . +.It Fl C +Start in control mode (see the +.Sx CONTROL MODE +section). +Given twice +.Xo ( Fl CC ) Xc +disables echo. +.It Fl c Ar shell-command +Execute +.Ar shell-command +using the default shell. +If necessary, the +.Nm +server will be started to retrieve the +.Ic default-shell +option. +This option is for compatibility with +.Xr sh 1 +when +.Nm +is used as a login shell. +.It Fl D +Do not start the +.Nm +server as a daemon. +This also turns the +.Ic exit-empty +option off. +With +.Fl D , +.Ar command +may not be specified. +.It Fl f Ar file +Specify an alternative configuration file. +By default, +.Nm +loads the system configuration file from +.Pa @SYSCONFDIR@/tmux.conf , +if present, then looks for a user configuration file at +.Pa ~/.tmux.conf, +.Pa $XDG_CONFIG_HOME/tmux/tmux.conf +or +.Pa ~/.config/tmux/tmux.conf . +.Pp +The configuration file is a set of +.Nm +commands which are executed in sequence when the server is first started. +.Nm +loads configuration files once when the server process has started. +The +.Ic source-file +command may be used to load a file later. +.Pp +.Nm +shows any error messages from commands in configuration files in the first +session created, and continues to process the rest of the configuration file. +.It Fl L Ar socket-name +.Nm +stores the server socket in a directory under +.Ev TMUX_TMPDIR +or +.Pa /tmp +if it is unset. +The default socket is named +.Em default . +This option allows a different socket name to be specified, allowing several +independent +.Nm +servers to be run. +Unlike +.Fl S +a full path is not necessary: the sockets are all created in a directory +.Pa tmux-UID +under the directory given by +.Ev TMUX_TMPDIR +or in +.Pa /tmp . +The +.Pa tmux-UID +directory is created by +.Nm +and must not be world readable, writable or executable. +.Pp +If the socket is accidentally removed, the +.Dv SIGUSR1 +signal may be sent to the +.Nm +server process to recreate it (note that this will fail if any parent +directories are missing). +.It Fl 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. +.It Fl N +Do not start the server even if the command would normally do so (for example +.Ic new-session +or +.Ic start-server ) . +.It Fl S Ar socket-path +Specify a full alternative path to the server socket. +If +.Fl S +is specified, the default socket directory is not used and any +.Fl L +flag is ignored. +.It Fl u +Write UTF-8 output to the terminal even if the first environment +variable of +.Ev LC_ALL , +.Ev LC_CTYPE , +or +.Ev LANG +that is set does not contain +.Qq UTF-8 +or +.Qq UTF8 . +This is equivalent to +.Fl T Ar UTF-8 . +.It Fl T Ar features +Set terminal features for the client. +This is a comma-separated list of features. +See the +.Ic terminal-features +option. +.It Fl v +Request verbose logging. +Log messages will be saved into +.Pa tmux-client-PID.log +and +.Pa tmux-server-PID.log +files in the current directory, where +.Em PID +is the PID of the server or client process. +If +.Fl v +is specified twice, an additional +.Pa tmux-out-PID.log +file is generated with a copy of everything +.Nm +writes to the terminal. +.Pp +The +.Dv SIGUSR2 +signal may be sent to the +.Nm +server process to toggle logging between on (as if +.Fl v +was given) and off. +.It Fl V +Report the +.Nm +version. +.It Ar command Op Ar flags +This specifies one of a set of commands used to control +.Nm , +as described in the following sections. +If no commands are specified, the +.Ic new-session +command is assumed. +.El +.Sh DEFAULT KEY BINDINGS +.Nm +may be controlled from an attached client by using a key combination of a +prefix key, +.Ql C-b +(Ctrl-b) by default, followed by a command key. +.Pp +The default command key bindings are: +.Pp +.Bl -tag -width "XXXXXXXXXX" -offset indent -compact +.It C-b +Send the prefix key (C-b) through to the application. +.It C-o +Rotate the panes in the current window forwards. +.It C-z +Suspend the +.Nm +client. +.It ! +Break the current pane out of the window. +.It \&" +.\" " +Split the current pane into two, top and bottom. +.It # +List all paste buffers. +.It $ +Rename the current session. +.It % +Split the current pane into two, left and right. +.It & +Kill the current window. +.It ' +Prompt for a window index to select. +.It \&( +Switch the attached client to the previous session. +.It \&) +Switch the attached client to the next session. +.It , +Rename the current window. +.It - +Delete the most recently copied buffer of text. +.It . +Prompt for an index to move the current window. +.It 0 to 9 +Select windows 0 to 9. +.It : +Enter the +.Nm +command prompt. +.It ; +Move to the previously active pane. +.It = +Choose which buffer to paste interactively from a list. +.It \&? +List all key bindings. +.It D +Choose a client to detach. +.It L +Switch the attached client back to the last session. +.It \&[ +Enter copy mode to copy text or view the history. +.It \&] +Paste the most recently copied buffer of text. +.It c +Create a new window. +.It d +Detach the current client. +.It f +Prompt to search for text in open windows. +.It i +Display some information about the current window. +.It l +Move to the previously selected window. +.It m +Mark the current pane (see +.Ic select-pane +.Fl m ) . +.It M +Clear the marked pane. +.It n +Change to the next window. +.It o +Select the next pane in the current window. +.It p +Change to the previous window. +.It q +Briefly display pane indexes. +.It r +Force redraw of the attached client. +.It s +Select a new session for the attached client interactively. +.It t +Show the time. +.It w +Choose the current window interactively. +.It x +Kill the current pane. +.It z +Toggle zoom state of the current pane. +.It { +Swap the current pane with the previous pane. +.It } +Swap the current pane with the next pane. +.It ~ +Show previous messages from +.Nm , +if any. +.It Page Up +Enter copy mode and scroll one page up. +.It Up, Down +.It Left, Right +Change to the pane above, below, to the left, or to the right of the current +pane. +.It M-1 to M-5 +Arrange panes in one of the five preset layouts: even-horizontal, +even-vertical, main-horizontal, main-vertical, or tiled. +.It Space +Arrange the current window in the next preset layout. +.It M-n +Move to the next window with a bell or activity marker. +.It M-o +Rotate the panes in the current window backwards. +.It M-p +Move to the previous window with a bell or activity marker. +.It C-Up, C-Down +.It C-Left, C-Right +Resize the current pane in steps of one cell. +.It M-Up, M-Down +.It M-Left, M-Right +Resize the current pane in steps of five cells. +.El +.Pp +Key bindings may be changed with the +.Ic bind-key +and +.Ic unbind-key +commands. +.Sh COMMAND PARSING AND EXECUTION +.Nm +supports a large number of commands which can be used to control its +behaviour. +Each command is named and can accept zero or more flags and arguments. +They may be bound to a key with the +.Ic bind-key +command or run from the shell prompt, a shell script, a configuration file or +the command prompt. +For example, the same +.Ic set-option +command run from the shell prompt, from +.Pa ~/.tmux.conf +and bound to a key may look like: +.Bd -literal -offset indent +$ tmux set-option -g status-style bg=cyan + +set-option -g status-style bg=cyan + +bind-key C set-option -g status-style bg=cyan +.Ed +.Pp +Here, the command name is +.Ql set-option , +.Ql Fl g +is a flag and +.Ql status-style +and +.Ql bg=cyan +are arguments. +.Pp +.Nm +distinguishes between command parsing and execution. +In order to execute a command, +.Nm +needs it to be split up into its name and arguments. +This is command parsing. +If a command is run from the shell, the shell parses it; from inside +.Nm +or from a configuration file, +.Nm +does. +Examples of when +.Nm +parses commands are: +.Bl -dash -offset indent +.It +in a configuration file; +.It +typed at the command prompt (see +.Ic command-prompt ) ; +.It +given to +.Ic bind-key ; +.It +passed as arguments to +.Ic if-shell +or +.Ic confirm-before . +.El +.Pp +To execute commands, each client has a +.Ql command queue . +A global command queue not attached to any client is used on startup +for configuration files like +.Pa ~/.tmux.conf . +Parsed commands added to the queue are executed in order. +Some commands, like +.Ic if-shell +and +.Ic confirm-before , +parse their argument to create a new command which is inserted immediately +after themselves. +This means that arguments can be parsed twice or more - once when the parent command (such as +.Ic if-shell ) +is parsed and again when it parses and executes its command. +Commands like +.Ic if-shell , +.Ic run-shell +and +.Ic display-panes +stop execution of subsequent commands on the queue until something happens - +.Ic if-shell +and +.Ic run-shell +until a shell command finishes and +.Ic display-panes +until a key is pressed. +For example, the following commands: +.Bd -literal -offset indent +new-session; new-window +if-shell "true" "split-window" +kill-session +.Ed +.Pp +Will execute +.Ic new-session , +.Ic new-window , +.Ic if-shell , +the shell command +.Xr true 1 , +.Ic split-window +and +.Ic kill-session +in that order. +.Pp +The +.Sx COMMANDS +section lists the +.Nm +commands and their arguments. +.Sh PARSING SYNTAX +This section describes the syntax of commands parsed by +.Nm , +for example in a configuration file or at the command prompt. +Note that when commands are entered into the shell, they are parsed by the shell +- see for example +.Xr ksh 1 +or +.Xr csh 1 . +.Pp +Each command is terminated by a newline or a semicolon (;). +Commands separated by semicolons together form a +.Ql command sequence +- if a command in the sequence encounters an error, no subsequent commands are +executed. +.Pp +It is recommended that a semicolon used as a command separator should be +written as an individual token, for example from +.Xr sh 1 : +.Bd -literal -offset indent +$ tmux neww \\; splitw +.Ed +.Pp +Or: +.Bd -literal -offset indent +$ tmux neww ';' splitw +.Ed +.Pp +Or from the tmux command prompt: +.Bd -literal -offset indent +neww ; splitw +.Ed +.Pp +However, a trailing semicolon is also interpreted as a command separator, +for example in these +.Xr sh 1 +commands: +.Bd -literal -offset indent +$ tmux neww\e\e; splitw +.Ed +.Pp +Or: +.Bd -literal -offset indent +$ tmux 'neww;' splitw +.Ed +.Pp +As in these examples, when running tmux from the shell extra care must be taken +to properly quote semicolons: +.Bl -enum -offset Ds +.It +Semicolons that should be interpreted as a command separator +should be escaped according to the shell conventions. +For +.Xr sh 1 +this typically means quoted (such as +.Ql neww ';' splitw ) +or escaped (such as +.Ql neww \e\e\e\e; splitw ) . +.It +Individual semicolons or trailing semicolons that should be interpreted as +arguments should be escaped twice: once according to the shell conventions and +a second time for +.Nm ; +for example: +.Bd -literal -offset indent +$ tmux neww 'foo\e\e;' bar +$ tmux neww foo\e\e\e\e; bar +.Ed +.It +Semicolons that are not individual tokens or trailing another token should only +be escaped once according to shell conventions; for example: +.Bd -literal -offset indent +$ tmux neww 'foo-;-bar' +$ tmux neww foo-\e\e;-bar +.Ed +.El +.Pp +Comments are marked by the unquoted # character - any remaining text after a +comment is ignored until the end of the line. +.Pp +If the last character of a line is \e, the line is joined with the following +line (the \e and the newline are completely removed). +This is called line continuation and applies both inside and outside quoted +strings and in comments, but not inside braces. +.Pp +Command arguments may be specified as strings surrounded by single (') quotes, +double quotes (") or braces ({}). +.\" " +This is required when the argument contains any special character. +Single and double quoted strings cannot span multiple lines except with line +continuation. +Braces can span multiple lines. +.Pp +Outside of quotes and inside double quotes, these replacements are performed: +.Bl -dash -offset indent +.It +Environment variables preceded by $ are replaced with their value from the +global environment (see the +.Sx GLOBAL AND SESSION ENVIRONMENT +section). +.It +A leading ~ or ~user is expanded to the home directory of the current or +specified user. +.It +\euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to +the given four or eight digit hexadecimal number. +.It +When preceded (escaped) by a \e, the following characters are replaced: \ee by +the escape character; \er by a carriage return; \en by a newline; and \et by a +tab. +.It +\eooo is replaced by a character of the octal value ooo. +Three octal digits are required, for example \e001. +The largest valid character is \e377. +.It +Any other characters preceded by \e are replaced by themselves (that is, the \e +is removed) and are not treated as having any special meaning - so for example +\e; will not mark a command sequence and \e$ will not expand an environment +variable. +.El +.Pp +Braces are parsed as a configuration file (so conditions such as +.Ql %if +are processed) and then converted into a string. +They are designed to avoid the need for additional escaping when passing a +group of +.Nm +commands as an argument (for example to +.Ic if-shell ) . +These two examples produce an identical command - note that no escaping is +needed when using {}: +.Bd -literal -offset indent +if-shell true { + display -p 'brace-dollar-foo: }$foo' +} + +if-shell true "display -p 'brace-dollar-foo: }\e$foo'" +.Ed +.Pp +Braces may be enclosed inside braces, for example: +.Bd -literal -offset indent +bind x if-shell "true" { + if-shell "true" { + display "true!" + } +} +.Ed +.Pp +Environment variables may be set by using the syntax +.Ql name=value , +for example +.Ql HOME=/home/user . +Variables set during parsing are added to the global environment. +A hidden variable may be set with +.Ql %hidden , +for example: +.Bd -literal -offset indent +%hidden MYVAR=42 +.Ed +.Pp +Hidden variables are not passed to the environment of processes created +by tmux. +See the +.Sx GLOBAL AND SESSION ENVIRONMENT +section. +.Pp +Commands may be parsed conditionally by surrounding them with +.Ql %if , +.Ql %elif , +.Ql %else +and +.Ql %endif . +The argument to +.Ql %if +and +.Ql %elif +is expanded as a format (see +.Sx FORMATS ) +and if it evaluates to false (zero or empty), subsequent text is ignored until +the closing +.Ql %elif , +.Ql %else +or +.Ql %endif . +For example: +.Bd -literal -offset indent +%if "#{==:#{host},myhost}" +set -g status-style bg=red +%elif "#{==:#{host},myotherhost}" +set -g status-style bg=green +%else +set -g status-style bg=blue +%endif +.Ed +.Pp +Will change the status line to red if running on +.Ql myhost , +green if running on +.Ql myotherhost , +or blue if running on another host. +Conditionals may be given on one line, for example: +.Bd -literal -offset indent +%if #{==:#{host},myhost} set -g status-style bg=red %endif +.Ed +.Sh COMMANDS +This section describes the commands supported by +.Nm . +Most commands accept the optional +.Fl t +(and sometimes +.Fl s ) +argument with one of +.Ar target-client , +.Ar target-session , +.Ar target-window , +or +.Ar target-pane . +These specify the client, session, window or pane which a command should affect. +.Pp +.Ar target-client +should be the name of the client, +typically the +.Xr pty 4 +file to which the client is connected, for example either of +.Pa /dev/ttyp1 +or +.Pa ttyp1 +for the client attached to +.Pa /dev/ttyp1 . +If no client is specified, +.Nm +attempts to work out the client currently in use; if that fails, an error is +reported. +Clients may be listed with the +.Ic list-clients +command. +.Pp +.Ar target-session +is tried as, in order: +.Bl -enum -offset Ds +.It +A session ID prefixed with a $. +.It +An exact name of a session (as listed by the +.Ic list-sessions +command). +.It +The start of a session name, for example +.Ql mysess +would match a session named +.Ql mysession . +.It +An +.Xr fnmatch 3 +pattern which is matched against the session name. +.El +.Pp +If the session name is prefixed with an +.Ql = , +only an exact match is accepted (so +.Ql =mysess +will only match exactly +.Ql mysess , +not +.Ql mysession ) . +.Pp +If a single session 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. +.Pp +.Ar target-window +(or +.Ar src-window +or +.Ar dst-window ) +specifies a window in the form +.Em session Ns \&: Ns Em window . +.Em session +follows the same rules as for +.Ar target-session , +and +.Em window +is looked for in order as: +.Bl -enum -offset Ds +.It +A special token, listed below. +.It +A window index, for example +.Ql mysession:1 +is window 1 in session +.Ql mysession . +.It +A window ID, such as @1. +.It +An exact window name, such as +.Ql mysession:mywindow . +.It +The start of a window name, such as +.Ql mysession:mywin . +.It +As an +.Xr fnmatch 3 +pattern matched against the window name. +.El +.Pp +Like sessions, a +.Ql = +prefix will do an exact match only. +An empty window name specifies the next unused index if appropriate (for +example the +.Ic new-window +and +.Ic link-window +commands) +otherwise the current window in +.Em session +is chosen. +.Pp +The following special tokens are available to indicate particular windows. +Each has a single-character alternative form. +.Bl -column "XXXXXXXXXX" "X" +.It Sy "Token" Ta Sy "" Ta Sy "Meaning" +.It Li "{start}" Ta "^" Ta "The lowest-numbered window" +.It Li "{end}" Ta "$" Ta "The highest-numbered window" +.It Li "{last}" Ta "!" Ta "The last (previously current) window" +.It Li "{next}" Ta "+" Ta "The next window by number" +.It Li "{previous}" Ta "-" Ta "The previous window by number" +.El +.Pp +.Ar target-pane +(or +.Ar src-pane +or +.Ar dst-pane ) +may be a pane ID or takes a similar form to +.Ar target-window +but with the optional addition of a period followed by a pane index or pane ID, +for example: +.Ql mysession:mywindow.1 . +If the pane index is omitted, the currently active pane in the specified +window is used. +The following special tokens are available for the pane index: +.Bl -column "XXXXXXXXXXXXXX" "X" +.It Sy "Token" Ta Sy "" Ta Sy "Meaning" +.It Li "{last}" Ta "!" Ta "The last (previously active) pane" +.It Li "{next}" Ta "+" Ta "The next pane by number" +.It Li "{previous}" Ta "-" Ta "The previous pane by number" +.It Li "{top}" Ta "" Ta "The top pane" +.It Li "{bottom}" Ta "" Ta "The bottom pane" +.It Li "{left}" Ta "" Ta "The leftmost pane" +.It Li "{right}" Ta "" Ta "The rightmost pane" +.It Li "{top-left}" Ta "" Ta "The top-left pane" +.It Li "{top-right}" Ta "" Ta "The top-right pane" +.It Li "{bottom-left}" Ta "" Ta "The bottom-left pane" +.It Li "{bottom-right}" Ta "" Ta "The bottom-right pane" +.It Li "{up-of}" Ta "" Ta "The pane above the active pane" +.It Li "{down-of}" Ta "" Ta "The pane below the active pane" +.It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane" +.It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane" +.El +.Pp +The tokens +.Ql + +and +.Ql - +may be followed by an offset, for example: +.Bd -literal -offset indent +select-window -t:+2 +.Ed +.Pp +In addition, +.Em target-session , +.Em target-window +or +.Em target-pane +may consist entirely of the token +.Ql {mouse} +(alternative form +.Ql = ) +to specify the session, window or pane where the most recent mouse event occurred +(see the +.Sx MOUSE SUPPORT +section) +or +.Ql {marked} +(alternative form +.Ql ~ ) +to specify the marked pane (see +.Ic select-pane +.Fl m ) . +.Pp +Sessions, window and panes are each numbered with a unique ID; session IDs are +prefixed with a +.Ql $ , +windows with a +.Ql @ , +and panes with a +.Ql % . +These are unique and are unchanged for the life of the session, window or pane +in the +.Nm +server. +The pane ID is passed to the child process of the pane in the +.Ev TMUX_PANE +environment variable. +IDs may be displayed using the +.Ql session_id , +.Ql window_id , +or +.Ql pane_id +formats (see the +.Sx FORMATS +section) and the +.Ic display-message , +.Ic list-sessions , +.Ic list-windows +or +.Ic list-panes +commands. +.Pp +.Ar shell-command +arguments are +.Xr sh 1 +commands. +This may be a single argument passed to the shell, for example: +.Bd -literal -offset indent +new-window 'vi ~/.tmux.conf' +.Ed +.Pp +Will run: +.Bd -literal -offset indent +/bin/sh -c 'vi ~/.tmux.conf' +.Ed +.Pp +Additionally, the +.Ic new-window , +.Ic new-session , +.Ic split-window , +.Ic respawn-window +and +.Ic respawn-pane +commands allow +.Ar shell-command +to be given as multiple arguments and executed directly (without +.Ql sh -c ) . +This can avoid issues with shell quoting. +For example: +.Bd -literal -offset indent +$ tmux new-window vi ~/.tmux.conf +.Ed +.Pp +Will run +.Xr vi 1 +directly without invoking the shell. +.Pp +.Ar command +.Op Ar arguments +refers to a +.Nm +command, either passed with the command and arguments separately, for example: +.Bd -literal -offset indent +bind-key F1 set-option status off +.Ed +.Pp +Or passed as a single string argument in +.Pa .tmux.conf , +for example: +.Bd -literal -offset indent +bind-key F1 { set-option status off } +.Ed +.Pp +Example +.Nm +commands include: +.Bd -literal -offset indent +refresh-client -t/dev/ttyp2 + +rename-session -tfirst newname + +set-option -wt:0 monitor-activity on + +new-window ; split-window -d + +bind-key R source-file ~/.tmux.conf \e; \e + display-message "source-file done" +.Ed +.Pp +Or from +.Xr sh 1 : +.Bd -literal -offset indent +$ tmux kill-window -t :1 + +$ tmux new-window \e; split-window -d + +$ tmux new-session -d 'vi ~/.tmux.conf' \e; split-window -d \e; attach +.Ed +.Sh CLIENTS AND SESSIONS +The +.Nm +server manages clients, sessions, windows and panes. +Clients are attached to sessions to interact with them, either +when they are created with the +.Ic new-session +command, or later with the +.Ic attach-session +command. +Each session has one or more windows +.Em 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. +.Pp +The following commands are available to manage clients and sessions: +.Bl -tag -width Ds +.Tg attach +.It Xo Ic attach-session +.Op Fl dErx +.Op Fl c Ar working-directory +.Op Fl f Ar flags +.Op Fl t Ar target-session +.Xc +.D1 Pq alias: Ic attach +If run from outside +.Nm , +create a new client in the current terminal and attach it to +.Ar target-session . +If used from inside, switch the current client. +If +.Fl d +is specified, any other clients attached to the session are detached. +If +.Fl x +is given, send +.Dv SIGHUP +to the parent process of the client as well as +detaching the client, typically causing it to exit. +.Fl f +sets a comma-separated list of client flags. +The flags are: +.Bl -tag -width Ds +.It active-pane +the client has an independent active pane +.It ignore-size +the client does not affect the size of other clients +.It no-output +the client does not receive pane output in control mode +.It pause-after=seconds +output is paused once the pane is +.Ar seconds +behind in control mode +.It read-only +the client is read-only +.It wait-exit +wait for an empty line input before exiting in control mode +.El +.Pp +A leading +.Ql \&! +turns a flag off if the client is already attached. +.Fl r +is an alias for +.Fl f +.Ar read-only,ignore-size . +When a client is read-only, only keys bound to the +.Ic detach-client +or +.Ic switch-client +commands have any effect. +A client with the +.Ar active-pane +flag allows the active pane to be selected independently of the window's active +pane used by clients without the flag. +This only affects the cursor position and commands issued from the client; +other features such as hooks and styles continue to use the window's active +pane. +.Pp +If no server is started, +.Ic attach-session +will attempt to start it; this will fail unless sessions are created in the +configuration file. +.Pp +The +.Ar target-session +rules for +.Ic attach-session +are slightly adjusted: if +.Nm +needs to select the most recently used session, it will prefer the most +recently used +.Em unattached +session. +.Pp +.Fl c +will set the session working directory (used for new windows) to +.Ar working-directory . +.Pp +If +.Fl E +is used, the +.Ic update-environment +option will not be applied. +.Tg detach +.It Xo Ic detach-client +.Op Fl aP +.Op Fl E Ar shell-command +.Op Fl s Ar target-session +.Op Fl t Ar target-client +.Xc +.D1 Pq alias: Ic detach +Detach the current client if bound to a key, the client specified with +.Fl t , +or all clients currently attached to the session specified by +.Fl s . +The +.Fl a +option kills all but the client given with +.Fl t . +If +.Fl P +is given, send +.Dv SIGHUP +to the parent process of the client, typically causing it +to exit. +With +.Fl E , +run +.Ar shell-command +to replace the client. +.Tg has +.It Ic has-session Op Fl t Ar target-session +.D1 Pq alias: Ic has +Report an error and exit with 1 if the specified session does not exist. +If it does exist, exit with 0. +.It Ic kill-server +Kill the +.Nm +server and clients and destroy all sessions. +.It Xo Ic kill-session +.Op Fl aC +.Op Fl t Ar target-session +.Xc +Destroy the given session, closing any windows linked to it and no other +sessions, and detaching all clients attached to it. +If +.Fl a +is given, all sessions but the specified one is killed. +The +.Fl C +flag clears alerts (bell, activity, or silence) in all windows linked to the +session. +.Tg lsc +.It Xo Ic list-clients +.Op Fl F Ar format +.Op Fl t Ar target-session +.Xc +.D1 Pq alias: Ic lsc +List all clients attached to the server. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +If +.Ar target-session +is specified, list only clients connected to that session. +.Tg lscm +.It Xo Ic list-commands +.Op Fl F Ar format +.Op Ar command +.Xc +.D1 Pq alias: Ic lscm +List the syntax of +.Ar command +or - if omitted - of all commands supported by +.Nm . +.Tg ls +.It Xo Ic list-sessions +.Op Fl F Ar format +.Op Fl f Ar filter +.Xc +.D1 Pq alias: Ic ls +List all sessions managed by the server. +.Fl F +specifies the format of each line and +.Fl f +a filter. +Only sessions for which the filter is true are shown. +See the +.Sx FORMATS +section. +.Tg lockc +.It Ic lock-client Op Fl t Ar target-client +.D1 Pq alias: Ic lockc +Lock +.Ar target-client , +see the +.Ic lock-server +command. +.Tg locks +.It Ic lock-session Op Fl t Ar target-session +.D1 Pq alias: Ic locks +Lock all clients attached to +.Ar target-session . +.Tg new +.It Xo Ic new-session +.Op Fl AdDEPX +.Op Fl c Ar start-directory +.Op Fl e Ar environment +.Op Fl f Ar flags +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl s Ar session-name +.Op Fl t Ar group-name +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic new +Create a new session with name +.Ar session-name . +.Pp +The new session is attached to the current terminal unless +.Fl d +is given. +.Ar window-name +and +.Ar shell-command +are the name of and shell command to execute in the initial window. +With +.Fl d , +the initial size comes from the global +.Ic default-size +option; +.Fl x +and +.Fl y +can be used to specify a different size. +.Ql - +uses the size of the current client if any. +If +.Fl x +or +.Fl y +is given, the +.Ic default-size +option is set for the session. +.Fl f +sets a comma-separated list of client flags (see +.Ic attach-session ) . +.Pp +If run from a terminal, any +.Xr termios 4 +special characters are saved and used for new windows in the new session. +.Pp +The +.Fl A +flag makes +.Ic new-session +behave like +.Ic attach-session +if +.Ar session-name +already exists; in this case, +.Fl D +behaves like +.Fl d +to +.Ic attach-session , +and +.Fl X +behaves like +.Fl x +to +.Ic attach-session . +.Pp +If +.Fl t +is given, it specifies a +.Ic session group . +Sessions in the same group share the same set of windows - new windows are +linked to all sessions in the group and any windows closed removed from all +sessions. +The current and previous window and any session options remain independent and +any session in a group may be killed without affecting the others. +The +.Ar group-name +argument may be: +.Bl -enum -width Ds +.It +the name of an existing group, in which case the new session is added to that +group; +.It +the name of an existing session - the new session is added to the same group +as that session, creating a new group if necessary; +.It +the name for a new group containing only the new session. +.El +.Pp +.Fl n +and +.Ar shell-command +are invalid if +.Fl t +is used. +.Pp +The +.Fl P +option prints information about the new session after it has been created. +By default, it uses the format +.Ql #{session_name}:\& +but a different format may be specified with +.Fl F . +.Pp +If +.Fl E +is used, the +.Ic update-environment +option will not be applied. +.Fl e +takes the form +.Ql VARIABLE=value +and sets an environment variable for the newly created session; it may be +specified multiple times. +.Tg refresh +.It Xo Ic refresh-client +.Op Fl cDLRSU +.Op Fl A Ar pane:state +.Op Fl B Ar name:what:format +.Op Fl C Ar size +.Op Fl f Ar flags +.Op Fl l Op Ar target-pane +.Op Fl t Ar target-client +.Op Ar adjustment +.Xc +.D1 Pq alias: Ic refresh +Refresh the current client if bound to a key, or a single client if one is given +with +.Fl t . +If +.Fl S +is specified, only update the client's status line. +.Pp +The +.Fl U , +.Fl D , +.Fl L +.Fl R , +and +.Fl c +flags allow the visible portion of a window which is larger than the client +to be changed. +.Fl U +moves the visible part up by +.Ar adjustment +rows and +.Fl D +down, +.Fl L +left by +.Ar adjustment +columns and +.Fl R +right. +.Fl c +returns to tracking the cursor automatically. +If +.Ar adjustment +is omitted, 1 is used. +Note that the visible position is a property of the client not of the +window, changing the current window in the attached session will reset +it. +.Pp +.Fl C +sets the width and height of a control mode client or of a window for a +control mode client, +.Ar size +must be one of +.Ql widthxheight +or +.Ql window ID:widthxheight , +for example +.Ql 80x24 +or +.Ql @0:80x24 . +.Fl A +allows a control mode client to trigger actions on a pane. +The argument is a pane ID (with leading +.Ql % ) , +a colon, then one of +.Ql on , +.Ql off , +.Ql continue +or +.Ql pause . +If +.Ql off , +.Nm +will not send output from the pane to the client and if all clients have turned +the pane off, will stop reading from the pane. +If +.Ql continue , +.Nm +will return to sending output to the pane if it was paused (manually or with the +.Ar pause-after +flag). +If +.Ql pause , +.Nm +will pause the pane. +.Fl A +may be given multiple times for different panes. +.Pp +.Fl B +sets a subscription to a format for a control mode client. +The argument is split into three items by colons: +.Ar name +is a name for the subscription; +.Ar what +is a type of item to subscribe to; +.Ar format +is the format. +After a subscription is added, changes to the format are reported with the +.Ic %subscription-changed +notification, at most once a second. +If only the name is given, the subscription is removed. +.Ar what +may be empty to check the format only for the attached session, or one of: +a pane ID such as +.Ql %0 ; +.Ql %* +for all panes in the attached session; +a window ID such as +.Ql @0 ; +or +.Ql @* +for all windows in the attached session. +.Pp +.Fl f +sets a comma-separated list of client flags, see +.Ic attach-session . +.Pp +.Fl l +requests the clipboard from the client using the +.Xr xterm 1 +escape sequence. +If +Ar target-pane +is given, the clipboard is sent (in encoded form), otherwise it is stored in a +new paste buffer. +.Pp +.Fl L , +.Fl R , +.Fl U +and +.Fl D +move the visible portion of the window left, right, up or down +by +.Ar adjustment , +if the window is larger than the client. +.Fl c +resets so that the position follows the cursor. +See the +.Ic window-size +option. +.Tg rename +.It Xo Ic rename-session +.Op Fl t Ar target-session +.Ar new-name +.Xc +.D1 Pq alias: Ic rename +Rename the session to +.Ar new-name . +.It Xo Ic server-access +.Op Fl adlrw +.Op Ar user +.Xc +Change the access or read/write permission of +.Ar user . +The user running the +.Nm +server (its owner) and the root user cannot be changed and are always +permitted access. +.Pp +.Fl a +and +.Fl d +are used to give or revoke access for the specified user. +If the user is already attached, the +.Fl d +flag causes their clients to be detached. +.Pp +.Fl r +and +.Fl w +change the permissions for +.Ar user : +.Fl r +makes their clients read-only and +.Fl w +writable. +.Fl l +lists current access permissions. +.Pp +By default, the access list is empty and +.Nm +creates sockets with file system permissions preventing access by any user +other than the owner (and root). +These permissions must be changed manually. +Great care should be taken not to allow access to untrusted users even +read-only. +.Tg showmsgs +.It Xo Ic show-messages +.Op Fl JT +.Op Fl t Ar target-client +.Xc +.D1 Pq alias: Ic showmsgs +Show server messages or information. +Messages are stored, up to a maximum of the limit set by the +.Ar message-limit +server option. +.Fl J +and +.Fl T +show debugging information about jobs and terminals. +.Tg source +.It Xo Ic source-file +.Op Fl Fnqv +.Ar path +.Ar ... +.Xc +.D1 Pq alias: Ic source +Execute commands from one or more files specified by +.Ar path +(which may be +.Xr glob 7 +patterns). +If +.Fl F +is present, then +.Ar path +is expanded as a format. +If +.Fl q +is given, no error will be returned if +.Ar path +does not exist. +With +.Fl n , +the file is parsed but no commands are executed. +.Fl v +shows the parsed commands and line numbers if possible. +.Tg start +.It Ic start-server +.D1 Pq alias: Ic start +Start the +.Nm +server, if not already running, without creating any sessions. +.Pp +Note that as by default the +.Nm +server will exit with no sessions, this is only useful if a session is created in +.Pa ~/.tmux.conf , +.Ic exit-empty +is turned off, or another command is run as part of the same command sequence. +For example: +.Bd -literal -offset indent +$ tmux start \\; show -g +.Ed +.Tg suspendc +.It Xo Ic suspend-client +.Op Fl t Ar target-client +.Xc +.D1 Pq alias: Ic suspendc +Suspend a client by sending +.Dv SIGTSTP +(tty stop). +.Tg switchc +.It Xo Ic switch-client +.Op Fl ElnprZ +.Op Fl c Ar target-client +.Op Fl t Ar target-session +.Op Fl T Ar key-table +.Xc +.D1 Pq alias: Ic switchc +Switch the current session for client +.Ar target-client +to +.Ar target-session . +As a special case, +.Fl t +may refer to a pane (a target that contains +.Ql \&: , +.Ql \&. +or +.Ql % ) , +to change session, window and pane. +In that case, +.Fl Z +keeps the window zoomed if it was zoomed. +If +.Fl l , +.Fl n +or +.Fl p +is used, the client is moved to the last, next or previous session +respectively. +.Fl r +toggles the client +.Ic read-only +and +.Ic ignore-size +flags (see the +.Ic attach-session +command). +.Pp +If +.Fl E +is used, +.Ic update-environment +option will not be applied. +.Pp +.Fl T +sets the client's key table; the next key from the client will be interpreted +from +.Ar key-table . +This may be used to configure multiple prefix keys, or to bind commands to +sequences of keys. +For example, to make typing +.Ql abc +run the +.Ic list-keys +command: +.Bd -literal -offset indent +bind-key -Ttable2 c list-keys +bind-key -Ttable1 b switch-client -Ttable2 +bind-key -Troot a switch-client -Ttable1 +.Ed +.El +.Sh WINDOWS AND PANES +Each window displayed by +.Nm +may be split into one or more +.Em 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 +.Ic split-window +command. +Windows may be split horizontally (with the +.Fl h +flag) or vertically. +Panes may be resized with the +.Ic resize-pane +command (bound to +.Ql C-Up , +.Ql C-Down +.Ql C-Left +and +.Ql C-Right +by default), the current pane may be changed with the +.Ic select-pane +command and the +.Ic rotate-window +and +.Ic 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. +.Pp +By default, a +.Nm +pane permits direct access to the terminal contained in the pane. +A pane may also be put into one of several modes: +.Bl -dash -offset indent +.It +Copy mode, which permits a section of a window or its +history to be copied to a +.Em paste buffer +for later insertion into another window. +This mode is entered with the +.Ic copy-mode +command, bound to +.Ql \&[ +by default. +Copied text can be pasted with the +.Ic paste-buffer +command, bound to +.Ql \&] . +.It +View mode, which is like copy mode but is entered when a command that produces +output, such as +.Ic list-keys , +is executed from a key binding. +.It +Choose mode, which allows an item to be chosen from a list. +This may be a client, a session or window or pane, or a buffer. +This mode is entered with the +.Ic choose-buffer , +.Ic choose-client +and +.Ic choose-tree +commands. +.El +.Pp +In copy mode an indicator is displayed in the top-right corner of the pane with +the current position and the number of lines in the history. +.Pp +Commands are sent to copy mode using the +.Fl X +flag to the +.Ic send-keys +command. +When a key is pressed, copy mode automatically uses one of two key tables, +depending on the +.Ic mode-keys +option: +.Ic copy-mode +for emacs, or +.Ic copy-mode-vi +for vi. +Key tables may be viewed with the +.Ic list-keys +command. +.Pp +The following commands are supported in copy mode: +.Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent +.It Sy "Command" Ta Sy "vi" Ta Sy "emacs" +.It Li "append-selection" Ta "" Ta "" +.It Li "append-selection-and-cancel" Ta "A" Ta "" +.It Li "back-to-indentation" Ta "^" Ta "M-m" +.It Li "begin-selection" Ta "Space" Ta "C-Space" +.It Li "bottom-line" Ta "L" Ta "" +.It Li "cancel" Ta "q" Ta "Escape" +.It Li "clear-selection" Ta "Escape" Ta "C-g" +.It Li "copy-end-of-line [<prefix>]" Ta "" Ta "" +.It Li "copy-end-of-line-and-cancel [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe-end-of-line [<command>] [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe-end-of-line-and-cancel [<command>] [<prefix>]" Ta "D" Ta "C-k" +.It Li "copy-line [<prefix>]" Ta "" Ta "" +.It Li "copy-line-and-cancel [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe-line [<command>] [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe-line-and-cancel [<command>] [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe [<command>] [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe-no-clear [<command>] [<prefix>]" Ta "" Ta "" +.It Li "copy-pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta "" +.It Li "copy-selection [<prefix>]" Ta "" Ta "" +.It Li "copy-selection-no-clear [<prefix>]" Ta "" Ta "" +.It Li "copy-selection-and-cancel [<prefix>]" Ta "Enter" Ta "M-w" +.It Li "cursor-down" Ta "j" Ta "Down" +.It Li "cursor-down-and-cancel" Ta "" Ta "" +.It Li "cursor-left" Ta "h" Ta "Left" +.It Li "cursor-right" Ta "l" Ta "Right" +.It Li "cursor-up" Ta "k" Ta "Up" +.It Li "end-of-line" Ta "$" Ta "C-e" +.It Li "goto-line <line>" Ta ":" Ta "g" +.It Li "halfpage-down" Ta "C-d" Ta "M-Down" +.It Li "halfpage-down-and-cancel" Ta "" Ta "" +.It Li "halfpage-up" Ta "C-u" Ta "M-Up" +.It Li "history-bottom" Ta "G" Ta "M->" +.It Li "history-top" Ta "g" Ta "M-<" +.It Li "jump-again" Ta ";" Ta ";" +.It Li "jump-backward <to>" Ta "F" Ta "F" +.It Li "jump-forward <to>" Ta "f" Ta "f" +.It Li "jump-reverse" Ta "," Ta "," +.It Li "jump-to-backward <to>" Ta "T" Ta "" +.It Li "jump-to-forward <to>" Ta "t" Ta "" +.It Li "jump-to-mark" Ta "M-x" Ta "M-x" +.It Li "middle-line" Ta "M" Ta "M-r" +.It Li "next-matching-bracket" Ta "%" Ta "M-C-f" +.It Li "next-paragraph" Ta "}" Ta "M-}" +.It Li "next-space" Ta "W" Ta "" +.It Li "next-space-end" Ta "E" Ta "" +.It Li "next-word" Ta "w" Ta "" +.It Li "next-word-end" Ta "e" Ta "M-f" +.It Li "other-end" Ta "o" Ta "" +.It Li "page-down" Ta "C-f" Ta "PageDown" +.It Li "page-down-and-cancel" Ta "" Ta "" +.It Li "page-up" Ta "C-b" Ta "PageUp" +.It Li "pipe [<command>] [<prefix>]" Ta "" Ta "" +.It Li "pipe-no-clear [<command>] [<prefix>]" Ta "" Ta "" +.It Li "pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta "" +.It Li "previous-matching-bracket" Ta "" Ta "M-C-b" +.It Li "previous-paragraph" Ta "{" Ta "M-{" +.It Li "previous-space" Ta "B" Ta "" +.It Li "previous-word" Ta "b" Ta "M-b" +.It Li "rectangle-on" Ta "" Ta "" +.It Li "rectangle-off" Ta "" Ta "" +.It Li "rectangle-toggle" Ta "v" Ta "R" +.It Li "refresh-from-pane" Ta "r" Ta "r" +.It Li "scroll-down" Ta "C-e" Ta "C-Down" +.It Li "scroll-down-and-cancel" Ta "" Ta "" +.It Li "scroll-up" Ta "C-y" Ta "C-Up" +.It Li "search-again" Ta "n" Ta "n" +.It Li "search-backward <for>" Ta "?" Ta "" +.It Li "search-backward-incremental <for>" Ta "" Ta "C-r" +.It Li "search-backward-text <for>" Ta "" Ta "" +.It Li "search-forward <for>" Ta "/" Ta "" +.It Li "search-forward-incremental <for>" Ta "" Ta "C-s" +.It Li "search-forward-text <for>" Ta "" Ta "" +.It Li "search-reverse" Ta "N" Ta "N" +.It Li "select-line" Ta "V" Ta "" +.It Li "select-word" Ta "" Ta "" +.It Li "set-mark" Ta "X" Ta "X" +.It Li "start-of-line" Ta "0" Ta "C-a" +.It Li "stop-selection" Ta "" Ta "" +.It Li "toggle-position" Ta "P" Ta "P" +.It Li "top-line" Ta "H" Ta "M-R" +.El +.Pp +The search commands come in several varieties: +.Ql search-forward +and +.Ql search-backward +search for a regular expression; +the +.Ql -text +variants search for a plain text string rather than a regular expression; +.Ql -incremental +perform an incremental search and expect to be used with the +.Fl i +flag to the +.Ic command-prompt +command. +.Ql search-again +repeats the last search and +.Ql search-reverse +does the same but reverses the direction (forward becomes backward and backward +becomes forward). +.Pp +Copy commands may take an optional buffer prefix argument which is used +to generate the buffer name (the default is +.Ql buffer +so buffers are named +.Ql buffer0 , +.Ql buffer1 +and so on). +Pipe commands take a command argument which is the command to which the +selected text is piped. +.Ql copy-pipe +variants also copy the selection. +The +.Ql -and-cancel +variants of some commands exit copy mode after they have completed (for copy +commands) or when the cursor reaches the bottom (for scrolling commands). +.Ql -no-clear +variants do not clear the selection. +.Pp +The next and previous word keys skip over whitespace and treat consecutive +runs of either word separators or other letters as words. +Word separators can be customized with the +.Em 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. +Setting +.Em word-separators +to the empty string makes next/previous word equivalent to next/previous space. +.Pp +The jump commands enable quick movement within a line. +For instance, typing +.Ql f +followed by +.Ql / +will move the cursor to the next +.Ql / +character on the current line. +A +.Ql \&; +will then jump to the next occurrence. +.Pp +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. +.Pp +The synopsis for the +.Ic copy-mode +command is: +.Bl -tag -width Ds +.It Xo Ic copy-mode +.Op Fl eHMqu +.Op Fl s Ar src-pane +.Op Fl t Ar target-pane +.Xc +Enter copy mode. +The +.Fl u +option scrolls one page up. +.Fl M +begins a mouse drag (only valid if bound to a mouse key binding, see +.Sx MOUSE SUPPORT ) . +.Fl H +hides the position indicator in the top right. +.Fl q +cancels copy mode and any other modes. +.Fl s +copies from +.Ar src-pane +instead of +.Ar target-pane . +.Pp +.Fl e +specifies that scrolling to the bottom of the history (to the visible screen) +should exit copy mode. +While in copy mode, pressing a key other than those used for scrolling will +disable this behaviour. +This is intended to allow fast scrolling through a pane's history, for +example with: +.Bd -literal -offset indent +bind PageUp copy-mode -eu +.Ed +.El +.Pp +A number of preset arrangements of panes are available, these are called layouts. +These may be selected with the +.Ic select-layout +command or cycled with +.Ic next-layout +(bound to +.Ql Space +by default); once a layout is chosen, panes within it may be moved and resized +as normal. +.Pp +The following layouts are supported: +.Bl -tag -width Ds +.It Ic even-horizontal +Panes are spread out evenly from left to right across the window. +.It Ic even-vertical +Panes are spread evenly from top to bottom. +.It Ic 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 +.Em main-pane-height +window option to specify the height of the top pane. +.It Ic main-vertical +Similar to +.Ic main-horizontal +but the large pane is placed on the left and the others spread from top to +bottom along the right. +See the +.Em main-pane-width +window option. +.It Ic tiled +Panes are spread out as evenly as possible over the window in both rows and +columns. +.El +.Pp +In addition, +.Ic select-layout +may be used to apply a previously used layout - the +.Ic list-windows +command displays the layout of each window in a form suitable for use with +.Ic select-layout . +For example: +.Bd -literal -offset indent +$ 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} +.Ed +.Pp +.Nm +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. +.Pp +Commands related to windows and panes are as follows: +.Bl -tag -width Ds +.Tg breakp +.It Xo Ic break-pane +.Op Fl abdP +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl s Ar src-pane +.Op Fl t Ar dst-window +.Xc +.D1 Pq alias: Ic breakp +Break +.Ar src-pane +off from its containing window to make it the only pane in +.Ar dst-window . +With +.Fl a +or +.Fl b , +the window is moved to the next index after or before (existing windows are +moved if necessary). +If +.Fl d +is given, the new window does not become the current window. +The +.Fl P +option prints information about the new window after it has been created. +By default, it uses the format +.Ql #{session_name}:#{window_index}.#{pane_index} +but a different format may be specified with +.Fl F . +.Tg capturep +.It Xo Ic capture-pane +.Op Fl aepPqCJN +.Op Fl b Ar buffer-name +.Op Fl E Ar end-line +.Op Fl S Ar start-line +.Op Fl t Ar target-pane +.Xc +.D1 Pq alias: Ic capturep +Capture the contents of a pane. +If +.Fl p +is given, the output goes to stdout, otherwise to the buffer specified with +.Fl b +or a new buffer if omitted. +If +.Fl 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 +.Fl q +is given. +If +.Fl e +is given, the output includes escape sequences for text and background +attributes. +.Fl C +also escapes non-printable characters as octal \exxx. +.Fl N +preserves trailing spaces at each line's end and +.Fl J +preserves trailing spaces and joins any wrapped lines. +.Fl P +captures only any output that the pane has received that is the beginning of an +as-yet incomplete escape sequence. +.Pp +.Fl S +and +.Fl E +specify the starting and ending line numbers, zero is the first line of the +visible pane and negative numbers are lines in the history. +.Ql - +to +.Fl S +is the start of the history and to +.Fl E +the end of the visible pane. +The default is to capture only the visible contents of the pane. +.It Xo +.Ic choose-client +.Op Fl NrZ +.Op Fl F Ar format +.Op Fl f Ar filter +.Op Fl K Ar key-format +.Op Fl O Ar sort-order +.Op Fl t Ar target-pane +.Op Ar template +.Xc +Put a pane into client mode, allowing a client to be selected interactively from +a list. +Each client is shown on one line. +A shortcut key is shown on the left in brackets allowing for immediate choice, +or the list may be navigated and an item chosen or otherwise manipulated using +the keys below. +.Fl Z +zooms the pane. +The following keys may be used in client mode: +.Bl -column "Key" "Function" -offset indent +.It Sy "Key" Ta Sy "Function" +.It Li "Enter" Ta "Choose selected client" +.It Li "Up" Ta "Select previous client" +.It Li "Down" Ta "Select next client" +.It Li "C-s" Ta "Search by name" +.It Li "n" Ta "Repeat last search" +.It Li "t" Ta "Toggle if client is tagged" +.It Li "T" Ta "Tag no clients" +.It Li "C-t" Ta "Tag all clients" +.It Li "d" Ta "Detach selected client" +.It Li "D" Ta "Detach tagged clients" +.It Li "x" Ta "Detach and HUP selected client" +.It Li "X" Ta "Detach and HUP tagged clients" +.It Li "z" Ta "Suspend selected client" +.It Li "Z" Ta "Suspend tagged clients" +.It Li "f" Ta "Enter a format to filter items" +.It Li "O" Ta "Change sort field" +.It Li "r" Ta "Reverse sort order" +.It Li "v" Ta "Toggle preview" +.It Li "q" Ta "Exit mode" +.El +.Pp +After a client is chosen, +.Ql %% +is replaced by the client name in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "detach-client -t '%%'" is used. +.Pp +.Fl O +specifies the initial sort field: one of +.Ql name , +.Ql size , +.Ql creation , +or +.Ql activity . +.Fl r +reverses the sort order. +.Fl f +specifies an initial filter: the filter is a format - if it evaluates to zero, +the item in the list is not shown, otherwise it is shown. +If a filter would lead to an empty list, it is ignored. +.Fl F +specifies the format for each item in the list and +.Fl K +a format for each shortcut key; both are evaluated once for each line. +.Fl N +starts without the preview. +This command works only if at least one client is attached. +.It Xo +.Ic choose-tree +.Op Fl GNrswZ +.Op Fl F Ar format +.Op Fl f Ar filter +.Op Fl K Ar key-format +.Op Fl O Ar sort-order +.Op Fl t Ar target-pane +.Op Ar template +.Xc +Put a pane into tree mode, where a session, window or pane may be chosen +interactively from a tree. +Each session, window or pane is shown on one line. +A shortcut key is shown on the left in brackets allowing for immediate choice, +or the tree may be navigated and an item chosen or otherwise manipulated using +the keys below. +.Fl s +starts with sessions collapsed and +.Fl w +with windows collapsed. +.Fl Z +zooms the pane. +The following keys may be used in tree mode: +.Bl -column "Key" "Function" -offset indent +.It Sy "Key" Ta Sy "Function" +.It Li "Enter" Ta "Choose selected item" +.It Li "Up" Ta "Select previous item" +.It Li "Down" Ta "Select next item" +.It Li "+" Ta "Expand selected item" +.It Li "-" Ta "Collapse selected item" +.It Li "M-+" Ta "Expand all items" +.It Li "M--" Ta "Collapse all items" +.It Li "x" Ta "Kill selected item" +.It Li "X" Ta "Kill tagged items" +.It Li "<" Ta "Scroll list of previews left" +.It Li ">" Ta "Scroll list of previews right" +.It Li "C-s" Ta "Search by name" +.It Li "m" Ta "Set the marked pane" +.It Li "M" Ta "Clear the marked pane" +.It Li "n" Ta "Repeat last search" +.It Li "t" Ta "Toggle if item is tagged" +.It Li "T" Ta "Tag no items" +.It Li "C-t" Ta "Tag all items" +.It Li "\&:" Ta "Run a command for each tagged item" +.It Li "f" Ta "Enter a format to filter items" +.It Li "H" Ta "Jump to the starting pane" +.It Li "O" Ta "Change sort field" +.It Li "r" Ta "Reverse sort order" +.It Li "v" Ta "Toggle preview" +.It Li "q" Ta "Exit mode" +.El +.Pp +After a session, window or pane is chosen, the first instance of +.Ql %% +and all instances of +.Ql %1 +are replaced by the target in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "switch-client -t '%%'" is used. +.Pp +.Fl O +specifies the initial sort field: one of +.Ql index , +.Ql name , +or +.Ql time . +.Fl r +reverses the sort order. +.Fl f +specifies an initial filter: the filter is a format - if it evaluates to zero, +the item in the list is not shown, otherwise it is shown. +If a filter would lead to an empty list, it is ignored. +.Fl F +specifies the format for each item in the tree and +.Fl K +a format for each shortcut key; both are evaluated once for each line. +.Fl N +starts without the preview. +.Fl G +includes all sessions in any session groups in the tree rather than only the +first. +This command works only if at least one client is attached. +.It Xo +.Ic customize-mode +.Op Fl NZ +.Op Fl F Ar format +.Op Fl f Ar filter +.Op Fl t Ar target-pane +.Op Ar template +.Xc +Put a pane into customize mode, where options and key bindings may be browsed +and modified from a list. +Option values in the list are shown for the active pane in the current window. +.Fl Z +zooms the pane. +The following keys may be used in customize mode: +.Bl -column "Key" "Function" -offset indent +.It Sy "Key" Ta Sy "Function" +.It Li "Enter" Ta "Set pane, window, session or global option value" +.It Li "Up" Ta "Select previous item" +.It Li "Down" Ta "Select next item" +.It Li "+" Ta "Expand selected item" +.It Li "-" Ta "Collapse selected item" +.It Li "M-+" Ta "Expand all items" +.It Li "M--" Ta "Collapse all items" +.It Li "s" Ta "Set option value or key attribute" +.It Li "S" Ta "Set global option value" +.It Li "w" Ta "Set window option value, if option is for pane and window" +.It Li "d" Ta "Set an option or key to the default" +.It Li "D" Ta "Set tagged options and tagged keys to the default" +.It Li "u" Ta "Unset an option (set to default value if global) or unbind a key" +.It Li "U" Ta "Unset tagged options and unbind tagged keys" +.It Li "C-s" Ta "Search by name" +.It Li "n" Ta "Repeat last search" +.It Li "t" Ta "Toggle if item is tagged" +.It Li "T" Ta "Tag no items" +.It Li "C-t" Ta "Tag all items" +.It Li "f" Ta "Enter a format to filter items" +.It Li "v" Ta "Toggle option information" +.It Li "q" Ta "Exit mode" +.El +.Pp +.Fl f +specifies an initial filter: the filter is a format - if it evaluates to zero, +the item in the list is not shown, otherwise it is shown. +If a filter would lead to an empty list, it is ignored. +.Fl F +specifies the format for each item in the tree. +.Fl N +starts without the option information. +This command works only if at least one client is attached. +.It Xo +.Tg displayp +.Ic display-panes +.Op Fl bN +.Op Fl d Ar duration +.Op Fl t Ar target-client +.Op Ar template +.Xc +.D1 Pq alias: Ic displayp +Display a visible indicator of each pane shown by +.Ar target-client . +See the +.Ic display-panes-colour +and +.Ic display-panes-active-colour +session options. +The indicator is closed when a key is pressed (unless +.Fl N +is given) or +.Ar duration +milliseconds have passed. +If +.Fl d +is not given, +.Ic display-panes-time +is used. +A duration of zero means the indicator stays until a key is pressed. +While the indicator is on screen, a pane may be chosen with the +.Ql 0 +to +.Ql 9 +keys, which will cause +.Ar template +to be executed as a command with +.Ql %% +substituted by the pane ID. +The default +.Ar template +is "select-pane -t '%%'". +With +.Fl b , +other commands are not blocked from running until the indicator is closed. +.Tg findw +.It Xo Ic find-window +.Op Fl iCNrTZ +.Op Fl t Ar target-pane +.Ar match-string +.Xc +.D1 Pq alias: Ic findw +Search for a +.Xr fnmatch 3 +pattern or, with +.Fl r , +regular expression +.Ar match-string +in window names, titles, and visible content (but not history). +The flags control matching behavior: +.Fl C +matches only visible window contents, +.Fl N +matches only the window name and +.Fl T +matches only the window title. +.Fl i +makes the search ignore case. +The default is +.Fl CNT . +.Fl Z +zooms the pane. +.Pp +This command works only if at least one client is attached. +.Tg joinp +.It Xo Ic join-pane +.Op Fl bdfhv +.Op Fl l Ar size +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 Pq alias: Ic joinp +Like +.Ic split-window , +but instead of splitting +.Ar dst-pane +and creating a new pane, split it and move +.Ar src-pane +into the space. +This can be used to reverse +.Ic break-pane . +The +.Fl b +option causes +.Ar src-pane +to be joined to left of or above +.Ar dst-pane . +.Pp +If +.Fl s +is omitted and a marked pane is present (see +.Ic select-pane +.Fl m ) , +the marked pane is used rather than the current pane. +.Tg killp +.It Xo Ic kill-pane +.Op Fl a +.Op Fl t Ar target-pane +.Xc +.D1 Pq alias: Ic killp +Destroy the given pane. +If no panes remain in the containing window, it is also destroyed. +The +.Fl a +option kills all but the pane given with +.Fl t . +.Tg killw +.It Xo Ic kill-window +.Op Fl a +.Op Fl t Ar target-window +.Xc +.D1 Pq alias: Ic killw +Kill the current window or the window at +.Ar target-window , +removing it from any sessions to which it is linked. +The +.Fl a +option kills all but the window given with +.Fl t . +.Tg lastp +.It Xo Ic last-pane +.Op Fl deZ +.Op Fl t Ar target-window +.Xc +.D1 Pq alias: Ic lastp +Select the last (previously selected) pane. +.Fl Z +keeps the window zoomed if it was zoomed. +.Fl e +enables or +.Fl d +disables input to the pane. +.Tg last +.It Ic last-window Op Fl t Ar target-session +.D1 Pq alias: Ic last +Select the last (previously selected) window. +If no +.Ar target-session +is specified, select the last window of the current session. +.Tg link +.It Xo Ic link-window +.Op Fl abdk +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 Pq alias: Ic linkw +Link the window at +.Ar src-window +to the specified +.Ar dst-window . +If +.Ar dst-window +is specified and no such window exists, the +.Ar src-window +is linked there. +With +.Fl a +or +.Fl b +the window is moved to the next index after or before +.Ar dst-window +(existing windows are moved if necessary). +If +.Fl k +is given and +.Ar dst-window +exists, it is killed, otherwise an error is generated. +If +.Fl d +is given, the newly linked window is not selected. +.Tg lsp +.It Xo Ic list-panes +.Op Fl as +.Op Fl F Ar format +.Op Fl f Ar filter +.Op Fl t Ar target +.Xc +.D1 Pq alias: Ic lsp +If +.Fl a +is given, +.Ar target +is ignored and all panes on the server are listed. +If +.Fl s +is given, +.Ar target +is a session (or the current session). +If neither is given, +.Ar target +is a window (or the current window). +.Fl F +specifies the format of each line and +.Fl f +a filter. +Only panes for which the filter is true are shown. +See the +.Sx FORMATS +section. +.Tg lsw +.It Xo Ic list-windows +.Op Fl a +.Op Fl F Ar format +.Op Fl f Ar filter +.Op Fl t Ar target-session +.Xc +.D1 Pq alias: Ic lsw +If +.Fl a +is given, list all windows on the server. +Otherwise, list windows in the current session or in +.Ar target-session . +.Fl F +specifies the format of each line and +.Fl f +a filter. +Only windows for which the filter is true are shown. +See the +.Sx FORMATS +section. +.Tg movep +.It Xo Ic move-pane +.Op Fl bdfhv +.Op Fl l Ar size +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 Pq alias: Ic movep +Does the same as +.Ic join-pane . +.Tg movew +.It Xo Ic move-window +.Op Fl abrdk +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 Pq alias: Ic movew +This is similar to +.Ic link-window , +except the window at +.Ar src-window +is moved to +.Ar dst-window . +With +.Fl r , +all windows in the session are renumbered in sequential order, respecting +the +.Ic base-index +option. +.Tg neww +.It Xo Ic new-window +.Op Fl abdkPS +.Op Fl c Ar start-directory +.Op Fl e Ar environment +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl t Ar target-window +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic neww +Create a new window. +With +.Fl a +or +.Fl b , +the new window is inserted at the next index after or before the specified +.Ar target-window , +moving windows up if necessary; +otherwise +.Ar target-window +is the new window location. +.Pp +If +.Fl d +is given, the session does not make the new window the current window. +.Ar target-window +represents the window to be created; if the target already exists an error is +shown, unless the +.Fl k +flag is used, in which case it is destroyed. +If +.Fl S +is given and a window named +.Ar window-name +already exists, it is selected (unless +.Fl d +is also given in which case the command does nothing). +.Pp +.Ar shell-command +is the command to execute. +If +.Ar shell-command +is not specified, the value of the +.Ic default-command +option is used. +.Fl c +specifies the working directory in which the new window is created. +.Pp +When the shell command completes, the window closes. +See the +.Ic remain-on-exit +option to change this behaviour. +.Pp +.Fl e +takes the form +.Ql VARIABLE=value +and sets an environment variable for the newly created window; it may be +specified multiple times. +.Pp +The +.Ev TERM +environment variable must be set to +.Ql screen +or +.Ql tmux +for all programs running +.Em inside +.Nm . +New windows will automatically have +.Ql TERM=screen +added to their environment, but care must be taken not to reset this in shell +start-up files or by the +.Fl e +option. +.Pp +The +.Fl P +option prints information about the new window after it has been created. +By default, it uses the format +.Ql #{session_name}:#{window_index} +but a different format may be specified with +.Fl F . +.Tg nextl +.It Ic next-layout Op Fl t Ar target-window +.D1 Pq alias: Ic nextl +Move a window to the next layout and rearrange the panes to fit. +.Tg next +.It Xo Ic next-window +.Op Fl a +.Op Fl t Ar target-session +.Xc +.D1 Pq alias: Ic next +Move to the next window in the session. +If +.Fl a +is used, move to the next window with an alert. +.Tg pipep +.It Xo Ic pipe-pane +.Op Fl IOo +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic pipep +Pipe output sent by the program in +.Ar target-pane +to a shell command or vice versa. +A pane may only be connected to one command at a time, any existing pipe is +closed before +.Ar shell-command +is executed. +The +.Ar shell-command +string may contain the special character sequences supported by the +.Ic status-left +option. +If no +.Ar shell-command +is given, the current pipe (if any) is closed. +.Pp +.Fl I +and +.Fl O +specify which of the +.Ar shell-command +output streams are connected to the pane: +with +.Fl I +stdout is connected (so anything +.Ar shell-command +prints is written to the pane as if it were typed); +with +.Fl O +stdin is connected (so any output in the pane is piped to +.Ar shell-command ) . +Both may be used together and if neither are specified, +.Fl O +is used. +.Pp +The +.Fl o +option only opens a new pipe if no previous pipe exists, allowing a pipe to +be toggled with a single key, for example: +.Bd -literal -offset indent +bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' +.Ed +.Tg prevl +.It Xo Ic previous-layout +.Op Fl t Ar target-window +.Xc +.D1 Pq alias: Ic prevl +Move to the previous layout in the session. +.Tg prev +.It Xo Ic previous-window +.Op Fl a +.Op Fl t Ar target-session +.Xc +.D1 Pq alias: Ic prev +Move to the previous window in the session. +With +.Fl a , +move to the previous window with an alert. +.Tg renamew +.It Xo Ic rename-window +.Op Fl t Ar target-window +.Ar new-name +.Xc +.D1 Pq alias: Ic renamew +Rename the current window, or the window at +.Ar target-window +if specified, to +.Ar new-name . +.Tg resizep +.It Xo Ic resize-pane +.Op Fl DLMRTUZ +.Op Fl t Ar target-pane +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar adjustment +.Xc +.D1 Pq alias: Ic resizep +Resize a pane, up, down, left or right by +.Ar adjustment +with +.Fl U , +.Fl D , +.Fl L +or +.Fl R , +or +to an absolute size +with +.Fl x +or +.Fl y . +The +.Ar adjustment +is given in lines or columns (the default is 1); +.Fl x +and +.Fl y +may be a given as a number of lines or columns or followed by +.Ql % +for a percentage of the window size (for example +.Ql -x 10% ) . +With +.Fl Z , +the active pane is toggled between zoomed (occupying the whole of the window) +and unzoomed (its normal position in the layout). +.Pp +.Fl M +begins mouse resizing (only valid if bound to a mouse key binding, see +.Sx MOUSE SUPPORT ) . +.Pp +.Fl T +trims all lines below the current cursor position and moves lines out of the +history to replace them. +.Tg resizew +.It Xo Ic resize-window +.Op Fl aADLRU +.Op Fl t Ar target-window +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar adjustment +.Xc +.D1 Pq alias: Ic resizew +Resize a window, up, down, left or right by +.Ar adjustment +with +.Fl U , +.Fl D , +.Fl L +or +.Fl R , +or +to an absolute size +with +.Fl x +or +.Fl y . +The +.Ar adjustment +is given in lines or cells (the default is 1). +.Fl A +sets the size of the largest session containing the window; +.Fl a +the size of the smallest. +This command will automatically set +.Ic window-size +to manual in the window options. +.Tg respawnp +.It Xo Ic respawn-pane +.Op Fl k +.Op Fl c Ar start-directory +.Op Fl e Ar environment +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic respawnp +Reactivate a pane in which the command has exited (see the +.Ic remain-on-exit +window option). +If +.Ar shell-command +is not given, the command used when the pane was created or last respawned is +executed. +The pane must be already inactive, unless +.Fl k +is given, in which case any existing command is killed. +.Fl c +specifies a new working directory for the pane. +The +.Fl e +option has the same meaning as for the +.Ic new-window +command. +.Tg respawnw +.It Xo Ic respawn-window +.Op Fl k +.Op Fl c Ar start-directory +.Op Fl e Ar environment +.Op Fl t Ar target-window +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic respawnw +Reactivate a window in which the command has exited (see the +.Ic remain-on-exit +window option). +If +.Ar shell-command +is not given, the command used when the window was created or last respawned is +executed. +The window must be already inactive, unless +.Fl k +is given, in which case any existing command is killed. +.Fl c +specifies a new working directory for the window. +The +.Fl e +option has the same meaning as for the +.Ic new-window +command. +.Tg rotatew +.It Xo Ic rotate-window +.Op Fl DUZ +.Op Fl t Ar target-window +.Xc +.D1 Pq alias: Ic rotatew +Rotate the positions of the panes within a window, either upward (numerically +lower) with +.Fl U +or downward (numerically higher). +.Fl Z +keeps the window zoomed if it was zoomed. +.Tg selectl +.It Xo Ic select-layout +.Op Fl Enop +.Op Fl t Ar target-pane +.Op Ar layout-name +.Xc +.D1 Pq alias: Ic selectl +Choose a specific layout for a window. +If +.Ar layout-name +is not given, the last preset layout used (if any) is reapplied. +.Fl n +and +.Fl p +are equivalent to the +.Ic next-layout +and +.Ic previous-layout +commands. +.Fl o +applies the last set layout if possible (undoes the most recent layout change). +.Fl E +spreads the current pane and any panes next to it out evenly. +.Tg selectp +.It Xo Ic select-pane +.Op Fl DdeLlMmRUZ +.Op Fl T Ar title +.Op Fl t Ar target-pane +.Xc +.D1 Pq alias: Ic selectp +Make pane +.Ar target-pane +the active pane in its window. +If one of +.Fl D , +.Fl L , +.Fl R , +or +.Fl U +is used, respectively the pane below, to the left, to the right, or above the +target pane is used. +.Fl Z +keeps the window zoomed if it was zoomed. +.Fl l +is the same as using the +.Ic last-pane +command. +.Fl e +enables or +.Fl d +disables input to the pane. +.Fl T +sets the pane title. +.Pp +.Fl m +and +.Fl M +are used to set and clear the +.Em marked pane . +There is one marked pane at a time, setting a new marked pane clears the last. +The marked pane is the default target for +.Fl s +to +.Ic join-pane , +.Ic move-pane , +.Ic swap-pane +and +.Ic swap-window . +.Tg selectw +.It Xo Ic select-window +.Op Fl lnpT +.Op Fl t Ar target-window +.Xc +.D1 Pq alias: Ic selectw +Select the window at +.Ar target-window . +.Fl l , +.Fl n +and +.Fl p +are equivalent to the +.Ic last-window , +.Ic next-window +and +.Ic previous-window +commands. +If +.Fl T +is given and the selected window is already the current window, +the command behaves like +.Ic last-window . +.Tg splitw +.It Xo Ic split-window +.Op Fl bdfhIvPZ +.Op Fl c Ar start-directory +.Op Fl e Ar environment +.Op Fl l Ar size +.Op Fl t Ar target-pane +.Op Ar shell-command +.Op Fl F Ar format +.Xc +.D1 Pq alias: Ic splitw +Create a new pane by splitting +.Ar target-pane : +.Fl h +does a horizontal split and +.Fl v +a vertical split; if neither is specified, +.Fl v +is assumed. +The +.Fl l +option specifies the size of the new pane in lines (for vertical split) or in +columns (for horizontal split); +.Ar size +may be followed by +.Ql % +to specify a percentage of the available space. +The +.Fl b +option causes the new pane to be created to the left of or above +.Ar target-pane . +The +.Fl f +option creates a new pane spanning the full window height (with +.Fl h ) +or full window width (with +.Fl v ) , +instead of splitting the active pane. +.Fl Z +zooms if the window is not zoomed, or keeps it zoomed if already zoomed. +.Pp +An empty +.Ar shell-command +('') will create a pane with no command running in it. +Output can be sent to such a pane with the +.Ic display-message +command. +The +.Fl I +flag (if +.Ar shell-command +is not specified or empty) +will create an empty pane and forward any output from stdin to it. +For example: +.Bd -literal -offset indent +$ make 2>&1|tmux splitw -dI & +.Ed +.Pp +All other options have the same meaning as for the +.Ic new-window +command. +.Tg swapp +.It Xo Ic swap-pane +.Op Fl dDUZ +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 Pq alias: Ic swapp +Swap two panes. +If +.Fl U +is used and no source pane is specified with +.Fl s , +.Ar dst-pane +is swapped with the previous pane (before it numerically); +.Fl D +swaps with the next pane (after it numerically). +.Fl d +instructs +.Nm +not to change the active pane and +.Fl Z +keeps the window zoomed if it was zoomed. +.Pp +If +.Fl s +is omitted and a marked pane is present (see +.Ic select-pane +.Fl m ) , +the marked pane is used rather than the current pane. +.Tg swapw +.It Xo Ic swap-window +.Op Fl d +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 Pq alias: Ic swapw +This is similar to +.Ic link-window , +except the source and destination windows are swapped. +It is an error if no window exists at +.Ar src-window . +If +.Fl d +is given, the new window does not become the current window. +.Pp +If +.Fl s +is omitted and a marked pane is present (see +.Ic select-pane +.Fl m ) , +the window containing the marked pane is used rather than the current window. +.Tg unlinkw +.It Xo Ic unlink-window +.Op Fl k +.Op Fl t Ar target-window +.Xc +.D1 Pq alias: Ic unlinkw +Unlink +.Ar target-window . +Unless +.Fl 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 +.Fl k +is specified and the window is linked to only one session, it is unlinked and +destroyed. +.El +.Sh KEY BINDINGS +.Nm +allows a command to be bound to most keys, with or without a prefix key. +When specifying keys, most represent themselves (for example +.Ql A +to +.Ql Z ) . +Ctrl keys may be prefixed with +.Ql C- +or +.Ql ^ , +Shift keys with +.Ql S- +and Alt (meta) with +.Ql M- . +In addition, the following special key names are accepted: +.Em Up , +.Em Down , +.Em Left , +.Em Right , +.Em BSpace , +.Em BTab , +.Em DC +(Delete), +.Em End , +.Em Enter , +.Em Escape , +.Em F1 +to +.Em F12 , +.Em Home , +.Em IC +(Insert), +.Em NPage/PageDown/PgDn , +.Em PPage/PageUp/PgUp , +.Em Space , +and +.Em Tab . +Note that to bind the +.Ql \&" +or +.Ql ' +keys, quotation marks are necessary, for example: +.Bd -literal -offset indent +bind-key '"' split-window +bind-key "'" new-window +.Ed +.Pp +A command bound to the +.Em Any +key will execute for all keys which do not have a more specific binding. +.Pp +Commands related to key bindings are as follows: +.Bl -tag -width Ds +.Tg bind +.It Xo Ic bind-key +.Op Fl nr +.Op Fl N Ar note +.Op Fl T Ar key-table +.Ar key command Op Ar arguments +.Xc +.D1 Pq alias: Ic bind +Bind key +.Ar key +to +.Ar command . +Keys are bound in a key table. +By default (without -T), the key is bound in +the +.Em prefix +key table. +This table is used for keys pressed after the prefix key (for example, +by default +.Ql c +is bound to +.Ic new-window +in the +.Em prefix +table, so +.Ql C-b c +creates a new window). +The +.Em root +table is used for keys pressed without the prefix key: binding +.Ql c +to +.Ic new-window +in the +.Em root +table (not recommended) means a plain +.Ql c +will create a new window. +.Fl n +is an alias +for +.Fl T Ar root . +Keys may also be bound in custom key tables and the +.Ic switch-client +.Fl T +command used to switch to them from a key binding. +The +.Fl r +flag indicates this key may repeat, see the +.Ic repeat-time +option. +.Fl N +attaches a note to the key (shown with +.Ic list-keys +.Fl N ) . +.Pp +To view the default bindings and possible commands, see the +.Ic list-keys +command. +.Tg lsk +.It Xo Ic list-keys +.Op Fl 1aN +.Op Fl P Ar prefix-string Fl T Ar key-table +.Op Ar key +.Xc +.D1 Pq alias: Ic lsk +List key bindings. +There are two forms: the default lists keys as +.Ic bind-key +commands; +.Fl N +lists only keys with attached notes and shows only the key and note for each +key. +.Pp +With the default form, all key tables are listed by default. +.Fl T +lists only keys in +.Ar key-table . +.Pp +With the +.Fl N +form, only keys in the +.Em root +and +.Em prefix +key tables are listed by default; +.Fl T +also lists only keys in +.Ar key-table . +.Fl P +specifies a prefix to print before each key and +.Fl 1 +lists only the first matching key. +.Fl a +lists the command for keys that do not have a note rather than skipping them. +.Tg send +.It Xo Ic send-keys +.Op Fl FHlMRX +.Op Fl N Ar repeat-count +.Op Fl t Ar target-pane +.Ar key Ar ... +.Xc +.D1 Pq alias: Ic send +Send a key or keys to a window. +Each argument +.Ar key +is the name of the key (such as +.Ql C-a +or +.Ql 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. +If no keys are given and the command is bound to a key, then that key is used. +.Pp +The +.Fl l +flag disables key name lookup and processes the keys as literal UTF-8 +characters. +The +.Fl H +flag expects each key to be a hexadecimal number for an ASCII character. +.Pp +The +.Fl R +flag causes the terminal state to be reset. +.Pp +.Fl M +passes through a mouse event (only valid if bound to a mouse key binding, see +.Sx MOUSE SUPPORT ) . +.Pp +.Fl X +is used to send a command into copy mode - see +the +.Sx WINDOWS AND PANES +section. +.Fl N +specifies a repeat count and +.Fl F +expands formats in arguments where appropriate. +.It Xo Ic send-prefix +.Op Fl 2 +.Op Fl t Ar target-pane +.Xc +Send the prefix key, or with +.Fl 2 +the secondary prefix key, to a window as if it was pressed. +.Tg unbind +.It Xo Ic unbind-key +.Op Fl anq +.Op Fl T Ar key-table +.Ar key +.Xc +.D1 Pq alias: Ic unbind +Unbind the command bound to +.Ar key . +.Fl n +and +.Fl T +are the same as for +.Ic bind-key . +If +.Fl a +is present, all key bindings are removed. +The +.Fl q +option prevents errors being returned. +.El +.Sh OPTIONS +The appearance and behaviour of +.Nm +may be modified by changing the value of various options. +There are four types of option: +.Em server options , +.Em session options , +.Em window options , +and +.Em pane options . +.Pp +The +.Nm +server has a set of global server options which do not apply to any particular +window or session or pane. +These are altered with the +.Ic set-option +.Fl s +command, or displayed with the +.Ic show-options +.Fl s +command. +.Pp +In addition, 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 +.Ic set-option +command and may be listed with the +.Ic show-options +command. +The available server and session options are listed under the +.Ic set-option +command. +.Pp +Similarly, a set of window options is attached to each window and a set of pane +options to each pane. +Pane options inherit from window options. +This means any pane option may be set as a window option to apply the option to +all panes in the window without the option set, for example these commands will +set the background colour to red for all panes except pane 0: +.Bd -literal -offset indent +set -w window-style bg=red +set -pt:.0 window-style bg=blue +.Ed +.Pp +There is also a set of global window options from which any unset window or +pane options are inherited. +Window and pane options are altered with +.Ic set-option +.Fl w +and +.Fl p +commands and displayed with +.Ic show-option +.Fl w +and +.Fl p . +.Pp +.Nm +also supports user options which are prefixed with a +.Ql \&@ . +User options may have any name, so long as they are prefixed with +.Ql \&@ , +and be set to any string. +For example: +.Bd -literal -offset indent +$ tmux set -wq @foo "abc123" +$ tmux show -wv @foo +abc123 +.Ed +.Pp +Commands which set options are as follows: +.Bl -tag -width Ds +.Tg set +.It Xo Ic set-option +.Op Fl aFgopqsuUw +.Op Fl t Ar target-pane +.Ar option Ar value +.Xc +.D1 Pq alias: Ic set +Set a pane option with +.Fl p , +a window option with +.Fl w , +a server option with +.Fl s , +otherwise a session option. +If the option is not a user option, +.Fl w +or +.Fl s +may be unnecessary - +.Nm +will infer the type from the option name, assuming +.Fl w +for pane options. +If +.Fl g +is given, the global session or window option is set. +.Pp +.Fl F +expands formats in the option value. +The +.Fl u +flag unsets an option, so a session inherits the option from the global +options (or with +.Fl g , +restores a global option to the default). +.Fl U +unsets an option (like +.Fl u ) +but if the option is a pane option also unsets the option on any panes in the +window. +.Ar value +depends on the option and may be a number, a string, or a flag (on, off, or +omitted to toggle). +.Pp +The +.Fl o +flag prevents setting an option that is already set and the +.Fl q +flag suppresses errors about unknown or ambiguous options. +.Pp +With +.Fl a , +and if the option expects a string or a style, +.Ar value +is appended to the existing setting. +For example: +.Bd -literal -offset indent +set -g status-left "foo" +set -ag status-left "bar" +.Ed +.Pp +Will result in +.Ql foobar . +And: +.Bd -literal -offset indent +set -g status-style "bg=red" +set -ag status-style "fg=blue" +.Ed +.Pp +Will result in a red background +.Em and +blue foreground. +Without +.Fl a , +the result would be the default background and a blue foreground. +.Tg show +.It Xo Ic show-options +.Op Fl AgHpqsvw +.Op Fl t Ar target-pane +.Op Ar option +.Xc +.D1 Pq alias: Ic show +Show the pane options (or a single option if +.Ar option +is provided) with +.Fl p , +the window options with +.Fl w , +the server options with +.Fl s , +otherwise the session options. +If the option is not a user option, +.Fl w +or +.Fl s +may be unnecessary - +.Nm +will infer the type from the option name, assuming +.Fl w +for pane options. +Global session or window options are listed if +.Fl g +is used. +.Fl v +shows only the option value, not the name. +If +.Fl q +is set, no error will be returned if +.Ar option +is unset. +.Fl H +includes hooks (omitted by default). +.Fl A +includes options inherited from a parent set of options, such options are +marked with an asterisk. +.El +.Pp +Available server options are: +.Bl -tag -width Ds +.It Ic backspace Ar key +Set the key sent by +.Nm +for backspace. +.It Ic buffer-limit Ar number +Set the number of buffers; as new buffers are added to the top of the stack, +old ones are removed from the bottom if necessary to maintain this maximum +length. +.It Xo Ic command-alias[] +.Ar name=value +.Xc +This is an array of custom aliases for commands. +If an unknown command matches +.Ar name , +it is replaced with +.Ar value . +For example, after: +.Pp +.Dl set -s command-alias[100] zoom='resize-pane -Z' +.Pp +Using: +.Pp +.Dl zoom -t:.1 +.Pp +Is equivalent to: +.Pp +.Dl resize-pane -Z -t:.1 +.Pp +Note that aliases are expanded when a command is parsed rather than when it is +executed, so binding an alias with +.Ic bind-key +will bind the expanded form. +.It Ic default-terminal Ar terminal +Set the default terminal for new windows created in this session - the +default value of the +.Ev TERM +environment variable. +For +.Nm +to work correctly, this +.Em must +be set to +.Ql screen , +.Ql tmux +or a derivative of them. +.It Ic copy-command Ar shell-command +Give the command to pipe to if the +.Ic copy-pipe +copy mode command is used without arguments. +.It Ic escape-time Ar time +Set the time in milliseconds for which +.Nm +waits after an escape is input to determine if it is part of a function or meta +key sequences. +The default is 500 milliseconds. +.It Ic editor Ar shell-command +Set the command used when +.Nm +runs an editor. +.It Xo Ic exit-empty +.Op Ic on | off +.Xc +If enabled (the default), the server will exit when there are no active +sessions. +.It Xo Ic exit-unattached +.Op Ic on | off +.Xc +If enabled, the server will exit when there are no attached clients. +.It Xo Ic extended-keys +.Op Ic on | off | always +.Xc +When +.Ic on +or +.Ic always , +the escape sequence to enable extended keys is sent to the terminal, if +.Nm +knows that it is supported. +.Nm +always recognises extended keys itself. +If this option is +.Ic on , +.Nm +will only forward extended keys to applications when they request them; if +.Ic always , +.Nm +will always forward the keys. +.It Xo Ic focus-events +.Op Ic on | off +.Xc +When enabled, focus events are requested from the terminal if supported and +passed through to applications running in +.Nm . +Attached clients should be detached and attached again after changing this +option. +.It Ic history-file Ar path +If not empty, a file to which +.Nm +will write command prompt history on exit and load it from on start. +.It Ic message-limit Ar number +Set the number of error or information messages to save in the message log for +each client. +.It Ic prompt-history-limit Ar number +Set the number of history items to save in the history file for each type of +command prompt. +.It Xo Ic set-clipboard +.Op Ic on | external | off +.Xc +Attempt to set the terminal clipboard content using the +.Xr xterm 1 +escape sequence, if there is an +.Em \&Ms +entry in the +.Xr terminfo 5 +description (see the +.Sx TERMINFO EXTENSIONS +section). +.Pp +If set to +.Ic on , +.Nm +will both accept the escape sequence to create a buffer and attempt to set +the terminal clipboard. +If set to +.Ic external , +.Nm +will attempt to set the terminal clipboard but ignore attempts +by applications to set +.Nm +buffers. +If +.Ic off , +.Nm +will neither accept the clipboard escape sequence nor attempt to set the +clipboard. +.Pp +Note that this feature needs to be enabled in +.Xr xterm 1 +by setting the resource: +.Bd -literal -offset indent +disallowedWindowOps: 20,21,SetXprop +.Ed +.Pp +Or changing this property from the +.Xr xterm 1 +interactive menu when required. +.It Ic terminal-features[] Ar string +Set terminal features for terminal types read from +.Xr terminfo 5 . +.Nm +has a set of named terminal features. +Each will apply appropriate changes to the +.Xr terminfo 5 +entry in use. +.Pp +.Nm +can detect features for a few common terminals; this option can be used to +easily tell tmux about features supported by terminals it cannot detect. +The +.Ic terminal-overrides +option allows individual +.Xr terminfo 5 +capabilities to be set instead, +.Ic terminal-features +is intended for classes of functionality supported in a standard way but not +reported by +.Xr terminfo 5 . +Care must be taken to configure this only with features the terminal actually +supports. +.Pp +This is an array option where each entry is a colon-separated string made up +of a terminal type pattern (matched using +.Xr fnmatch 3 ) +followed by a list of terminal features. +The available features are: +.Bl -tag -width Ds +.It 256 +Supports 256 colours with the SGR escape sequences. +.It clipboard +Allows setting the system clipboard. +.It ccolour +Allows setting the cursor colour. +.It cstyle +Allows setting the cursor style. +.It extkeys +Supports extended keys. +.It focus +Supports focus reporting. +.It margins +Supports DECSLRM margins. +.It mouse +Supports +.Xr xterm 1 +mouse sequences. +.It osc7 +Supports the OSC 7 working directory extension. +.It overline +Supports the overline SGR attribute. +.It rectfill +Supports the DECFRA rectangle fill escape sequence. +.It RGB +Supports RGB colour with the SGR escape sequences. +.It strikethrough +Supports the strikethrough SGR escape sequence. +.It sync +Supports synchronized updates. +.It title +Supports +.Xr xterm 1 +title setting. +.It usstyle +Allows underscore style and colour to be set. +.El +.It Ic terminal-overrides[] Ar string +Allow terminal descriptions read using +.Xr terminfo 5 +to be overridden. +Each entry is a colon-separated string made up of a terminal type pattern +(matched using +.Xr fnmatch 3 ) +and a set of +.Em name=value +entries. +.Pp +For example, to set the +.Ql clear +.Xr terminfo 5 +entry to +.Ql \ee[H\ee[2J +for all terminal types matching +.Ql rxvt* : +.Pp +.Dl "rxvt*:clear=\ee[H\ee[2J" +.Pp +The terminal entry value is passed through +.Xr strunvis 3 +before interpretation. +.It Ic user-keys[] Ar key +Set list of user-defined key escape sequences. +Each item is associated with a key named +.Ql User0 , +.Ql User1 , +and so on. +.Pp +For example: +.Bd -literal -offset indent +set -s user-keys[0] "\ee[5;30012~" +bind User0 resize-pane -L 3 +.Ed +.El +.Pp +Available session options are: +.Bl -tag -width Ds +.It Xo Ic activity-action +.Op Ic any | none | current | other +.Xc +Set action on window activity when +.Ic monitor-activity +is on. +.Ic any +means activity in any window linked to a session causes a bell or message +(depending on +.Ic visual-activity ) +in the current window of that session, +.Ic none +means all activity is ignored (equivalent to +.Ic monitor-activity +being off), +.Ic current +means only activity in windows other than the current window are ignored and +.Ic other +means activity in the current window is ignored but not those in other windows. +.It Ic assume-paste-time Ar milliseconds +If keys are entered faster than one in +.Ar milliseconds , +they are assumed to have been pasted rather than typed and +.Nm +key bindings are not processed. +The default is one millisecond and zero disables. +.It Ic base-index Ar index +Set the base index from which an unused index should be searched when a new +window is created. +The default is zero. +.It Xo Ic bell-action +.Op Ic any | none | current | other +.Xc +Set action on a bell in a window when +.Ic monitor-bell +is on. +The values are the same as those for +.Ic activity-action . +.It Ic default-command Ar shell-command +Set the command used for new windows (if not specified when the window is +created) to +.Ar shell-command , +which may be any +.Xr sh 1 +command. +The default is an empty string, which instructs +.Nm +to create a login shell using the value of the +.Ic default-shell +option. +.It Ic default-shell Ar path +Specify the default shell. +This is used as the login shell for new windows when the +.Ic default-command +option is set to empty, and must be the full path of the executable. +When started +.Nm +tries to set a default value from the first suitable of the +.Ev SHELL +environment variable, the shell returned by +.Xr getpwuid 3 , +or +.Pa /bin/sh . +This option should be configured when +.Nm +is used as a login shell. +.It Ic default-size Ar XxY +Set the default size of new windows when the +.Ic window-size +option is set to manual or when a session is created with +.Ic new-session +.Fl d . +The value is the width and height separated by an +.Ql x +character. +The default is 80x24. +.It Xo Ic destroy-unattached +.Op Ic on | off +.Xc +If enabled and the session is no longer attached to any clients, it is +destroyed. +.It Xo Ic detach-on-destroy +.Op Ic off | on | no-detached +.Xc +If on (the default), the client is detached when the session it is attached to +is destroyed. +If off, the client is switched to the most recently active of the remaining +sessions. +If +.Ic no-detached , +the client is detached only if there are no detached sessions; if detached +sessions exist, the client is switched to the most recently active. +.It Ic display-panes-active-colour Ar colour +Set the colour used by the +.Ic display-panes +command to show the indicator for the active pane. +.It Ic display-panes-colour Ar colour +Set the colour used by the +.Ic display-panes +command to show the indicators for inactive panes. +.It Ic display-panes-time Ar time +Set the time in milliseconds for which the indicators shown by the +.Ic display-panes +command appear. +.It Ic display-time Ar time +Set the amount of time for which status line messages and other on-screen +indicators are displayed. +If set to 0, messages and indicators are displayed until a key is pressed. +.Ar time +is in milliseconds. +.It Ic history-limit Ar lines +Set the maximum number of lines held in window history. +This setting applies only to new windows - existing window histories are not +resized and retain the limit at the point they were created. +.It Ic key-table Ar key-table +Set the default key table to +.Ar key-table +instead of +.Em root . +.It Ic lock-after-time Ar number +Lock the session (like the +.Ic lock-session +command) after +.Ar number +seconds of inactivity. +The default is not to lock (set to 0). +.It Ic lock-command Ar shell-command +Command to run when locking each client. +The default is to run +.Xr lock 1 +with +.Fl np . +.It Ic message-command-style Ar style +Set status line message command style. +This is used for the command prompt with +.Xr vi 1 +keys when in command mode. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.It Ic message-style Ar style +Set status line message style. +This is used for messages and for the command prompt. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.It Xo Ic mouse +.Op Ic on | off +.Xc +If on, +.Nm +captures the mouse and allows mouse events to be bound as key bindings. +See the +.Sx MOUSE SUPPORT +section for details. +.It Ic prefix Ar key +Set the key accepted as a prefix key. +In addition to the standard keys described under +.Sx KEY BINDINGS , +.Ic prefix +can be set to the special key +.Ql None +to set no prefix. +.It Ic prefix2 Ar key +Set a secondary key accepted as a prefix key. +Like +.Ic prefix , +.Ic prefix2 +can be set to +.Ql None . +.It Xo Ic renumber-windows +.Op Ic on | off +.Xc +If on, when a window is closed in a session, automatically renumber the other +windows in numerical order. +This respects the +.Ic base-index +option if it has been set. +If off, do not renumber the windows. +.It Ic repeat-time Ar time +Allow multiple commands to be entered without pressing the prefix-key again +in the specified +.Ar time +milliseconds (the default is 500). +Whether a key repeats may be set when it is bound using the +.Fl r +flag to +.Ic bind-key . +Repeat is enabled for the default keys bound to the +.Ic resize-pane +command. +.It Xo Ic set-titles +.Op Ic on | off +.Xc +Attempt to set the client terminal title using the +.Em tsl +and +.Em fsl +.Xr terminfo 5 +entries if they exist. +.Nm +automatically sets these to the \ee]0;...\e007 sequence if +the terminal appears to be +.Xr xterm 1 . +This option is off by default. +.It Ic set-titles-string Ar string +String used to set the client terminal title if +.Ic set-titles +is on. +Formats are expanded, see the +.Sx FORMATS +section. +.It Xo Ic silence-action +.Op Ic any | none | current | other +.Xc +Set action on window silence when +.Ic monitor-silence +is on. +The values are the same as those for +.Ic activity-action . +.It Xo Ic status +.Op Ic off | on | 2 | 3 | 4 | 5 +.Xc +Show or hide the status line or specify its size. +Using +.Ic on +gives a status line one row in height; +.Ic 2 , +.Ic 3 , +.Ic 4 +or +.Ic 5 +more rows. +.It Ic status-format[] Ar format +Specify the format to be used for each line of the status line. +The default builds the top status line from the various individual status +options below. +.It Ic status-interval Ar interval +Update the status line every +.Ar interval +seconds. +By default, updates will occur every 15 seconds. +A setting of zero disables redrawing at interval. +.It Xo Ic status-justify +.Op Ic left | centre | right | absolute-centre +.Xc +Set the position of the window list in the status line: left, centre or right. +centre puts the window list in the relative centre of the available free space; +absolute-centre uses the centre of the entire horizontal space. +.It Xo Ic status-keys +.Op Ic vi | emacs +.Xc +Use vi or emacs-style +key bindings in the status line, for example at the command prompt. +The default is emacs, unless the +.Ev VISUAL +or +.Ev EDITOR +environment variables are set and contain the string +.Ql vi . +.It Ic status-left Ar string +Display +.Ar string +(by default the session name) to the left of the status line. +.Ar string +will be passed through +.Xr strftime 3 . +Also see the +.Sx FORMATS +and +.Sx STYLES +sections. +.Pp +For details on how the names and titles can be set see the +.Sx "NAMES AND TITLES" +section. +.Pp +Examples are: +.Bd -literal -offset indent +#(sysctl vm.loadavg) +#[fg=yellow,bold]#(apm -l)%%#[default] [#S] +.Ed +.Pp +The default is +.Ql "[#S] " . +.It Ic status-left-length Ar length +Set the maximum +.Ar length +of the left component of the status line. +The default is 10. +.It Ic status-left-style Ar style +Set the style of the left part of the status line. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.It Xo Ic status-position +.Op Ic top | bottom +.Xc +Set the position of the status line. +.It Ic status-right Ar string +Display +.Ar string +to the right of the status line. +By default, the current pane title in double quotes, the date and the time +are shown. +As with +.Ic status-left , +.Ar string +will be passed to +.Xr strftime 3 +and character pairs are replaced. +.It Ic status-right-length Ar length +Set the maximum +.Ar length +of the right component of the status line. +The default is 40. +.It Ic status-right-style Ar style +Set the style of the right part of the status line. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.It Ic status-style Ar style +Set status line style. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.It Ic update-environment[] Ar variable +Set list of environment variables to be copied into the session environment +when a new session is created or an existing session is attached. +Any variables that do not exist in the source environment are set to be +removed from the session environment (as if +.Fl r +was given to the +.Ic set-environment +command). +.It Xo Ic visual-activity +.Op Ic on | off | both +.Xc +If on, display a message instead of sending a bell when activity occurs in a +window for which the +.Ic monitor-activity +window option is enabled. +If set to both, a bell and a message are produced. +.It Xo Ic visual-bell +.Op Ic on | off | both +.Xc +If on, a message is shown on a bell in a window for which the +.Ic monitor-bell +window option is enabled instead of it being passed through to the +terminal (which normally makes a sound). +If set to both, a bell and a message are produced. +Also see the +.Ic bell-action +option. +.It Xo Ic visual-silence +.Op Ic on | off | both +.Xc +If +.Ic monitor-silence +is enabled, prints a message after the interval has expired on a given window +instead of sending a bell. +If set to both, a bell and a message are produced. +.It Ic word-separators Ar string +Sets the session's conception of what characters are considered word +separators, for the purposes of the next and previous word commands in +copy mode. +.El +.Pp +Available window options are: +.Pp +.Bl -tag -width Ds -compact +.It Xo Ic aggressive-resize +.Op Ic on | off +.Xc +Aggressively resize the chosen window. +This means that +.Nm +will resize the window to the size of the smallest or largest session +(see the +.Ic window-size +option) for which it is the current window, rather than the session to +which it is attached. +The window may resize when the current window is changed on another +session; this option is good for full-screen programs which support +.Dv SIGWINCH +and poor for interactive programs such as shells. +.Pp +.It Xo Ic automatic-rename +.Op Ic on | off +.Xc +Control automatic window renaming. +When this setting is enabled, +.Nm +will rename the window automatically using the format specified by +.Ic automatic-rename-format . +This flag is automatically disabled for an individual window when a name +is specified at creation with +.Ic new-window +or +.Ic new-session , +or later with +.Ic rename-window , +or with a terminal escape sequence. +It may be switched off globally with: +.Bd -literal -offset indent +set-option -wg automatic-rename off +.Ed +.Pp +.It Ic automatic-rename-format Ar format +The format (see +.Sx FORMATS ) +used when the +.Ic automatic-rename +option is enabled. +.Pp +.It Ic clock-mode-colour Ar colour +Set clock colour. +.Pp +.It Xo Ic clock-mode-style +.Op Ic 12 | 24 +.Xc +Set clock hour format. +.Pp +.It Ic fill-character Ar character +Set the character used to fill areas of the terminal unused by a window. +.Pp +.It Ic main-pane-height Ar height +.It Ic main-pane-width Ar width +Set the width or height of the main (left or top) pane in the +.Ic main-horizontal +or +.Ic main-vertical +layouts. +If suffixed by +.Ql % , +this is a percentage of the window size. +.Pp +.It Ic copy-mode-match-style Ar style +Set the style of search matches in copy mode. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic copy-mode-mark-style Ar style +Set the style of the line containing the mark in copy mode. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic copy-mode-current-match-style Ar style +Set the style of the current search match in copy mode. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Xo Ic mode-keys +.Op Ic vi | emacs +.Xc +Use vi or emacs-style key bindings in copy mode. +The default is emacs, unless +.Ev VISUAL +or +.Ev EDITOR +contains +.Ql vi . +.Pp +.It Ic mode-style Ar style +Set window modes style. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Xo Ic monitor-activity +.Op Ic on | off +.Xc +Monitor for activity in the window. +Windows with activity are highlighted in the status line. +.Pp +.It Xo Ic monitor-bell +.Op Ic on | off +.Xc +Monitor for a bell in the window. +Windows with a bell are highlighted in the status line. +.Pp +.It Xo Ic monitor-silence +.Op Ic interval +.Xc +Monitor for silence (no activity) in the window within +.Ic interval +seconds. +Windows that have been silent for the interval are highlighted in the +status line. +An interval of zero disables the monitoring. +.Pp +.It Ic other-pane-height Ar height +Set the height of the other panes (not the main pane) in the +.Ic main-horizontal +layout. +If this option is set to 0 (the default), it will have no effect. +If both the +.Ic main-pane-height +and +.Ic other-pane-height +options are set, the main pane will grow taller to make the other panes the +specified height, but will never shrink to do so. +If suffixed by +.Ql % , +this is a percentage of the window size. +.Pp +.It Ic other-pane-width Ar width +Like +.Ic other-pane-height , +but set the width of other panes in the +.Ic main-vertical +layout. +.Pp +.It Ic pane-active-border-style Ar style +Set the pane border style for the currently active pane. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +Attributes are ignored. +.Pp +.It Ic pane-base-index Ar index +Like +.Ic base-index , +but set the starting index for pane numbers. +.Pp +.It Ic pane-border-format Ar format +Set the text shown in pane border status lines. +.Pp +.It Xo Ic pane-border-indicators +.Op Ic off | colour | arrows | both +.Xc +Indicate active pane by colouring only half of the border in windows with +exactly two panes, by displaying arrow markers, by drawing both or neither. +.Pp +.It Ic pane-border-lines Ar type +Set the type of characters used for drawing pane borders. +.Ar type +may be one of: +.Bl -tag -width Ds +.It single +single lines using ACS or UTF-8 characters +.It double +double lines using UTF-8 characters +.It heavy +heavy lines using UTF-8 characters +.It simple +simple ASCII characters +.It number +the pane number +.El +.Pp +.Ql double +and +.Ql heavy +will fall back to standard ACS line drawing when UTF-8 is not supported. +.Pp +.It Xo Ic pane-border-status +.Op Ic off | top | bottom +.Xc +Turn pane border status lines off or set their position. +.Pp +.It Ic pane-border-style Ar style +Set the pane border style for panes aside from the active pane. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +Attributes are ignored. +.Pp +.It Ic popup-style Ar style +Set the popup style. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +Attributes are ignored. +.Pp +.It Ic popup-border-style Ar style +Set the popup border style. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +Attributes are ignored. +.Pp +.It Ic popup-border-lines Ar type +Set the type of characters used for drawing popup borders. +.Ar type +may be one of: +.Bl -tag -width Ds +.It single +single lines using ACS or UTF-8 characters (default) +.It rounded +variation of single with rounded corners using UTF-8 characters +.It double +double lines using UTF-8 characters +.It heavy +heavy lines using UTF-8 characters +.It simple +simple ASCII characters +.It padded +simple ASCII space character +.It none +no border +.El +.Pp +.Ql double +and +.Ql heavy +will fall back to standard ACS line drawing when UTF-8 is not supported. +.Pp +.It Ic window-status-activity-style Ar style +Set status line style for windows with an activity alert. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic window-status-bell-style Ar style +Set status line style for windows with a bell alert. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic window-status-current-format Ar string +Like +.Ar window-status-format , +but is the format used when the window is the current window. +.Pp +.It Ic window-status-current-style Ar style +Set status line style for the currently active window. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic window-status-format Ar string +Set the format in which the window is displayed in the status line window list. +See the +.Sx FORMATS +and +.Sx STYLES +sections. +.Pp +.It Ic window-status-last-style Ar style +Set status line style for the last active window. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic window-status-separator Ar string +Sets the separator drawn between windows in the status line. +The default is a single space character. +.Pp +.It Ic window-status-style Ar style +Set status line style for a single window. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Xo Ic window-size +.Ar largest | Ar smallest | Ar manual | Ar latest +.Xc +Configure how +.Nm +determines the window size. +If set to +.Ar largest , +the size of the largest attached session is used; if +.Ar smallest , +the size of the smallest. +If +.Ar manual , +the size of a new window is set from the +.Ic default-size +option and windows are resized automatically. +With +.Ar latest , +.Nm +uses the size of the client that had the most recent activity. +See also the +.Ic resize-window +command and the +.Ic aggressive-resize +option. +.Pp +.It Xo Ic wrap-search +.Op Ic on | off +.Xc +If this option is set, searches will wrap around the end of the pane contents. +The default is on. +.El +.Pp +Available pane options are: +.Pp +.Bl -tag -width Ds -compact +.It Xo Ic allow-passthrough +.Op Ic on | off +.Xc +Allow programs in the pane to bypass +.Nm +using a terminal escape sequence (\eePtmux;...\ee\e\e). +.Pp +.It Xo Ic allow-rename +.Op Ic on | off +.Xc +Allow programs in the pane to change the window name using a terminal escape +sequence (\eek...\ee\e\e). +.Pp +.It Xo Ic alternate-screen +.Op Ic on | off +.Xc +This option configures whether programs running inside the pane may use the +terminal alternate screen feature, which allows the +.Em smcup +and +.Em rmcup +.Xr terminfo 5 +capabilities. +The alternate screen feature preserves the contents of the window when an +interactive application starts and restores it on exit, so that any output +visible before the application starts reappears unchanged after it exits. +.Pp +.It Ic cursor-colour Ar colour +Set the colour of the cursor. +.Pp +.It Ic pane-colours[] Ar colour +The default colour palette. +Each entry in the array defines the colour +.Nm +uses when the colour with that index is requested. +The index may be from zero to 255. +.Pp +.It Ic cursor-style Ar style +Set the style of the cursor. +Available styles are: +.Ic default , +.Ic blinking-block , +.Ic block , +.Ic blinking-underline , +.Ic underline , +.Ic blinking-bar , +.Ic bar . +.Pp +.It Xo Ic remain-on-exit +.Op Ic on | off | failed +.Xc +A pane with this flag set is not destroyed when the program running in it +exits. +If set to +.Ic failed , +then only when the program exit status is not zero. +The pane may be reactivated with the +.Ic respawn-pane +command. +.Pp +.It Ic remain-on-exit-format Ar string +Set the text shown at the bottom of exited panes when +.Ic remain-on-exit +is enabled. +.Pp +.It Xo Ic scroll-on-clear +.Op Ic on | off +.Xc +When the entire screen is cleared and this option is on, scroll the contents of +the screen into history before clearing it. +.Pp +.It Xo Ic synchronize-panes +.Op Ic on | off +.Xc +Duplicate input to all other panes in the same window where this option is also +on (only for panes that are not in any mode). +.Pp +.It Ic window-active-style Ar style +Set the pane style when it is the active pane. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.It Ic window-style Ar style +Set the pane style. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.El +.Sh HOOKS +.Nm +allows commands to run on various triggers, called +.Em hooks . +Most +.Nm +commands have an +.Em after +hook and there are a number of hooks not associated with commands. +.Pp +Hooks are stored as array options, members of the array are executed in +order when the hook is triggered. +Like options different hooks may be global or belong to a session, window or pane. +Hooks may be configured with the +.Ic set-hook +or +.Ic set-option +commands and displayed with +.Ic show-hooks +or +.Ic show-options +.Fl H . +The following two commands are equivalent: +.Bd -literal -offset indent. +set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red' +set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red' +.Ed +.Pp +Setting a hook without specifying an array index clears the hook and sets the +first member of the array. +.Pp +A command's after +hook is run after it completes, except when the command is run as part of a hook +itself. +They are named with an +.Ql after- +prefix. +For example, the following command adds a hook to select the even-vertical +layout after every +.Ic split-window : +.Bd -literal -offset indent +set-hook -g after-split-window "selectl even-vertical" +.Ed +.Pp +All the notifications listed in the +.Sx CONTROL MODE +section are hooks (without any arguments), except +.Ic %exit . +The following additional hooks are available: +.Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX" +.It alert-activity +Run when a window has activity. +See +.Ic monitor-activity . +.It alert-bell +Run when a window has received a bell. +See +.Ic monitor-bell . +.It alert-silence +Run when a window has been silent. +See +.Ic monitor-silence . +.It client-active +Run when a client becomes the latest active client of its session. +.It client-attached +Run when a client is attached. +.It client-detached +Run when a client is detached +.It client-focus-in +Run when focus enters a client +.It client-focus-out +Run when focus exits a client +.It client-resized +Run when a client is resized. +.It client-session-changed +Run when a client's attached session is changed. +.It pane-died +Run when the program running in a pane exits, but +.Ic remain-on-exit +is on so the pane has not closed. +.It pane-exited +Run when the program running in a pane exits. +.It pane-focus-in +Run when the focus enters a pane, if the +.Ic focus-events +option is on. +.It pane-focus-out +Run when the focus exits a pane, if the +.Ic focus-events +option is on. +.It pane-set-clipboard +Run when the terminal clipboard is set using the +.Xr xterm 1 +escape sequence. +.It session-created +Run when a new session created. +.It session-closed +Run when a session closed. +.It session-renamed +Run when a session is renamed. +.It window-linked +Run when a window is linked into a session. +.It window-renamed +Run when a window is renamed. +.It window-resized +Run when a window is resized. +This may be after the +.Ar client-resized +hook is run. +.It window-unlinked +Run when a window is unlinked from a session. +.El +.Pp +Hooks are managed with these commands: +.Bl -tag -width Ds +.It Xo Ic set-hook +.Op Fl agpRuw +.Op Fl t Ar target-pane +.Ar hook-name +.Ar command +.Xc +Without +.Fl R , +sets (or with +.Fl u +unsets) hook +.Ar hook-name +to +.Ar command . +The flags are the same as for +.Ic set-option . +.Pp +With +.Fl R , +run +.Ar hook-name +immediately. +.It Xo Ic show-hooks +.Op Fl gpw +.Op Fl t Ar target-pane +.Xc +Shows hooks. +The flags are the same as for +.Ic show-options . +.El +.Sh MOUSE SUPPORT +If the +.Ic mouse +option is on (the default is off), +.Nm +allows mouse events to be bound as keys. +The name of each key is made up of a mouse event (such as +.Ql MouseUp1 ) +and a location suffix, one of the following: +.Bl -column "XXXXXXXXXXXXX" -offset indent +.It Li "Pane" Ta "the contents of a pane" +.It Li "Border" Ta "a pane border" +.It Li "Status" Ta "the status line window list" +.It Li "StatusLeft" Ta "the left part of the status line" +.It Li "StatusRight" Ta "the right part of the status line" +.It Li "StatusDefault" Ta "any other part of the status line" +.El +.Pp +The following mouse events are available: +.Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent +.It Li "WheelUp" Ta "WheelDown" Ta "" +.It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1" +.It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2" +.It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3" +.It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3" +.It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3" +.It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3" +.El +.Pp +The +.Ql SecondClick +events are fired for the second click of a double click, even if there may be a +third click which will fire +.Ql TripleClick +instead of +.Ql DoubleClick . +.Pp +Each should be suffixed with a location, for example +.Ql MouseDown1Status . +.Pp +The special token +.Ql {mouse} +or +.Ql = +may be used as +.Ar target-window +or +.Ar target-pane +in commands bound to mouse key bindings. +It resolves to the window or pane over which the mouse event took place +(for example, the window in the status line over which button 1 was released for a +.Ql MouseUp1Status +binding, or the pane over which the wheel was scrolled for a +.Ql WheelDownPane +binding). +.Pp +The +.Ic send-keys +.Fl M +flag may be used to forward a mouse event to a pane. +.Pp +The default key bindings allow the mouse to be used to select and resize panes, +to copy text and to change window using the status line. +These take effect if the +.Ic mouse +option is turned on. +.Sh FORMATS +Certain commands accept the +.Fl F +flag with a +.Ar format +argument. +This is a string which controls the output format of the command. +Format variables are enclosed in +.Ql #{ +and +.Ql } , +for example +.Ql #{session_name} . +The possible variables are listed in the table below, or the name of a +.Nm +option may be used for an option's value. +Some variables have a shorter alias such as +.Ql #S ; +.Ql ## +is replaced by a single +.Ql # , +.Ql #, +by a +.Ql \&, +and +.Ql #} +by a +.Ql } . +.Pp +Conditionals are available by prefixing with +.Ql \&? +and separating two alternatives with a comma; +if the specified variable exists and is not zero, the first alternative +is chosen, otherwise the second is used. +For example +.Ql #{?session_attached,attached,not attached} +will include the string +.Ql attached +if the session is attached and the string +.Ql not attached +if it is unattached, or +.Ql #{?automatic-rename,yes,no} +will include +.Ql yes +if +.Ic automatic-rename +is enabled, or +.Ql no +if not. +Conditionals can be nested arbitrarily. +Inside a conditional, +.Ql \&, +and +.Ql } +must be escaped as +.Ql #, +and +.Ql #} , +unless they are part of a +.Ql #{...} +replacement. +For example: +.Bd -literal -offset indent +#{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W . +.Ed +.Pp +String comparisons may be expressed by prefixing two comma-separated +alternatives by +.Ql == , +.Ql != , +.Ql < , +.Ql > , +.Ql <= +or +.Ql >= +and a colon. +For example +.Ql #{==:#{host},myhost} +will be replaced by +.Ql 1 +if running on +.Ql myhost , +otherwise by +.Ql 0 . +.Ql || +and +.Ql && +evaluate to true if either or both of two comma-separated alternatives are +true, for example +.Ql #{||:#{pane_in_mode},#{alternate_on}} . +.Pp +An +.Ql m +specifies an +.Xr fnmatch 3 +or regular expression comparison. +The first argument is the pattern and the second the string to compare. +An optional argument specifies flags: +.Ql r +means the pattern is a regular expression instead of the default +.Xr fnmatch 3 +pattern, and +.Ql i +means to ignore case. +For example: +.Ql #{m:*foo*,#{host}} +or +.Ql #{m/ri:^A,MYVAR} . +A +.Ql C +performs a search for an +.Xr fnmatch 3 +pattern or regular expression in the pane content and evaluates to zero if not +found, or a line number if found. +Like +.Ql m , +an +.Ql r +flag means search for a regular expression and +.Ql i +ignores case. +For example: +.Ql #{C/r:^Start} +.Pp +Numeric operators may be performed by prefixing two comma-separated alternatives with an +.Ql e +and an operator. +An optional +.Ql f +flag may be given after the operator to use floating point numbers, otherwise integers are used. +This may be followed by a number giving the number of decimal places to use for the result. +The available operators are: +addition +.Ql + , +subtraction +.Ql - , +multiplication +.Ql * , +division +.Ql / , +modulus +.Ql m +or +.Ql % +(note that +.Ql % +must be escaped as +.Ql %% +in formats which are also expanded by +.Xr strftime 3 ) +and numeric comparison operators +.Ql == , +.Ql != , +.Ql < , +.Ql <= , +.Ql > +and +.Ql >= . +For example, +.Ql #{e|*|f|4:5.5,3} +multiplies 5.5 by 3 for a result with four decimal places and +.Ql #{e|%%:7,3} +returns the modulus of 7 and 3. +.Ql a +replaces a numeric argument by its ASCII equivalent, so +.Ql #{a:98} +results in +.Ql b . +.Ql c +replaces a +.Nm +colour by its six-digit hexadecimal RGB value. +.Pp +A limit may be placed on the length of the resultant string by prefixing it +by an +.Ql = , +a number and a colon. +Positive numbers count from the start of the string and negative from the end, +so +.Ql #{=5:pane_title} +will include at most the first five characters of the pane title, or +.Ql #{=-5:pane_title} +the last five characters. +A suffix or prefix may be given as a second argument - if provided then it is +appended or prepended to the string if the length has been trimmed, for example +.Ql #{=/5/...:pane_title} +will append +.Ql ... +if the pane title is more than five characters. +Similarly, +.Ql p +pads the string to a given width, for example +.Ql #{p10:pane_title} +will result in a width of at least 10 characters. +A positive width pads on the left, a negative on the right. +.Ql n +expands to the length of the variable and +.Ql w +to its width when displayed, for example +.Ql #{n:window_name} . +.Pp +Prefixing a time variable with +.Ql t:\& +will convert it to a string, so if +.Ql #{window_activity} +gives +.Ql 1445765102 , +.Ql #{t:window_activity} +gives +.Ql Sun Oct 25 09:25:02 2015 . +Adding +.Ql p ( +.Ql `t/p` ) +will use shorter but less accurate time format for times in the past. +A custom format may be given using an +.Ql f +suffix (note that +.Ql % +must be escaped as +.Ql %% +if the format is separately being passed through +.Xr strftime 3 , +for example in the +.Ic status-left +option): +.Ql #{t/f/%%H#:%%M:window_activity} , +see +.Xr strftime 3 . +.Pp +The +.Ql b:\& +and +.Ql d:\& +prefixes are +.Xr basename 3 +and +.Xr dirname 3 +of the variable respectively. +.Ql q:\& +will escape +.Xr sh 1 +special characters or with a +.Ql h +suffix, escape hash characters (so +.Ql # +becomes +.Ql ## ) . +.Ql E:\& +will expand the format twice, for example +.Ql #{E:status-left} +is the result of expanding the content of the +.Ic status-left +option rather than the option itself. +.Ql T:\& +is like +.Ql E:\& +but also expands +.Xr strftime 3 +specifiers. +.Ql S:\& , +.Ql W:\& +or +.Ql P:\& +will loop over each session, window or pane and insert the format once +for each. +For windows and panes, two comma-separated formats may be given: +the second is used for the current window or active pane. +For example, to get a list of windows formatted like the status line: +.Bd -literal -offset indent +#{W:#{E:window-status-format} ,#{E:window-status-current-format} } +.Ed +.Pp +.Ql N:\& +checks if a window (without any suffix or with the +.Ql w +suffix) or a session (with the +.Ql s +suffix) name exists, for example +.Ql `N/w:foo` +is replaced with 1 if a window named +.Ql foo +exists. +.Pp +A prefix of the form +.Ql s/foo/bar/:\& +will substitute +.Ql foo +with +.Ql bar +throughout. +The first argument may be an extended regular expression and a final argument may be +.Ql i +to ignore case, for example +.Ql s/a(.)/\e1x/i:\& +would change +.Ql abABab +into +.Ql bxBxbx . +.Pp +In addition, the last line of a shell command's output may be inserted using +.Ql #() . +For example, +.Ql #(uptime) +will insert the system's uptime. +When constructing formats, +.Nm +does not wait for +.Ql #() +commands to finish; instead, the previous result from running the same command is used, +or a placeholder if the command has not been run before. +If the command hasn't exited, the most recent line of output will be used, but the status +line will not be updated more than once a second. +Commands are executed using +.Pa /bin/sh +and with the +.Nm +global environment set (see the +.Sx GLOBAL AND SESSION ENVIRONMENT +section). +.Pp +An +.Ql l +specifies that a string should be interpreted literally and not expanded. +For example +.Ql #{l:#{?pane_in_mode,yes,no}} +will be replaced by +.Ql #{?pane_in_mode,yes,no} . +.Pp +The following variables are available, where appropriate: +.Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX" +.It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with" +.It Li "active_window_index" Ta "" Ta "Index of active window in session" +.It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen" +.It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen" +.It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen" +.It Li "buffer_created" Ta "" Ta "Time buffer created" +.It Li "buffer_name" Ta "" Ta "Name of buffer" +.It Li "buffer_sample" Ta "" Ta "Sample of start of buffer" +.It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes" +.It Li "client_activity" Ta "" Ta "Time client last had activity" +.It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels" +.It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels" +.It Li "client_control_mode" Ta "" Ta "1 if client is in control mode" +.It Li "client_created" Ta "" Ta "Time client created" +.It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind" +.It Li "client_flags" Ta "" Ta "List of client flags" +.It Li "client_height" Ta "" Ta "Height of client" +.It Li "client_key_table" Ta "" Ta "Current key table" +.It Li "client_last_session" Ta "" Ta "Name of the client's last session" +.It Li "client_name" Ta "" Ta "Name of client" +.It Li "client_pid" Ta "" Ta "PID of client process" +.It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed" +.It Li "client_readonly" Ta "" Ta "1 if client is read-only" +.It Li "client_session" Ta "" Ta "Name of the client's session" +.It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any" +.It Li "client_termname" Ta "" Ta "Terminal name of client" +.It Li "client_termtype" Ta "" Ta "Terminal type of client, if available" +.It Li "client_tty" Ta "" Ta "Pseudo terminal of client" +.It Li "client_uid" Ta "" Ta "UID of client process" +.It Li "client_user" Ta "" Ta "User of client process" +.It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8" +.It Li "client_width" Ta "" Ta "Width of client" +.It Li "client_written" Ta "" Ta "Bytes written to client" +.It Li "command" Ta "" Ta "Name of command in use, if any" +.It Li "command_list_alias" Ta "" Ta "Command alias if listing commands" +.It Li "command_list_name" Ta "" Ta "Command name if listing commands" +.It Li "command_list_usage" Ta "" Ta "Command usage if listing commands" +.It Li "config_files" Ta "" Ta "List of configuration files loaded" +.It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode" +.It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode" +.It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode" +.It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode" +.It Li "current_file" Ta "" Ta "Current configuration file" +.It Li "cursor_character" Ta "" Ta "Character at cursor in pane" +.It Li "cursor_flag" Ta "" Ta "Pane cursor flag" +.It Li "cursor_x" Ta "" Ta "Cursor X position in pane" +.It Li "cursor_y" Ta "" Ta "Cursor Y position in pane" +.It Li "history_bytes" Ta "" Ta "Number of bytes in window history" +.It Li "history_limit" Ta "" Ta "Maximum window history lines" +.It Li "history_size" Ta "" Ta "Size of history in lines" +.It Li "hook" Ta "" Ta "Name of running hook, if any" +.It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any" +.It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any" +.It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any" +.It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any" +.It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any" +.It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any" +.It Li "host" Ta "#H" Ta "Hostname of local host" +.It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)" +.It Li "insert_flag" Ta "" Ta "Pane insert flag" +.It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag" +.It Li "keypad_flag" Ta "" Ta "Pane keypad flag" +.It Li "last_window_index" Ta "" Ta "Index of last window in session" +.It Li "line" Ta "" Ta "Line number in the list" +.It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag" +.It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag" +.It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag" +.It Li "mouse_line" Ta "" Ta "Line under mouse, if any" +.It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag" +.It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag" +.It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag" +.It Li "mouse_word" Ta "" Ta "Word under mouse, if any" +.It Li "mouse_x" Ta "" Ta "Mouse X position, if any" +.It Li "mouse_y" Ta "" Ta "Mouse Y position, if any" +.It Li "next_session_id" Ta "" Ta "Unique session ID for next new session" +.It Li "origin_flag" Ta "" Ta "Pane origin flag" +.It Li "pane_active" Ta "" Ta "1 if active pane" +.It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window" +.It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window" +.It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window" +.It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window" +.It Li "pane_bg" Ta "" Ta "Pane background colour" +.It Li "pane_bottom" Ta "" Ta "Bottom of pane" +.It Li "pane_current_command" Ta "" Ta "Current command if available" +.It Li "pane_current_path" Ta "" Ta "Current path if available" +.It Li "pane_dead" Ta "" Ta "1 if pane is dead" +.It Li "pane_dead_signal" Ta "" Ta "Exit signal of process in dead pane" +.It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane" +.It Li "pane_dead_time" Ta "" Ta "Exit time of process in dead pane" +.It Li "pane_fg" Ta "" Ta "Pane foreground colour" +.It Li "pane_format" Ta "" Ta "1 if format is for a pane" +.It Li "pane_height" Ta "" Ta "Height of pane" +.It Li "pane_id" Ta "#D" Ta "Unique pane ID" +.It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode" +.It Li "pane_index" Ta "#P" Ta "Index of pane" +.It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled" +.It Li "pane_last" Ta "" Ta "1 if last pane" +.It Li "pane_left" Ta "" Ta "Left of pane" +.It Li "pane_marked" Ta "" Ta "1 if this is the marked pane" +.It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set" +.It Li "pane_mode" Ta "" Ta "Name of pane mode, if any" +.It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)" +.It Li "pane_pid" Ta "" Ta "PID of first process in pane" +.It Li "pane_pipe" Ta "" Ta "1 if pane is being piped" +.It Li "pane_right" Ta "" Ta "Right of pane" +.It Li "pane_search_string" Ta "" Ta "Last search string in copy mode" +.It Li "pane_start_command" Ta "" Ta "Command pane started with" +.It Li "pane_start_path" Ta "" Ta "Path pane started with" +.It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized" +.It Li "pane_tabs" Ta "" Ta "Pane tab positions" +.It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)" +.It Li "pane_top" Ta "" Ta "Top of pane" +.It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane" +.It Li "pane_width" Ta "" Ta "Width of pane" +.It Li "pid" Ta "" Ta "Server PID" +.It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated" +.It Li "scroll_position" Ta "" Ta "Scroll position in copy mode" +.It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane" +.It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane" +.It Li "search_match" Ta "" Ta "Search match if any" +.It Li "search_present" Ta "" Ta "1 if search started in copy mode" +.It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode" +.It Li "selection_end_x" Ta "" Ta "X position of the end of the selection" +.It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection" +.It Li "selection_present" Ta "" Ta "1 if selection started in copy mode" +.It Li "selection_start_x" Ta "" Ta "X position of the start of the selection" +.It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection" +.It Li "session_activity" Ta "" Ta "Time of session last activity" +.It Li "session_alerts" Ta "" Ta "List of window indexes with alerts" +.It Li "session_attached" Ta "" Ta "Number of clients session is attached to" +.It Li "session_attached_list" Ta "" Ta "List of clients session is attached to" +.It Li "session_created" Ta "" Ta "Time session created" +.It Li "session_format" Ta "" Ta "1 if format is for a session" +.It Li "session_group" Ta "" Ta "Name of session group" +.It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to" +.It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to" +.It Li "session_group_list" Ta "" Ta "List of sessions in group" +.It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group" +.It Li "session_group_size" Ta "" Ta "Size of session group" +.It Li "session_grouped" Ta "" Ta "1 if session in a group" +.It Li "session_id" Ta "" Ta "Unique session ID" +.It Li "session_last_attached" Ta "" Ta "Time session last attached" +.It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached" +.It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane" +.It Li "session_name" Ta "#S" Ta "Name of session" +.It Li "session_path" Ta "" Ta "Working directory of session" +.It Li "session_stack" Ta "" Ta "Window indexes in most recent order" +.It Li "session_windows" Ta "" Ta "Number of windows in session" +.It Li "socket_path" Ta "" Ta "Server socket path" +.It Li "start_time" Ta "" Ta "Server start time" +.It Li "uid" Ta "" Ta "Server UID" +.It Li "user" Ta "" Ta "Server user" +.It Li "version" Ta "" Ta "Server version" +.It Li "window_active" Ta "" Ta "1 if window active" +.It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window" +.It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window" +.It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active" +.It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active" +.It Li "window_activity" Ta "" Ta "Time of window last activity" +.It Li "window_activity_flag" Ta "" Ta "1 if window has activity" +.It Li "window_bell_flag" Ta "" Ta "1 if window has bell" +.It Li "window_bigger" Ta "" Ta "1 if window is larger than client" +.It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels" +.It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels" +.It Li "window_end_flag" Ta "" Ta "1 if window has the highest index" +.It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##" +.It Li "window_format" Ta "" Ta "1 if format is for a window" +.It Li "window_height" Ta "" Ta "Height of window" +.It Li "window_id" Ta "" Ta "Unique window ID" +.It Li "window_index" Ta "#I" Ta "Index of window" +.It Li "window_last_flag" Ta "" Ta "1 if window is the last used" +.It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes" +.It Li "window_linked" Ta "" Ta "1 if window is linked across sessions" +.It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to" +.It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to" +.It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane" +.It Li "window_name" Ta "#W" Ta "Name of window" +.It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client" +.It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client" +.It Li "window_panes" Ta "" Ta "Number of panes in window" +.It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped" +.It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert" +.It Li "window_stack_index" Ta "" Ta "Index in session most recent stack" +.It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index" +.It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes" +.It Li "window_width" Ta "" Ta "Width of window" +.It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed" +.It Li "wrap_flag" Ta "" Ta "Pane wrap flag" +.El +.Sh STYLES +.Nm +offers various options to specify the colour and attributes of aspects of the +interface, for example +.Ic status-style +for the status line. +In addition, embedded styles may be specified in format options, such as +.Ic status-left , +by enclosing them in +.Ql #[ +and +.Ql \&] . +.Pp +A style may be the single term +.Ql default +to specify the default style (which may come from an option, for example +.Ic status-style +in the status line) or a space +or comma separated list of the following: +.Bl -tag -width Ds +.It Ic fg=colour +Set the foreground colour. +The colour is one of: +.Ic black , +.Ic red , +.Ic green , +.Ic yellow , +.Ic blue , +.Ic magenta , +.Ic cyan , +.Ic white ; +if supported the bright variants +.Ic brightred , +.Ic brightgreen , +.Ic brightyellow ; +.Ic colour0 +to +.Ic colour255 +from the 256-colour set; +.Ic default +for the default colour; +.Ic terminal +for the terminal default colour; or a hexadecimal RGB string such as +.Ql #ffffff . +.It Ic bg=colour +Set the background colour. +.It Ic none +Set no attributes (turn off any active attributes). +.It Xo Ic acs , +.Ic bright +(or +.Ic bold ) , +.Ic dim , +.Ic underscore , +.Ic blink , +.Ic reverse , +.Ic hidden , +.Ic italics , +.Ic overline , +.Ic strikethrough , +.Ic double-underscore , +.Ic curly-underscore , +.Ic dotted-underscore , +.Ic dashed-underscore +.Xc +Set an attribute. +Any of the attributes may be prefixed with +.Ql no +to unset. +.Ic acs +is the terminal alternate character set. +.It Xo Ic align=left +(or +.Ic noalign ) , +.Ic align=centre , +.Ic align=right +.Xc +Align text to the left, centre or right of the available space if appropriate. +.It Ic fill=colour +Fill the available space with a background colour if appropriate. +.It Xo Ic list=on , +.Ic list=focus , +.Ic list=left-marker , +.Ic list=right-marker , +.Ic nolist +.Xc +Mark the position of the various window list components in the +.Ic status-format +option: +.Ic list=on +marks the start of the list; +.Ic list=focus +is the part of the list that should be kept in focus if the entire list won't fit +in the available space (typically the current window); +.Ic list=left-marker +and +.Ic list=right-marker +mark the text to be used to mark that text has been trimmed from the left or +right of the list if there is not enough space. +.It Xo Ic push-default , +.Ic pop-default +.Xc +Store the current colours and attributes as the default or reset to the previous +default. +A +.Ic push-default +affects any subsequent use of the +.Ic default +term until a +.Ic pop-default . +Only one default may be pushed (each +.Ic push-default +replaces the previous saved default). +.It Xo Ic range=left , +.Ic range=right , +.Ic range=window|X , +.Ic norange +.Xc +Mark a range in the +.Ic status-format +option. +.Ic range=left +and +.Ic range=right +are the text used for the +.Ql StatusLeft +and +.Ql StatusRight +mouse keys. +.Ic range=window|X +is the range for a window passed to the +.Ql Status +mouse key, where +.Ql X +is a window index. +.El +.Pp +Examples are: +.Bd -literal -offset indent +fg=yellow bold underscore blink +bg=black,fg=default,noreverse +.Ed +.Sh NAMES AND TITLES +.Nm +distinguishes between names and titles. +Windows and sessions have names, which may be used to specify them in targets +and are displayed in the status line and various lists: the name is the +.Nm +identifier for a window or session. +Only panes have titles. +A pane's title is typically set by the program running inside the pane using +an escape sequence (like it would set the +.Xr xterm 1 +window title in +.Xr X 7 ) . +Windows themselves do not have titles - a window's title is the title of its +active pane. +.Nm +itself may set the title of the terminal in which the client is running, see +the +.Ic set-titles +option. +.Pp +A session's name is set with the +.Ic new-session +and +.Ic rename-session +commands. +A window's name is set with one of: +.Bl -enum -width Ds +.It +A command argument (such as +.Fl n +for +.Ic new-window +or +.Ic new-session ) . +.It +An escape sequence (if the +.Ic allow-rename +option is turned on): +.Bd -literal -offset indent +$ printf '\e033kWINDOW_NAME\e033\e\e' +.Ed +.It +Automatic renaming, which sets the name to the active command in the window's +active pane. +See the +.Ic automatic-rename +option. +.El +.Pp +When a pane is first created, its title is the hostname. +A pane's title can be set via the title setting escape sequence, for example: +.Bd -literal -offset indent +$ printf '\e033]2;My Title\e033\e\e' +.Ed +.Pp +It can also be modified with the +.Ic select-pane +.Fl T +command. +.Sh GLOBAL AND SESSION ENVIRONMENT +When the server is started, +.Nm +copies the environment into the +.Em global environment ; +in addition, each session has a +.Em session environment . +When a window is created, the session and global environments are merged. +If a variable exists in both, the value from the session environment is used. +The result is the initial environment passed to the new process. +.Pp +The +.Ic update-environment +session option may be used to update the session environment from the client +when a new session is created or an old reattached. +.Nm +also initialises the +.Ev TMUX +variable with some internal information to allow commands to be executed +from inside, and the +.Ev TERM +variable with the correct terminal setting of +.Ql screen . +.Pp +Variables in both session and global environments may be marked as hidden. +Hidden variables are not passed into the environment of new processes and +instead can only be used by tmux itself (for example in formats, see the +.Sx FORMATS +section). +.Pp +Commands to alter and view the environment are: +.Bl -tag -width Ds +.Tg setenv +.It Xo Ic set-environment +.Op Fl Fhgru +.Op Fl t Ar target-session +.Ar name Op Ar value +.Xc +.D1 Pq alias: Ic setenv +Set or unset an environment variable. +If +.Fl g +is used, the change is made in the global environment; otherwise, it is applied +to the session environment for +.Ar target-session . +If +.Fl F +is present, then +.Ar value +is expanded as a format. +The +.Fl u +flag unsets a variable. +.Fl r +indicates the variable is to be removed from the environment before starting a +new process. +.Fl h +marks the variable as hidden. +.Tg showenv +.It Xo Ic show-environment +.Op Fl hgs +.Op Fl t Ar target-session +.Op Ar variable +.Xc +.D1 Pq alias: Ic showenv +Display the environment for +.Ar target-session +or the global environment with +.Fl g . +If +.Ar variable +is omitted, all variables are shown. +Variables removed from the environment are prefixed with +.Ql - . +If +.Fl s +is used, the output is formatted as a set of Bourne shell commands. +.Fl h +shows hidden variables (omitted by default). +.El +.Sh STATUS LINE +.Nm +includes an optional status line which is displayed in the bottom line of each +terminal. +.Pp +By default, the status line is enabled and one line in height (it may be +disabled or made multiple lines with the +.Ic status +session option) and contains, from left-to-right: the name of the current +session in square brackets; the window list; the title of the active pane +in double quotes; and the time and date. +.Pp +Each line of the status line is configured with the +.Ic status-format +option. +The default 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 +.Ic status-left , +.Ic status-left-length , +.Ic status-right , +and +.Ic status-right-length +options below), and a central window list. +By default, the window list shows the index, name and (if any) flag of the +windows present in the current session in ascending numerical order. +It may be customised with the +.Ar window-status-format +and +.Ar window-status-current-format +options. +The flag is one of the following symbols appended to the window name: +.Bl -column "Symbol" "Meaning" -offset indent +.It Sy "Symbol" Ta Sy "Meaning" +.It Li "*" Ta "Denotes the current window." +.It Li "-" Ta "Marks the last window (previously selected)." +.It Li "#" Ta "Window activity is monitored and activity has been detected." +.It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window." +.It Li "~" Ta "The window has been silent for the monitor-silence interval." +.It Li "M" Ta "The window contains the marked pane." +.It Li "Z" Ta "The window's active pane is zoomed." +.El +.Pp +The # symbol relates to the +.Ic monitor-activity +window option. +The window name is printed in inverted colours if an alert (bell, activity or +silence) is present. +.Pp +The colour and attributes of the status line may be configured, the entire +status line using the +.Ic status-style +session option and individual windows using the +.Ic window-status-style +window option. +.Pp +The status line is automatically refreshed at interval if it has changed, the +interval may be controlled with the +.Ic status-interval +session option. +.Pp +Commands related to the status line are as follows: +.Bl -tag -width Ds +.Tg clearphist +.It Xo Ic clear-prompt-history +.Op Fl T Ar prompt-type +.Xc +.D1 Pq alias: Ic clearphist +Clear status prompt history for prompt type +.Ar prompt-type . +If +.Fl T +is omitted, then clear history for all types. +See +.Ic command-prompt +for possible values for +.Ar prompt-type . +.It Xo Ic command-prompt +.Op Fl 1bFikN +.Op Fl I Ar inputs +.Op Fl p Ar prompts +.Op Fl t Ar target-client +.Op Fl T Ar prompt-type +.Op Ar template +.Xc +Open the command prompt in a client. +This may be used from inside +.Nm +to execute commands interactively. +.Pp +If +.Ar template +is specified, it is used as the command. +With +.Fl F , +.Ar template +is expanded as a format. +.Pp +If present, +.Fl I +is a comma-separated list of the initial text for each prompt. +If +.Fl p +is given, +.Ar prompts +is a comma-separated list of prompts which are displayed in order; otherwise +a single prompt is displayed, constructed from +.Ar template +if it is present, or +.Ql \&: +if not. +.Pp +Before the command is executed, the first occurrence of the string +.Ql %% +and all occurrences of +.Ql %1 +are replaced by the response to the first prompt, all +.Ql %2 +are replaced with the response to the second prompt, and so on for further +prompts. +Up to nine prompt responses may be replaced +.Po +.Ql %1 +to +.Ql %9 +.Pc . +.Ql %%% +is like +.Ql %% +but any quotation marks are escaped. +.Pp +.Fl 1 +makes the prompt only accept one key press, in this case the resulting input +is a single character. +.Fl k +is like +.Fl 1 +but the key press is translated to a key name. +.Fl N +makes the prompt only accept numeric key presses. +.Fl i +executes the command every time the prompt input changes instead of when the +user exits the command prompt. +.Pp +.Fl T +tells +.Nm +the prompt type. +This affects what completions are offered when +.Em Tab +is pressed. +Available types are: +.Ql command , +.Ql search , +.Ql target +and +.Ql window-target . +.Pp +The following keys have a special meaning in the command prompt, depending +on the value of the +.Ic status-keys +option: +.Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent +.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" +.It Li "Cancel command prompt" Ta "q" Ta "Escape" +.It Li "Delete from cursor to start of word" Ta "" Ta "C-w" +.It Li "Delete entire command" Ta "d" Ta "C-u" +.It Li "Delete from cursor to end" Ta "D" Ta "C-k" +.It Li "Execute command" Ta "Enter" Ta "Enter" +.It Li "Get next command from history" Ta "" Ta "Down" +.It Li "Get previous command from history" Ta "" Ta "Up" +.It Li "Insert top paste buffer" Ta "p" Ta "C-y" +.It Li "Look for completions" Ta "Tab" Ta "Tab" +.It Li "Move cursor left" Ta "h" Ta "Left" +.It Li "Move cursor right" Ta "l" Ta "Right" +.It Li "Move cursor to end" Ta "$" Ta "C-e" +.It Li "Move cursor to next word" Ta "w" Ta "M-f" +.It Li "Move cursor to previous word" Ta "b" Ta "M-b" +.It Li "Move cursor to start" Ta "0" Ta "C-a" +.It Li "Transpose characters" Ta "" Ta "C-t" +.El +.Pp +With +.Fl b , +the prompt is shown in the background and the invoking client does not exit +until it is dismissed. +.Tg confirm +.It Xo Ic confirm-before +.Op Fl b +.Op Fl p Ar prompt +.Op Fl t Ar target-client +.Ar command +.Xc +.D1 Pq alias: Ic confirm +Ask for confirmation before executing +.Ar command . +If +.Fl p +is given, +.Ar prompt +is the prompt to display; otherwise a prompt is constructed from +.Ar command . +It may contain the special character sequences supported by the +.Ic status-left +option. +With +.Fl b , +the prompt is shown in the background and the invoking client does not exit +until it is dismissed. +.Tg menu +.It Xo Ic display-menu +.Op Fl O +.Op Fl c Ar target-client +.Op Fl t Ar target-pane +.Op Fl T Ar title +.Op Fl x Ar position +.Op Fl y Ar position +.Ar name +.Ar key +.Ar command +.Ar ... +.Xc +.D1 Pq alias: Ic menu +Display a menu on +.Ar target-client . +.Ar target-pane +gives the target for any commands run from the menu. +.Pp +A menu is passed as a series of arguments: first the menu item name, +second the key shortcut (or empty for none) and third the command +to run when the menu item is chosen. +The name and command are formats, see the +.Sx FORMATS +and +.Sx STYLES +sections. +If the name begins with a hyphen (-), then the item is disabled (shown dim) and +may not be chosen. +The name may be empty for a separator line, in which case both the key and +command should be omitted. +.Pp +.Fl T +is a format for the menu title (see +.Sx FORMATS ) . +.Pp +.Fl x +and +.Fl y +give the position of the menu. +Both may be a row or column number, or one of the following special values: +.Bl -column "XXXXX" "XXXX" -offset indent +.It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning" +.It Li "C" Ta "Both" Ta "The centre of the terminal" +.It Li "R" Ta Fl x Ta "The right side of the terminal" +.It Li "P" Ta "Both" Ta "The bottom left of the pane" +.It Li "M" Ta "Both" Ta "The mouse position" +.It Li "W" Ta "Both" Ta "The window position on the status line" +.It Li "S" Ta Fl y Ta "The line above or below the status line" +.El +.Pp +Or a format, which is expanded including the following additional variables: +.Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent +.It Sy "Variable name" Ta Sy "Replaced with" +.It Li "popup_centre_x" Ta "Centered in the client" +.It Li "popup_centre_y" Ta "Centered in the client" +.It Li "popup_height" Ta "Height of menu or popup" +.It Li "popup_mouse_bottom" Ta "Bottom of at the mouse" +.It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse" +.It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse" +.It Li "popup_mouse_top" Ta "Top at the mouse" +.It Li "popup_mouse_x" Ta "Mouse X position" +.It Li "popup_mouse_y" Ta "Mouse Y position" +.It Li "popup_pane_bottom" Ta "Bottom of the pane" +.It Li "popup_pane_left" Ta "Left of the pane" +.It Li "popup_pane_right" Ta "Right of the pane" +.It Li "popup_pane_top" Ta "Top of the pane" +.It Li "popup_status_line_y" Ta "Above or below the status line" +.It Li "popup_width" Ta "Width of menu or popup" +.It Li "popup_window_status_line_x" Ta "At the window position in status line" +.It Li "popup_window_status_line_y" Ta "At the status line showing the window" +.El +.Pp +Each menu consists of items followed by a key shortcut shown in brackets. +If the menu is too large to fit on the terminal, it is not displayed. +Pressing the key shortcut chooses the corresponding item. +If the mouse is enabled and the menu is opened from a mouse key binding, +releasing the mouse button with an item selected chooses that item and +releasing the mouse button without an item selected closes the menu. +.Fl O +changes this behaviour so that the menu does not close when the mouse button is +released without an item selected the menu is not closed and a mouse button +must be clicked to choose an item. +.Pp +The following keys are also available: +.Bl -column "Key" "Function" -offset indent +.It Sy "Key" Ta Sy "Function" +.It Li "Enter" Ta "Choose selected item" +.It Li "Up" Ta "Select previous item" +.It Li "Down" Ta "Select next item" +.It Li "q" Ta "Exit menu" +.El +.Tg display +.It Xo Ic display-message +.Op Fl aINpv +.Op Fl c Ar target-client +.Op Fl d Ar delay +.Op Fl t Ar target-pane +.Op Ar message +.Xc +.D1 Pq alias: Ic display +Display a message. +If +.Fl p +is given, the output is printed to stdout, otherwise it is displayed in the +.Ar target-client +status line for up to +.Ar delay +milliseconds. +If +.Ar delay +is not given, the +.Ic display-time +option is used; a delay of zero waits for a key press. +.Ql N +ignores key presses and closes only after the delay expires. +The format of +.Ar message +is described in the +.Sx FORMATS +section; information is taken from +.Ar target-pane +if +.Fl t +is given, otherwise the active pane. +.Pp +.Fl v +prints verbose logging as the format is parsed and +.Fl a +lists the format variables and their values. +.Pp +.Fl I +forwards any input read from stdin to the empty pane given by +.Ar target-pane . +.Tg popup +.It Xo Ic display-popup +.Op Fl BCE +.Op Fl b Ar border-lines +.Op Fl c Ar target-client +.Op Fl d Ar start-directory +.Op Fl e Ar environment +.Op Fl h Ar height +.Op Fl s Ar style +.Op Fl S Ar border-style +.Op Fl t Ar target-pane +.Op Fl T Ar title +.Op Fl w Ar width +.Op Fl x Ar position +.Op Fl y Ar position +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic popup +Display a popup running +.Ar shell-command +on +.Ar target-client . +A popup is a rectangular box drawn over the top of any panes. +Panes are not updated while a popup is present. +.Pp +.Fl E +closes the popup automatically when +.Ar shell-command +exits. +Two +.Fl E +closes the popup only if +.Ar shell-command +exited with success. +.Pp +.Fl x +and +.Fl y +give the position of the popup, they have the same meaning as for the +.Ic display-menu +command. +.Fl w +and +.Fl h +give the width and height - both may be a percentage (followed by +.Ql % ) . +If omitted, half of the terminal size is used. +.Pp +.Fl B +does not surround the popup by a border. +.Pp +.Fl b +sets the type of border line for the popup. +When +.Fl B +is specified, the +.Fl b +option is ignored. +See +.Ic popup-border-lines +for possible values for +.Ar border-lines . +.Pp +.Fl s +sets the style for the popup and +.Fl S +sets the style for the popup border. +For how to specify +.Ar style , +see the +.Sx STYLES +section. +.Pp +.Fl e +takes the form +.Ql VARIABLE=value +and sets an environment variable for the popup; it may be specified multiple +times. +.Pp +.Fl T +is a format for the popup title (see +.Sx FORMATS ) . +.Pp +The +.Fl C +flag closes any popup on the client. +.Tg showphist +.It Xo Ic show-prompt-history +.Op Fl T Ar prompt-type +.Xc +.D1 Pq alias: Ic showphist +Display status prompt history for prompt type +.Ar prompt-type . +If +.Fl T +is omitted, then show history for all types. +See +.Ic command-prompt +for possible values for +.Ar prompt-type . +.El +.Sh BUFFERS +.Nm +maintains a set of named +.Em paste buffers . +Each buffer may be either explicitly or automatically named. +Explicitly named buffers are named when created with the +.Ic set-buffer +or +.Ic load-buffer +commands, or by renaming an automatically named buffer with +.Ic set-buffer +.Fl n . +Automatically named buffers are given a name such as +.Ql buffer0001 , +.Ql buffer0002 +and so on. +When the +.Ic buffer-limit +option is reached, the oldest automatically named buffer is deleted. +Explicitly named buffers are not subject to +.Ic buffer-limit +and may be deleted with the +.Ic delete-buffer +command. +.Pp +Buffers may be added using +.Ic copy-mode +or the +.Ic set-buffer +and +.Ic load-buffer +commands, and pasted into a window using the +.Ic paste-buffer +command. +If a buffer command is used and no buffer is specified, the most +recently added automatically named buffer is assumed. +.Pp +A configurable history buffer is also maintained for each window. +By default, up to 2000 lines are kept; this can be altered with the +.Ic history-limit +option (see the +.Ic set-option +command above). +.Pp +The buffer commands are as follows: +.Bl -tag -width Ds +.It Xo +.Ic choose-buffer +.Op Fl NZr +.Op Fl F Ar format +.Op Fl f Ar filter +.Op Fl K Ar key-format +.Op Fl O Ar sort-order +.Op Fl t Ar target-pane +.Op Ar template +.Xc +Put a pane into buffer mode, where a buffer may be chosen interactively from +a list. +Each buffer is shown on one line. +A shortcut key is shown on the left in brackets allowing for immediate choice, +or the list may be navigated and an item chosen or otherwise manipulated using +the keys below. +.Fl Z +zooms the pane. +The following keys may be used in buffer mode: +.Bl -column "Key" "Function" -offset indent +.It Sy "Key" Ta Sy "Function" +.It Li "Enter" Ta "Paste selected buffer" +.It Li "Up" Ta "Select previous buffer" +.It Li "Down" Ta "Select next buffer" +.It Li "C-s" Ta "Search by name or content" +.It Li "n" Ta "Repeat last search" +.It Li "t" Ta "Toggle if buffer is tagged" +.It Li "T" Ta "Tag no buffers" +.It Li "C-t" Ta "Tag all buffers" +.It Li "p" Ta "Paste selected buffer" +.It Li "P" Ta "Paste tagged buffers" +.It Li "d" Ta "Delete selected buffer" +.It Li "D" Ta "Delete tagged buffers" +.It Li "e" Ta "Open the buffer in an editor" +.It Li "f" Ta "Enter a format to filter items" +.It Li "O" Ta "Change sort field" +.It Li "r" Ta "Reverse sort order" +.It Li "v" Ta "Toggle preview" +.It Li "q" Ta "Exit mode" +.El +.Pp +After a buffer is chosen, +.Ql %% +is replaced by the buffer name in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "paste-buffer -b '%%'" is used. +.Pp +.Fl O +specifies the initial sort field: one of +.Ql time , +.Ql name +or +.Ql size . +.Fl r +reverses the sort order. +.Fl f +specifies an initial filter: the filter is a format - if it evaluates to zero, +the item in the list is not shown, otherwise it is shown. +If a filter would lead to an empty list, it is ignored. +.Fl F +specifies the format for each item in the list and +.Fl K +a format for each shortcut key; both are evaluated once for each line. +.Fl N +starts without the preview. +This command works only if at least one client is attached. +.Tg clearhist +.It Ic clear-history Op Fl t Ar target-pane +.D1 Pq alias: Ic clearhist +Remove and free the history for the specified pane. +.Tg deleteb +.It Ic delete-buffer Op Fl b Ar buffer-name +.D1 Pq alias: Ic deleteb +Delete the buffer named +.Ar buffer-name , +or the most recently added automatically named buffer if not specified. +.Tg lsb +.It Xo Ic list-buffers +.Op Fl F Ar format +.Op Fl f Ar filter +.Xc +.D1 Pq alias: Ic lsb +List the global buffers. +.Fl F +specifies the format of each line and +.Fl f +a filter. +Only buffers for which the filter is true are shown. +See the +.Sx FORMATS +section. +.It Xo Ic load-buffer +.Op Fl w +.Op Fl b Ar buffer-name +.Op Fl t Ar target-client +.Ar path +.Xc +.Tg loadb +.D1 Pq alias: Ic loadb +Load the contents of the specified paste buffer from +.Ar path . +If +.Fl w +is given, the buffer is also sent to the clipboard for +.Ar target-client +using the +.Xr xterm 1 +escape sequence, if possible. +.Tg pasteb +.It Xo Ic paste-buffer +.Op Fl dpr +.Op Fl b Ar buffer-name +.Op Fl s Ar separator +.Op Fl t Ar target-pane +.Xc +.D1 Pq alias: Ic pasteb +Insert the contents of a paste buffer into the specified pane. +If not specified, paste into the current one. +With +.Fl d , +also delete the paste buffer. +When output, any linefeed (LF) characters in the paste buffer are replaced with +a separator, by default carriage return (CR). +A custom separator may be specified using the +.Fl s +flag. +The +.Fl r +flag means to do no replacement (equivalent to a separator of LF). +If +.Fl p +is specified, paste bracket control codes are inserted around the +buffer if the application has requested bracketed paste mode. +.Tg saveb +.It Xo Ic save-buffer +.Op Fl a +.Op Fl b Ar buffer-name +.Ar path +.Xc +.D1 Pq alias: Ic saveb +Save the contents of the specified paste buffer to +.Ar path . +The +.Fl a +option appends to rather than overwriting the file. +.It Xo Ic set-buffer +.Op Fl aw +.Op Fl b Ar buffer-name +.Op Fl t Ar target-client +.Tg setb +.Op Fl n Ar new-buffer-name +.Ar data +.Xc +.D1 Pq alias: Ic setb +Set the contents of the specified buffer to +.Ar data . +If +.Fl w +is given, the buffer is also sent to the clipboard for +.Ar target-client +using the +.Xr xterm 1 +escape sequence, if possible. +The +.Fl a +option appends to rather than overwriting the buffer. +The +.Fl n +option renames the buffer to +.Ar new-buffer-name . +.Tg showb +.It Xo Ic show-buffer +.Op Fl b Ar buffer-name +.Xc +.D1 Pq alias: Ic showb +Display the contents of the specified buffer. +.El +.Sh MISCELLANEOUS +Miscellaneous commands are as follows: +.Bl -tag -width Ds +.It Ic clock-mode Op Fl t Ar target-pane +Display a large clock. +.Tg if +.It Xo Ic if-shell +.Op Fl bF +.Op Fl t Ar target-pane +.Ar shell-command command +.Op Ar command +.Xc +.D1 Pq alias: Ic if +Execute the first +.Ar command +if +.Ar shell-command +(run with +.Pa /bin/sh ) +returns success or the second +.Ar command +otherwise. +Before being executed, +.Ar shell-command +is expanded using the rules specified in the +.Sx FORMATS +section, including those relevant to +.Ar target-pane . +With +.Fl b , +.Ar shell-command +is run in the background. +.Pp +If +.Fl F +is given, +.Ar shell-command +is not executed but considered success if neither empty nor zero (after formats +are expanded). +.Tg lock +.It Ic lock-server +.D1 Pq alias: Ic lock +Lock each client individually by running the command specified by the +.Ic lock-command +option. +.Tg run +.It Xo Ic run-shell +.Op Fl bC +.Op Fl d Ar delay +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 Pq alias: Ic run +Execute +.Ar shell-command +using +.Pa /bin/sh +or (with +.Fl C ) +a +.Nm +command in the background without creating a window. +Before being executed, +.Ar shell-command +is expanded using the rules specified in the +.Sx FORMATS +section. +With +.Fl b , +the command is run in the background. +.Fl d +waits for +.Ar delay +seconds before starting the command. +If +.Fl C +is not given, any output to stdout is displayed in view mode (in the pane +specified by +.Fl t +or the current pane if omitted) after the command finishes. +If the command fails, the exit status is also displayed. +.Tg wait +.It Xo Ic wait-for +.Op Fl L | S | U +.Ar channel +.Xc +.D1 Pq alias: Ic wait +When used without options, prevents the client from exiting until woken using +.Ic wait-for +.Fl S +with the same channel. +When +.Fl L +is used, the channel is locked and any clients that try to lock the same +channel are made to wait until the channel is unlocked with +.Ic wait-for +.Fl U . +.El +.Sh EXIT MESSAGES +When a +.Nm +client detaches, it prints a message. +This may be one of: +.Bl -tag -width Ds +.It detached (from session ...) +The client was detached normally. +.It detached and SIGHUP +The client was detached and its parent sent the +.Dv SIGHUP +signal (for example with +.Ic detach-client +.Fl P ) . +.It lost tty +The client's +.Xr tty 4 +or +.Xr pty 4 +was unexpectedly destroyed. +.It terminated +The client was killed with +.Dv SIGTERM . +.It too far behind +The client is in control mode and became unable to keep up with the data from +.Nm . +.It exited +The server exited when it had no sessions. +.It server exited +The server exited when it received +.Dv SIGTERM . +.It server exited unexpectedly +The server crashed or otherwise exited without telling the client the reason. +.El +.Sh TERMINFO EXTENSIONS +.Nm +understands some unofficial extensions to +.Xr terminfo 5 . +It is not normally necessary to set these manually, instead the +.Ic terminal-features +option should be used. +.Bl -tag -width Ds +.It Em \&AX +An existing extension that tells +.Nm +the terminal supports default colours. +.It Em \&Bidi +Tell +.Nm +that the terminal supports the VTE bidirectional text extensions. +.It Em \&Cs , Cr +Set the cursor colour. +The first takes a single string argument and is used to set the colour; +the second takes no arguments and restores the default cursor colour. +If set, a sequence such as this may be used +to change the cursor colour from inside +.Nm : +.Bd -literal -offset indent +$ printf '\e033]12;red\e033\e\e' +.Ed +.Pp +The colour is an +.Xr X 7 +colour, see +.Xr XParseColor 3 . +.It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg +Set, clear, disable or enable DECSLRM margins. +These are set automatically if the terminal reports it is +.Em VT420 +compatible. +.It Em \&Dsbp , \&Enbp +Disable and enable bracketed paste. +These are set automatically if the +.Em XT +capability is present. +.It Em \&Dseks , \&Eneks +Disable and enable extended keys. +.It Em \&Dsfcs , \&Enfcs +Disable and enable focus reporting. +These are set automatically if the +.Em XT +capability is present. +.It Em \&Rect +Tell +.Nm +that the terminal supports rectangle operations. +.It Em \&Smol +Enable the overline attribute. +.It Em \&Smulx +Set a styled underscore. +The single parameter is one of: 0 for no underscore, 1 for normal +underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted +underscore and 5 for dashed underscore. +.It Em \&Setulc , \&ol +Set the underscore colour or reset to the default. +The argument is (red * 65536) + (green * 256) + blue where each is between 0 +and 255. +.It Em \&Ss , Se +Set or reset the cursor style. +If set, a sequence such as this may be used +to change the cursor to an underline: +.Bd -literal -offset indent +$ printf '\e033[4 q' +.Ed +.Pp +If +.Em Se +is not set, \&Ss with argument 0 will be used to reset the cursor style instead. +.It Em \&Swd +Set the opening sequence for the working directory notification. +The sequence is terminated using the standard +.Em fsl +capability. +.It Em \&Sync +Start (parameter is 1) or end (parameter is 2) a synchronized update. +.It Em \&Tc +Indicate that the terminal supports the +.Ql direct colour +RGB escape sequence (for example, \ee[38;2;255;255;255m). +.Pp +If supported, this is used for the initialize colour escape sequence (which +may be enabled by adding the +.Ql initc +and +.Ql ccc +capabilities to the +.Nm +.Xr terminfo 5 +entry). +.Pp +This is equivalent to the +.Em RGB +.Xr terminfo 5 +capability. +.It Em \&Ms +Store the current buffer in the host terminal's selection (clipboard). +See the +.Em set-clipboard +option above and the +.Xr xterm 1 +man page. +.It Em \&XT +This is an existing extension capability that tmux uses to mean that the +terminal supports the +.Xr xterm 1 +title set sequences and to automatically set some of the capabilities above. +.El +.Sh CONTROL MODE +.Nm +offers a textual interface called +.Em control mode . +This allows applications to communicate with +.Nm +using a simple text-only protocol. +.Pp +In control mode, a client sends +.Nm +commands or command sequences terminated by newlines on standard input. +Each command will produce one block of output on standard output. +An output block consists of a +.Em %begin +line followed by the output (which may be empty). +The output block ends with a +.Em %end +or +.Em %error . +.Em %begin +and matching +.Em %end +or +.Em %error +have three arguments: an integer time (as seconds from epoch), command number and +flags (currently not used). +For example: +.Bd -literal -offset indent +%begin 1363006971 2 1 +0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) +%end 1363006971 2 1 +.Ed +.Pp +The +.Ic refresh-client +.Fl C +command may be used to set the size of a client in control mode. +.Pp +In control mode, +.Nm +outputs notifications. +A notification will never occur inside an output block. +.Pp +The following notifications are defined: +.Bl -tag -width Ds +.It Ic %client-detached Ar client +The client has detached. +.It Ic %client-session-changed Ar client session-id name +The client is now attached to the session with ID +.Ar session-id , +which is named +.Ar name . +.It Ic %continue Ar pane-id +The pane has been continued after being paused (if the +.Ar pause-after +flag is set, see +.Ic refresh-client +.Fl A ) . +.It Ic %exit Op Ar reason +The +.Nm +client is exiting immediately, either because it is not attached to any session +or an error occurred. +If present, +.Ar reason +describes why the client exited. +.It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value +New form of +.Ic %output +sent when the +.Ar pause-after +flag is set. +.Ar age +is the time in milliseconds for which tmux had buffered the output before it was sent. +Any subsequent arguments up until a single +.Ql \&: +are for future use and should be ignored. +.It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags +The layout of a window with ID +.Ar window-id +changed. +The new layout is +.Ar window-layout . +The window's visible layout is +.Ar window-visible-layout +and the window flags are +.Ar window-flags . +.It Ic %output Ar pane-id Ar value +A window pane produced output. +.Ar value +escapes non-printable characters and backslash as octal \\xxx. +.It Ic %pane-mode-changed Ar pane-id +The pane with ID +.Ar pane-id +has changed mode. +.It Ic %pause Ar pane-id +The pane has been paused (if the +.Ar pause-after +flag is set). +.It Ic %session-changed Ar session-id Ar name +The client is now attached to the session with ID +.Ar session-id , +which is named +.Ar name . +.It Ic %session-renamed Ar name +The current session was renamed to +.Ar name . +.It Ic %session-window-changed Ar session-id Ar window-id +The session with ID +.Ar session-id +changed its active window to the window with ID +.Ar window-id . +.It Ic %sessions-changed +A session was created or destroyed. +.It Xo Ic %subscription-changed +.Ar name +.Ar session-id +.Ar window-id +.Ar window-index +.Ar pane-id ... \& : +.Ar value +.Xc +The value of the format associated with subscription +.Ar name +has changed to +.Ar value . +See +.Ic refresh-client +.Fl B . +Any arguments after +.Ar pane-id +up until a single +.Ql \&: +are for future use and should be ignored. +.It Ic %unlinked-window-add Ar window-id +The window with ID +.Ar window-id +was created but is not linked to the current session. +.It Ic %unlinked-window-close Ar window-id +The window with ID +.Ar window-id , +which is not linked to the current session, was closed. +.It Ic %unlinked-window-renamed Ar window-id +The window with ID +.Ar window-id , +which is not linked to the current session, was renamed. +.It Ic %window-add Ar window-id +The window with ID +.Ar window-id +was linked to the current session. +.It Ic %window-close Ar window-id +The window with ID +.Ar window-id +closed. +.It Ic %window-pane-changed Ar window-id Ar pane-id +The active pane in the window with ID +.Ar window-id +changed to the pane with ID +.Ar pane-id . +.It Ic %window-renamed Ar window-id Ar name +The window with ID +.Ar window-id +was renamed to +.Ar name . +.El +.Sh ENVIRONMENT +When +.Nm +is started, it inspects the following environment variables: +.Bl -tag -width LC_CTYPE +.It Ev EDITOR +If the command specified in this variable contains the string +.Ql vi +and +.Ev VISUAL +is unset, use vi-style key bindings. +Overridden by the +.Ic mode-keys +and +.Ic status-keys +options. +.It Ev HOME +The user's login directory. +If unset, the +.Xr passwd 5 +database is consulted. +.It Ev LC_CTYPE +The character encoding +.Xr locale 1 . +It is used for two separate purposes. +For output to the terminal, UTF-8 is used if the +.Fl u +option is given or if +.Ev LC_CTYPE +contains +.Qq UTF-8 +or +.Qq UTF8 . +Otherwise, only ASCII characters are written and non-ASCII characters +are replaced with underscores +.Pq Ql _ . +For input, +.Nm +always runs with a UTF-8 locale. +If en_US.UTF-8 is provided by the operating system, it is used and +.Ev LC_CTYPE +is ignored for input. +Otherwise, +.Ev LC_CTYPE +tells +.Nm +what the UTF-8 locale is called on the current system. +If the locale specified by +.Ev LC_CTYPE +is not available or is not a UTF-8 locale, +.Nm +exits with an error message. +.It Ev LC_TIME +The date and time format +.Xr locale 1 . +It is used for locale-dependent +.Xr strftime 3 +format specifiers. +.It Ev PWD +The current working directory to be set in the global environment. +This may be useful if it contains symbolic links. +If the value of the variable does not match the current working +directory, the variable is ignored and the result of +.Xr getcwd 3 +is used instead. +.It Ev SHELL +The absolute path to the default shell for new windows. +See the +.Ic default-shell +option for details. +.It Ev TMUX_TMPDIR +The parent directory of the directory containing the server sockets. +See the +.Fl L +option for details. +.It Ev VISUAL +If the command specified in this variable contains the string +.Ql vi , +use vi-style key bindings. +Overridden by the +.Ic mode-keys +and +.Ic status-keys +options. +.El +.Sh FILES +.Bl -tag -width "@SYSCONFDIR@/tmux.confXXX" -compact +.It Pa ~/.tmux.conf +.It Pa $XDG_CONFIG_HOME/tmux/tmux.conf +.It Pa ~/.config/tmux/tmux.conf +Default +.Nm +configuration file. +.It Pa @SYSCONFDIR@/tmux.conf +System-wide configuration file. +.El +.Sh EXAMPLES +To create a new +.Nm +session running +.Xr vi 1 : +.Pp +.Dl $ tmux new-session vi +.Pp +Most commands have a shorter form, known as an alias. +For new-session, this is +.Ic new : +.Pp +.Dl $ tmux new vi +.Pp +Alternatively, the shortest unambiguous form of a command is accepted. +If there are several options, they are listed: +.Bd -literal -offset indent +$ tmux n +ambiguous command: n, could be: new-session, new-window, next-window +.Ed +.Pp +Within an active session, a new window may be created by typing +.Ql C-b c +(Ctrl +followed by the +.Ql b +key +followed by the +.Ql c +key). +.Pp +Windows may be navigated with: +.Ql C-b 0 +(to select window 0), +.Ql C-b 1 +(to select window 1), and so on; +.Ql C-b n +to select the next window; and +.Ql C-b p +to select the previous window. +.Pp +A session may be detached using +.Ql C-b d +(or by an external event such as +.Xr ssh 1 +disconnection) and reattached with: +.Pp +.Dl $ tmux attach-session +.Pp +Typing +.Ql C-b \&? +lists the current key bindings in the current window; up and down may be used +to navigate the list or +.Ql q +to exit from it. +.Pp +Commands to be run when the +.Nm +server is started may be placed in the +.Pa ~/.tmux.conf +configuration file. +Common examples include: +.Pp +Changing the default prefix key: +.Bd -literal -offset indent +set-option -g prefix C-a +unbind-key C-b +bind-key C-a send-prefix +.Ed +.Pp +Turning the status line off, or changing its colour: +.Bd -literal -offset indent +set-option -g status off +set-option -g status-style bg=blue +.Ed +.Pp +Setting other options, such as the default command, +or locking after 30 minutes of inactivity: +.Bd -literal -offset indent +set-option -g default-command "exec /bin/ksh" +set-option -g lock-after-time 1800 +.Ed +.Pp +Creating new key bindings: +.Bd -literal -offset indent +bind-key b set-option status +bind-key / command-prompt "split-window 'exec man %%'" +bind-key S command-prompt "new-window -n %1 'ssh %1'" +.Ed +.Sh SEE ALSO +.Xr pty 4 +.Sh AUTHORS +.An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com |