3 .\" Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER
14 .\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
15 .\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22 .Nd terminal multiplexer
27 .Op Fl c Ar shell-command
29 .Op Fl L Ar socket-name
30 .Op Fl S Ar socket-path
32 .Op Ar command Op Ar flags
36 is a terminal multiplexer:
37 it enables a number of terminals to be created, accessed, and
38 controlled from a single screen.
40 may be detached from a screen
41 and continue running in the background,
42 then later reattached.
46 is started, it creates a new
50 and displays it on screen.
51 A status line at the bottom of the screen
52 shows information on the current session
53 and is used to enter interactive commands.
55 A session is a single collection of
57 under the management of
59 Each session has one or more
61 A window occupies the entire screen
62 and may be split into rectangular panes,
63 each of which is a separate pseudo terminal
66 manual page documents the technical details of pseudo terminals).
69 instances may connect to the same session,
70 and any number of windows may be present in the same session.
71 Once all sessions are killed,
75 Each session is persistent and will survive accidental disconnection
78 connection timeout) or intentional detaching (with the
82 may be reattached using:
88 a session is displayed on screen by a
90 and all sessions are managed by a single
92 The server and each client are separate processes which communicate through a
96 The options are as follows:
97 .Bl -tag -width "XXXXXXXXXXXX"
101 to assume the terminal supports 256 colours.
102 This is equivalent to
105 Start in control mode (see the
111 .It Fl c Ar shell-command
114 using the default shell.
117 server will be started to retrieve the
120 This option is for compatibility with
124 is used as a login shell.
135 may not be specified.
137 Specify an alternative configuration file.
140 loads the system configuration file from
141 .Pa @SYSCONFDIR@/tmux.conf ,
142 if present, then looks for a user configuration file at
145 .Pa $XDG_CONFIG_HOME/tmux/tmux.conf .
147 The configuration file is a set of
149 commands which are executed in sequence when the server is first started.
151 loads configuration files once when the server process has started.
154 command may be used to load a file later.
157 shows any error messages from commands in configuration files in the first
158 session created, and continues to process the rest of the configuration file.
159 .It Fl L Ar socket-name
161 stores the server socket in a directory under
166 The default socket is named
168 This option allows a different socket name to be specified, allowing several
174 a full path is not necessary: the sockets are all created in a directory
176 under the directory given by
182 directory is created by
184 and must not be world readable, writable or executable.
186 If the socket is accidentally removed, the
188 signal may be sent to the
190 server process to recreate it (note that this will fail if any parent
191 directories are missing).
193 Behave as a login shell.
194 This flag currently has no effect and is for compatibility with other shells
195 when using tmux as a login shell.
197 Do not start the server even if the command would normally do so (for example
201 .It Fl S Ar socket-path
202 Specify a full alternative path to the server socket.
205 is specified, the default socket directory is not used and any
209 Set terminal features for the client.
210 This is a comma-separated list of features.
212 .Ic terminal-features
215 Write UTF-8 output to the terminal even if the first environment
221 that is set does not contain
230 Request verbose logging.
231 Log messages will be saved into
232 .Pa tmux-client-PID.log
234 .Pa tmux-server-PID.log
235 files in the current directory, where
237 is the PID of the server or client process.
240 is specified twice, an additional
242 file is generated with a copy of everything
244 writes to the terminal.
248 signal may be sent to the
250 server process to toggle logging between on (as if
253 .It Ar command Op Ar flags
254 This specifies one of a set of commands used to control
256 as described in the following sections.
257 If no commands are specified, the
261 .Sh DEFAULT KEY BINDINGS
263 may be controlled from an attached client by using a key combination of a
266 (Ctrl-b) by default, followed by a command key.
268 The default command key bindings are:
270 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
272 Send the prefix key (C-b) through to the application.
274 Rotate the panes in the current window forwards.
280 Break the current pane out of the window.
283 Split the current pane into two, top and bottom.
285 List all paste buffers.
287 Rename the current session.
289 Split the current pane into two, left and right.
291 Kill the current window.
293 Prompt for a window index to select.
295 Switch the attached client to the previous session.
297 Switch the attached client to the next session.
299 Rename the current window.
301 Delete the most recently copied buffer of text.
303 Prompt for an index to move the current window.
305 Select windows 0 to 9.
311 Move to the previously active pane.
313 Choose which buffer to paste interactively from a list.
315 List all key bindings.
317 Choose a client to detach.
319 Switch the attached client back to the last session.
321 Enter copy mode to copy text or view the history.
323 Paste the most recently copied buffer of text.
327 Detach the current client.
329 Prompt to search for text in open windows.
331 Display some information about the current window.
333 Move to the previously selected window.
335 Mark the current pane (see
339 Clear the marked pane.
341 Change to the next window.
343 Select the next pane in the current window.
345 Change to the previous window.
347 Briefly display pane indexes.
349 Force redraw of the attached client.
351 Select a new session for the attached client interactively.
355 Choose the current window interactively.
357 Kill the current pane.
359 Toggle zoom state of the current pane.
361 Swap the current pane with the previous pane.
363 Swap the current pane with the next pane.
365 Show previous messages from
369 Enter copy mode and scroll one page up.
372 Change to the pane above, below, to the left, or to the right of the current
375 Arrange panes in one of the five preset layouts: even-horizontal,
376 even-vertical, main-horizontal, main-vertical, or tiled.
378 Arrange the current window in the next preset layout.
380 Move to the next window with a bell or activity marker.
382 Rotate the panes in the current window backwards.
384 Move to the previous window with a bell or activity marker.
387 Resize the current pane in steps of one cell.
390 Resize the current pane in steps of five cells.
393 Key bindings may be changed with the
398 .Sh COMMAND PARSING AND EXECUTION
400 supports a large number of commands which can be used to control its
402 Each command is named and can accept zero or more flags and arguments.
403 They may be bound to a key with the
405 command or run from the shell prompt, a shell script, a configuration file or
407 For example, the same
409 command run from the shell prompt, from
411 and bound to a key may look like:
412 .Bd -literal -offset indent
413 $ tmux set-option -g status-style bg=cyan
415 set-option -g status-style bg=cyan
417 bind-key C set-option -g status-style bg=cyan
420 Here, the command name is
430 distinguishes between command parsing and execution.
431 In order to execute a command,
433 needs it to be split up into its name and arguments.
434 This is command parsing.
435 If a command is run from the shell, the shell parses it; from inside
437 or from a configuration file,
443 .Bl -dash -offset indent
445 in a configuration file;
447 typed at the command prompt (see
448 .Ic command-prompt ) ;
453 passed as arguments to
459 To execute commands, each client has a
461 A global command queue not attached to any client is used on startup
462 for configuration files like
463 .Pa \[ti]/.tmux.conf .
464 Parsed commands added to the queue are executed in order.
469 parse their argument to create a new command which is inserted immediately
471 This means that arguments can be parsed twice or more - once when the parent
474 is parsed and again when it parses and executes its command.
480 stop execution of subsequent commands on the queue until something happens -
484 until a shell command finishes and
486 until a key is pressed.
487 For example, the following commands:
488 .Bd -literal -offset indent
489 new-session; new-window
490 if-shell "true" "split-window"
509 commands and their arguments.
511 This section describes the syntax of commands parsed by
513 for example in a configuration file or at the command prompt.
514 Note that when commands are entered into the shell, they are parsed by the shell
520 Each command is terminated by a newline or a semicolon (;).
521 Commands separated by semicolons together form a
523 - if a command in the sequence encounters an error, no subsequent commands are
526 It is recommended that a semicolon used as a command separator should be
527 written as an individual token, for example from
529 .Bd -literal -offset indent
530 $ tmux neww \\; splitw
534 .Bd -literal -offset indent
535 $ tmux neww \[aq];\[aq] splitw
538 Or from the tmux command prompt:
539 .Bd -literal -offset indent
543 However, a trailing semicolon is also interpreted as a command separator,
547 .Bd -literal -offset indent
548 $ tmux neww\e; splitw
552 .Bd -literal -offset indent
553 $ tmux \[aq]neww;\[aq] splitw
556 As in these examples, when running tmux from the shell extra care must be taken
557 to properly quote semicolons:
560 Semicolons that should be interpreted as a command separator
561 should be escaped according to the shell conventions.
564 this typically means quoted (such as
565 .Ql neww \[aq];\[aq] splitw )
567 .Ql neww \e\e\e\e; splitw ) .
569 Individual semicolons or trailing semicolons that should be interpreted as
570 arguments should be escaped twice: once according to the shell conventions and
574 .Bd -literal -offset indent
575 $ tmux neww \[aq]foo\e\e;\[aq] bar
576 $ tmux neww foo\e\e\e\e; bar
579 Semicolons that are not individual tokens or trailing another token should only
580 be escaped once according to shell conventions; for example:
581 .Bd -literal -offset indent
582 $ tmux neww \[aq]foo-;-bar\[aq]
583 $ tmux neww foo-\e\e;-bar
587 Comments are marked by the unquoted # character - any remaining text after a
588 comment is ignored until the end of the line.
590 If the last character of a line is \e, the line is joined with the following
591 line (the \e and the newline are completely removed).
592 This is called line continuation and applies both inside and outside quoted
593 strings and in comments, but not inside braces.
595 Command arguments may be specified as strings surrounded by single (\[aq])
596 quotes, double quotes (\[dq]) or braces ({}).
598 This is required when the argument contains any special character.
599 Single and double quoted strings cannot span multiple lines except with line
601 Braces can span multiple lines.
603 Outside of quotes and inside double quotes, these replacements are performed:
604 .Bl -dash -offset indent
606 Environment variables preceded by $ are replaced with their value from the
607 global environment (see the
608 .Sx GLOBAL AND SESSION ENVIRONMENT
611 A leading \[ti] or \[ti]user is expanded to the home directory of the current or
614 \euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to
615 the given four or eight digit hexadecimal number.
617 When preceded (escaped) by a \e, the following characters are replaced: \ee by
618 the escape character; \er by a carriage return; \en by a newline; and \et by a
621 \eooo is replaced by a character of the octal value ooo.
622 Three octal digits are required, for example \e001.
623 The largest valid character is \e377.
625 Any other characters preceded by \e are replaced by themselves (that is, the \e
626 is removed) and are not treated as having any special meaning - so for example
627 \e; will not mark a command sequence and \e$ will not expand an environment
631 Braces are parsed as a configuration file (so conditions such as
633 are processed) and then converted into a string.
634 They are designed to avoid the need for additional escaping when passing a
637 commands as an argument (for example to
639 These two examples produce an identical command - note that no escaping is
640 needed when using {}:
641 .Bd -literal -offset indent
643 display -p \[aq]brace-dollar-foo: }$foo\[aq]
646 if-shell true "display -p \[aq]brace-dollar-foo: }\e$foo\[aq]"
649 Braces may be enclosed inside braces, for example:
650 .Bd -literal -offset indent
651 bind x if-shell "true" {
658 Environment variables may be set by using the syntax
661 .Ql HOME=/home/user .
662 Variables set during parsing are added to the global environment.
663 A hidden variable may be set with
666 .Bd -literal -offset indent
670 Hidden variables are not passed to the environment of processes created
673 .Sx GLOBAL AND SESSION ENVIRONMENT
676 Commands may be parsed conditionally by surrounding them with
686 is expanded as a format (see
688 and if it evaluates to false (zero or empty), subsequent text is ignored until
695 .Bd -literal -offset indent
696 %if "#{==:#{host},myhost}"
697 set -g status-style bg=red
698 %elif "#{==:#{host},myotherhost}"
699 set -g status-style bg=green
701 set -g status-style bg=blue
705 Will change the status line to red if running on
709 or blue if running on another host.
710 Conditionals may be given on one line, for example:
711 .Bd -literal -offset indent
712 %if #{==:#{host},myhost} set -g status-style bg=red %endif
715 This section describes the commands supported by
717 Most commands accept the optional
727 These specify the client, session, window or pane which a command should affect.
730 should be the name of the client,
733 file to which the client is connected, for example either of
737 for the client attached to
739 If no client is specified,
741 attempts to work out the client currently in use; if that fails, an error is
743 Clients may be listed with the
748 is tried as, in order:
751 A session ID prefixed with a $.
753 An exact name of a session (as listed by the
757 The start of a session name, for example
759 would match a session named
764 pattern which is matched against the session name.
767 If the session name is prefixed with an
769 only an exact match is accepted (so
771 will only match exactly
776 If a single session is found, it is used as the target session; multiple matches
778 If a session is omitted, the current session is used if available; if no
779 current session is available, the most recently used is chosen.
786 specifies a window in the form
787 .Em session Ns \&: Ns Em window .
789 follows the same rules as for
793 is looked for in order as:
796 A special token, listed below.
798 A window index, for example
800 is window 1 in session
803 A window ID, such as @1.
805 An exact window name, such as
806 .Ql mysession:mywindow .
808 The start of a window name, such as
809 .Ql mysession:mywin .
813 pattern matched against the window name.
818 prefix will do an exact match only.
819 An empty window name specifies the next unused index if appropriate (for
825 otherwise the current window in
829 The following special tokens are available to indicate particular windows.
830 Each has a single-character alternative form.
831 .Bl -column "XXXXXXXXXX" "X"
832 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
833 .It Li "{start}" Ta "^" Ta "The lowest-numbered window"
834 .It Li "{end}" Ta "$" Ta "The highest-numbered window"
835 .It Li "{last}" Ta "!" Ta "The last (previously current) window"
836 .It Li "{next}" Ta "+" Ta "The next window by number"
837 .It Li "{previous}" Ta "-" Ta "The previous window by number"
845 may be a pane ID or takes a similar form to
847 but with the optional addition of a period followed by a pane index or pane ID,
849 .Ql mysession:mywindow.1 .
850 If the pane index is omitted, the currently active pane in the specified
852 The following special tokens are available for the pane index:
853 .Bl -column "XXXXXXXXXXXXXX" "X"
854 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
855 .It Li "{last}" Ta "!" Ta "The last (previously active) pane"
856 .It Li "{next}" Ta "+" Ta "The next pane by number"
857 .It Li "{previous}" Ta "-" Ta "The previous pane by number"
858 .It Li "{top}" Ta "" Ta "The top pane"
859 .It Li "{bottom}" Ta "" Ta "The bottom pane"
860 .It Li "{left}" Ta "" Ta "The leftmost pane"
861 .It Li "{right}" Ta "" Ta "The rightmost pane"
862 .It Li "{top-left}" Ta "" Ta "The top-left pane"
863 .It Li "{top-right}" Ta "" Ta "The top-right pane"
864 .It Li "{bottom-left}" Ta "" Ta "The bottom-left pane"
865 .It Li "{bottom-right}" Ta "" Ta "The bottom-right pane"
866 .It Li "{up-of}" Ta "" Ta "The pane above the active pane"
867 .It Li "{down-of}" Ta "" Ta "The pane below the active pane"
868 .It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane"
869 .It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane"
876 may be followed by an offset, for example:
877 .Bd -literal -offset indent
886 may consist entirely of the token
890 to specify the session, window or pane where the most recent mouse event
898 to specify the marked pane (see
902 Sessions, window and panes are each numbered with a unique ID; session IDs are
909 These are unique and are unchanged for the life of the session, window or pane
913 The pane ID is passed to the child process of the pane in the
915 environment variable.
916 IDs may be displayed using the
924 .Ic display-message ,
935 This may be a single argument passed to the shell, for example:
936 .Bd -literal -offset indent
937 new-window \[aq]vi \[ti]/.tmux.conf\[aq]
941 .Bd -literal -offset indent
942 /bin/sh -c \[aq]vi \[ti]/.tmux.conf\[aq]
954 to be given as multiple arguments and executed directly (without
956 This can avoid issues with shell quoting.
958 .Bd -literal -offset indent
959 $ tmux new-window vi \[ti]/.tmux.conf
964 directly without invoking the shell.
970 command, either passed with the command and arguments separately, for example:
971 .Bd -literal -offset indent
972 bind-key F1 set-option status off
975 Or passed as a single string argument in
978 .Bd -literal -offset indent
979 bind-key F1 { set-option status off }
985 .Bd -literal -offset indent
986 refresh-client -t/dev/ttyp2
988 rename-session -tfirst newname
990 set-option -wt:0 monitor-activity on
992 new-window ; split-window -d
994 bind-key R source-file \[ti]/.tmux.conf \e; \e
995 display-message "source-file done"
1000 .Bd -literal -offset indent
1001 $ tmux kill-window -t :1
1003 $ tmux new-window \e; split-window -d
1005 $ tmux new-session -d \[aq]vi \[ti]/.tmux.conf\[aq] \e; split-window -d \e; attach
1007 .Sh CLIENTS AND SESSIONS
1010 server manages clients, sessions, windows and panes.
1011 Clients are attached to sessions to interact with them, either
1012 when they are created with the
1014 command, or later with the
1017 Each session has one or more windows
1020 Windows may be linked to multiple sessions and are made up of one or
1022 each of which contains a pseudo terminal.
1023 Commands for creating, linking and otherwise manipulating windows
1026 .Sx WINDOWS AND PANES
1029 The following commands are available to manage clients and sessions:
1032 .It Xo Ic attach-session
1034 .Op Fl c Ar working-directory
1036 .Op Fl t Ar target-session
1038 .D1 Pq alias: Ic attach
1043 in the current terminal.
1045 must already exist - to create a new session, see the
1049 to create or attach).
1050 If used from inside, switch the currently attached session to
1051 .Ar target-session .
1054 is specified, any other clients attached to the session are detached.
1059 to the parent process of the client as well as
1060 detaching the client, typically causing it to exit.
1062 sets a comma-separated list of client flags.
1066 the client has an independent active pane
1068 the client does not affect the size of other clients
1070 the client does not receive pane output in control mode
1071 .It pause-after=seconds
1072 output is paused once the pane is
1074 behind in control mode
1076 the client is read-only
1078 wait for an empty line input before exiting in control mode
1083 turns a flag off if the client is already attached.
1087 .Ar read-only,ignore-size .
1088 When a client is read-only, only keys bound to the
1092 commands have any effect.
1095 flag allows the active pane to be selected independently of the window's active
1096 pane used by clients without the flag.
1097 This only affects the cursor position and commands issued from the client;
1098 other features such as hooks and styles continue to use the window's active
1101 If no server is started,
1103 will attempt to start it; this will fail unless sessions are created in the
1110 are slightly adjusted: if
1112 needs to select the most recently used session, it will prefer the most
1118 will set the session working directory (used for new windows) to
1119 .Ar working-directory .
1124 .Ic update-environment
1125 option will not be applied.
1127 .It Xo Ic detach-client
1129 .Op Fl E Ar shell-command
1130 .Op Fl s Ar target-session
1131 .Op Fl t Ar target-client
1133 .D1 Pq alias: Ic detach
1134 Detach the current client if bound to a key, the client specified with
1136 or all clients currently attached to the session specified by
1140 option kills all but the client given with
1146 to the parent process of the client, typically causing it
1152 to replace the client.
1154 .It Ic has-session Op Fl t Ar target-session
1155 .D1 Pq alias: Ic has
1156 Report an error and exit with 1 if the specified session does not exist.
1157 If it does exist, exit with 0.
1161 server and clients and destroy all sessions.
1162 .It Xo Ic kill-session
1164 .Op Fl t Ar target-session
1166 Destroy the given session, closing any windows linked to it and no other
1167 sessions, and detaching all clients attached to it.
1170 is given, all sessions but the specified one is killed.
1173 flag clears alerts (bell, activity, or silence) in all windows linked to the
1176 .It Xo Ic list-clients
1179 .Op Fl t Ar target-session
1181 .D1 Pq alias: Ic lsc
1182 List all clients attached to the server.
1184 specifies the format of each line and
1187 Only clients for which the filter is true are shown.
1193 is specified, list only clients connected to that session.
1195 .It Xo Ic list-commands
1199 .D1 Pq alias: Ic lscm
1202 or - if omitted - of all commands supported by
1205 .It Xo Ic list-sessions
1210 List all sessions managed by the server.
1212 specifies the format of each line and
1215 Only sessions for which the filter is true are shown.
1220 .It Ic lock-client Op Fl t Ar target-client
1221 .D1 Pq alias: Ic lockc
1228 .It Ic lock-session Op Fl t Ar target-session
1229 .D1 Pq alias: Ic locks
1230 Lock all clients attached to
1231 .Ar target-session .
1233 .It Xo Ic new-session
1235 .Op Fl c Ar start-directory
1236 .Op Fl e Ar environment
1239 .Op Fl n Ar window-name
1240 .Op Fl s Ar session-name
1241 .Op Fl t Ar group-name
1244 .Op Ar shell-command
1246 .D1 Pq alias: Ic new
1247 Create a new session with name
1250 The new session is attached to the current terminal unless
1256 are the name of and shell command to execute in the initial window.
1259 the initial size comes from the global
1265 can be used to specify a different size.
1267 uses the size of the current client if any.
1274 option is set for the session.
1276 sets a comma-separated list of client flags (see
1277 .Ic attach-session ) .
1279 If run from a terminal, any
1281 special characters are saved and used for new windows in the new session.
1299 .Ic attach-session ,
1305 .Ic attach-session .
1309 is given, it specifies a
1311 Sessions in the same group share the same set of windows - new windows are
1312 linked to all sessions in the group and any windows closed removed from all
1314 The current and previous window and any session options remain independent and
1315 any session in a group may be killed without affecting the others.
1321 the name of an existing group, in which case the new session is added to that
1324 the name of an existing session - the new session is added to the same group
1325 as that session, creating a new group if necessary;
1327 the name for a new group containing only the new session.
1339 option prints information about the new session after it has been created.
1340 By default, it uses the format
1341 .Ql #{session_name}:\&
1342 but a different format may be specified with
1348 .Ic update-environment
1349 option will not be applied.
1353 and sets an environment variable for the newly created session; it may be
1354 specified multiple times.
1356 .It Xo Ic refresh-client
1358 .Op Fl A Ar pane:state
1359 .Op Fl B Ar name:what:format
1362 .Op Fl l Op Ar target-pane
1363 .Op Fl t Ar target-client
1366 .D1 Pq alias: Ic refresh
1367 Refresh the current client if bound to a key, or a single client if one is given
1372 is specified, only update the client's status line.
1381 flags allow the visible portion of a window which is larger than the client
1384 moves the visible part up by
1396 returns to tracking the cursor automatically.
1399 is omitted, 1 is used.
1400 Note that the visible position is a property of the client not of the
1401 window, changing the current window in the attached session will reset
1405 sets the width and height of a control mode client or of a window for a
1406 control mode client,
1411 .Ql window ID:widthxheight ,
1417 allows a control mode client to trigger actions on a pane.
1418 The argument is a pane ID (with leading
1420 a colon, then one of
1429 will not send output from the pane to the client and if all clients have turned
1430 the pane off, will stop reading from the pane.
1434 will return to sending output to the pane if it was paused (manually or with the
1440 will pause the pane.
1442 may be given multiple times for different panes.
1445 sets a subscription to a format for a control mode client.
1446 The argument is split into three items by colons:
1448 is a name for the subscription;
1450 is a type of item to subscribe to;
1453 After a subscription is added, changes to the format are reported with the
1454 .Ic %subscription-changed
1455 notification, at most once a second.
1456 If only the name is given, the subscription is removed.
1458 may be empty to check the format only for the attached session, or one of:
1462 for all panes in the attached session;
1467 for all windows in the attached session.
1470 sets a comma-separated list of client flags, see
1471 .Ic attach-session .
1474 requests the clipboard from the client using the
1479 is given, the clipboard is sent (in encoded form), otherwise it is stored in a
1487 move the visible portion of the window left, right, up or down
1490 if the window is larger than the client.
1492 resets so that the position follows the cursor.
1497 .It Xo Ic rename-session
1498 .Op Fl t Ar target-session
1501 .D1 Pq alias: Ic rename
1502 Rename the session to
1504 .It Xo Ic server-access
1508 Change the access or read/write permission of
1510 The user running the
1512 server (its owner) and the root user cannot be changed and are always
1518 are used to give or revoke access for the specified user.
1519 If the user is already attached, the
1521 flag causes their clients to be detached.
1526 change the permissions for
1529 makes their clients read-only and
1533 lists current access permissions.
1535 By default, the access list is empty and
1537 creates sockets with file system permissions preventing access by any user
1538 other than the owner (and root).
1539 These permissions must be changed manually.
1540 Great care should be taken not to allow access to untrusted users even
1543 .It Xo Ic show-messages
1545 .Op Fl t Ar target-client
1547 .D1 Pq alias: Ic showmsgs
1548 Show server messages or information.
1549 Messages are stored, up to a maximum of the limit set by the
1555 show debugging information about jobs and terminals.
1557 .It Xo Ic source-file
1559 .Op Fl t Ar target-pane
1562 .D1 Pq alias: Ic source
1563 Execute commands from one or more files specified by
1572 is expanded as a format.
1575 is given, no error will be returned if
1580 the file is parsed but no commands are executed.
1582 shows the parsed commands and line numbers if possible.
1585 .D1 Pq alias: Ic start
1588 server, if not already running, without creating any sessions.
1590 Note that as by default the
1592 server will exit with no sessions, this is only useful if a session is created
1594 .Pa \[ti]/.tmux.conf ,
1596 is turned off, or another command is run as part of the same command sequence.
1598 .Bd -literal -offset indent
1599 $ tmux start \\; show -g
1602 .It Xo Ic suspend-client
1603 .Op Fl t Ar target-client
1605 .D1 Pq alias: Ic suspendc
1606 Suspend a client by sending
1610 .It Xo Ic switch-client
1612 .Op Fl c Ar target-client
1613 .Op Fl t Ar target-session
1614 .Op Fl T Ar key-table
1616 .D1 Pq alias: Ic switchc
1617 Switch the current session for client
1620 .Ar target-session .
1623 may refer to a pane (a target that contains
1628 to change session, window and pane.
1631 keeps the window zoomed if it was zoomed.
1637 is used, the client is moved to the last, next or previous session
1651 .Ic update-environment
1652 option will not be applied.
1655 sets the client's key table; the next key from the client will be interpreted
1658 This may be used to configure multiple prefix keys, or to bind commands to
1660 For example, to make typing
1665 .Bd -literal -offset indent
1666 bind-key -Ttable2 c list-keys
1667 bind-key -Ttable1 b switch-client -Ttable2
1668 bind-key -Troot a switch-client -Ttable1
1671 .Sh WINDOWS AND PANES
1672 Each window displayed by
1674 may be split into one or more
1676 each pane takes up a certain area of the display and is a separate terminal.
1677 A window may be split into panes using the
1680 Windows may be split horizontally (with the
1682 flag) or vertically.
1683 Panes may be resized with the
1691 by default), the current pane may be changed with the
1697 commands may be used to swap panes without changing their position.
1698 Panes are numbered beginning from zero in the order they are created.
1702 pane permits direct access to the terminal contained in the pane.
1703 A pane may also be put into one of several modes:
1704 .Bl -dash -offset indent
1706 Copy mode, which permits a section of a window or its
1707 history to be copied to a
1709 for later insertion into another window.
1710 This mode is entered with the
1715 Copied text can be pasted with the
1720 View mode, which is like copy mode but is entered when a command that produces
1723 is executed from a key binding.
1725 Choose mode, which allows an item to be chosen from a list.
1726 This may be a client, a session or window or pane, or a buffer.
1727 This mode is entered with the
1735 In copy mode an indicator is displayed in the top-right corner of the pane with
1736 the current position and the number of lines in the history.
1738 Commands are sent to copy mode using the
1743 When a key is pressed, copy mode automatically uses one of two key tables,
1751 Key tables may be viewed with the
1755 The following commands are supported in copy mode:
1758 .Ic append-selection
1760 Append the selection to the top paste buffer.
1762 .Ic append-selection-and-cancel
1765 Append the selection to the top paste buffer and exit copy mode.
1767 .Ic back-to-indentation
1771 Move the cursor back to the indentation.
1782 Move to the bottom line.
1794 Clear the current selection.
1796 .Ic copy-end-of-line
1799 Copy from the cursor position to the end of the line.
1801 is used to name the new paste buffer.
1803 .Ic copy-end-of-line-and-cancel
1806 Copy from the cursor position and exit copy mode.
1811 Copy the entire line.
1813 .Ic copy-line-and-cancel
1816 Copy the entire line and exit copy mode.
1821 Copies the current selection.
1823 .Ic copy-selection-and-cancel
1828 Copy the current selection and exit copy mode.
1834 Move the cursor down.
1840 Move the cursor left.
1846 Move the cursor right.
1858 Move the cursor to the end of the line.
1865 Move the cursor to a specific line.
1871 Scroll to the bottom of the history.
1877 Scroll to the top of the history.
1883 Repeat the last jump.
1890 Jump backwards to the specified text.
1897 Jump forward to the specified text.
1903 Jump to the last mark.
1909 Move to the middle line.
1911 .Ic next-matching-bracket
1915 Move to the next matching bracket.
1921 Move to the next paragraph.
1926 Move to the next prompt.
1931 Move to the next word.
1937 Scroll down by one page.
1943 Scroll up by one page.
1945 .Ic previous-matching-bracket
1948 Move to the previous matching bracket.
1950 .Ic previous-paragraph
1954 Move to the previous paragraph.
1959 Move to the previous prompt.
1965 Move to the previous word.
1967 .Ic rectangle-toggle
1971 Toggle rectangle selection mode.
1973 .Ic refresh-from-pane
1977 Refresh the content from the pane.
1983 Repeat the last search.
1989 Search backwards for the specified text.
1995 Search forward for the specified text.
2000 Select the current line.
2004 Select the current word.
2010 Move the cursor to the start of the line.
2016 Move to the top line.
2019 The search commands come in several varieties:
2023 search for a regular expression;
2026 variants search for a plain text string rather than a regular expression;
2028 perform an incremental search and expect to be used with the
2034 repeats the last search and
2036 does the same but reverses the direction (forward becomes backward and backward
2043 move between shell prompts, but require the shell to emit an escape sequence
2044 (\e033]133;A\e033\e\e) to tell
2046 where the prompts are located; if the shell does not do this, these commands
2050 flag jumps to the beginning of the command output instead of the shell prompt.
2052 Copy commands may take an optional buffer prefix argument which is used
2053 to generate the buffer name (the default is
2055 so buffers are named
2059 Pipe commands take a command argument which is the command to which the
2060 selected text is piped.
2062 variants also copy the selection.
2065 variants of some commands exit copy mode after they have completed (for copy
2066 commands) or when the cursor reaches the bottom (for scrolling commands).
2068 variants do not clear the selection.
2070 The next and previous word keys skip over whitespace and treat consecutive
2071 runs of either word separators or other letters as words.
2072 Word separators can be customized with the
2075 Next word moves to the start of the next word, next word end to the end of the
2076 next word and previous word to the start of the previous word.
2077 The three next and previous space keys work similarly but use a space alone as
2081 to the empty string makes next/previous word equivalent to next/previous space.
2083 The jump commands enable quick movement within a line.
2084 For instance, typing
2088 will move the cursor to the next
2090 character on the current line.
2093 will then jump to the next occurrence.
2095 Commands in copy mode may be prefaced by an optional repeat count.
2096 With vi key bindings, a prefix is entered using the number keys; with
2097 emacs, the Alt (meta) key and a number begins prefix entry.
2099 The synopsis for the
2105 .Op Fl s Ar src-pane
2106 .Op Fl t Ar target-pane
2111 option scrolls one page up.
2113 begins a mouse drag (only valid if bound to a mouse key binding, see
2114 .Sx MOUSE SUPPORT ) .
2116 hides the position indicator in the top right.
2118 cancels copy mode and any other modes.
2126 specifies that scrolling to the bottom of the history (to the visible screen)
2127 should exit copy mode.
2128 While in copy mode, pressing a key other than those used for scrolling will
2129 disable this behaviour.
2130 This is intended to allow fast scrolling through a pane's history, for
2132 .Bd -literal -offset indent
2133 bind PageUp copy-mode -eu
2137 A number of preset arrangements of panes are available, these are called
2139 These may be selected with the
2141 command or cycled with
2145 by default); once a layout is chosen, panes within it may be moved and resized
2148 The following layouts are supported:
2150 .It Ic even-horizontal
2151 Panes are spread out evenly from left to right across the window.
2152 .It Ic even-vertical
2153 Panes are spread evenly from top to bottom.
2154 .It Ic main-horizontal
2155 A large (main) pane is shown at the top of the window and the remaining panes
2156 are spread from left to right in the leftover space at the bottom.
2158 .Em main-pane-height
2159 window option to specify the height of the top pane.
2160 .It Ic main-vertical
2163 but the large pane is placed on the left and the others spread from top to
2164 bottom along the right.
2169 Panes are spread out as evenly as possible over the window in both rows and
2175 may be used to apply a previously used layout - the
2177 command displays the layout of each window in a form suitable for use with
2180 .Bd -literal -offset indent
2183 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
2184 $ tmux select-layout \[aq]bb62,159x48,0,0{79x48,0,0,79x48,80,0}\[aq]
2188 automatically adjusts the size of the layout for the current window size.
2189 Note that a layout cannot be applied to a window with more panes than that
2190 from which the layout was originally defined.
2192 Commands related to windows and panes are as follows:
2195 .It Xo Ic break-pane
2198 .Op Fl n Ar window-name
2199 .Op Fl s Ar src-pane
2200 .Op Fl t Ar dst-window
2202 .D1 Pq alias: Ic breakp
2205 off from its containing window to make it the only pane in
2211 the window is moved to the next index after or before (existing windows are
2212 moved if necessary).
2215 is given, the new window does not become the current window.
2218 option prints information about the new window after it has been created.
2219 By default, it uses the format
2220 .Ql #{session_name}:#{window_index}.#{pane_index}
2221 but a different format may be specified with
2224 .It Xo Ic capture-pane
2226 .Op Fl b Ar buffer-name
2227 .Op Fl E Ar end-line
2228 .Op Fl S Ar start-line
2229 .Op Fl t Ar target-pane
2231 .D1 Pq alias: Ic capturep
2232 Capture the contents of a pane.
2235 is given, the output goes to stdout, otherwise to the buffer specified with
2237 or a new buffer if omitted.
2240 is given, the alternate screen is used, and the history is not accessible.
2241 If no alternate screen exists, an error will be returned unless
2246 is given, the output includes escape sequences for text and background
2249 also escapes non-printable characters as octal \exxx.
2251 ignores trailing positions that do not contain a character.
2253 preserves trailing spaces at each line's end and
2255 preserves trailing spaces and joins any wrapped lines;
2260 captures only any output that the pane has received that is the beginning of an
2261 as-yet incomplete escape sequence.
2266 specify the starting and ending line numbers, zero is the first line of the
2267 visible pane and negative numbers are lines in the history.
2271 is the start of the history and to
2273 the end of the visible pane.
2274 The default is to capture only the visible contents of the pane.
2280 .Op Fl K Ar key-format
2281 .Op Fl O Ar sort-order
2282 .Op Fl t Ar target-pane
2285 Put a pane into client mode, allowing a client to be selected interactively from
2287 Each client is shown on one line.
2288 A shortcut key is shown on the left in brackets allowing for immediate choice,
2289 or the list may be navigated and an item chosen or otherwise manipulated using
2293 The following keys may be used in client mode:
2294 .Bl -column "Key" "Function" -offset indent
2295 .It Sy "Key" Ta Sy "Function"
2296 .It Li "Enter" Ta "Choose selected client"
2297 .It Li "Up" Ta "Select previous client"
2298 .It Li "Down" Ta "Select next client"
2299 .It Li "C-s" Ta "Search by name"
2300 .It Li "n" Ta "Repeat last search forwards"
2301 .It Li "N" Ta "Repeat last search backwards"
2302 .It Li "t" Ta "Toggle if client is tagged"
2303 .It Li "T" Ta "Tag no clients"
2304 .It Li "C-t" Ta "Tag all clients"
2305 .It Li "d" Ta "Detach selected client"
2306 .It Li "D" Ta "Detach tagged clients"
2307 .It Li "x" Ta "Detach and HUP selected client"
2308 .It Li "X" Ta "Detach and HUP tagged clients"
2309 .It Li "z" Ta "Suspend selected client"
2310 .It Li "Z" Ta "Suspend tagged clients"
2311 .It Li "f" Ta "Enter a format to filter items"
2312 .It Li "O" Ta "Change sort field"
2313 .It Li "r" Ta "Reverse sort order"
2314 .It Li "v" Ta "Toggle preview"
2315 .It Li "q" Ta "Exit mode"
2318 After a client is chosen,
2320 is replaced by the client name in
2322 and the result executed as a command.
2325 is not given, "detach-client -t \[aq]%%\[aq]" is used.
2328 specifies the initial sort field: one of
2337 reverses the sort order.
2339 specifies an initial filter: the filter is a format - if it evaluates to zero,
2340 the item in the list is not shown, otherwise it is shown.
2341 If a filter would lead to an empty list, it is ignored.
2343 specifies the format for each item in the list and
2345 a format for each shortcut key; both are evaluated once for each line.
2347 starts without the preview.
2348 This command works only if at least one client is attached.
2354 .Op Fl K Ar key-format
2355 .Op Fl O Ar sort-order
2356 .Op Fl t Ar target-pane
2359 Put a pane into tree mode, where a session, window or pane may be chosen
2360 interactively from a tree.
2361 Each session, window or pane is shown on one line.
2362 A shortcut key is shown on the left in brackets allowing for immediate choice,
2363 or the tree may be navigated and an item chosen or otherwise manipulated using
2366 starts with sessions collapsed and
2368 with windows collapsed.
2371 The following keys may be used in tree mode:
2372 .Bl -column "Key" "Function" -offset indent
2373 .It Sy "Key" Ta Sy "Function"
2374 .It Li "Enter" Ta "Choose selected item"
2375 .It Li "Up" Ta "Select previous item"
2376 .It Li "Down" Ta "Select next item"
2377 .It Li "+" Ta "Expand selected item"
2378 .It Li "-" Ta "Collapse selected item"
2379 .It Li "M-+" Ta "Expand all items"
2380 .It Li "M--" Ta "Collapse all items"
2381 .It Li "x" Ta "Kill selected item"
2382 .It Li "X" Ta "Kill tagged items"
2383 .It Li "<" Ta "Scroll list of previews left"
2384 .It Li ">" Ta "Scroll list of previews right"
2385 .It Li "C-s" Ta "Search by name"
2386 .It Li "m" Ta "Set the marked pane"
2387 .It Li "M" Ta "Clear the marked pane"
2388 .It Li "n" Ta "Repeat last search forwards"
2389 .It Li "N" Ta "Repeat last search backwards"
2390 .It Li "t" Ta "Toggle if item is tagged"
2391 .It Li "T" Ta "Tag no items"
2392 .It Li "C-t" Ta "Tag all items"
2393 .It Li "\&:" Ta "Run a command for each tagged item"
2394 .It Li "f" Ta "Enter a format to filter items"
2395 .It Li "H" Ta "Jump to the starting pane"
2396 .It Li "O" Ta "Change sort field"
2397 .It Li "r" Ta "Reverse sort order"
2398 .It Li "v" Ta "Toggle preview"
2399 .It Li "q" Ta "Exit mode"
2402 After a session, window or pane is chosen, the first instance of
2404 and all instances of
2406 are replaced by the target in
2408 and the result executed as a command.
2411 is not given, "switch-client -t \[aq]%%\[aq]" is used.
2414 specifies the initial sort field: one of
2421 reverses the sort order.
2423 specifies an initial filter: the filter is a format - if it evaluates to zero,
2424 the item in the list is not shown, otherwise it is shown.
2425 If a filter would lead to an empty list, it is ignored.
2427 specifies the format for each item in the tree and
2429 a format for each shortcut key; both are evaluated once for each line.
2431 starts without the preview.
2433 includes all sessions in any session groups in the tree rather than only the
2435 This command works only if at least one client is attached.
2441 .Op Fl t Ar target-pane
2444 Put a pane into customize mode, where options and key bindings may be browsed
2445 and modified from a list.
2446 Option values in the list are shown for the active pane in the current window.
2449 The following keys may be used in customize mode:
2450 .Bl -column "Key" "Function" -offset indent
2451 .It Sy "Key" Ta Sy "Function"
2452 .It Li "Enter" Ta "Set pane, window, session or global option value"
2453 .It Li "Up" Ta "Select previous item"
2454 .It Li "Down" Ta "Select next item"
2455 .It Li "+" Ta "Expand selected item"
2456 .It Li "-" Ta "Collapse selected item"
2457 .It Li "M-+" Ta "Expand all items"
2458 .It Li "M--" Ta "Collapse all items"
2459 .It Li "s" Ta "Set option value or key attribute"
2460 .It Li "S" Ta "Set global option value"
2461 .It Li "w" Ta "Set window option value, if option is for pane and window"
2462 .It Li "d" Ta "Set an option or key to the default"
2463 .It Li "D" Ta "Set tagged options and tagged keys to the default"
2464 .It Li "u" Ta "Unset an option (set to default value if global) or unbind a key"
2465 .It Li "U" Ta "Unset tagged options and unbind tagged keys"
2466 .It Li "C-s" Ta "Search by name"
2467 .It Li "n" Ta "Repeat last search forwards"
2468 .It Li "N" Ta "Repeat last search backwards"
2469 .It Li "t" Ta "Toggle if item is tagged"
2470 .It Li "T" Ta "Tag no items"
2471 .It Li "C-t" Ta "Tag all items"
2472 .It Li "f" Ta "Enter a format to filter items"
2473 .It Li "v" Ta "Toggle option information"
2474 .It Li "q" Ta "Exit mode"
2478 specifies an initial filter: the filter is a format - if it evaluates to zero,
2479 the item in the list is not shown, otherwise it is shown.
2480 If a filter would lead to an empty list, it is ignored.
2482 specifies the format for each item in the tree.
2484 starts without the option information.
2485 This command works only if at least one client is attached.
2490 .Op Fl d Ar duration
2491 .Op Fl t Ar target-client
2494 .D1 Pq alias: Ic displayp
2495 Display a visible indicator of each pane shown by
2498 .Ic display-panes-colour
2500 .Ic display-panes-active-colour
2502 The indicator is closed when a key is pressed (unless
2506 milliseconds have passed.
2510 .Ic display-panes-time
2512 A duration of zero means the indicator stays until a key is pressed.
2513 While the indicator is on screen, a pane may be chosen with the
2517 keys, which will cause
2519 to be executed as a command with
2521 substituted by the pane ID.
2524 is "select-pane -t \[aq]%%\[aq]".
2527 other commands are not blocked from running until the indicator is closed.
2529 .It Xo Ic find-window
2531 .Op Fl t Ar target-pane
2534 .D1 Pq alias: Ic findw
2541 in window names, titles, and visible content (but not history).
2542 The flags control matching behavior:
2544 matches only visible window contents,
2546 matches only the window name and
2548 matches only the window title.
2550 makes the search ignore case.
2556 This command works only if at least one client is attached.
2561 .Op Fl s Ar src-pane
2562 .Op Fl t Ar dst-pane
2564 .D1 Pq alias: Ic joinp
2567 but instead of splitting
2569 and creating a new pane, split it and move
2572 This can be used to reverse
2578 to be joined to left of or above
2583 is omitted and a marked pane is present (see
2586 the marked pane is used rather than the current pane.
2590 .Op Fl t Ar target-pane
2592 .D1 Pq alias: Ic killp
2593 Destroy the given pane.
2594 If no panes remain in the containing window, it is also destroyed.
2597 option kills all but the pane given with
2600 .It Xo Ic kill-window
2602 .Op Fl t Ar target-window
2604 .D1 Pq alias: Ic killw
2605 Kill the current window or the window at
2607 removing it from any sessions to which it is linked.
2610 option kills all but the window given with
2615 .Op Fl t Ar target-window
2617 .D1 Pq alias: Ic lastp
2618 Select the last (previously selected) pane.
2620 keeps the window zoomed if it was zoomed.
2624 disables input to the pane.
2626 .It Ic last-window Op Fl t Ar target-session
2627 .D1 Pq alias: Ic last
2628 Select the last (previously selected) window.
2631 is specified, select the last window of the current session.
2633 .It Xo Ic link-window
2635 .Op Fl s Ar src-window
2636 .Op Fl t Ar dst-window
2638 .D1 Pq alias: Ic linkw
2645 is specified and no such window exists, the
2652 the window is moved to the next index after or before
2654 (existing windows are moved if necessary).
2659 exists, it is killed, otherwise an error is generated.
2662 is given, the newly linked window is not selected.
2664 .It Xo Ic list-panes
2670 .D1 Pq alias: Ic lsp
2675 is ignored and all panes on the server are listed.
2680 is a session (or the current session).
2681 If neither is given,
2683 is a window (or the current window).
2685 specifies the format of each line and
2688 Only panes for which the filter is true are shown.
2693 .It Xo Ic list-windows
2697 .Op Fl t Ar target-session
2699 .D1 Pq alias: Ic lsw
2702 is given, list all windows on the server.
2703 Otherwise, list windows in the current session or in
2704 .Ar target-session .
2706 specifies the format of each line and
2709 Only windows for which the filter is true are shown.
2717 .Op Fl s Ar src-pane
2718 .Op Fl t Ar dst-pane
2720 .D1 Pq alias: Ic movep
2724 .It Xo Ic move-window
2726 .Op Fl s Ar src-window
2727 .Op Fl t Ar dst-window
2729 .D1 Pq alias: Ic movew
2732 except the window at
2738 all windows in the session are renumbered in sequential order, respecting
2743 .It Xo Ic new-window
2745 .Op Fl c Ar start-directory
2746 .Op Fl e Ar environment
2748 .Op Fl n Ar window-name
2749 .Op Fl t Ar target-window
2750 .Op Ar shell-command
2752 .D1 Pq alias: Ic neww
2753 Create a new window.
2758 the new window is inserted at the next index after or before the specified
2760 moving windows up if necessary;
2763 is the new window location.
2767 is given, the session does not make the new window the current window.
2769 represents the window to be created; if the target already exists an error is
2772 flag is used, in which case it is destroyed.
2775 is given and a window named
2777 already exists, it is selected (unless
2779 is also given in which case the command does nothing).
2782 is the command to execute.
2785 is not specified, the value of the
2789 specifies the working directory in which the new window is created.
2791 When the shell command completes, the window closes.
2794 option to change this behaviour.
2799 and sets an environment variable for the newly created window; it may be
2800 specified multiple times.
2804 environment variable must be set to
2808 for all programs running
2811 New windows will automatically have
2813 added to their environment, but care must be taken not to reset this in shell
2814 start-up files or by the
2820 option prints information about the new window after it has been created.
2821 By default, it uses the format
2822 .Ql #{session_name}:#{window_index}
2823 but a different format may be specified with
2826 .It Ic next-layout Op Fl t Ar target-window
2827 .D1 Pq alias: Ic nextl
2828 Move a window to the next layout and rearrange the panes to fit.
2830 .It Xo Ic next-window
2832 .Op Fl t Ar target-session
2834 .D1 Pq alias: Ic next
2835 Move to the next window in the session.
2838 is used, move to the next window with an alert.
2842 .Op Fl t Ar target-pane
2843 .Op Ar shell-command
2845 .D1 Pq alias: Ic pipep
2846 Pipe output sent by the program in
2848 to a shell command or vice versa.
2849 A pane may only be connected to one command at a time, any existing pipe is
2855 string may contain the special character sequences supported by the
2860 is given, the current pipe (if any) is closed.
2865 specify which of the
2867 output streams are connected to the pane:
2870 stdout is connected (so anything
2872 prints is written to the pane as if it were typed);
2875 stdin is connected (so any output in the pane is piped to
2876 .Ar shell-command ) .
2877 Both may be used together and if neither are specified,
2883 option only opens a new pipe if no previous pipe exists, allowing a pipe to
2884 be toggled with a single key, for example:
2885 .Bd -literal -offset indent
2886 bind-key C-p pipe-pane -o \[aq]cat >>\[ti]/output.#I-#P\[aq]
2889 .It Xo Ic previous-layout
2890 .Op Fl t Ar target-window
2892 .D1 Pq alias: Ic prevl
2893 Move to the previous layout in the session.
2895 .It Xo Ic previous-window
2897 .Op Fl t Ar target-session
2899 .D1 Pq alias: Ic prev
2900 Move to the previous window in the session.
2903 move to the previous window with an alert.
2905 .It Xo Ic rename-window
2906 .Op Fl t Ar target-window
2909 .D1 Pq alias: Ic renamew
2910 Rename the current window, or the window at
2915 .It Xo Ic resize-pane
2917 .Op Fl t Ar target-pane
2922 .D1 Pq alias: Ic resizep
2923 Resize a pane, up, down, left or right by
2939 is given in lines or columns (the default is 1);
2943 may be a given as a number of lines or columns or followed by
2945 for a percentage of the window size (for example
2949 the active pane is toggled between zoomed (occupying the whole of the window)
2950 and unzoomed (its normal position in the layout).
2953 begins mouse resizing (only valid if bound to a mouse key binding, see
2954 .Sx MOUSE SUPPORT ) .
2957 trims all lines below the current cursor position and moves lines out of the
2958 history to replace them.
2960 .It Xo Ic resize-window
2962 .Op Fl t Ar target-window
2967 .D1 Pq alias: Ic resizew
2968 Resize a window, up, down, left or right by
2984 is given in lines or cells (the default is 1).
2986 sets the size of the largest session containing the window;
2988 the size of the smallest.
2989 This command will automatically set
2991 to manual in the window options.
2993 .It Xo Ic respawn-pane
2995 .Op Fl c Ar start-directory
2996 .Op Fl e Ar environment
2997 .Op Fl t Ar target-pane
2998 .Op Ar shell-command
3000 .D1 Pq alias: Ic respawnp
3001 Reactivate a pane in which the command has exited (see the
3006 is not given, the command used when the pane was created or last respawned is
3008 The pane must be already inactive, unless
3010 is given, in which case any existing command is killed.
3012 specifies a new working directory for the pane.
3015 option has the same meaning as for the
3019 .It Xo Ic respawn-window
3021 .Op Fl c Ar start-directory
3022 .Op Fl e Ar environment
3023 .Op Fl t Ar target-window
3024 .Op Ar shell-command
3026 .D1 Pq alias: Ic respawnw
3027 Reactivate a window in which the command has exited (see the
3032 is not given, the command used when the window was created or last respawned is
3034 The window must be already inactive, unless
3036 is given, in which case any existing command is killed.
3038 specifies a new working directory for the window.
3041 option has the same meaning as for the
3045 .It Xo Ic rotate-window
3047 .Op Fl t Ar target-window
3049 .D1 Pq alias: Ic rotatew
3050 Rotate the positions of the panes within a window, either upward (numerically
3053 or downward (numerically higher).
3055 keeps the window zoomed if it was zoomed.
3057 .It Xo Ic select-layout
3059 .Op Fl t Ar target-pane
3062 .D1 Pq alias: Ic selectl
3063 Choose a specific layout for a window.
3066 is not given, the last preset layout used (if any) is reapplied.
3070 are equivalent to the
3076 applies the last set layout if possible (undoes the most recent layout change).
3078 spreads the current pane and any panes next to it out evenly.
3080 .It Xo Ic select-pane
3083 .Op Fl t Ar target-pane
3085 .D1 Pq alias: Ic selectp
3088 the active pane in its window.
3095 is used, respectively the pane below, to the left, to the right, or above the
3096 target pane is used.
3098 keeps the window zoomed if it was zoomed.
3100 is the same as using the
3106 disables input to the pane.
3108 sets the pane title.
3113 are used to set and clear the
3115 There is one marked pane at a time, setting a new marked pane clears the last.
3116 The marked pane is the default target for
3125 .It Xo Ic select-window
3127 .Op Fl t Ar target-window
3129 .D1 Pq alias: Ic selectw
3130 Select the window at
3136 are equivalent to the
3144 is given and the selected window is already the current window,
3145 the command behaves like
3148 .It Xo Ic split-window
3150 .Op Fl c Ar start-directory
3151 .Op Fl e Ar environment
3153 .Op Fl t Ar target-pane
3154 .Op Ar shell-command
3157 .D1 Pq alias: Ic splitw
3158 Create a new pane by splitting
3161 does a horizontal split and
3163 a vertical split; if neither is specified,
3168 option specifies the size of the new pane in lines (for vertical split) or in
3169 columns (for horizontal split);
3173 to specify a percentage of the available space.
3176 option causes the new pane to be created to the left of or above
3180 option creates a new pane spanning the full window height (with
3182 or full window width (with
3184 instead of splitting the active pane.
3186 zooms if the window is not zoomed, or keeps it zoomed if already zoomed.
3190 (\[aq]\[aq]) will create a pane with no command running in it.
3191 Output can be sent to such a pane with the
3198 is not specified or empty)
3199 will create an empty pane and forward any output from stdin to it.
3201 .Bd -literal -offset indent
3202 $ make 2>&1|tmux splitw -dI &
3205 All other options have the same meaning as for the
3211 .Op Fl s Ar src-pane
3212 .Op Fl t Ar dst-pane
3214 .D1 Pq alias: Ic swapp
3218 is used and no source pane is specified with
3221 is swapped with the previous pane (before it numerically);
3223 swaps with the next pane (after it numerically).
3227 not to change the active pane and
3229 keeps the window zoomed if it was zoomed.
3233 is omitted and a marked pane is present (see
3236 the marked pane is used rather than the current pane.
3238 .It Xo Ic swap-window
3240 .Op Fl s Ar src-window
3241 .Op Fl t Ar dst-window
3243 .D1 Pq alias: Ic swapw
3246 except the source and destination windows are swapped.
3247 It is an error if no window exists at
3251 is given, the new window does not become the current window.
3255 is omitted and a marked pane is present (see
3258 the window containing the marked pane is used rather than the current window.
3260 .It Xo Ic unlink-window
3262 .Op Fl t Ar target-window
3264 .D1 Pq alias: Ic unlinkw
3269 is given, a window may be unlinked only if it is linked to multiple sessions -
3270 windows may not be linked to no sessions;
3273 is specified and the window is linked to only one session, it is unlinked and
3278 allows a command to be bound to most keys, with or without a prefix key.
3279 When specifying keys, most represent themselves (for example
3283 Ctrl keys may be prefixed with
3291 In addition, the following special key names are accepted:
3309 .Em NPage/PageDown/PgDn ,
3310 .Em PPage/PageUp/PgUp ,
3314 Note that to bind the
3318 keys, quotation marks are necessary, for example:
3319 .Bd -literal -offset indent
3320 bind-key \[aq]"\[aq] split-window
3321 bind-key "\[aq]" new-window
3324 A command bound to the
3326 key will execute for all keys which do not have a more specific binding.
3328 Commands related to key bindings are as follows:
3334 .Op Fl T Ar key-table
3335 .Ar key command Op Ar argument ...
3337 .D1 Pq alias: Ic bind
3342 Keys are bound in a key table.
3343 By default (without -T), the key is bound in
3347 This table is used for keys pressed after the prefix key (for example,
3356 creates a new window).
3359 table is used for keys pressed without the prefix key: binding
3365 table (not recommended) means a plain
3367 will create a new window.
3372 Keys may also be bound in custom key tables and the
3375 command used to switch to them from a key binding.
3378 flag indicates this key may repeat, see the
3382 attaches a note to the key (shown with
3386 To view the default bindings and possible commands, see the
3392 .Op Fl P Ar prefix-string Fl T Ar key-table
3395 .D1 Pq alias: Ic lsk
3397 There are two forms: the default lists keys as
3401 lists only keys with attached notes and shows only the key and note for each
3404 With the default form, all key tables are listed by default.
3411 form, only keys in the
3415 key tables are listed by default;
3417 also lists only keys in
3420 specifies a prefix to print before each key and
3422 lists only the first matching key.
3424 lists the command for keys that do not have a note rather than skipping them.
3428 .Op Fl c Ar target-client
3429 .Op Fl N Ar repeat-count
3430 .Op Fl t Ar target-pane
3433 .D1 Pq alias: Ic send
3434 Send a key or keys to a window or client.
3437 is the name of the key (such as
3441 to send; if the string is not recognised as a key, it is sent as a series of
3445 is given, keys are sent to
3447 so they are looked up in the client's key table, rather than to
3449 All arguments are sent sequentially from first to last.
3450 If no keys are given and the command is bound to a key, then that key is used.
3454 flag disables key name lookup and processes the keys as literal UTF-8
3458 flag expects each key to be a hexadecimal number for an ASCII character.
3462 flag causes the terminal state to be reset.
3465 passes through a mouse event (only valid if bound to a mouse key binding, see
3466 .Sx MOUSE SUPPORT ) .
3469 is used to send a command into copy mode - see
3471 .Sx WINDOWS AND PANES
3474 specifies a repeat count and
3476 expands formats in arguments where appropriate.
3477 .It Xo Ic send-prefix
3479 .Op Fl t Ar target-pane
3481 Send the prefix key, or with
3483 the secondary prefix key, to a window as if it was pressed.
3485 .It Xo Ic unbind-key
3487 .Op Fl T Ar key-table
3490 .D1 Pq alias: Ic unbind
3491 Unbind the command bound to
3500 is present, all key bindings are removed.
3503 option prevents errors being returned.
3506 The appearance and behaviour of
3508 may be modified by changing the value of various options.
3509 There are four types of option:
3510 .Em server options ,
3511 .Em session options ,
3512 .Em window options ,
3518 server has a set of global server options which do not apply to any particular
3519 window or session or pane.
3520 These are altered with the
3523 command, or displayed with the
3528 In addition, each individual session may have a set of session options, and
3529 there is a separate set of global session options.
3530 Sessions which do not have a particular option configured inherit the value
3531 from the global session options.
3532 Session options are set or unset with the
3534 command and may be listed with the
3537 The available server and session options are listed under the
3541 Similarly, a set of window options is attached to each window and a set of pane
3542 options to each pane.
3543 Pane options inherit from window options.
3544 This means any pane option may be set as a window option to apply the option to
3545 all panes in the window without the option set, for example these commands will
3546 set the background colour to red for all panes except pane 0:
3547 .Bd -literal -offset indent
3548 set -w window-style bg=red
3549 set -pt:.0 window-style bg=blue
3552 There is also a set of global window options from which any unset window or
3553 pane options are inherited.
3554 Window and pane options are altered with
3559 commands and displayed with
3566 also supports user options which are prefixed with a
3568 User options may have any name, so long as they are prefixed with
3570 and be set to any string.
3572 .Bd -literal -offset indent
3573 $ tmux set -wq @foo "abc123"
3574 $ tmux show -wv @foo
3578 Commands which set options are as follows:
3581 .It Xo Ic set-option
3583 .Op Fl t Ar target-pane
3586 .D1 Pq alias: Ic set
3587 Set a pane option with
3589 a window option with
3591 a server option with
3593 otherwise a session option.
3594 If the option is not a user option,
3598 may be unnecessary -
3600 will infer the type from the option name, assuming
3605 is given, the global session or window option is set.
3608 expands formats in the option value.
3611 flag unsets an option, so a session inherits the option from the global
3614 restores a global option to the default).
3616 unsets an option (like
3618 but if the option is a pane option also unsets the option on any panes in the
3621 depends on the option and may be a number, a string, or a flag (on, off, or
3626 flag prevents setting an option that is already set and the
3628 flag suppresses errors about unknown or ambiguous options.
3632 and if the option expects a string or a style,
3634 is appended to the existing setting.
3636 .Bd -literal -offset indent
3637 set -g status-left "foo"
3638 set -ag status-left "bar"
3644 .Bd -literal -offset indent
3645 set -g status-style "bg=red"
3646 set -ag status-style "fg=blue"
3649 Will result in a red background
3654 the result would be the default background and a blue foreground.
3656 .It Xo Ic show-options
3658 .Op Fl t Ar target-pane
3661 .D1 Pq alias: Ic show
3662 Show the pane options (or a single option if
3666 the window options with
3668 the server options with
3670 otherwise the session options.
3671 If the option is not a user option,
3675 may be unnecessary -
3677 will infer the type from the option name, assuming
3680 Global session or window options are listed if
3684 shows only the option value, not the name.
3687 is set, no error will be returned if
3691 includes hooks (omitted by default).
3693 includes options inherited from a parent set of options, such options are
3694 marked with an asterisk.
3697 Available server options are:
3699 .It Ic backspace Ar key
3703 .It Ic buffer-limit Ar number
3704 Set the number of buffers; as new buffers are added to the top of the stack,
3705 old ones are removed from the bottom if necessary to maintain this maximum
3707 .It Xo Ic command-alias[]
3710 This is an array of custom aliases for commands.
3711 If an unknown command matches
3717 .Dl set -s command-alias[100] zoom=\[aq]resize-pane -Z\[aq]
3725 .Dl resize-pane -Z -t:.1
3727 Note that aliases are expanded when a command is parsed rather than when it is
3728 executed, so binding an alias with
3730 will bind the expanded form.
3731 .It Ic default-terminal Ar terminal
3732 Set the default terminal for new windows created in this session - the
3733 default value of the
3735 environment variable.
3738 to work correctly, this
3743 or a derivative of them.
3744 .It Ic copy-command Ar shell-command
3745 Give the command to pipe to if the
3747 copy mode command is used without arguments.
3748 .It Ic escape-time Ar time
3749 Set the time in milliseconds for which
3751 waits after an escape is input to determine if it is part of a function or meta
3753 .It Ic editor Ar shell-command
3754 Set the command used when
3757 .It Xo Ic exit-empty
3760 If enabled (the default), the server will exit when there are no active
3762 .It Xo Ic exit-unattached
3765 If enabled, the server will exit when there are no attached clients.
3766 .It Xo Ic extended-keys
3767 .Op Ic on | off | always
3773 the escape sequence to enable extended keys is sent to the terminal, if
3775 knows that it is supported.
3777 always recognises extended keys itself.
3781 will only forward extended keys to applications when they request them; if
3784 will always forward the keys.
3785 .It Xo Ic focus-events
3788 When enabled, focus events are requested from the terminal if supported and
3789 passed through to applications running in
3791 Attached clients should be detached and attached again after changing this
3793 .It Ic history-file Ar path
3794 If not empty, a file to which
3796 will write command prompt history on exit and load it from on start.
3797 .It Ic message-limit Ar number
3798 Set the number of error or information messages to save in the message log for
3800 .It Ic prompt-history-limit Ar number
3801 Set the number of history items to save in the history file for each type of
3803 .It Xo Ic set-clipboard
3804 .Op Ic on | external | off
3806 Attempt to set the terminal clipboard content using the
3808 escape sequence, if there is an
3812 description (see the
3813 .Sx TERMINFO EXTENSIONS
3819 will both accept the escape sequence to create a buffer and attempt to set
3820 the terminal clipboard.
3824 will attempt to set the terminal clipboard but ignore attempts
3825 by applications to set
3831 will neither accept the clipboard escape sequence nor attempt to set the
3834 Note that this feature needs to be enabled in
3836 by setting the resource:
3837 .Bd -literal -offset indent
3838 disallowedWindowOps: 20,21,SetXprop
3841 Or changing this property from the
3843 interactive menu when required.
3844 .It Ic terminal-features[] Ar string
3845 Set terminal features for terminal types read from
3848 has a set of named terminal features.
3849 Each will apply appropriate changes to the
3854 can detect features for a few common terminals; this option can be used to
3855 easily tell tmux about features supported by terminals it cannot detect.
3857 .Ic terminal-overrides
3858 option allows individual
3860 capabilities to be set instead,
3861 .Ic terminal-features
3862 is intended for classes of functionality supported in a standard way but not
3865 Care must be taken to configure this only with features the terminal actually
3868 This is an array option where each entry is a colon-separated string made up
3869 of a terminal type pattern (matched using
3871 followed by a list of terminal features.
3872 The available features are:
3875 Supports 256 colours with the SGR escape sequences.
3877 Allows setting the system clipboard.
3879 Allows setting the cursor colour.
3881 Allows setting the cursor style.
3883 Supports extended keys.
3885 Supports focus reporting.
3887 Supports OSC 8 hyperlinks.
3889 Ignore function keys from
3895 Supports DECSLRM margins.
3901 Supports the OSC 7 working directory extension.
3903 Supports the overline SGR attribute.
3905 Supports the DECFRA rectangle fill escape sequence.
3907 Supports RGB colour with the SGR escape sequences.
3909 Supports SIXEL graphics.
3911 Supports the strikethrough SGR escape sequence.
3913 Supports synchronized updates.
3919 Allows underscore style and colour to be set.
3921 .It Ic terminal-overrides[] Ar string
3922 Allow terminal descriptions read using
3925 Each entry is a colon-separated string made up of a terminal type pattern
3932 For example, to set the
3937 for all terminal types matching
3940 .Dl "rxvt*:clear=\ee[H\ee[2J"
3942 The terminal entry value is passed through
3944 before interpretation.
3945 .It Ic user-keys[] Ar key
3946 Set list of user-defined key escape sequences.
3947 Each item is associated with a key named
3953 .Bd -literal -offset indent
3954 set -s user-keys[0] "\ee[5;30012\[ti]"
3955 bind User0 resize-pane -L 3
3959 Available session options are:
3961 .It Xo Ic activity-action
3962 .Op Ic any | none | current | other
3964 Set action on window activity when
3965 .Ic monitor-activity
3968 means activity in any window linked to a session causes a bell or message
3970 .Ic visual-activity )
3971 in the current window of that session,
3973 means all activity is ignored (equivalent to
3974 .Ic monitor-activity
3977 means only activity in windows other than the current window are ignored and
3979 means activity in the current window is ignored but not those in other windows.
3980 .It Ic assume-paste-time Ar milliseconds
3981 If keys are entered faster than one in
3983 they are assumed to have been pasted rather than typed and
3985 key bindings are not processed.
3986 The default is one millisecond and zero disables.
3987 .It Ic base-index Ar index
3988 Set the base index from which an unused index should be searched when a new
3990 The default is zero.
3991 .It Xo Ic bell-action
3992 .Op Ic any | none | current | other
3994 Set action on a bell in a window when
3997 The values are the same as those for
3998 .Ic activity-action .
3999 .It Ic default-command Ar shell-command
4000 Set the command used for new windows (if not specified when the window is
4006 The default is an empty string, which instructs
4008 to create a login shell using the value of the
4011 .It Ic default-shell Ar path
4012 Specify the default shell.
4013 This is used as the login shell for new windows when the
4015 option is set to empty, and must be the full path of the executable.
4018 tries to set a default value from the first suitable of the
4020 environment variable, the shell returned by
4024 This option should be configured when
4026 is used as a login shell.
4027 .It Ic default-size Ar XxY
4028 Set the default size of new windows when the
4030 option is set to manual or when a session is created with
4033 The value is the width and height separated by an
4036 The default is 80x24.
4037 .It Xo Ic destroy-unattached
4038 .Op Ic off | on | keep-last | keep-group
4042 destroy the session after the last client has detached.
4045 (the default), leave the session orphaned.
4048 destroy the session only if it is in a group and has other sessions in that group.
4051 destroy the session unless it is in a group and is the only session in that group.
4052 .It Xo Ic detach-on-destroy
4053 .Op Ic off | on | no-detached | previous | next
4057 (the default), the client is detached when the session it is attached to
4061 the client is switched to the most recently active of the remaining
4065 the client is detached only if there are no detached sessions; if detached
4066 sessions exist, the client is switched to the most recently active.
4071 the client is switched to the previous or next session in alphabetical order.
4072 .It Ic display-panes-active-colour Ar colour
4073 Set the colour used by the
4075 command to show the indicator for the active pane.
4076 .It Ic display-panes-colour Ar colour
4077 Set the colour used by the
4079 command to show the indicators for inactive panes.
4080 .It Ic display-panes-time Ar time
4081 Set the time in milliseconds for which the indicators shown by the
4084 .It Ic display-time Ar time
4085 Set the amount of time for which status line messages and other on-screen
4086 indicators are displayed.
4087 If set to 0, messages and indicators are displayed until a key is pressed.
4090 .It Ic history-limit Ar lines
4091 Set the maximum number of lines held in window history.
4092 This setting applies only to new windows - existing window histories are not
4093 resized and retain the limit at the point they were created.
4094 .It Ic key-table Ar key-table
4095 Set the default key table to
4099 .It Ic lock-after-time Ar number
4100 Lock the session (like the
4104 seconds of inactivity.
4105 The default is not to lock (set to 0).
4106 .It Ic lock-command Ar shell-command
4107 Command to run when locking each client.
4108 The default is to run
4112 .It Ic menu-style Ar style
4116 section on how to specify
4118 Attributes are ignored.
4119 .It Ic menu-selected-style Ar style
4120 Set the selected menu item style.
4123 section on how to specify
4125 Attributes are ignored.
4126 .It Ic menu-border-style Ar style
4127 Set the menu border style.
4130 section on how to specify
4132 Attributes are ignored.
4133 .It Ic menu-border-lines Ar type
4134 Set the type of characters used for drawing menu borders.
4136 .Ic popup-border-lines
4137 for possible values for
4139 .It Ic message-command-style Ar style
4140 Set status line message command style.
4141 This is used for the command prompt with
4143 keys when in command mode.
4149 .It Xo Ic message-line
4150 .Op Ic 0 | 1 | 2 | 3 | 4
4152 Set line on which status line messages and the command prompt are shown.
4153 .It Ic message-style Ar style
4154 Set status line message style.
4155 This is used for messages and for the command prompt.
4166 captures the mouse and allows mouse events to be bound as key bindings.
4169 section for details.
4170 .It Ic prefix Ar key
4171 Set the key accepted as a prefix key.
4172 In addition to the standard keys described under
4175 can be set to the special key
4178 .It Ic prefix2 Ar key
4179 Set a secondary key accepted as a prefix key.
4185 .It Xo Ic renumber-windows
4188 If on, when a window is closed in a session, automatically renumber the other
4189 windows in numerical order.
4192 option if it has been set.
4193 If off, do not renumber the windows.
4194 .It Ic repeat-time Ar time
4195 Allow multiple commands to be entered without pressing the prefix-key again
4198 milliseconds (the default is 500).
4199 Whether a key repeats may be set when it is bound using the
4203 Repeat is enabled for the default keys bound to the
4206 .It Xo Ic set-titles
4209 Attempt to set the client terminal title using the
4214 entries if they exist.
4216 automatically sets these to the \ee]0;...\e007 sequence if
4217 the terminal appears to be
4219 This option is off by default.
4220 .It Ic set-titles-string Ar string
4221 String used to set the client terminal title if
4224 Formats are expanded, see the
4227 .It Xo Ic silence-action
4228 .Op Ic any | none | current | other
4230 Set action on window silence when
4233 The values are the same as those for
4234 .Ic activity-action .
4236 .Op Ic off | on | 2 | 3 | 4 | 5
4238 Show or hide the status line or specify its size.
4241 gives a status line one row in height;
4248 .It Ic status-format[] Ar format
4249 Specify the format to be used for each line of the status line.
4250 The default builds the top status line from the various individual status
4252 .It Ic status-interval Ar interval
4253 Update the status line every
4256 By default, updates will occur every 15 seconds.
4257 A setting of zero disables redrawing at interval.
4258 .It Xo Ic status-justify
4259 .Op Ic left | centre | right | absolute-centre
4261 Set the position of the window list in the status line: left, centre or right.
4262 centre puts the window list in the relative centre of the available free space;
4263 absolute-centre uses the centre of the entire horizontal space.
4264 .It Xo Ic status-keys
4267 Use vi or emacs-style
4268 key bindings in the status line, for example at the command prompt.
4269 The default is emacs, unless the
4273 environment variables are set and contain the string
4275 .It Ic status-left Ar string
4278 (by default the session name) to the left of the status line.
4280 will be passed through
4288 For details on how the names and titles can be set see the
4289 .Sx "NAMES AND TITLES"
4293 .Bd -literal -offset indent
4294 #(sysctl vm.loadavg)
4295 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
4300 .It Ic status-left-length Ar length
4303 of the left component of the status line.
4305 .It Ic status-left-style Ar style
4306 Set the style of the left part of the status line.
4312 .It Xo Ic status-position
4315 Set the position of the status line.
4316 .It Ic status-right Ar string
4319 to the right of the status line.
4320 By default, the current pane title in double quotes, the date and the time
4327 and character pairs are replaced.
4328 .It Ic status-right-length Ar length
4331 of the right component of the status line.
4333 .It Ic status-right-style Ar style
4334 Set the style of the right part of the status line.
4340 .It Ic status-style Ar style
4341 Set status line style.
4347 .It Ic update-environment[] Ar variable
4348 Set list of environment variables to be copied into the session environment
4349 when a new session is created or an existing session is attached.
4350 Any variables that do not exist in the source environment are set to be
4351 removed from the session environment (as if
4356 .It Xo Ic visual-activity
4357 .Op Ic on | off | both
4359 If on, display a message instead of sending a bell when activity occurs in a
4360 window for which the
4361 .Ic monitor-activity
4362 window option is enabled.
4363 If set to both, a bell and a message are produced.
4364 .It Xo Ic visual-bell
4365 .Op Ic on | off | both
4367 If on, a message is shown on a bell in a window for which the
4369 window option is enabled instead of it being passed through to the
4370 terminal (which normally makes a sound).
4371 If set to both, a bell and a message are produced.
4375 .It Xo Ic visual-silence
4376 .Op Ic on | off | both
4380 is enabled, prints a message after the interval has expired on a given window
4381 instead of sending a bell.
4382 If set to both, a bell and a message are produced.
4383 .It Ic word-separators Ar string
4384 Sets the session's conception of what characters are considered word
4385 separators, for the purposes of the next and previous word commands in
4389 Available window options are:
4391 .Bl -tag -width Ds -compact
4392 .It Xo Ic aggressive-resize
4395 Aggressively resize the chosen window.
4398 will resize the window to the size of the smallest or largest session
4401 option) for which it is the current window, rather than the session to
4402 which it is attached.
4403 The window may resize when the current window is changed on another
4404 session; this option is good for full-screen programs which support
4406 and poor for interactive programs such as shells.
4408 .It Xo Ic automatic-rename
4411 Control automatic window renaming.
4412 When this setting is enabled,
4414 will rename the window automatically using the format specified by
4415 .Ic automatic-rename-format .
4416 This flag is automatically disabled for an individual window when a name
4417 is specified at creation with
4423 or with a terminal escape sequence.
4424 It may be switched off globally with:
4425 .Bd -literal -offset indent
4426 set-option -wg automatic-rename off
4429 .It Ic automatic-rename-format Ar format
4433 .Ic automatic-rename
4436 .It Ic clock-mode-colour Ar colour
4439 .It Xo Ic clock-mode-style
4442 Set clock hour format.
4444 .It Ic fill-character Ar character
4445 Set the character used to fill areas of the terminal unused by a window.
4447 .It Ic main-pane-height Ar height
4448 .It Ic main-pane-width Ar width
4449 Set the width or height of the main (left or top) pane in the
4456 this is a percentage of the window size.
4458 .It Ic copy-mode-match-style Ar style
4459 Set the style of search matches in copy mode.
4466 .It Ic copy-mode-mark-style Ar style
4467 Set the style of the line containing the mark in copy mode.
4474 .It Ic copy-mode-current-match-style Ar style
4475 Set the style of the current search match in copy mode.
4485 Use vi or emacs-style key bindings in copy mode.
4486 The default is emacs, unless
4493 .It Ic mode-style Ar style
4494 Set window modes style.
4501 .It Xo Ic monitor-activity
4504 Monitor for activity in the window.
4505 Windows with activity are highlighted in the status line.
4507 .It Xo Ic monitor-bell
4510 Monitor for a bell in the window.
4511 Windows with a bell are highlighted in the status line.
4513 .It Xo Ic monitor-silence
4516 Monitor for silence (no activity) in the window within
4519 Windows that have been silent for the interval are highlighted in the
4521 An interval of zero disables the monitoring.
4523 .It Ic other-pane-height Ar height
4524 Set the height of the other panes (not the main pane) in the
4527 If this option is set to 0 (the default), it will have no effect.
4529 .Ic main-pane-height
4531 .Ic other-pane-height
4532 options are set, the main pane will grow taller to make the other panes the
4533 specified height, but will never shrink to do so.
4536 this is a percentage of the window size.
4538 .It Ic other-pane-width Ar width
4540 .Ic other-pane-height ,
4541 but set the width of other panes in the
4545 .It Ic pane-active-border-style Ar style
4546 Set the pane border style for the currently active pane.
4552 Attributes are ignored.
4554 .It Ic pane-base-index Ar index
4557 but set the starting index for pane numbers.
4559 .It Ic pane-border-format Ar format
4560 Set the text shown in pane border status lines.
4562 .It Xo Ic pane-border-indicators
4563 .Op Ic off | colour | arrows | both
4565 Indicate active pane by colouring only half of the border in windows with
4566 exactly two panes, by displaying arrow markers, by drawing both or neither.
4568 .It Ic pane-border-lines Ar type
4569 Set the type of characters used for drawing pane borders.
4574 single lines using ACS or UTF-8 characters
4576 double lines using UTF-8 characters
4578 heavy lines using UTF-8 characters
4580 simple ASCII characters
4588 will fall back to standard ACS line drawing when UTF-8 is not supported.
4590 .It Xo Ic pane-border-status
4591 .Op Ic off | top | bottom
4593 Turn pane border status lines off or set their position.
4595 .It Ic pane-border-style Ar style
4596 Set the pane border style for panes aside from the active pane.
4602 Attributes are ignored.
4604 .It Ic popup-style Ar style
4605 Set the popup style.
4608 section on how to specify
4610 Attributes are ignored.
4612 .It Ic popup-border-style Ar style
4613 Set the popup border style.
4616 section on how to specify
4618 Attributes are ignored.
4620 .It Ic popup-border-lines Ar type
4621 Set the type of characters used for drawing popup borders.
4626 single lines using ACS or UTF-8 characters (default)
4628 variation of single with rounded corners using UTF-8 characters
4630 double lines using UTF-8 characters
4632 heavy lines using UTF-8 characters
4634 simple ASCII characters
4636 simple ASCII space character
4644 will fall back to standard ACS line drawing when UTF-8 is not supported.
4646 .It Ic window-status-activity-style Ar style
4647 Set status line style for windows with an activity alert.
4654 .It Ic window-status-bell-style Ar style
4655 Set status line style for windows with a bell alert.
4662 .It Ic window-status-current-format Ar string
4664 .Ar window-status-format ,
4665 but is the format used when the window is the current window.
4667 .It Ic window-status-current-style Ar style
4668 Set status line style for the currently active window.
4675 .It Ic window-status-format Ar string
4676 Set the format in which the window is displayed in the status line window list.
4683 .It Ic window-status-last-style Ar style
4684 Set status line style for the last active window.
4691 .It Ic window-status-separator Ar string
4692 Sets the separator drawn between windows in the status line.
4693 The default is a single space character.
4695 .It Ic window-status-style Ar style
4696 Set status line style for a single window.
4703 .It Xo Ic window-size
4704 .Ar largest | Ar smallest | Ar manual | Ar latest
4708 determines the window size.
4711 the size of the largest attached session is used; if
4713 the size of the smallest.
4716 the size of a new window is set from the
4718 option and windows are resized automatically.
4722 uses the size of the client that had the most recent activity.
4726 .Ic aggressive-resize
4729 .It Xo Ic wrap-search
4732 If this option is set, searches will wrap around the end of the pane contents.
4736 Available pane options are:
4738 .Bl -tag -width Ds -compact
4739 .It Xo Ic allow-passthrough
4740 .Op Ic on | off | all
4742 Allow programs in the pane to bypass
4744 using a terminal escape sequence (\eePtmux;...\ee\e\e).
4747 passthrough sequences will be allowed only if the pane is visible.
4750 they will be allowed even if the pane is invisible.
4752 .It Xo Ic allow-rename
4755 Allow programs in the pane to change the window name using a terminal escape
4756 sequence (\eek...\ee\e\e).
4758 .It Xo Ic allow-set-title
4761 Allow programs in the pane to change the title using the terminal escape
4762 sequences (\ee]2;...\ee\e\e or \ee]0;...\ee\e\e).
4764 .It Xo Ic alternate-screen
4767 This option configures whether programs running inside the pane may use the
4768 terminal alternate screen feature, which allows the
4774 The alternate screen feature preserves the contents of the window when an
4775 interactive application starts and restores it on exit, so that any output
4776 visible before the application starts reappears unchanged after it exits.
4778 .It Ic cursor-colour Ar colour
4779 Set the colour of the cursor.
4781 .It Ic pane-colours[] Ar colour
4782 The default colour palette.
4783 Each entry in the array defines the colour
4785 uses when the colour with that index is requested.
4786 The index may be from zero to 255.
4788 .It Ic cursor-style Ar style
4789 Set the style of the cursor.
4790 Available styles are:
4792 .Ic blinking-block ,
4794 .Ic blinking-underline ,
4799 .It Xo Ic remain-on-exit
4800 .Op Ic on | off | failed
4802 A pane with this flag set is not destroyed when the program running in it
4806 then only when the program exit status is not zero.
4807 The pane may be reactivated with the
4811 .It Ic remain-on-exit-format Ar string
4812 Set the text shown at the bottom of exited panes when
4816 .It Xo Ic scroll-on-clear
4819 When the entire screen is cleared and this option is on, scroll the contents of
4820 the screen into history before clearing it.
4822 .It Xo Ic synchronize-panes
4825 Duplicate input to all other panes in the same window where this option is also
4826 on (only for panes that are not in any mode).
4828 .It Ic window-active-style Ar style
4829 Set the pane style when it is the active pane.
4836 .It Ic window-style Ar style
4846 allows commands to run on various triggers, called
4852 hook and there are a number of hooks not associated with commands.
4854 Hooks are stored as array options, members of the array are executed in
4855 order when the hook is triggered.
4856 Like options different hooks may be global or belong to a session, window or
4858 Hooks may be configured with the
4862 commands and displayed with
4867 The following two commands are equivalent:
4868 .Bd -literal -offset indent.
4869 set-hook -g pane-mode-changed[42] \[aq]set -g status-left-style bg=red\[aq]
4870 set-option -g pane-mode-changed[42] \[aq]set -g status-left-style bg=red\[aq]
4873 Setting a hook without specifying an array index clears the hook and sets the
4874 first member of the array.
4877 hook is run after it completes, except when the command is run as part of a hook
4879 They are named with an
4882 For example, the following command adds a hook to select the even-vertical
4885 .Bd -literal -offset indent
4886 set-hook -g after-split-window "selectl even-vertical"
4889 If a command fails, the
4892 For example, this could be used to write to a log file:
4893 .Bd -literal -offset indent
4894 set-hook -g command-error "run-shell \\"echo 'a tmux command failed' >>/tmp/log\\""
4897 All the notifications listed in the
4899 section are hooks (without any arguments), except
4901 The following additional hooks are available:
4902 .Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX"
4904 Run when a window has activity.
4906 .Ic monitor-activity .
4908 Run when a window has received a bell.
4912 Run when a window has been silent.
4914 .Ic monitor-silence .
4916 Run when a client becomes the latest active client of its session.
4918 Run when a client is attached.
4920 Run when a client is detached
4922 Run when focus enters a client
4923 .It client-focus-out
4924 Run when focus exits a client
4926 Run when a client is resized.
4927 .It client-session-changed
4928 Run when a client's attached session is changed.
4930 Run when a command fails.
4932 Run when the program running in a pane exits, but
4934 is on so the pane has not closed.
4936 Run when the program running in a pane exits.
4938 Run when the focus enters a pane, if the
4942 Run when the focus exits a pane, if the
4945 .It pane-set-clipboard
4946 Run when the terminal clipboard is set using the
4950 Run when a new session created.
4952 Run when a session closed.
4954 Run when a session is renamed.
4956 Run when a window is linked into a session.
4958 Run when a window is renamed.
4960 Run when a window is resized.
4961 This may be after the
4965 Run when a window is unlinked from a session.
4968 Hooks are managed with these commands:
4972 .Op Fl t Ar target-pane
4984 The flags are the same as for
4992 .It Xo Ic show-hooks
4994 .Op Fl t Ar target-pane
4997 The flags are the same as for
5003 option is on (the default is off),
5005 allows mouse events to be bound as keys.
5006 The name of each key is made up of a mouse event (such as
5008 and a location suffix, one of the following:
5009 .Bl -column "XXXXXXXXXXXXX" -offset indent
5010 .It Li "Pane" Ta "the contents of a pane"
5011 .It Li "Border" Ta "a pane border"
5012 .It Li "Status" Ta "the status line window list"
5013 .It Li "StatusLeft" Ta "the left part of the status line"
5014 .It Li "StatusRight" Ta "the right part of the status line"
5015 .It Li "StatusDefault" Ta "any other part of the status line"
5018 The following mouse events are available:
5019 .Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
5020 .It Li "WheelUp" Ta "WheelDown" Ta ""
5021 .It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
5022 .It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
5023 .It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
5024 .It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3"
5025 .It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3"
5026 .It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3"
5031 events are fired for the second click of a double click, even if there may be a
5032 third click which will fire
5037 Each should be suffixed with a location, for example
5038 .Ql MouseDown1Status .
5048 in commands bound to mouse key bindings.
5049 It resolves to the window or pane over which the mouse event took place
5050 (for example, the window in the status line over which button 1 was released
5053 binding, or the pane over which the wheel was scrolled for a
5060 flag may be used to forward a mouse event to a pane.
5062 The default key bindings allow the mouse to be used to select and resize panes,
5063 to copy text and to change window using the status line.
5064 These take effect if the
5066 option is turned on.
5068 Certain commands accept the
5073 This is a string which controls the output format of the command.
5074 Format variables are enclosed in
5079 .Ql #{session_name} .
5080 The possible variables are listed in the table below, or the name of a
5082 option may be used for an option's value.
5083 Some variables have a shorter alias such as
5086 is replaced by a single
5096 Conditionals are available by prefixing with
5098 and separating two alternatives with a comma;
5099 if the specified variable exists and is not zero, the first alternative
5100 is chosen, otherwise the second is used.
5102 .Ql #{?session_attached,attached,not attached}
5103 will include the string
5105 if the session is attached and the string
5107 if it is unattached, or
5108 .Ql #{?automatic-rename,yes,no}
5112 .Ic automatic-rename
5116 Conditionals can be nested arbitrarily.
5117 Inside a conditional,
5125 unless they are part of a
5129 .Bd -literal -offset indent
5130 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
5133 String comparisons may be expressed by prefixing two comma-separated
5144 .Ql #{==:#{host},myhost}
5154 evaluate to true if either or both of two comma-separated alternatives are
5156 .Ql #{||:#{pane_in_mode},#{alternate_on}} .
5162 or regular expression comparison.
5163 The first argument is the pattern and the second the string to compare.
5164 An optional argument specifies flags:
5166 means the pattern is a regular expression instead of the default
5170 means to ignore case.
5172 .Ql #{m:*foo*,#{host}}
5174 .Ql #{m/ri:^A,MYVAR} .
5177 performs a search for an
5179 pattern or regular expression in the pane content and evaluates to zero if not
5180 found, or a line number if found.
5185 flag means search for a regular expression and
5191 Numeric operators may be performed by prefixing two comma-separated alternatives
5197 flag may be given after the operator to use floating point numbers, otherwise
5199 This may be followed by a number giving the number of decimal places to use for
5201 The available operators are:
5218 in formats which are also expanded by
5220 and numeric comparison operators
5229 .Ql #{e|*|f|4:5.5,3}
5230 multiplies 5.5 by 3 for a result with four decimal places and
5232 returns the modulus of 7 and 3.
5234 replaces a numeric argument by its ASCII equivalent, so
5241 colour by its six-digit hexadecimal RGB value.
5243 A limit may be placed on the length of the resultant string by prefixing it
5246 a number and a colon.
5247 Positive numbers count from the start of the string and negative from the end,
5249 .Ql #{=5:pane_title}
5250 will include at most the first five characters of the pane title, or
5251 .Ql #{=-5:pane_title}
5252 the last five characters.
5253 A suffix or prefix may be given as a second argument - if provided then it is
5254 appended or prepended to the string if the length has been trimmed, for example
5255 .Ql #{=/5/...:pane_title}
5258 if the pane title is more than five characters.
5261 pads the string to a given width, for example
5262 .Ql #{p10:pane_title}
5263 will result in a width of at least 10 characters.
5264 A positive width pads on the left, a negative on the right.
5266 expands to the length of the variable and
5268 to its width when displayed, for example
5269 .Ql #{n:window_name} .
5271 Prefixing a time variable with
5273 will convert it to a string, so if
5274 .Ql #{window_activity}
5277 .Ql #{t:window_activity}
5279 .Ql Sun Oct 25 09:25:02 2015 .
5283 will use shorter but less accurate time format for times in the past.
5284 A custom format may be given using an
5290 if the format is separately being passed through
5295 .Ql #{t/f/%%H#:%%M:window_activity} ,
5307 of the variable respectively.
5311 special characters or with a
5313 suffix, escape hash characters (so
5318 will expand the format twice, for example
5319 .Ql #{E:status-left}
5320 is the result of expanding the content of the
5322 option rather than the option itself.
5334 will loop over each session, window, pane or client and insert the format once
5336 For windows and panes, two comma-separated formats may be given:
5337 the second is used for the current window or active pane.
5338 For example, to get a list of windows formatted like the status line:
5339 .Bd -literal -offset indent
5340 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
5344 checks if a window (without any suffix or with the
5346 suffix) or a session (with the
5348 suffix) name exists, for example
5350 is replaced with 1 if a window named
5354 A prefix of the form
5361 The first argument may be an extended regular expression and a final argument
5364 to ignore case, for example
5365 .Ql s/a(.)/\e1x/i:\&
5370 A different delimiter character may also be used, to avoid collisions with
5371 literal slashes in the pattern.
5380 In addition, the last line of a shell command's output may be inserted using
5384 will insert the system's uptime.
5385 When constructing formats,
5389 commands to finish; instead, the previous result from running the same command
5390 is used, or a placeholder if the command has not been run before.
5391 If the command hasn't exited, the most recent line of output will be used, but
5392 the status line will not be updated more than once a second.
5393 Commands are executed using
5397 global environment set (see the
5398 .Sx GLOBAL AND SESSION ENVIRONMENT
5403 specifies that a string should be interpreted literally and not expanded.
5405 .Ql #{l:#{?pane_in_mode,yes,no}}
5407 .Ql #{?pane_in_mode,yes,no} .
5409 The following variables are available, where appropriate:
5410 .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
5411 .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
5412 .It Li "active_window_index" Ta "" Ta "Index of active window in session"
5413 .It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen"
5414 .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
5415 .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
5416 .It Li "buffer_created" Ta "" Ta "Time buffer created"
5417 .It Li "buffer_name" Ta "" Ta "Name of buffer"
5418 .It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
5419 .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
5420 .It Li "client_activity" Ta "" Ta "Time client last had activity"
5421 .It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels"
5422 .It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels"
5423 .It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
5424 .It Li "client_created" Ta "" Ta "Time client created"
5425 .It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind"
5426 .It Li "client_flags" Ta "" Ta "List of client flags"
5427 .It Li "client_height" Ta "" Ta "Height of client"
5428 .It Li "client_key_table" Ta "" Ta "Current key table"
5429 .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
5430 .It Li "client_name" Ta "" Ta "Name of client"
5431 .It Li "client_pid" Ta "" Ta "PID of client process"
5432 .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
5433 .It Li "client_readonly" Ta "" Ta "1 if client is read-only"
5434 .It Li "client_session" Ta "" Ta "Name of the client's session"
5435 .It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any"
5436 .It Li "client_termname" Ta "" Ta "Terminal name of client"
5437 .It Li "client_termtype" Ta "" Ta "Terminal type of client, if available"
5438 .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
5439 .It Li "client_uid" Ta "" Ta "UID of client process"
5440 .It Li "client_user" Ta "" Ta "User of client process"
5441 .It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8"
5442 .It Li "client_width" Ta "" Ta "Width of client"
5443 .It Li "client_written" Ta "" Ta "Bytes written to client"
5444 .It Li "command" Ta "" Ta "Name of command in use, if any"
5445 .It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
5446 .It Li "command_list_name" Ta "" Ta "Command name if listing commands"
5447 .It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
5448 .It Li "config_files" Ta "" Ta "List of configuration files loaded"
5449 .It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode"
5450 .It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode"
5451 .It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode"
5452 .It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode"
5453 .It Li "current_file" Ta "" Ta "Current configuration file"
5454 .It Li "cursor_character" Ta "" Ta "Character at cursor in pane"
5455 .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
5456 .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
5457 .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
5458 .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
5459 .It Li "history_limit" Ta "" Ta "Maximum window history lines"
5460 .It Li "history_size" Ta "" Ta "Size of history in lines"
5461 .It Li "hook" Ta "" Ta "Name of running hook, if any"
5462 .It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any"
5463 .It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
5464 .It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
5465 .It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
5466 .It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
5467 .It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
5468 .It Li "host" Ta "#H" Ta "Hostname of local host"
5469 .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
5470 .It Li "insert_flag" Ta "" Ta "Pane insert flag"
5471 .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
5472 .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
5473 .It Li "last_window_index" Ta "" Ta "Index of last window in session"
5474 .It Li "line" Ta "" Ta "Line number in the list"
5475 .It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
5476 .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
5477 .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
5478 .It Li "mouse_hyperlink" Ta "" Ta "Hyperlink under mouse, if any"
5479 .It Li "mouse_line" Ta "" Ta "Line under mouse, if any"
5480 .It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag"
5481 .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
5482 .It Li "mouse_status_line" Ta "" Ta "Status line on which mouse event took place"
5483 .It Li "mouse_status_range" Ta "" Ta "Range type or argument of mouse event on status line"
5484 .It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag"
5485 .It Li "mouse_word" Ta "" Ta "Word under mouse, if any"
5486 .It Li "mouse_x" Ta "" Ta "Mouse X position, if any"
5487 .It Li "mouse_y" Ta "" Ta "Mouse Y position, if any"
5488 .It Li "next_session_id" Ta "" Ta "Unique session ID for next new session"
5489 .It Li "origin_flag" Ta "" Ta "Pane origin flag"
5490 .It Li "pane_active" Ta "" Ta "1 if active pane"
5491 .It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window"
5492 .It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window"
5493 .It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window"
5494 .It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window"
5495 .It Li "pane_bg" Ta "" Ta "Pane background colour"
5496 .It Li "pane_bottom" Ta "" Ta "Bottom of pane"
5497 .It Li "pane_current_command" Ta "" Ta "Current command if available"
5498 .It Li "pane_current_path" Ta "" Ta "Current path if available"
5499 .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
5500 .It Li "pane_dead_signal" Ta "" Ta "Exit signal of process in dead pane"
5501 .It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
5502 .It Li "pane_dead_time" Ta "" Ta "Exit time of process in dead pane"
5503 .It Li "pane_fg" Ta "" Ta "Pane foreground colour"
5504 .It Li "pane_format" Ta "" Ta "1 if format is for a pane"
5505 .It Li "pane_height" Ta "" Ta "Height of pane"
5506 .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
5507 .It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode"
5508 .It Li "pane_index" Ta "#P" Ta "Index of pane"
5509 .It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled"
5510 .It Li "pane_last" Ta "" Ta "1 if last pane"
5511 .It Li "pane_left" Ta "" Ta "Left of pane"
5512 .It Li "pane_marked" Ta "" Ta "1 if this is the marked pane"
5513 .It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set"
5514 .It Li "pane_mode" Ta "" Ta "Name of pane mode, if any"
5515 .It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)"
5516 .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
5517 .It Li "pane_pipe" Ta "" Ta "1 if pane is being piped"
5518 .It Li "pane_right" Ta "" Ta "Right of pane"
5519 .It Li "pane_search_string" Ta "" Ta "Last search string in copy mode"
5520 .It Li "pane_start_command" Ta "" Ta "Command pane started with"
5521 .It Li "pane_start_path" Ta "" Ta "Path pane started with"
5522 .It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized"
5523 .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
5524 .It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)"
5525 .It Li "pane_top" Ta "" Ta "Top of pane"
5526 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
5527 .It Li "pane_unseen_changes" Ta "" Ta "1 if there were changes in pane while in mode"
5528 .It Li "pane_width" Ta "" Ta "Width of pane"
5529 .It Li "pid" Ta "" Ta "Server PID"
5530 .It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated"
5531 .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
5532 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
5533 .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
5534 .It Li "search_match" Ta "" Ta "Search match if any"
5535 .It Li "search_present" Ta "" Ta "1 if search started in copy mode"
5536 .It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode"
5537 .It Li "selection_end_x" Ta "" Ta "X position of the end of the selection"
5538 .It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection"
5539 .It Li "selection_present" Ta "" Ta "1 if selection started in copy mode"
5540 .It Li "selection_start_x" Ta "" Ta "X position of the start of the selection"
5541 .It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection"
5542 .It Li "server_sessions" Ta "" Ta "Number of sessions"
5543 .It Li "session_activity" Ta "" Ta "Time of session last activity"
5544 .It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
5545 .It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
5546 .It Li "session_attached_list" Ta "" Ta "List of clients session is attached to"
5547 .It Li "session_created" Ta "" Ta "Time session created"
5548 .It Li "session_format" Ta "" Ta "1 if format is for a session"
5549 .It Li "session_group" Ta "" Ta "Name of session group"
5550 .It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to"
5551 .It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to"
5552 .It Li "session_group_list" Ta "" Ta "List of sessions in group"
5553 .It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group"
5554 .It Li "session_group_size" Ta "" Ta "Size of session group"
5555 .It Li "session_grouped" Ta "" Ta "1 if session in a group"
5556 .It Li "session_id" Ta "" Ta "Unique session ID"
5557 .It Li "session_last_attached" Ta "" Ta "Time session last attached"
5558 .It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
5559 .It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane"
5560 .It Li "session_name" Ta "#S" Ta "Name of session"
5561 .It Li "session_path" Ta "" Ta "Working directory of session"
5562 .It Li "session_stack" Ta "" Ta "Window indexes in most recent order"
5563 .It Li "session_windows" Ta "" Ta "Number of windows in session"
5564 .It Li "socket_path" Ta "" Ta "Server socket path"
5565 .It Li "start_time" Ta "" Ta "Server start time"
5566 .It Li "uid" Ta "" Ta "Server UID"
5567 .It Li "user" Ta "" Ta "Server user"
5568 .It Li "version" Ta "" Ta "Server version"
5569 .It Li "window_active" Ta "" Ta "1 if window active"
5570 .It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window"
5571 .It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window"
5572 .It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active"
5573 .It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active"
5574 .It Li "window_activity" Ta "" Ta "Time of window last activity"
5575 .It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
5576 .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
5577 .It Li "window_bigger" Ta "" Ta "1 if window is larger than client"
5578 .It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels"
5579 .It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels"
5580 .It Li "window_end_flag" Ta "" Ta "1 if window has the highest index"
5581 .It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##"
5582 .It Li "window_format" Ta "" Ta "1 if format is for a window"
5583 .It Li "window_height" Ta "" Ta "Height of window"
5584 .It Li "window_id" Ta "" Ta "Unique window ID"
5585 .It Li "window_index" Ta "#I" Ta "Index of window"
5586 .It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
5587 .It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
5588 .It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
5589 .It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to"
5590 .It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to"
5591 .It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane"
5592 .It Li "window_name" Ta "#W" Ta "Name of window"
5593 .It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client"
5594 .It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client"
5595 .It Li "window_panes" Ta "" Ta "Number of panes in window"
5596 .It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped"
5597 .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
5598 .It Li "window_stack_index" Ta "" Ta "Index in session most recent stack"
5599 .It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index"
5600 .It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
5601 .It Li "window_width" Ta "" Ta "Width of window"
5602 .It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
5603 .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
5607 offers various options to specify the colour and attributes of aspects of the
5608 interface, for example
5610 for the status line.
5611 In addition, embedded styles may be specified in format options, such as
5613 by enclosing them in
5618 A style may be the single term
5620 to specify the default style (which may come from an option, for example
5622 in the status line) or a space
5623 or comma separated list of the following:
5626 Set the foreground colour.
5627 The colour is one of:
5636 if supported the bright variants
5643 from the 256-colour set;
5645 for the default colour;
5647 for the terminal default colour; or a hexadecimal RGB string such as
5650 Set the background colour.
5652 Set the underscore colour.
5654 Set no attributes (turn off any active attributes).
5667 .Ic double-underscore ,
5668 .Ic curly-underscore ,
5669 .Ic dotted-underscore ,
5670 .Ic dashed-underscore
5673 Any of the attributes may be prefixed with
5677 is the terminal alternate character set.
5678 .It Xo Ic align=left
5684 Align text to the left, centre or right of the available space if appropriate.
5686 Fill the available space with a background colour if appropriate.
5689 .Ic list=left-marker ,
5690 .Ic list=right-marker ,
5693 Mark the position of the various window list components in the
5697 marks the start of the list;
5699 is the part of the list that should be kept in focus if the entire list won't
5700 fit in the available space (typically the current window);
5701 .Ic list=left-marker
5703 .Ic list=right-marker
5704 mark the text to be used to mark that text has been trimmed from the left or
5705 right of the list if there is not enough space.
5706 .It Xo Ic push-default ,
5709 Store the current colours and attributes as the default or reset to the previous
5713 affects any subsequent use of the
5717 Only one default may be pushed (each
5719 replaces the previous saved default).
5720 .It Xo Ic range=left ,
5722 .Ic range=session|X ,
5723 .Ic range=window|X ,
5728 Mark a range for mouse events in the
5731 When a mouse event occurs in the
5739 key bindings are triggered.
5741 .Ic range=session|X ,
5745 are ranges for a session, window or pane.
5748 mouse key with the target session, window or pane given by the
5752 is a session ID, window index in the current session or a pane ID.
5754 .Ic mouse_status_range
5755 format variable will be set to
5762 is a user-defined range; it triggers the
5767 will be available in the
5768 .Ic mouse_status_range
5771 must be at most 15 bytes in length.
5775 .Bd -literal -offset indent
5776 fg=yellow bold underscore blink
5777 bg=black,fg=default,noreverse
5779 .Sh NAMES AND TITLES
5781 distinguishes between names and titles.
5782 Windows and sessions have names, which may be used to specify them in targets
5783 and are displayed in the status line and various lists: the name is the
5785 identifier for a window or session.
5786 Only panes have titles.
5787 A pane's title is typically set by the program running inside the pane using
5788 an escape sequence (like it would set the
5792 Windows themselves do not have titles - a window's title is the title of its
5795 itself may set the title of the terminal in which the client is running, see
5800 A session's name is set with the
5805 A window's name is set with one of:
5808 A command argument (such as
5815 An escape sequence (if the
5817 option is turned on):
5818 .Bd -literal -offset indent
5819 $ printf \[aq]\e033kWINDOW_NAME\e033\e\e\[aq]
5822 Automatic renaming, which sets the name to the active command in the window's
5825 .Ic automatic-rename
5829 When a pane is first created, its title is the hostname.
5830 A pane's title can be set via the title setting escape sequence, for example:
5831 .Bd -literal -offset indent
5832 $ printf \[aq]\e033]2;My Title\e033\e\e\[aq]
5835 It can also be modified with the
5839 .Sh GLOBAL AND SESSION ENVIRONMENT
5840 When the server is started,
5842 copies the environment into the
5843 .Em global environment ;
5844 in addition, each session has a
5845 .Em session environment .
5846 When a window is created, the session and global environments are merged.
5847 If a variable exists in both, the value from the session environment is used.
5848 The result is the initial environment passed to the new process.
5851 .Ic update-environment
5852 session option may be used to update the session environment from the client
5853 when a new session is created or an old reattached.
5855 also initialises the
5857 variable with some internal information to allow commands to be executed
5858 from inside, and the
5860 variable with the correct terminal setting of
5863 Variables in both session and global environments may be marked as hidden.
5864 Hidden variables are not passed into the environment of new processes and
5865 instead can only be used by tmux itself (for example in formats, see the
5869 Commands to alter and view the environment are:
5872 .It Xo Ic set-environment
5874 .Op Fl t Ar target-session
5875 .Ar name Op Ar value
5877 .D1 Pq alias: Ic setenv
5878 Set or unset an environment variable.
5881 is used, the change is made in the global environment; otherwise, it is applied
5882 to the session environment for
5883 .Ar target-session .
5888 is expanded as a format.
5891 flag unsets a variable.
5893 indicates the variable is to be removed from the environment before starting a
5896 marks the variable as hidden.
5898 .It Xo Ic show-environment
5900 .Op Fl t Ar target-session
5903 .D1 Pq alias: Ic showenv
5904 Display the environment for
5906 or the global environment with
5910 is omitted, all variables are shown.
5911 Variables removed from the environment are prefixed with
5915 is used, the output is formatted as a set of Bourne shell commands.
5917 shows hidden variables (omitted by default).
5921 includes an optional status line which is displayed in the bottom line of each
5924 By default, the status line is enabled and one line in height (it may be
5925 disabled or made multiple lines with the
5927 session option) and contains, from left-to-right: the name of the current
5928 session in square brackets; the window list; the title of the active pane
5929 in double quotes; and the time and date.
5931 Each line of the status line is configured with the
5934 The default is made of three parts: configurable left and right sections (which
5935 may contain dynamic content such as the time or output from a shell command,
5938 .Ic status-left-length ,
5941 .Ic status-right-length
5942 options below), and a central window list.
5943 By default, the window list shows the index, name and (if any) flag of the
5944 windows present in the current session in ascending numerical order.
5945 It may be customised with the
5946 .Ar window-status-format
5948 .Ar window-status-current-format
5950 The flag is one of the following symbols appended to the window name:
5951 .Bl -column "Symbol" "Meaning" -offset indent
5952 .It Sy "Symbol" Ta Sy "Meaning"
5953 .It Li "*" Ta "Denotes the current window."
5954 .It Li "-" Ta "Marks the last window (previously selected)."
5955 .It Li "#" Ta "Window activity is monitored and activity has been detected."
5956 .It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window."
5957 .It Li "\[ti]" Ta "The window has been silent for the monitor-silence interval."
5958 .It Li "M" Ta "The window contains the marked pane."
5959 .It Li "Z" Ta "The window's active pane is zoomed."
5962 The # symbol relates to the
5963 .Ic monitor-activity
5965 The window name is printed in inverted colours if an alert (bell, activity or
5966 silence) is present.
5968 The colour and attributes of the status line may be configured, the entire
5969 status line using the
5971 session option and individual windows using the
5972 .Ic window-status-style
5975 The status line is automatically refreshed at interval if it has changed, the
5976 interval may be controlled with the
5980 Commands related to the status line are as follows:
5983 .It Xo Ic clear-prompt-history
5984 .Op Fl T Ar prompt-type
5986 .D1 Pq alias: Ic clearphist
5987 Clear status prompt history for prompt type
5991 is omitted, then clear history for all types.
5994 for possible values for
5996 .It Xo Ic command-prompt
6000 .Op Fl t Ar target-client
6001 .Op Fl T Ar prompt-type
6004 Open the command prompt in a client.
6005 This may be used from inside
6007 to execute commands interactively.
6011 is specified, it is used as the command.
6015 is expanded as a format.
6019 is a comma-separated list of the initial text for each prompt.
6024 is a comma-separated list of prompts which are displayed in order; otherwise
6025 a single prompt is displayed, constructed from
6027 if it is present, or
6031 Before the command is executed, the first occurrence of the string
6033 and all occurrences of
6035 are replaced by the response to the first prompt, all
6037 are replaced with the response to the second prompt, and so on for further
6039 Up to nine prompt responses may be replaced
6048 but any quotation marks are escaped.
6051 makes the prompt only accept one key press, in this case the resulting input
6052 is a single character.
6056 but the key press is translated to a key name.
6058 makes the prompt only accept numeric key presses.
6060 executes the command every time the prompt input changes instead of when the
6061 user exits the command prompt.
6067 This affects what completions are offered when
6070 Available types are:
6077 The following keys have a special meaning in the command prompt, depending
6081 .Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
6082 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
6083 .It Li "Cancel command prompt" Ta "q" Ta "Escape"
6084 .It Li "Delete from cursor to start of word" Ta "" Ta "C-w"
6085 .It Li "Delete entire command" Ta "d" Ta "C-u"
6086 .It Li "Delete from cursor to end" Ta "D" Ta "C-k"
6087 .It Li "Execute command" Ta "Enter" Ta "Enter"
6088 .It Li "Get next command from history" Ta "" Ta "Down"
6089 .It Li "Get previous command from history" Ta "" Ta "Up"
6090 .It Li "Insert top paste buffer" Ta "p" Ta "C-y"
6091 .It Li "Look for completions" Ta "Tab" Ta "Tab"
6092 .It Li "Move cursor left" Ta "h" Ta "Left"
6093 .It Li "Move cursor right" Ta "l" Ta "Right"
6094 .It Li "Move cursor to end" Ta "$" Ta "C-e"
6095 .It Li "Move cursor to next word" Ta "w" Ta "M-f"
6096 .It Li "Move cursor to previous word" Ta "b" Ta "M-b"
6097 .It Li "Move cursor to start" Ta "0" Ta "C-a"
6098 .It Li "Transpose characters" Ta "" Ta "C-t"
6103 the prompt is shown in the background and the invoking client does not exit
6104 until it is dismissed.
6106 .It Xo Ic confirm-before
6108 .Op Fl c Ar confirm-key
6110 .Op Fl t Ar target-client
6113 .D1 Pq alias: Ic confirm
6114 Ask for confirmation before executing
6120 is the prompt to display; otherwise a prompt is constructed from
6122 It may contain the special character sequences supported by the
6127 the prompt is shown in the background and the invoking client does not exit
6128 until it is dismissed.
6130 changes the default behaviour (if Enter alone is pressed) of the prompt to
6133 changes the confirmation key to
6138 .It Xo Ic display-menu
6140 .Op Fl b Ar border-lines
6141 .Op Fl c Ar target-client
6142 .Op Fl C Ar starting-choice
6143 .Op Fl H Ar selected-style
6145 .Op Fl S Ar border-style
6146 .Op Fl t Ar target-pane
6148 .Op Fl x Ar position
6149 .Op Fl y Ar position
6152 .Ar command Op Ar argument ...
6154 .D1 Pq alias: Ic menu
6158 gives the target for any commands run from the menu.
6160 A menu is passed as a series of arguments: first the menu item name,
6161 second the key shortcut (or empty for none) and third the command
6162 to run when the menu item is chosen.
6163 The name and command are formats, see the
6168 If the name begins with a hyphen (-), then the item is disabled (shown dim) and
6170 The name may be empty for a separator line, in which case both the key and
6171 command should be omitted.
6174 sets the type of characters used for drawing menu borders.
6176 .Ic popup-border-lines
6177 for possible values for
6181 sets the style for the selected menu item (see
6185 sets the style for the menu and
6187 sets the style for the menu border (see
6191 is a format for the menu title (see
6195 sets the menu item selected by default, if the menu is not bound to a mouse key
6201 give the position of the menu.
6202 Both may be a row or column number, or one of the following special values:
6203 .Bl -column "XXXXX" "XXXX" -offset indent
6204 .It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning"
6205 .It Li "C" Ta "Both" Ta "The centre of the terminal"
6206 .It Li "R" Ta Fl x Ta "The right side of the terminal"
6207 .It Li "P" Ta "Both" Ta "The bottom left of the pane"
6208 .It Li "M" Ta "Both" Ta "The mouse position"
6209 .It Li "W" Ta "Both" Ta "The window position on the status line"
6210 .It Li "S" Ta Fl y Ta "The line above or below the status line"
6213 Or a format, which is expanded including the following additional variables:
6214 .Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
6215 .It Sy "Variable name" Ta Sy "Replaced with"
6216 .It Li "popup_centre_x" Ta "Centered in the client"
6217 .It Li "popup_centre_y" Ta "Centered in the client"
6218 .It Li "popup_height" Ta "Height of menu or popup"
6219 .It Li "popup_mouse_bottom" Ta "Bottom of at the mouse"
6220 .It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse"
6221 .It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse"
6222 .It Li "popup_mouse_top" Ta "Top at the mouse"
6223 .It Li "popup_mouse_x" Ta "Mouse X position"
6224 .It Li "popup_mouse_y" Ta "Mouse Y position"
6225 .It Li "popup_pane_bottom" Ta "Bottom of the pane"
6226 .It Li "popup_pane_left" Ta "Left of the pane"
6227 .It Li "popup_pane_right" Ta "Right of the pane"
6228 .It Li "popup_pane_top" Ta "Top of the pane"
6229 .It Li "popup_status_line_y" Ta "Above or below the status line"
6230 .It Li "popup_width" Ta "Width of menu or popup"
6231 .It Li "popup_window_status_line_x" Ta "At the window position in status line"
6232 .It Li "popup_window_status_line_y" Ta "At the status line showing the window"
6235 Each menu consists of items followed by a key shortcut shown in brackets.
6236 If the menu is too large to fit on the terminal, it is not displayed.
6237 Pressing the key shortcut chooses the corresponding item.
6238 If the mouse is enabled and the menu is opened from a mouse key binding,
6239 releasing the mouse button with an item selected chooses that item and
6240 releasing the mouse button without an item selected closes the menu.
6242 changes this behaviour so that the menu does not close when the mouse button is
6243 released without an item selected the menu is not closed and a mouse button
6244 must be clicked to choose an item.
6249 the menu should handle mouse events; by default only menus opened from mouse
6252 The following keys are available in menus:
6253 .Bl -column "Key" "Function" -offset indent
6254 .It Sy "Key" Ta Sy "Function"
6255 .It Li "Enter" Ta "Choose selected item"
6256 .It Li "Up" Ta "Select previous item"
6257 .It Li "Down" Ta "Select next item"
6258 .It Li "q" Ta "Exit menu"
6261 .It Xo Ic display-message
6263 .Op Fl c Ar target-client
6265 .Op Fl t Ar target-pane
6268 .D1 Pq alias: Ic display
6272 is given, the output is printed to stdout, otherwise it is displayed in the
6274 status line for up to
6281 option is used; a delay of zero waits for a key press.
6283 ignores key presses and closes only after the delay expires.
6288 is printed unchanged.
6289 Otherwise, the format of
6293 section; information is taken from
6297 is given, otherwise the active pane.
6300 prints verbose logging as the format is parsed and
6302 lists the format variables and their values.
6305 forwards any input read from stdin to the empty pane given by
6308 .It Xo Ic display-popup
6310 .Op Fl b Ar border-lines
6311 .Op Fl c Ar target-client
6312 .Op Fl d Ar start-directory
6313 .Op Fl e Ar environment
6315 .Op Fl s Ar border-style
6317 .Op Fl t Ar target-pane
6320 .Op Fl x Ar position
6321 .Op Fl y Ar position
6322 .Op Ar shell-command
6324 .D1 Pq alias: Ic popup
6325 Display a popup running
6329 A popup is a rectangular box drawn over the top of any panes.
6330 Panes are not updated while a popup is present.
6333 closes the popup automatically when
6338 closes the popup only if
6340 exited with success.
6345 give the position of the popup, they have the same meaning as for the
6351 give the width and height - both may be a percentage (followed by
6353 If omitted, half of the terminal size is used.
6356 does not surround the popup by a border.
6359 sets the type of characters used for drawing popup borders.
6366 .Ic popup-border-lines
6367 for possible values for
6371 sets the style for the popup and
6373 sets the style for the popup border (see
6379 and sets an environment variable for the popup; it may be specified multiple
6383 is a format for the popup title (see
6388 flag closes any popup on the client.
6390 .It Xo Ic show-prompt-history
6391 .Op Fl T Ar prompt-type
6393 .D1 Pq alias: Ic showphist
6394 Display status prompt history for prompt type
6398 is omitted, then show history for all types.
6401 for possible values for
6406 maintains a set of named
6408 Each buffer may be either explicitly or automatically named.
6409 Explicitly named buffers are named when created with the
6413 commands, or by renaming an automatically named buffer with
6416 Automatically named buffers are given a name such as
6422 option is reached, the oldest automatically named buffer is deleted.
6423 Explicitly named buffers are not subject to
6425 and may be deleted with the
6429 Buffers may be added using
6435 commands, and pasted into a window using the
6438 If a buffer command is used and no buffer is specified, the most
6439 recently added automatically named buffer is assumed.
6441 A configurable history buffer is also maintained for each window.
6442 By default, up to 2000 lines are kept; this can be altered with the
6448 The buffer commands are as follows:
6455 .Op Fl K Ar key-format
6456 .Op Fl O Ar sort-order
6457 .Op Fl t Ar target-pane
6460 Put a pane into buffer mode, where a buffer may be chosen interactively from
6462 Each buffer is shown on one line.
6463 A shortcut key is shown on the left in brackets allowing for immediate choice,
6464 or the list may be navigated and an item chosen or otherwise manipulated using
6468 The following keys may be used in buffer mode:
6469 .Bl -column "Key" "Function" -offset indent
6470 .It Sy "Key" Ta Sy "Function"
6471 .It Li "Enter" Ta "Paste selected buffer"
6472 .It Li "Up" Ta "Select previous buffer"
6473 .It Li "Down" Ta "Select next buffer"
6474 .It Li "C-s" Ta "Search by name or content"
6475 .It Li "n" Ta "Repeat last search forwards"
6476 .It Li "N" Ta "Repeat last search backwards"
6477 .It Li "t" Ta "Toggle if buffer is tagged"
6478 .It Li "T" Ta "Tag no buffers"
6479 .It Li "C-t" Ta "Tag all buffers"
6480 .It Li "p" Ta "Paste selected buffer"
6481 .It Li "P" Ta "Paste tagged buffers"
6482 .It Li "d" Ta "Delete selected buffer"
6483 .It Li "D" Ta "Delete tagged buffers"
6484 .It Li "e" Ta "Open the buffer in an editor"
6485 .It Li "f" Ta "Enter a format to filter items"
6486 .It Li "O" Ta "Change sort field"
6487 .It Li "r" Ta "Reverse sort order"
6488 .It Li "v" Ta "Toggle preview"
6489 .It Li "q" Ta "Exit mode"
6492 After a buffer is chosen,
6494 is replaced by the buffer name in
6496 and the result executed as a command.
6499 is not given, "paste-buffer -p -b \[aq]%%\[aq]" is used.
6502 specifies the initial sort field: one of
6509 reverses the sort order.
6511 specifies an initial filter: the filter is a format - if it evaluates to zero,
6512 the item in the list is not shown, otherwise it is shown.
6513 If a filter would lead to an empty list, it is ignored.
6515 specifies the format for each item in the list and
6517 a format for each shortcut key; both are evaluated once for each line.
6519 starts without the preview.
6520 This command works only if at least one client is attached.
6522 .It Xo Ic clear-history
6524 .Op Fl t Ar target-pane
6526 .D1 Pq alias: Ic clearhist
6527 Remove and free the history for the specified pane.
6529 also removes all hyperlinks.
6531 .It Ic delete-buffer Op Fl b Ar buffer-name
6532 .D1 Pq alias: Ic deleteb
6533 Delete the buffer named
6535 or the most recently added automatically named buffer if not specified.
6537 .It Xo Ic list-buffers
6541 .D1 Pq alias: Ic lsb
6542 List the global buffers.
6544 specifies the format of each line and
6547 Only buffers for which the filter is true are shown.
6551 .It Xo Ic load-buffer
6553 .Op Fl b Ar buffer-name
6554 .Op Fl t Ar target-client
6558 .D1 Pq alias: Ic loadb
6559 Load the contents of the specified paste buffer from
6563 is given, the buffer is also sent to the clipboard for
6567 escape sequence, if possible.
6569 .It Xo Ic paste-buffer
6571 .Op Fl b Ar buffer-name
6572 .Op Fl s Ar separator
6573 .Op Fl t Ar target-pane
6575 .D1 Pq alias: Ic pasteb
6576 Insert the contents of a paste buffer into the specified pane.
6577 If not specified, paste into the current one.
6580 also delete the paste buffer.
6581 When output, any linefeed (LF) characters in the paste buffer are replaced with
6582 a separator, by default carriage return (CR).
6583 A custom separator may be specified using the
6588 flag means to do no replacement (equivalent to a separator of LF).
6591 is specified, paste bracket control codes are inserted around the
6592 buffer if the application has requested bracketed paste mode.
6594 .It Xo Ic save-buffer
6596 .Op Fl b Ar buffer-name
6599 .D1 Pq alias: Ic saveb
6600 Save the contents of the specified paste buffer to
6604 option appends to rather than overwriting the file.
6605 .It Xo Ic set-buffer
6607 .Op Fl b Ar buffer-name
6608 .Op Fl t Ar target-client
6610 .Op Fl n Ar new-buffer-name
6613 .D1 Pq alias: Ic setb
6614 Set the contents of the specified buffer to
6618 is given, the buffer is also sent to the clipboard for
6622 escape sequence, if possible.
6625 option appends to rather than overwriting the buffer.
6628 option renames the buffer to
6629 .Ar new-buffer-name .
6631 .It Xo Ic show-buffer
6632 .Op Fl b Ar buffer-name
6634 .D1 Pq alias: Ic showb
6635 Display the contents of the specified buffer.
6638 Miscellaneous commands are as follows:
6640 .It Ic clock-mode Op Fl t Ar target-pane
6641 Display a large clock.
6645 .Op Fl t Ar target-pane
6646 .Ar shell-command command
6656 returns success or the second
6659 Before being executed,
6661 is expanded using the rules specified in the
6663 section, including those relevant to
6668 is run in the background.
6674 is not executed but considered success if neither empty nor zero (after formats
6678 .D1 Pq alias: Ic lock
6679 Lock each client individually by running the command specified by the
6685 .Op Fl c Ar start-directory
6687 .Op Fl t Ar target-pane
6688 .Op Ar shell-command
6690 .D1 Pq alias: Ic run
6699 command in the background without creating a window.
6700 Before being executed,
6702 is expanded using the rules specified in the
6707 the command is run in the background.
6711 seconds before starting the command.
6714 is given, the current working directory is set to
6715 .Ar start-directory .
6718 is not given, any output to stdout is displayed in view mode (in the pane
6721 or the current pane if omitted) after the command finishes.
6722 If the command fails, the exit status is also displayed.
6728 .D1 Pq alias: Ic wait
6729 When used without options, prevents the client from exiting until woken using
6732 with the same channel.
6735 is used, the channel is locked and any clients that try to lock the same
6736 channel are made to wait until the channel is unlocked with
6743 client detaches, it prints a message.
6746 .It detached (from session ...)
6747 The client was detached normally.
6748 .It detached and SIGHUP
6749 The client was detached and its parent sent the
6751 signal (for example with
6759 was unexpectedly destroyed.
6761 The client was killed with
6764 The client is in control mode and became unable to keep up with the data from
6767 The server exited when it had no sessions.
6769 The server exited when it received
6771 .It server exited unexpectedly
6772 The server crashed or otherwise exited without telling the client the reason.
6774 .Sh TERMINFO EXTENSIONS
6776 understands some unofficial extensions to
6778 It is not normally necessary to set these manually, instead the
6779 .Ic terminal-features
6780 option should be used.
6783 An existing extension that tells
6785 the terminal supports default colours.
6789 that the terminal supports the VTE bidirectional text extensions.
6791 Set the cursor colour.
6792 The first takes a single string argument and is used to set the colour;
6793 the second takes no arguments and restores the default cursor colour.
6794 If set, a sequence such as this may be used
6795 to change the cursor colour from inside
6797 .Bd -literal -offset indent
6798 $ printf \[aq]\e033]12;red\e033\e\e\[aq]
6805 .It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg
6806 Set, clear, disable or enable DECSLRM margins.
6807 These are set automatically if the terminal reports it is
6810 .It Em \&Dsbp , \&Enbp
6811 Disable and enable bracketed paste.
6812 These are set automatically if the
6814 capability is present.
6815 .It Em \&Dseks , \&Eneks
6816 Disable and enable extended keys.
6817 .It Em \&Dsfcs , \&Enfcs
6818 Disable and enable focus reporting.
6819 These are set automatically if the
6821 capability is present.
6823 Set or clear a hyperlink annotation.
6827 that the terminal does not use bright colors for bold display.
6831 that the terminal supports rectangle operations.
6833 Enable the overline attribute.
6835 Set a styled underscore.
6836 The single parameter is one of: 0 for no underscore, 1 for normal
6837 underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted
6838 underscore and 5 for dashed underscore.
6839 .It Em \&Setulc , \&Setulc1, \&ol
6840 Set the underscore colour or reset to the default.
6842 is for RGB colours and
6844 for ANSI or 256 colours.
6847 argument is (red * 65536) + (green * 256) + blue where each is between 0
6850 Set or reset the cursor style.
6851 If set, a sequence such as this may be used
6852 to change the cursor to an underline:
6853 .Bd -literal -offset indent
6854 $ printf \[aq]\e033[4 q\[aq]
6859 is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
6861 Set the opening sequence for the working directory notification.
6862 The sequence is terminated using the standard
6866 Indicates that the terminal supports SIXEL.
6868 Start (parameter is 1) or end (parameter is 2) a synchronized update.
6870 Indicate that the terminal supports the
6872 RGB escape sequence (for example, \ee[38;2;255;255;255m).
6874 If supported, this is used for the initialize colour escape sequence (which
6875 may be enabled by adding the
6884 This is equivalent to the
6889 Store the current buffer in the host terminal's selection (clipboard).
6892 option above and the
6896 This is an existing extension capability that tmux uses to mean that the
6897 terminal supports the
6899 title set sequences and to automatically set some of the capabilities above.
6903 offers a textual interface called
6905 This allows applications to communicate with
6907 using a simple text-only protocol.
6909 In control mode, a client sends
6911 commands or command sequences terminated by newlines on standard input.
6912 Each command will produce one block of output on standard output.
6913 An output block consists of a
6915 line followed by the output (which may be empty).
6916 The output block ends with a
6925 have three arguments: an integer time (as seconds from epoch), command number
6926 and flags (currently not used).
6928 .Bd -literal -offset indent
6929 %begin 1363006971 2 1
6930 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
6937 command may be used to set the size of a client in control mode.
6941 outputs notifications.
6942 A notification will never occur inside an output block.
6944 The following notifications are defined:
6946 .It Ic %client-detached Ar client
6947 The client has detached.
6948 .It Ic %client-session-changed Ar client session-id name
6949 The client is now attached to the session with ID
6953 .It Ic %config-error Ar error
6954 An error has happened in a configuration file.
6955 .It Ic %continue Ar pane-id
6956 The pane has been continued after being paused (if the
6961 .It Ic %exit Op Ar reason
6964 client is exiting immediately, either because it is not attached to any session
6965 or an error occurred.
6968 describes why the client exited.
6969 .It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value
6976 is the time in milliseconds for which tmux had buffered the output before it
6978 Any subsequent arguments up until a single
6980 are for future use and should be ignored.
6981 .It Xo Ic %layout-change
6984 .Ar window-visible-layout
6987 The layout of a window with ID
6992 The window's visible layout is
6993 .Ar window-visible-layout
6994 and the window flags are
6996 .It Ic %message Ar message
6997 A message sent with the
7000 .It Ic %output Ar pane-id Ar value
7001 A window pane produced output.
7003 escapes non-printable characters and backslash as octal \\xxx.
7004 .It Ic %pane-mode-changed Ar pane-id
7008 .It Ic %paste-buffer-changed Ar name
7012 .It Ic %paste-buffer-deleted Ar name
7016 .It Ic %pause Ar pane-id
7017 The pane has been paused (if the
7020 .It Ic %session-changed Ar session-id Ar name
7021 The client is now attached to the session with ID
7025 .It Ic %session-renamed Ar name
7026 The current session was renamed to
7028 .It Ic %session-window-changed Ar session-id Ar window-id
7031 changed its active window to the window with ID
7033 .It Ic %sessions-changed
7034 A session was created or destroyed.
7035 .It Xo Ic %subscription-changed
7040 .Ar pane-id ... \& :
7043 The value of the format associated with subscription
7054 are for future use and should be ignored.
7055 .It Ic %unlinked-window-add Ar window-id
7058 was created but is not linked to the current session.
7059 .It Ic %unlinked-window-close Ar window-id
7062 which is not linked to the current session, was closed.
7063 .It Ic %unlinked-window-renamed Ar window-id
7066 which is not linked to the current session, was renamed.
7067 .It Ic %window-add Ar window-id
7070 was linked to the current session.
7071 .It Ic %window-close Ar window-id
7075 .It Ic %window-pane-changed Ar window-id Ar pane-id
7076 The active pane in the window with ID
7078 changed to the pane with ID
7080 .It Ic %window-renamed Ar window-id Ar name
7089 is started, it inspects the following environment variables:
7090 .Bl -tag -width LC_CTYPE
7092 If the command specified in this variable contains the string
7096 is unset, use vi-style key bindings.
7103 The user's login directory.
7106 database is consulted.
7108 The character encoding
7110 It is used for two separate purposes.
7111 For output to the terminal, UTF-8 is used if the
7113 option is given or if
7119 Otherwise, only ASCII characters are written and non-ASCII characters
7120 are replaced with underscores
7124 always runs with a UTF-8 locale.
7125 If en_US.UTF-8 is provided by the operating system, it is used and
7127 is ignored for input.
7132 what the UTF-8 locale is called on the current system.
7133 If the locale specified by
7135 is not available or is not a UTF-8 locale,
7137 exits with an error message.
7139 The date and time format
7141 It is used for locale-dependent
7145 The current working directory to be set in the global environment.
7146 This may be useful if it contains symbolic links.
7147 If the value of the variable does not match the current working
7148 directory, the variable is ignored and the result of
7152 The absolute path to the default shell for new windows.
7157 The parent directory of the directory containing the server sockets.
7162 If the command specified in this variable contains the string
7164 use vi-style key bindings.
7172 .Bl -tag -width "@SYSCONFDIR@/tmux.confXXX" -compact
7173 .It Pa \[ti]/.tmux.conf
7174 .It Pa $XDG_CONFIG_HOME/tmux/tmux.conf
7175 .It Pa \[ti]/.config/tmux/tmux.conf
7179 .It Pa @SYSCONFDIR@/tmux.conf
7180 System-wide configuration file.
7188 .Dl $ tmux new-session vi
7190 Most commands have a shorter form, known as an alias.
7191 For new-session, this is
7196 Alternatively, the shortest unambiguous form of a command is accepted.
7197 If there are several options, they are listed:
7198 .Bd -literal -offset indent
7200 ambiguous command: n, could be: new-session, new-window, next-window
7203 Within an active session, a new window may be created by typing
7213 Windows may be navigated with:
7215 (to select window 0),
7217 (to select window 1), and so on;
7219 to select the next window; and
7221 to select the previous window.
7223 A session may be detached using
7225 (or by an external event such as
7227 disconnection) and reattached with:
7229 .Dl $ tmux attach-session
7233 lists the current key bindings in the current window; up and down may be used
7234 to navigate the list or
7238 Commands to be run when the
7240 server is started may be placed in the
7241 .Pa \[ti]/.tmux.conf
7243 Common examples include:
7245 Changing the default prefix key:
7246 .Bd -literal -offset indent
7247 set-option -g prefix C-a
7249 bind-key C-a send-prefix
7252 Turning the status line off, or changing its colour:
7253 .Bd -literal -offset indent
7254 set-option -g status off
7255 set-option -g status-style bg=blue
7258 Setting other options, such as the default command,
7259 or locking after 30 minutes of inactivity:
7260 .Bd -literal -offset indent
7261 set-option -g default-command "exec /bin/ksh"
7262 set-option -g lock-after-time 1800
7265 Creating new key bindings:
7266 .Bd -literal -offset indent
7267 bind-key b set-option status
7268 bind-key / command-prompt "split-window \[aq]exec man %%\[aq]"
7269 bind-key S command-prompt "new-window -n %1 \[aq]ssh %1\[aq]"
7274 .An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com