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
142 if present, then looks for a user configuration file at
143 .Pa \[ti]/.tmux.conf .
145 The configuration file is a set of
147 commands which are executed in sequence when the server is first started.
149 loads configuration files once when the server process has started.
152 command may be used to load a file later.
155 shows any error messages from commands in configuration files in the first
156 session created, and continues to process the rest of the configuration file.
157 .It Fl L Ar socket-name
159 stores the server socket in a directory under
164 The default socket is named
166 This option allows a different socket name to be specified, allowing several
172 a full path is not necessary: the sockets are all created in a directory
174 under the directory given by
180 directory is created by
182 and must not be world readable, writable or executable.
184 If the socket is accidentally removed, the
186 signal may be sent to the
188 server process to recreate it (note that this will fail if any parent
189 directories are missing).
191 Behave as a login shell.
192 This flag currently has no effect and is for compatibility with other shells
193 when using tmux as a login shell.
195 Do not start the server even if the command would normally do so (for example
199 .It Fl S Ar socket-path
200 Specify a full alternative path to the server socket.
203 is specified, the default socket directory is not used and any
207 Set terminal features for the client.
208 This is a comma-separated list of features.
210 .Ic terminal-features
213 Write UTF-8 output to the terminal even if the first environment
219 that is set does not contain
228 Request verbose logging.
229 Log messages will be saved into
230 .Pa tmux-client-PID.log
232 .Pa tmux-server-PID.log
233 files in the current directory, where
235 is the PID of the server or client process.
238 is specified twice, an additional
240 file is generated with a copy of everything
242 writes to the terminal.
246 signal may be sent to the
248 server process to toggle logging between on (as if
251 .It Ar command Op Ar flags
252 This specifies one of a set of commands used to control
254 as described in the following sections.
255 If no commands are specified, the
259 .Sh DEFAULT KEY BINDINGS
261 may be controlled from an attached client by using a key combination of a
264 (Ctrl-b) by default, followed by a command key.
266 The default command key bindings are:
268 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
270 Send the prefix key (C-b) through to the application.
272 Rotate the panes in the current window forwards.
278 Break the current pane out of the window.
281 Split the current pane into two, top and bottom.
283 List all paste buffers.
285 Rename the current session.
287 Split the current pane into two, left and right.
289 Kill the current window.
291 Prompt for a window index to select.
293 Switch the attached client to the previous session.
295 Switch the attached client to the next session.
297 Rename the current window.
299 Delete the most recently copied buffer of text.
301 Prompt for an index to move the current window.
303 Select windows 0 to 9.
309 Move to the previously active pane.
311 Choose which buffer to paste interactively from a list.
313 List all key bindings.
315 Choose a client to detach.
317 Switch the attached client back to the last session.
319 Enter copy mode to copy text or view the history.
321 Paste the most recently copied buffer of text.
325 Detach the current client.
327 Prompt to search for text in open windows.
329 Display some information about the current window.
331 Move to the previously selected window.
333 Mark the current pane (see
337 Clear the marked pane.
339 Change to the next window.
341 Select the next pane in the current window.
343 Change to the previous window.
345 Briefly display pane indexes.
347 Force redraw of the attached client.
349 Select a new session for the attached client interactively.
353 Choose the current window interactively.
355 Kill the current pane.
357 Toggle zoom state of the current pane.
359 Swap the current pane with the previous pane.
361 Swap the current pane with the next pane.
363 Show previous messages from
367 Enter copy mode and scroll one page up.
370 Change to the pane above, below, to the left, or to the right of the current
373 Arrange panes in one of the five preset layouts: even-horizontal,
374 even-vertical, main-horizontal, main-vertical, or tiled.
376 Arrange the current window in the next preset layout.
378 Move to the next window with a bell or activity marker.
380 Rotate the panes in the current window backwards.
382 Move to the previous window with a bell or activity marker.
385 Resize the current pane in steps of one cell.
388 Resize the current pane in steps of five cells.
391 Key bindings may be changed with the
396 .Sh COMMAND PARSING AND EXECUTION
398 supports a large number of commands which can be used to control its
400 Each command is named and can accept zero or more flags and arguments.
401 They may be bound to a key with the
403 command or run from the shell prompt, a shell script, a configuration file or
405 For example, the same
407 command run from the shell prompt, from
409 and bound to a key may look like:
410 .Bd -literal -offset indent
411 $ tmux set-option -g status-style bg=cyan
413 set-option -g status-style bg=cyan
415 bind-key C set-option -g status-style bg=cyan
418 Here, the command name is
428 distinguishes between command parsing and execution.
429 In order to execute a command,
431 needs it to be split up into its name and arguments.
432 This is command parsing.
433 If a command is run from the shell, the shell parses it; from inside
435 or from a configuration file,
441 .Bl -dash -offset indent
443 in a configuration file;
445 typed at the command prompt (see
446 .Ic command-prompt ) ;
451 passed as arguments to
457 To execute commands, each client has a
459 A global command queue not attached to any client is used on startup
460 for configuration files like
461 .Pa \[ti]/.tmux.conf .
462 Parsed commands added to the queue are executed in order.
467 parse their argument to create a new command which is inserted immediately
469 This means that arguments can be parsed twice or more - once when the parent
472 is parsed and again when it parses and executes its command.
478 stop execution of subsequent commands on the queue until something happens -
482 until a shell command finishes and
484 until a key is pressed.
485 For example, the following commands:
486 .Bd -literal -offset indent
487 new-session; new-window
488 if-shell "true" "split-window"
507 commands and their arguments.
509 This section describes the syntax of commands parsed by
511 for example in a configuration file or at the command prompt.
512 Note that when commands are entered into the shell, they are parsed by the shell
518 Each command is terminated by a newline or a semicolon (;).
519 Commands separated by semicolons together form a
521 - if a command in the sequence encounters an error, no subsequent commands are
524 It is recommended that a semicolon used as a command separator should be
525 written as an individual token, for example from
527 .Bd -literal -offset indent
528 $ tmux neww \\; splitw
532 .Bd -literal -offset indent
533 $ tmux neww \[aq];\[aq] splitw
536 Or from the tmux command prompt:
537 .Bd -literal -offset indent
541 However, a trailing semicolon is also interpreted as a command separator,
545 .Bd -literal -offset indent
546 $ tmux neww\e; splitw
550 .Bd -literal -offset indent
551 $ tmux \[aq]neww;\[aq] splitw
554 As in these examples, when running tmux from the shell extra care must be taken
555 to properly quote semicolons:
558 Semicolons that should be interpreted as a command separator
559 should be escaped according to the shell conventions.
562 this typically means quoted (such as
563 .Ql neww \[aq];\[aq] splitw )
565 .Ql neww \e\e\e\e; splitw ) .
567 Individual semicolons or trailing semicolons that should be interpreted as
568 arguments should be escaped twice: once according to the shell conventions and
572 .Bd -literal -offset indent
573 $ tmux neww \[aq]foo\e\e;\[aq] bar
574 $ tmux neww foo\e\e\e\e; bar
577 Semicolons that are not individual tokens or trailing another token should only
578 be escaped once according to shell conventions; for example:
579 .Bd -literal -offset indent
580 $ tmux neww \[aq]foo-;-bar\[aq]
581 $ tmux neww foo-\e\e;-bar
585 Comments are marked by the unquoted # character - any remaining text after a
586 comment is ignored until the end of the line.
588 If the last character of a line is \e, the line is joined with the following
589 line (the \e and the newline are completely removed).
590 This is called line continuation and applies both inside and outside quoted
591 strings and in comments, but not inside braces.
593 Command arguments may be specified as strings surrounded by single (\[aq])
594 quotes, double quotes (\[dq]) or braces ({}).
596 This is required when the argument contains any special character.
597 Single and double quoted strings cannot span multiple lines except with line
599 Braces can span multiple lines.
601 Outside of quotes and inside double quotes, these replacements are performed:
602 .Bl -dash -offset indent
604 Environment variables preceded by $ are replaced with their value from the
605 global environment (see the
606 .Sx GLOBAL AND SESSION ENVIRONMENT
609 A leading \[ti] or \[ti]user is expanded to the home directory of the current or
612 \euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to
613 the given four or eight digit hexadecimal number.
615 When preceded (escaped) by a \e, the following characters are replaced: \ee by
616 the escape character; \er by a carriage return; \en by a newline; and \et by a
619 \eooo is replaced by a character of the octal value ooo.
620 Three octal digits are required, for example \e001.
621 The largest valid character is \e377.
623 Any other characters preceded by \e are replaced by themselves (that is, the \e
624 is removed) and are not treated as having any special meaning - so for example
625 \e; will not mark a command sequence and \e$ will not expand an environment
629 Braces are parsed as a configuration file (so conditions such as
631 are processed) and then converted into a string.
632 They are designed to avoid the need for additional escaping when passing a
635 commands as an argument (for example to
637 These two examples produce an identical command - note that no escaping is
638 needed when using {}:
639 .Bd -literal -offset indent
641 display -p \[aq]brace-dollar-foo: }$foo\[aq]
644 if-shell true "display -p \[aq]brace-dollar-foo: }\e$foo\[aq]"
647 Braces may be enclosed inside braces, for example:
648 .Bd -literal -offset indent
649 bind x if-shell "true" {
656 Environment variables may be set by using the syntax
659 .Ql HOME=/home/user .
660 Variables set during parsing are added to the global environment.
661 A hidden variable may be set with
664 .Bd -literal -offset indent
668 Hidden variables are not passed to the environment of processes created
671 .Sx GLOBAL AND SESSION ENVIRONMENT
674 Commands may be parsed conditionally by surrounding them with
684 is expanded as a format (see
686 and if it evaluates to false (zero or empty), subsequent text is ignored until
693 .Bd -literal -offset indent
694 %if "#{==:#{host},myhost}"
695 set -g status-style bg=red
696 %elif "#{==:#{host},myotherhost}"
697 set -g status-style bg=green
699 set -g status-style bg=blue
703 Will change the status line to red if running on
707 or blue if running on another host.
708 Conditionals may be given on one line, for example:
709 .Bd -literal -offset indent
710 %if #{==:#{host},myhost} set -g status-style bg=red %endif
713 This section describes the commands supported by
715 Most commands accept the optional
725 These specify the client, session, window or pane which a command should affect.
728 should be the name of the client,
731 file to which the client is connected, for example either of
735 for the client attached to
737 If no client is specified,
739 attempts to work out the client currently in use; if that fails, an error is
741 Clients may be listed with the
746 is tried as, in order:
749 A session ID prefixed with a $.
751 An exact name of a session (as listed by the
755 The start of a session name, for example
757 would match a session named
762 pattern which is matched against the session name.
765 If the session name is prefixed with an
767 only an exact match is accepted (so
769 will only match exactly
774 If a single session is found, it is used as the target session; multiple matches
776 If a session is omitted, the current session is used if available; if no
777 current session is available, the most recently used is chosen.
784 specifies a window in the form
785 .Em session Ns \&: Ns Em window .
787 follows the same rules as for
791 is looked for in order as:
794 A special token, listed below.
796 A window index, for example
798 is window 1 in session
801 A window ID, such as @1.
803 An exact window name, such as
804 .Ql mysession:mywindow .
806 The start of a window name, such as
807 .Ql mysession:mywin .
811 pattern matched against the window name.
816 prefix will do an exact match only.
817 An empty window name specifies the next unused index if appropriate (for
823 otherwise the current window in
827 The following special tokens are available to indicate particular windows.
828 Each has a single-character alternative form.
829 .Bl -column "XXXXXXXXXX" "X"
830 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
831 .It Li "{start}" Ta "^" Ta "The lowest-numbered window"
832 .It Li "{end}" Ta "$" Ta "The highest-numbered window"
833 .It Li "{last}" Ta "!" Ta "The last (previously current) window"
834 .It Li "{next}" Ta "+" Ta "The next window by number"
835 .It Li "{previous}" Ta "-" Ta "The previous window by number"
843 may be a pane ID or takes a similar form to
845 but with the optional addition of a period followed by a pane index or pane ID,
847 .Ql mysession:mywindow.1 .
848 If the pane index is omitted, the currently active pane in the specified
850 The following special tokens are available for the pane index:
851 .Bl -column "XXXXXXXXXXXXXX" "X"
852 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
853 .It Li "{last}" Ta "!" Ta "The last (previously active) pane"
854 .It Li "{next}" Ta "+" Ta "The next pane by number"
855 .It Li "{previous}" Ta "-" Ta "The previous pane by number"
856 .It Li "{top}" Ta "" Ta "The top pane"
857 .It Li "{bottom}" Ta "" Ta "The bottom pane"
858 .It Li "{left}" Ta "" Ta "The leftmost pane"
859 .It Li "{right}" Ta "" Ta "The rightmost pane"
860 .It Li "{top-left}" Ta "" Ta "The top-left pane"
861 .It Li "{top-right}" Ta "" Ta "The top-right pane"
862 .It Li "{bottom-left}" Ta "" Ta "The bottom-left pane"
863 .It Li "{bottom-right}" Ta "" Ta "The bottom-right pane"
864 .It Li "{up-of}" Ta "" Ta "The pane above the active pane"
865 .It Li "{down-of}" Ta "" Ta "The pane below the active pane"
866 .It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane"
867 .It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane"
874 may be followed by an offset, for example:
875 .Bd -literal -offset indent
884 may consist entirely of the token
888 to specify the session, window or pane where the most recent mouse event
896 to specify the marked pane (see
900 Sessions, window and panes are each numbered with a unique ID; session IDs are
907 These are unique and are unchanged for the life of the session, window or pane
911 The pane ID is passed to the child process of the pane in the
913 environment variable.
914 IDs may be displayed using the
922 .Ic display-message ,
933 This may be a single argument passed to the shell, for example:
934 .Bd -literal -offset indent
935 new-window \[aq]vi \[ti]/.tmux.conf\[aq]
939 .Bd -literal -offset indent
940 /bin/sh -c \[aq]vi \[ti]/.tmux.conf\[aq]
952 to be given as multiple arguments and executed directly (without
954 This can avoid issues with shell quoting.
956 .Bd -literal -offset indent
957 $ tmux new-window vi \[ti]/.tmux.conf
962 directly without invoking the shell.
968 command, either passed with the command and arguments separately, for example:
969 .Bd -literal -offset indent
970 bind-key F1 set-option status off
973 Or passed as a single string argument in
976 .Bd -literal -offset indent
977 bind-key F1 { set-option status off }
983 .Bd -literal -offset indent
984 refresh-client -t/dev/ttyp2
986 rename-session -tfirst newname
988 set-option -wt:0 monitor-activity on
990 new-window ; split-window -d
992 bind-key R source-file \[ti]/.tmux.conf \e; \e
993 display-message "source-file done"
998 .Bd -literal -offset indent
999 $ tmux kill-window -t :1
1001 $ tmux new-window \e; split-window -d
1003 $ tmux new-session -d \[aq]vi \[ti]/.tmux.conf\[aq] \e; split-window -d \e; attach
1005 .Sh CLIENTS AND SESSIONS
1008 server manages clients, sessions, windows and panes.
1009 Clients are attached to sessions to interact with them, either
1010 when they are created with the
1012 command, or later with the
1015 Each session has one or more windows
1018 Windows may be linked to multiple sessions and are made up of one or
1020 each of which contains a pseudo terminal.
1021 Commands for creating, linking and otherwise manipulating windows
1024 .Sx WINDOWS AND PANES
1027 The following commands are available to manage clients and sessions:
1030 .It Xo Ic attach-session
1032 .Op Fl c Ar working-directory
1034 .Op Fl t Ar target-session
1036 .D1 Pq alias: Ic attach
1039 create a new client in the current terminal and attach it to
1040 .Ar target-session .
1041 If used from inside, switch the current client.
1044 is specified, any other clients attached to the session are detached.
1049 to the parent process of the client as well as
1050 detaching the client, typically causing it to exit.
1052 sets a comma-separated list of client flags.
1056 the client has an independent active pane
1058 the client does not affect the size of other clients
1060 the client does not receive pane output in control mode
1061 .It pause-after=seconds
1062 output is paused once the pane is
1064 behind in control mode
1066 the client is read-only
1068 wait for an empty line input before exiting in control mode
1073 turns a flag off if the client is already attached.
1077 .Ar read-only,ignore-size .
1078 When a client is read-only, only keys bound to the
1082 commands have any effect.
1085 flag allows the active pane to be selected independently of the window's active
1086 pane used by clients without the flag.
1087 This only affects the cursor position and commands issued from the client;
1088 other features such as hooks and styles continue to use the window's active
1091 If no server is started,
1093 will attempt to start it; this will fail unless sessions are created in the
1100 are slightly adjusted: if
1102 needs to select the most recently used session, it will prefer the most
1108 will set the session working directory (used for new windows) to
1109 .Ar working-directory .
1114 .Ic update-environment
1115 option will not be applied.
1117 .It Xo Ic detach-client
1119 .Op Fl E Ar shell-command
1120 .Op Fl s Ar target-session
1121 .Op Fl t Ar target-client
1123 .D1 Pq alias: Ic detach
1124 Detach the current client if bound to a key, the client specified with
1126 or all clients currently attached to the session specified by
1130 option kills all but the client given with
1136 to the parent process of the client, typically causing it
1142 to replace the client.
1144 .It Ic has-session Op Fl t Ar target-session
1145 .D1 Pq alias: Ic has
1146 Report an error and exit with 1 if the specified session does not exist.
1147 If it does exist, exit with 0.
1151 server and clients and destroy all sessions.
1152 .It Xo Ic kill-session
1154 .Op Fl t Ar target-session
1156 Destroy the given session, closing any windows linked to it and no other
1157 sessions, and detaching all clients attached to it.
1160 is given, all sessions but the specified one is killed.
1163 flag clears alerts (bell, activity, or silence) in all windows linked to the
1166 .It Xo Ic list-clients
1169 .Op Fl t Ar target-session
1171 .D1 Pq alias: Ic lsc
1172 List all clients attached to the server.
1174 specifies the format of each line and
1177 Only clients for which the filter is true are shown.
1183 is specified, list only clients connected to that session.
1185 .It Xo Ic list-commands
1189 .D1 Pq alias: Ic lscm
1192 or - if omitted - of all commands supported by
1195 .It Xo Ic list-sessions
1200 List all sessions managed by the server.
1202 specifies the format of each line and
1205 Only sessions for which the filter is true are shown.
1210 .It Ic lock-client Op Fl t Ar target-client
1211 .D1 Pq alias: Ic lockc
1218 .It Ic lock-session Op Fl t Ar target-session
1219 .D1 Pq alias: Ic locks
1220 Lock all clients attached to
1221 .Ar target-session .
1223 .It Xo Ic new-session
1225 .Op Fl c Ar start-directory
1226 .Op Fl e Ar environment
1229 .Op Fl n Ar window-name
1230 .Op Fl s Ar session-name
1231 .Op Fl t Ar group-name
1234 .Op Ar shell-command
1236 .D1 Pq alias: Ic new
1237 Create a new session with name
1240 The new session is attached to the current terminal unless
1246 are the name of and shell command to execute in the initial window.
1249 the initial size comes from the global
1255 can be used to specify a different size.
1257 uses the size of the current client if any.
1264 option is set for the session.
1266 sets a comma-separated list of client flags (see
1267 .Ic attach-session ) .
1269 If run from a terminal, any
1271 special characters are saved and used for new windows in the new session.
1289 .Ic attach-session ,
1295 .Ic attach-session .
1299 is given, it specifies a
1301 Sessions in the same group share the same set of windows - new windows are
1302 linked to all sessions in the group and any windows closed removed from all
1304 The current and previous window and any session options remain independent and
1305 any session in a group may be killed without affecting the others.
1311 the name of an existing group, in which case the new session is added to that
1314 the name of an existing session - the new session is added to the same group
1315 as that session, creating a new group if necessary;
1317 the name for a new group containing only the new session.
1329 option prints information about the new session after it has been created.
1330 By default, it uses the format
1331 .Ql #{session_name}:\&
1332 but a different format may be specified with
1338 .Ic update-environment
1339 option will not be applied.
1343 and sets an environment variable for the newly created session; it may be
1344 specified multiple times.
1346 .It Xo Ic refresh-client
1348 .Op Fl A Ar pane:state
1349 .Op Fl B Ar name:what:format
1352 .Op Fl l Op Ar target-pane
1353 .Op Fl t Ar target-client
1356 .D1 Pq alias: Ic refresh
1357 Refresh the current client if bound to a key, or a single client if one is given
1362 is specified, only update the client's status line.
1371 flags allow the visible portion of a window which is larger than the client
1374 moves the visible part up by
1386 returns to tracking the cursor automatically.
1389 is omitted, 1 is used.
1390 Note that the visible position is a property of the client not of the
1391 window, changing the current window in the attached session will reset
1395 sets the width and height of a control mode client or of a window for a
1396 control mode client,
1401 .Ql window ID:widthxheight ,
1407 allows a control mode client to trigger actions on a pane.
1408 The argument is a pane ID (with leading
1410 a colon, then one of
1419 will not send output from the pane to the client and if all clients have turned
1420 the pane off, will stop reading from the pane.
1424 will return to sending output to the pane if it was paused (manually or with the
1430 will pause the pane.
1432 may be given multiple times for different panes.
1435 sets a subscription to a format for a control mode client.
1436 The argument is split into three items by colons:
1438 is a name for the subscription;
1440 is a type of item to subscribe to;
1443 After a subscription is added, changes to the format are reported with the
1444 .Ic %subscription-changed
1445 notification, at most once a second.
1446 If only the name is given, the subscription is removed.
1448 may be empty to check the format only for the attached session, or one of:
1452 for all panes in the attached session;
1457 for all windows in the attached session.
1460 sets a comma-separated list of client flags, see
1461 .Ic attach-session .
1464 requests the clipboard from the client using the
1469 is given, the clipboard is sent (in encoded form), otherwise it is stored in a
1477 move the visible portion of the window left, right, up or down
1480 if the window is larger than the client.
1482 resets so that the position follows the cursor.
1487 .It Xo Ic rename-session
1488 .Op Fl t Ar target-session
1491 .D1 Pq alias: Ic rename
1492 Rename the session to
1494 .It Xo Ic server-access
1498 Change the access or read/write permission of
1500 The user running the
1502 server (its owner) and the root user cannot be changed and are always
1508 are used to give or revoke access for the specified user.
1509 If the user is already attached, the
1511 flag causes their clients to be detached.
1516 change the permissions for
1519 makes their clients read-only and
1523 lists current access permissions.
1525 By default, the access list is empty and
1527 creates sockets with file system permissions preventing access by any user
1528 other than the owner (and root).
1529 These permissions must be changed manually.
1530 Great care should be taken not to allow access to untrusted users even
1533 .It Xo Ic show-messages
1535 .Op Fl t Ar target-client
1537 .D1 Pq alias: Ic showmsgs
1538 Show server messages or information.
1539 Messages are stored, up to a maximum of the limit set by the
1545 show debugging information about jobs and terminals.
1547 .It Xo Ic source-file
1549 .Op Fl t Ar target-pane
1552 .D1 Pq alias: Ic source
1553 Execute commands from one or more files specified by
1562 is expanded as a format.
1565 is given, no error will be returned if
1570 the file is parsed but no commands are executed.
1572 shows the parsed commands and line numbers if possible.
1575 .D1 Pq alias: Ic start
1578 server, if not already running, without creating any sessions.
1580 Note that as by default the
1582 server will exit with no sessions, this is only useful if a session is created
1584 .Pa \[ti]/.tmux.conf ,
1586 is turned off, or another command is run as part of the same command sequence.
1588 .Bd -literal -offset indent
1589 $ tmux start \\; show -g
1592 .It Xo Ic suspend-client
1593 .Op Fl t Ar target-client
1595 .D1 Pq alias: Ic suspendc
1596 Suspend a client by sending
1600 .It Xo Ic switch-client
1602 .Op Fl c Ar target-client
1603 .Op Fl t Ar target-session
1604 .Op Fl T Ar key-table
1606 .D1 Pq alias: Ic switchc
1607 Switch the current session for client
1610 .Ar target-session .
1613 may refer to a pane (a target that contains
1618 to change session, window and pane.
1621 keeps the window zoomed if it was zoomed.
1627 is used, the client is moved to the last, next or previous session
1641 .Ic update-environment
1642 option will not be applied.
1645 sets the client's key table; the next key from the client will be interpreted
1648 This may be used to configure multiple prefix keys, or to bind commands to
1650 For example, to make typing
1655 .Bd -literal -offset indent
1656 bind-key -Ttable2 c list-keys
1657 bind-key -Ttable1 b switch-client -Ttable2
1658 bind-key -Troot a switch-client -Ttable1
1661 .Sh WINDOWS AND PANES
1662 Each window displayed by
1664 may be split into one or more
1666 each pane takes up a certain area of the display and is a separate terminal.
1667 A window may be split into panes using the
1670 Windows may be split horizontally (with the
1672 flag) or vertically.
1673 Panes may be resized with the
1681 by default), the current pane may be changed with the
1687 commands may be used to swap panes without changing their position.
1688 Panes are numbered beginning from zero in the order they are created.
1692 pane permits direct access to the terminal contained in the pane.
1693 A pane may also be put into one of several modes:
1694 .Bl -dash -offset indent
1696 Copy mode, which permits a section of a window or its
1697 history to be copied to a
1699 for later insertion into another window.
1700 This mode is entered with the
1705 Copied text can be pasted with the
1710 View mode, which is like copy mode but is entered when a command that produces
1713 is executed from a key binding.
1715 Choose mode, which allows an item to be chosen from a list.
1716 This may be a client, a session or window or pane, or a buffer.
1717 This mode is entered with the
1725 In copy mode an indicator is displayed in the top-right corner of the pane with
1726 the current position and the number of lines in the history.
1728 Commands are sent to copy mode using the
1733 When a key is pressed, copy mode automatically uses one of two key tables,
1741 Key tables may be viewed with the
1745 The following commands are supported in copy mode:
1748 .Ic append-selection
1750 Append the selection to the top paste buffer.
1752 .Ic append-selection-and-cancel
1755 Append the selection to the top paste buffer and exit copy mode.
1757 .Ic back-to-indentation
1761 Move the cursor back to the indentation.
1772 Move to the bottom line.
1784 Clear the current selection.
1786 .Ic copy-end-of-line
1789 Copy from the cursor position to the end of the line.
1791 is used to name the new paste buffer.
1793 .Ic copy-end-of-line-and-cancel
1796 Copy from the cursor position and exit copy mode.
1801 Copy the entire line.
1803 .Ic copy-line-and-cancel
1806 Copy the entire line and exit copy mode.
1811 Copies the current selection.
1813 .Ic copy-selection-and-cancel
1818 Copy the current selection and exit copy mode.
1824 Move the cursor down.
1830 Move the cursor left.
1836 Move the cursor right.
1848 Move the cursor to the end of the line.
1855 Move the cursor to a specific line.
1861 Scroll to the bottom of the history.
1867 Scroll to the top of the history.
1873 Repeat the last jump.
1880 Jump backwards to the specified text.
1887 Jump forward to the specified text.
1893 Jump to the last mark.
1899 Move to the middle line.
1901 .Ic next-matching-bracket
1905 Move to the next matching bracket.
1911 Move to the next paragraph.
1916 Move to the next prompt.
1921 Move to the next word.
1927 Scroll down by one page.
1933 Scroll up by one page.
1935 .Ic previous-matching-bracket
1938 Move to the previous matching bracket.
1940 .Ic previous-paragraph
1944 Move to the previous paragraph.
1949 Move to the previous prompt.
1955 Move to the previous word.
1957 .Ic rectangle-toggle
1961 Toggle rectangle selection mode.
1963 .Ic refresh-from-pane
1967 Refresh the content from the pane.
1973 Repeat the last search.
1979 Search backwards for the specified text.
1985 Search forward for the specified text.
1990 Select the current line.
1994 Select the current word.
2000 Move the cursor to the start of the line.
2006 Move to the top line.
2009 The search commands come in several varieties:
2013 search for a regular expression;
2016 variants search for a plain text string rather than a regular expression;
2018 perform an incremental search and expect to be used with the
2024 repeats the last search and
2026 does the same but reverses the direction (forward becomes backward and backward
2033 move between shell prompts, but require the shell to emit an escape sequence
2034 (\e033]133;A\e033\e\e) to tell
2036 where the prompts are located; if the shell does not do this, these commands
2040 flag jumps to the beginning of the command output instead of the shell prompt.
2042 Copy commands may take an optional buffer prefix argument which is used
2043 to generate the buffer name (the default is
2045 so buffers are named
2049 Pipe commands take a command argument which is the command to which the
2050 selected text is piped.
2052 variants also copy the selection.
2055 variants of some commands exit copy mode after they have completed (for copy
2056 commands) or when the cursor reaches the bottom (for scrolling commands).
2058 variants do not clear the selection.
2060 The next and previous word keys skip over whitespace and treat consecutive
2061 runs of either word separators or other letters as words.
2062 Word separators can be customized with the
2065 Next word moves to the start of the next word, next word end to the end of the
2066 next word and previous word to the start of the previous word.
2067 The three next and previous space keys work similarly but use a space alone as
2071 to the empty string makes next/previous word equivalent to next/previous space.
2073 The jump commands enable quick movement within a line.
2074 For instance, typing
2078 will move the cursor to the next
2080 character on the current line.
2083 will then jump to the next occurrence.
2085 Commands in copy mode may be prefaced by an optional repeat count.
2086 With vi key bindings, a prefix is entered using the number keys; with
2087 emacs, the Alt (meta) key and a number begins prefix entry.
2089 The synopsis for the
2095 .Op Fl s Ar src-pane
2096 .Op Fl t Ar target-pane
2101 option scrolls one page up.
2103 begins a mouse drag (only valid if bound to a mouse key binding, see
2104 .Sx MOUSE SUPPORT ) .
2106 hides the position indicator in the top right.
2108 cancels copy mode and any other modes.
2116 specifies that scrolling to the bottom of the history (to the visible screen)
2117 should exit copy mode.
2118 While in copy mode, pressing a key other than those used for scrolling will
2119 disable this behaviour.
2120 This is intended to allow fast scrolling through a pane's history, for
2122 .Bd -literal -offset indent
2123 bind PageUp copy-mode -eu
2127 A number of preset arrangements of panes are available, these are called
2129 These may be selected with the
2131 command or cycled with
2135 by default); once a layout is chosen, panes within it may be moved and resized
2138 The following layouts are supported:
2140 .It Ic even-horizontal
2141 Panes are spread out evenly from left to right across the window.
2142 .It Ic even-vertical
2143 Panes are spread evenly from top to bottom.
2144 .It Ic main-horizontal
2145 A large (main) pane is shown at the top of the window and the remaining panes
2146 are spread from left to right in the leftover space at the bottom.
2148 .Em main-pane-height
2149 window option to specify the height of the top pane.
2150 .It Ic main-vertical
2153 but the large pane is placed on the left and the others spread from top to
2154 bottom along the right.
2159 Panes are spread out as evenly as possible over the window in both rows and
2165 may be used to apply a previously used layout - the
2167 command displays the layout of each window in a form suitable for use with
2170 .Bd -literal -offset indent
2173 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
2174 $ tmux select-layout \[aq]bb62,159x48,0,0{79x48,0,0,79x48,80,0}\[aq]
2178 automatically adjusts the size of the layout for the current window size.
2179 Note that a layout cannot be applied to a window with more panes than that
2180 from which the layout was originally defined.
2182 Commands related to windows and panes are as follows:
2185 .It Xo Ic break-pane
2188 .Op Fl n Ar window-name
2189 .Op Fl s Ar src-pane
2190 .Op Fl t Ar dst-window
2192 .D1 Pq alias: Ic breakp
2195 off from its containing window to make it the only pane in
2201 the window is moved to the next index after or before (existing windows are
2202 moved if necessary).
2205 is given, the new window does not become the current window.
2208 option prints information about the new window after it has been created.
2209 By default, it uses the format
2210 .Ql #{session_name}:#{window_index}.#{pane_index}
2211 but a different format may be specified with
2214 .It Xo Ic capture-pane
2216 .Op Fl b Ar buffer-name
2217 .Op Fl E Ar end-line
2218 .Op Fl S Ar start-line
2219 .Op Fl t Ar target-pane
2221 .D1 Pq alias: Ic capturep
2222 Capture the contents of a pane.
2225 is given, the output goes to stdout, otherwise to the buffer specified with
2227 or a new buffer if omitted.
2230 is given, the alternate screen is used, and the history is not accessible.
2231 If no alternate screen exists, an error will be returned unless
2236 is given, the output includes escape sequences for text and background
2239 also escapes non-printable characters as octal \exxx.
2241 ignores trailing positions that do not contain a character.
2243 preserves trailing spaces at each line's end and
2245 preserves trailing spaces and joins any wrapped lines;
2250 captures only any output that the pane has received that is the beginning of an
2251 as-yet incomplete escape sequence.
2256 specify the starting and ending line numbers, zero is the first line of the
2257 visible pane and negative numbers are lines in the history.
2261 is the start of the history and to
2263 the end of the visible pane.
2264 The default is to capture only the visible contents of the pane.
2270 .Op Fl K Ar key-format
2271 .Op Fl O Ar sort-order
2272 .Op Fl t Ar target-pane
2275 Put a pane into client mode, allowing a client to be selected interactively from
2277 Each client is shown on one line.
2278 A shortcut key is shown on the left in brackets allowing for immediate choice,
2279 or the list may be navigated and an item chosen or otherwise manipulated using
2283 The following keys may be used in client mode:
2284 .Bl -column "Key" "Function" -offset indent
2285 .It Sy "Key" Ta Sy "Function"
2286 .It Li "Enter" Ta "Choose selected client"
2287 .It Li "Up" Ta "Select previous client"
2288 .It Li "Down" Ta "Select next client"
2289 .It Li "C-s" Ta "Search by name"
2290 .It Li "n" Ta "Repeat last search"
2291 .It Li "t" Ta "Toggle if client is tagged"
2292 .It Li "T" Ta "Tag no clients"
2293 .It Li "C-t" Ta "Tag all clients"
2294 .It Li "d" Ta "Detach selected client"
2295 .It Li "D" Ta "Detach tagged clients"
2296 .It Li "x" Ta "Detach and HUP selected client"
2297 .It Li "X" Ta "Detach and HUP tagged clients"
2298 .It Li "z" Ta "Suspend selected client"
2299 .It Li "Z" Ta "Suspend tagged clients"
2300 .It Li "f" Ta "Enter a format to filter items"
2301 .It Li "O" Ta "Change sort field"
2302 .It Li "r" Ta "Reverse sort order"
2303 .It Li "v" Ta "Toggle preview"
2304 .It Li "q" Ta "Exit mode"
2307 After a client is chosen,
2309 is replaced by the client name in
2311 and the result executed as a command.
2314 is not given, "detach-client -t \[aq]%%\[aq]" is used.
2317 specifies the initial sort field: one of
2326 reverses the sort order.
2328 specifies an initial filter: the filter is a format - if it evaluates to zero,
2329 the item in the list is not shown, otherwise it is shown.
2330 If a filter would lead to an empty list, it is ignored.
2332 specifies the format for each item in the list and
2334 a format for each shortcut key; both are evaluated once for each line.
2336 starts without the preview.
2337 This command works only if at least one client is attached.
2343 .Op Fl K Ar key-format
2344 .Op Fl O Ar sort-order
2345 .Op Fl t Ar target-pane
2348 Put a pane into tree mode, where a session, window or pane may be chosen
2349 interactively from a tree.
2350 Each session, window or pane is shown on one line.
2351 A shortcut key is shown on the left in brackets allowing for immediate choice,
2352 or the tree may be navigated and an item chosen or otherwise manipulated using
2355 starts with sessions collapsed and
2357 with windows collapsed.
2360 The following keys may be used in tree mode:
2361 .Bl -column "Key" "Function" -offset indent
2362 .It Sy "Key" Ta Sy "Function"
2363 .It Li "Enter" Ta "Choose selected item"
2364 .It Li "Up" Ta "Select previous item"
2365 .It Li "Down" Ta "Select next item"
2366 .It Li "+" Ta "Expand selected item"
2367 .It Li "-" Ta "Collapse selected item"
2368 .It Li "M-+" Ta "Expand all items"
2369 .It Li "M--" Ta "Collapse all items"
2370 .It Li "x" Ta "Kill selected item"
2371 .It Li "X" Ta "Kill tagged items"
2372 .It Li "<" Ta "Scroll list of previews left"
2373 .It Li ">" Ta "Scroll list of previews right"
2374 .It Li "C-s" Ta "Search by name"
2375 .It Li "m" Ta "Set the marked pane"
2376 .It Li "M" Ta "Clear the marked pane"
2377 .It Li "n" Ta "Repeat last search"
2378 .It Li "t" Ta "Toggle if item is tagged"
2379 .It Li "T" Ta "Tag no items"
2380 .It Li "C-t" Ta "Tag all items"
2381 .It Li "\&:" Ta "Run a command for each tagged item"
2382 .It Li "f" Ta "Enter a format to filter items"
2383 .It Li "H" Ta "Jump to the starting pane"
2384 .It Li "O" Ta "Change sort field"
2385 .It Li "r" Ta "Reverse sort order"
2386 .It Li "v" Ta "Toggle preview"
2387 .It Li "q" Ta "Exit mode"
2390 After a session, window or pane is chosen, the first instance of
2392 and all instances of
2394 are replaced by the target in
2396 and the result executed as a command.
2399 is not given, "switch-client -t \[aq]%%\[aq]" is used.
2402 specifies the initial sort field: one of
2409 reverses the sort order.
2411 specifies an initial filter: the filter is a format - if it evaluates to zero,
2412 the item in the list is not shown, otherwise it is shown.
2413 If a filter would lead to an empty list, it is ignored.
2415 specifies the format for each item in the tree and
2417 a format for each shortcut key; both are evaluated once for each line.
2419 starts without the preview.
2421 includes all sessions in any session groups in the tree rather than only the
2423 This command works only if at least one client is attached.
2429 .Op Fl t Ar target-pane
2432 Put a pane into customize mode, where options and key bindings may be browsed
2433 and modified from a list.
2434 Option values in the list are shown for the active pane in the current window.
2437 The following keys may be used in customize mode:
2438 .Bl -column "Key" "Function" -offset indent
2439 .It Sy "Key" Ta Sy "Function"
2440 .It Li "Enter" Ta "Set pane, window, session or global option value"
2441 .It Li "Up" Ta "Select previous item"
2442 .It Li "Down" Ta "Select next item"
2443 .It Li "+" Ta "Expand selected item"
2444 .It Li "-" Ta "Collapse selected item"
2445 .It Li "M-+" Ta "Expand all items"
2446 .It Li "M--" Ta "Collapse all items"
2447 .It Li "s" Ta "Set option value or key attribute"
2448 .It Li "S" Ta "Set global option value"
2449 .It Li "w" Ta "Set window option value, if option is for pane and window"
2450 .It Li "d" Ta "Set an option or key to the default"
2451 .It Li "D" Ta "Set tagged options and tagged keys to the default"
2452 .It Li "u" Ta "Unset an option (set to default value if global) or unbind a key"
2453 .It Li "U" Ta "Unset tagged options and unbind tagged keys"
2454 .It Li "C-s" Ta "Search by name"
2455 .It Li "n" Ta "Repeat last search"
2456 .It Li "t" Ta "Toggle if item is tagged"
2457 .It Li "T" Ta "Tag no items"
2458 .It Li "C-t" Ta "Tag all items"
2459 .It Li "f" Ta "Enter a format to filter items"
2460 .It Li "v" Ta "Toggle option information"
2461 .It Li "q" Ta "Exit mode"
2465 specifies an initial filter: the filter is a format - if it evaluates to zero,
2466 the item in the list is not shown, otherwise it is shown.
2467 If a filter would lead to an empty list, it is ignored.
2469 specifies the format for each item in the tree.
2471 starts without the option information.
2472 This command works only if at least one client is attached.
2477 .Op Fl d Ar duration
2478 .Op Fl t Ar target-client
2481 .D1 Pq alias: Ic displayp
2482 Display a visible indicator of each pane shown by
2485 .Ic display-panes-colour
2487 .Ic display-panes-active-colour
2489 The indicator is closed when a key is pressed (unless
2493 milliseconds have passed.
2497 .Ic display-panes-time
2499 A duration of zero means the indicator stays until a key is pressed.
2500 While the indicator is on screen, a pane may be chosen with the
2504 keys, which will cause
2506 to be executed as a command with
2508 substituted by the pane ID.
2511 is "select-pane -t \[aq]%%\[aq]".
2514 other commands are not blocked from running until the indicator is closed.
2516 .It Xo Ic find-window
2518 .Op Fl t Ar target-pane
2521 .D1 Pq alias: Ic findw
2528 in window names, titles, and visible content (but not history).
2529 The flags control matching behavior:
2531 matches only visible window contents,
2533 matches only the window name and
2535 matches only the window title.
2537 makes the search ignore case.
2543 This command works only if at least one client is attached.
2548 .Op Fl s Ar src-pane
2549 .Op Fl t Ar dst-pane
2551 .D1 Pq alias: Ic joinp
2554 but instead of splitting
2556 and creating a new pane, split it and move
2559 This can be used to reverse
2565 to be joined to left of or above
2570 is omitted and a marked pane is present (see
2573 the marked pane is used rather than the current pane.
2577 .Op Fl t Ar target-pane
2579 .D1 Pq alias: Ic killp
2580 Destroy the given pane.
2581 If no panes remain in the containing window, it is also destroyed.
2584 option kills all but the pane given with
2587 .It Xo Ic kill-window
2589 .Op Fl t Ar target-window
2591 .D1 Pq alias: Ic killw
2592 Kill the current window or the window at
2594 removing it from any sessions to which it is linked.
2597 option kills all but the window given with
2602 .Op Fl t Ar target-window
2604 .D1 Pq alias: Ic lastp
2605 Select the last (previously selected) pane.
2607 keeps the window zoomed if it was zoomed.
2611 disables input to the pane.
2613 .It Ic last-window Op Fl t Ar target-session
2614 .D1 Pq alias: Ic last
2615 Select the last (previously selected) window.
2618 is specified, select the last window of the current session.
2620 .It Xo Ic link-window
2622 .Op Fl s Ar src-window
2623 .Op Fl t Ar dst-window
2625 .D1 Pq alias: Ic linkw
2632 is specified and no such window exists, the
2639 the window is moved to the next index after or before
2641 (existing windows are moved if necessary).
2646 exists, it is killed, otherwise an error is generated.
2649 is given, the newly linked window is not selected.
2651 .It Xo Ic list-panes
2657 .D1 Pq alias: Ic lsp
2662 is ignored and all panes on the server are listed.
2667 is a session (or the current session).
2668 If neither is given,
2670 is a window (or the current window).
2672 specifies the format of each line and
2675 Only panes for which the filter is true are shown.
2680 .It Xo Ic list-windows
2684 .Op Fl t Ar target-session
2686 .D1 Pq alias: Ic lsw
2689 is given, list all windows on the server.
2690 Otherwise, list windows in the current session or in
2691 .Ar target-session .
2693 specifies the format of each line and
2696 Only windows for which the filter is true are shown.
2704 .Op Fl s Ar src-pane
2705 .Op Fl t Ar dst-pane
2707 .D1 Pq alias: Ic movep
2711 .It Xo Ic move-window
2713 .Op Fl s Ar src-window
2714 .Op Fl t Ar dst-window
2716 .D1 Pq alias: Ic movew
2719 except the window at
2725 all windows in the session are renumbered in sequential order, respecting
2730 .It Xo Ic new-window
2732 .Op Fl c Ar start-directory
2733 .Op Fl e Ar environment
2735 .Op Fl n Ar window-name
2736 .Op Fl t Ar target-window
2737 .Op Ar shell-command
2739 .D1 Pq alias: Ic neww
2740 Create a new window.
2745 the new window is inserted at the next index after or before the specified
2747 moving windows up if necessary;
2750 is the new window location.
2754 is given, the session does not make the new window the current window.
2756 represents the window to be created; if the target already exists an error is
2759 flag is used, in which case it is destroyed.
2762 is given and a window named
2764 already exists, it is selected (unless
2766 is also given in which case the command does nothing).
2769 is the command to execute.
2772 is not specified, the value of the
2776 specifies the working directory in which the new window is created.
2778 When the shell command completes, the window closes.
2781 option to change this behaviour.
2786 and sets an environment variable for the newly created window; it may be
2787 specified multiple times.
2791 environment variable must be set to
2795 for all programs running
2798 New windows will automatically have
2800 added to their environment, but care must be taken not to reset this in shell
2801 start-up files or by the
2807 option prints information about the new window after it has been created.
2808 By default, it uses the format
2809 .Ql #{session_name}:#{window_index}
2810 but a different format may be specified with
2813 .It Ic next-layout Op Fl t Ar target-window
2814 .D1 Pq alias: Ic nextl
2815 Move a window to the next layout and rearrange the panes to fit.
2817 .It Xo Ic next-window
2819 .Op Fl t Ar target-session
2821 .D1 Pq alias: Ic next
2822 Move to the next window in the session.
2825 is used, move to the next window with an alert.
2829 .Op Fl t Ar target-pane
2830 .Op Ar shell-command
2832 .D1 Pq alias: Ic pipep
2833 Pipe output sent by the program in
2835 to a shell command or vice versa.
2836 A pane may only be connected to one command at a time, any existing pipe is
2842 string may contain the special character sequences supported by the
2847 is given, the current pipe (if any) is closed.
2852 specify which of the
2854 output streams are connected to the pane:
2857 stdout is connected (so anything
2859 prints is written to the pane as if it were typed);
2862 stdin is connected (so any output in the pane is piped to
2863 .Ar shell-command ) .
2864 Both may be used together and if neither are specified,
2870 option only opens a new pipe if no previous pipe exists, allowing a pipe to
2871 be toggled with a single key, for example:
2872 .Bd -literal -offset indent
2873 bind-key C-p pipe-pane -o \[aq]cat >>\[ti]/output.#I-#P\[aq]
2876 .It Xo Ic previous-layout
2877 .Op Fl t Ar target-window
2879 .D1 Pq alias: Ic prevl
2880 Move to the previous layout in the session.
2882 .It Xo Ic previous-window
2884 .Op Fl t Ar target-session
2886 .D1 Pq alias: Ic prev
2887 Move to the previous window in the session.
2890 move to the previous window with an alert.
2892 .It Xo Ic rename-window
2893 .Op Fl t Ar target-window
2896 .D1 Pq alias: Ic renamew
2897 Rename the current window, or the window at
2902 .It Xo Ic resize-pane
2904 .Op Fl t Ar target-pane
2909 .D1 Pq alias: Ic resizep
2910 Resize a pane, up, down, left or right by
2926 is given in lines or columns (the default is 1);
2930 may be a given as a number of lines or columns or followed by
2932 for a percentage of the window size (for example
2936 the active pane is toggled between zoomed (occupying the whole of the window)
2937 and unzoomed (its normal position in the layout).
2940 begins mouse resizing (only valid if bound to a mouse key binding, see
2941 .Sx MOUSE SUPPORT ) .
2944 trims all lines below the current cursor position and moves lines out of the
2945 history to replace them.
2947 .It Xo Ic resize-window
2949 .Op Fl t Ar target-window
2954 .D1 Pq alias: Ic resizew
2955 Resize a window, up, down, left or right by
2971 is given in lines or cells (the default is 1).
2973 sets the size of the largest session containing the window;
2975 the size of the smallest.
2976 This command will automatically set
2978 to manual in the window options.
2980 .It Xo Ic respawn-pane
2982 .Op Fl c Ar start-directory
2983 .Op Fl e Ar environment
2984 .Op Fl t Ar target-pane
2985 .Op Ar shell-command
2987 .D1 Pq alias: Ic respawnp
2988 Reactivate a pane in which the command has exited (see the
2993 is not given, the command used when the pane was created or last respawned is
2995 The pane must be already inactive, unless
2997 is given, in which case any existing command is killed.
2999 specifies a new working directory for the pane.
3002 option has the same meaning as for the
3006 .It Xo Ic respawn-window
3008 .Op Fl c Ar start-directory
3009 .Op Fl e Ar environment
3010 .Op Fl t Ar target-window
3011 .Op Ar shell-command
3013 .D1 Pq alias: Ic respawnw
3014 Reactivate a window in which the command has exited (see the
3019 is not given, the command used when the window was created or last respawned is
3021 The window must be already inactive, unless
3023 is given, in which case any existing command is killed.
3025 specifies a new working directory for the window.
3028 option has the same meaning as for the
3032 .It Xo Ic rotate-window
3034 .Op Fl t Ar target-window
3036 .D1 Pq alias: Ic rotatew
3037 Rotate the positions of the panes within a window, either upward (numerically
3040 or downward (numerically higher).
3042 keeps the window zoomed if it was zoomed.
3044 .It Xo Ic select-layout
3046 .Op Fl t Ar target-pane
3049 .D1 Pq alias: Ic selectl
3050 Choose a specific layout for a window.
3053 is not given, the last preset layout used (if any) is reapplied.
3057 are equivalent to the
3063 applies the last set layout if possible (undoes the most recent layout change).
3065 spreads the current pane and any panes next to it out evenly.
3067 .It Xo Ic select-pane
3070 .Op Fl t Ar target-pane
3072 .D1 Pq alias: Ic selectp
3075 the active pane in its window.
3082 is used, respectively the pane below, to the left, to the right, or above the
3083 target pane is used.
3085 keeps the window zoomed if it was zoomed.
3087 is the same as using the
3093 disables input to the pane.
3095 sets the pane title.
3100 are used to set and clear the
3102 There is one marked pane at a time, setting a new marked pane clears the last.
3103 The marked pane is the default target for
3112 .It Xo Ic select-window
3114 .Op Fl t Ar target-window
3116 .D1 Pq alias: Ic selectw
3117 Select the window at
3123 are equivalent to the
3131 is given and the selected window is already the current window,
3132 the command behaves like
3135 .It Xo Ic split-window
3137 .Op Fl c Ar start-directory
3138 .Op Fl e Ar environment
3140 .Op Fl t Ar target-pane
3141 .Op Ar shell-command
3144 .D1 Pq alias: Ic splitw
3145 Create a new pane by splitting
3148 does a horizontal split and
3150 a vertical split; if neither is specified,
3155 option specifies the size of the new pane in lines (for vertical split) or in
3156 columns (for horizontal split);
3160 to specify a percentage of the available space.
3163 option causes the new pane to be created to the left of or above
3167 option creates a new pane spanning the full window height (with
3169 or full window width (with
3171 instead of splitting the active pane.
3173 zooms if the window is not zoomed, or keeps it zoomed if already zoomed.
3177 (\[aq]\[aq]) will create a pane with no command running in it.
3178 Output can be sent to such a pane with the
3185 is not specified or empty)
3186 will create an empty pane and forward any output from stdin to it.
3188 .Bd -literal -offset indent
3189 $ make 2>&1|tmux splitw -dI &
3192 All other options have the same meaning as for the
3198 .Op Fl s Ar src-pane
3199 .Op Fl t Ar dst-pane
3201 .D1 Pq alias: Ic swapp
3205 is used and no source pane is specified with
3208 is swapped with the previous pane (before it numerically);
3210 swaps with the next pane (after it numerically).
3214 not to change the active pane and
3216 keeps the window zoomed if it was zoomed.
3220 is omitted and a marked pane is present (see
3223 the marked pane is used rather than the current pane.
3225 .It Xo Ic swap-window
3227 .Op Fl s Ar src-window
3228 .Op Fl t Ar dst-window
3230 .D1 Pq alias: Ic swapw
3233 except the source and destination windows are swapped.
3234 It is an error if no window exists at
3238 is given, the new window does not become the current window.
3242 is omitted and a marked pane is present (see
3245 the window containing the marked pane is used rather than the current window.
3247 .It Xo Ic unlink-window
3249 .Op Fl t Ar target-window
3251 .D1 Pq alias: Ic unlinkw
3256 is given, a window may be unlinked only if it is linked to multiple sessions -
3257 windows may not be linked to no sessions;
3260 is specified and the window is linked to only one session, it is unlinked and
3265 allows a command to be bound to most keys, with or without a prefix key.
3266 When specifying keys, most represent themselves (for example
3270 Ctrl keys may be prefixed with
3278 In addition, the following special key names are accepted:
3296 .Em NPage/PageDown/PgDn ,
3297 .Em PPage/PageUp/PgUp ,
3301 Note that to bind the
3305 keys, quotation marks are necessary, for example:
3306 .Bd -literal -offset indent
3307 bind-key \[aq]"\[aq] split-window
3308 bind-key "\[aq]" new-window
3311 A command bound to the
3313 key will execute for all keys which do not have a more specific binding.
3315 Commands related to key bindings are as follows:
3321 .Op Fl T Ar key-table
3322 .Ar key command Op Ar argument ...
3324 .D1 Pq alias: Ic bind
3329 Keys are bound in a key table.
3330 By default (without -T), the key is bound in
3334 This table is used for keys pressed after the prefix key (for example,
3343 creates a new window).
3346 table is used for keys pressed without the prefix key: binding
3352 table (not recommended) means a plain
3354 will create a new window.
3359 Keys may also be bound in custom key tables and the
3362 command used to switch to them from a key binding.
3365 flag indicates this key may repeat, see the
3369 attaches a note to the key (shown with
3373 To view the default bindings and possible commands, see the
3379 .Op Fl P Ar prefix-string Fl T Ar key-table
3382 .D1 Pq alias: Ic lsk
3384 There are two forms: the default lists keys as
3388 lists only keys with attached notes and shows only the key and note for each
3391 With the default form, all key tables are listed by default.
3398 form, only keys in the
3402 key tables are listed by default;
3404 also lists only keys in
3407 specifies a prefix to print before each key and
3409 lists only the first matching key.
3411 lists the command for keys that do not have a note rather than skipping them.
3415 .Op Fl c Ar target-client
3416 .Op Fl N Ar repeat-count
3417 .Op Fl t Ar target-pane
3420 .D1 Pq alias: Ic send
3421 Send a key or keys to a window or client.
3424 is the name of the key (such as
3428 to send; if the string is not recognised as a key, it is sent as a series of
3432 is given, keys are sent to
3434 so they are looked up in the client's key table, rather than to
3436 All arguments are sent sequentially from first to last.
3437 If no keys are given and the command is bound to a key, then that key is used.
3441 flag disables key name lookup and processes the keys as literal UTF-8
3445 flag expects each key to be a hexadecimal number for an ASCII character.
3449 flag causes the terminal state to be reset.
3452 passes through a mouse event (only valid if bound to a mouse key binding, see
3453 .Sx MOUSE SUPPORT ) .
3456 is used to send a command into copy mode - see
3458 .Sx WINDOWS AND PANES
3461 specifies a repeat count and
3463 expands formats in arguments where appropriate.
3464 .It Xo Ic send-prefix
3466 .Op Fl t Ar target-pane
3468 Send the prefix key, or with
3470 the secondary prefix key, to a window as if it was pressed.
3472 .It Xo Ic unbind-key
3474 .Op Fl T Ar key-table
3477 .D1 Pq alias: Ic unbind
3478 Unbind the command bound to
3487 is present, all key bindings are removed.
3490 option prevents errors being returned.
3493 The appearance and behaviour of
3495 may be modified by changing the value of various options.
3496 There are four types of option:
3497 .Em server options ,
3498 .Em session options ,
3499 .Em window options ,
3505 server has a set of global server options which do not apply to any particular
3506 window or session or pane.
3507 These are altered with the
3510 command, or displayed with the
3515 In addition, each individual session may have a set of session options, and
3516 there is a separate set of global session options.
3517 Sessions which do not have a particular option configured inherit the value
3518 from the global session options.
3519 Session options are set or unset with the
3521 command and may be listed with the
3524 The available server and session options are listed under the
3528 Similarly, a set of window options is attached to each window and a set of pane
3529 options to each pane.
3530 Pane options inherit from window options.
3531 This means any pane option may be set as a window option to apply the option to
3532 all panes in the window without the option set, for example these commands will
3533 set the background colour to red for all panes except pane 0:
3534 .Bd -literal -offset indent
3535 set -w window-style bg=red
3536 set -pt:.0 window-style bg=blue
3539 There is also a set of global window options from which any unset window or
3540 pane options are inherited.
3541 Window and pane options are altered with
3546 commands and displayed with
3553 also supports user options which are prefixed with a
3555 User options may have any name, so long as they are prefixed with
3557 and be set to any string.
3559 .Bd -literal -offset indent
3560 $ tmux set -wq @foo "abc123"
3561 $ tmux show -wv @foo
3565 Commands which set options are as follows:
3568 .It Xo Ic set-option
3570 .Op Fl t Ar target-pane
3573 .D1 Pq alias: Ic set
3574 Set a pane option with
3576 a window option with
3578 a server option with
3580 otherwise a session option.
3581 If the option is not a user option,
3585 may be unnecessary -
3587 will infer the type from the option name, assuming
3592 is given, the global session or window option is set.
3595 expands formats in the option value.
3598 flag unsets an option, so a session inherits the option from the global
3601 restores a global option to the default).
3603 unsets an option (like
3605 but if the option is a pane option also unsets the option on any panes in the
3608 depends on the option and may be a number, a string, or a flag (on, off, or
3613 flag prevents setting an option that is already set and the
3615 flag suppresses errors about unknown or ambiguous options.
3619 and if the option expects a string or a style,
3621 is appended to the existing setting.
3623 .Bd -literal -offset indent
3624 set -g status-left "foo"
3625 set -ag status-left "bar"
3631 .Bd -literal -offset indent
3632 set -g status-style "bg=red"
3633 set -ag status-style "fg=blue"
3636 Will result in a red background
3641 the result would be the default background and a blue foreground.
3643 .It Xo Ic show-options
3645 .Op Fl t Ar target-pane
3648 .D1 Pq alias: Ic show
3649 Show the pane options (or a single option if
3653 the window options with
3655 the server options with
3657 otherwise the session options.
3658 If the option is not a user option,
3662 may be unnecessary -
3664 will infer the type from the option name, assuming
3667 Global session or window options are listed if
3671 shows only the option value, not the name.
3674 is set, no error will be returned if
3678 includes hooks (omitted by default).
3680 includes options inherited from a parent set of options, such options are
3681 marked with an asterisk.
3684 Available server options are:
3686 .It Ic backspace Ar key
3690 .It Ic buffer-limit Ar number
3691 Set the number of buffers; as new buffers are added to the top of the stack,
3692 old ones are removed from the bottom if necessary to maintain this maximum
3694 .It Xo Ic command-alias[]
3697 This is an array of custom aliases for commands.
3698 If an unknown command matches
3704 .Dl set -s command-alias[100] zoom=\[aq]resize-pane -Z\[aq]
3712 .Dl resize-pane -Z -t:.1
3714 Note that aliases are expanded when a command is parsed rather than when it is
3715 executed, so binding an alias with
3717 will bind the expanded form.
3718 .It Ic default-terminal Ar terminal
3719 Set the default terminal for new windows created in this session - the
3720 default value of the
3722 environment variable.
3725 to work correctly, this
3730 or a derivative of them.
3731 .It Ic copy-command Ar shell-command
3732 Give the command to pipe to if the
3734 copy mode command is used without arguments.
3735 .It Ic escape-time Ar time
3736 Set the time in milliseconds for which
3738 waits after an escape is input to determine if it is part of a function or meta
3740 The default is 500 milliseconds.
3741 .It Ic editor Ar shell-command
3742 Set the command used when
3745 .It Xo Ic exit-empty
3748 If enabled (the default), the server will exit when there are no active
3750 .It Xo Ic exit-unattached
3753 If enabled, the server will exit when there are no attached clients.
3754 .It Xo Ic extended-keys
3755 .Op Ic on | off | always
3761 the escape sequence to enable extended keys is sent to the terminal, if
3763 knows that it is supported.
3765 always recognises extended keys itself.
3769 will only forward extended keys to applications when they request them; if
3772 will always forward the keys.
3773 .It Xo Ic focus-events
3776 When enabled, focus events are requested from the terminal if supported and
3777 passed through to applications running in
3779 Attached clients should be detached and attached again after changing this
3781 .It Ic history-file Ar path
3782 If not empty, a file to which
3784 will write command prompt history on exit and load it from on start.
3785 .It Ic message-limit Ar number
3786 Set the number of error or information messages to save in the message log for
3788 .It Ic prompt-history-limit Ar number
3789 Set the number of history items to save in the history file for each type of
3791 .It Xo Ic set-clipboard
3792 .Op Ic on | external | off
3794 Attempt to set the terminal clipboard content using the
3796 escape sequence, if there is an
3800 description (see the
3801 .Sx TERMINFO EXTENSIONS
3807 will both accept the escape sequence to create a buffer and attempt to set
3808 the terminal clipboard.
3812 will attempt to set the terminal clipboard but ignore attempts
3813 by applications to set
3819 will neither accept the clipboard escape sequence nor attempt to set the
3822 Note that this feature needs to be enabled in
3824 by setting the resource:
3825 .Bd -literal -offset indent
3826 disallowedWindowOps: 20,21,SetXprop
3829 Or changing this property from the
3831 interactive menu when required.
3832 .It Ic terminal-features[] Ar string
3833 Set terminal features for terminal types read from
3836 has a set of named terminal features.
3837 Each will apply appropriate changes to the
3842 can detect features for a few common terminals; this option can be used to
3843 easily tell tmux about features supported by terminals it cannot detect.
3845 .Ic terminal-overrides
3846 option allows individual
3848 capabilities to be set instead,
3849 .Ic terminal-features
3850 is intended for classes of functionality supported in a standard way but not
3853 Care must be taken to configure this only with features the terminal actually
3856 This is an array option where each entry is a colon-separated string made up
3857 of a terminal type pattern (matched using
3859 followed by a list of terminal features.
3860 The available features are:
3863 Supports 256 colours with the SGR escape sequences.
3865 Allows setting the system clipboard.
3867 Allows setting the cursor colour.
3869 Allows setting the cursor style.
3871 Supports extended keys.
3873 Supports focus reporting.
3875 Supports OSC 8 hyperlinks.
3877 Ignore function keys from
3883 Supports DECSLRM margins.
3889 Supports the OSC 7 working directory extension.
3891 Supports the overline SGR attribute.
3893 Supports the DECFRA rectangle fill escape sequence.
3895 Supports RGB colour with the SGR escape sequences.
3897 Supports SIXEL graphics.
3899 Supports the strikethrough SGR escape sequence.
3901 Supports synchronized updates.
3907 Allows underscore style and colour to be set.
3909 .It Ic terminal-overrides[] Ar string
3910 Allow terminal descriptions read using
3913 Each entry is a colon-separated string made up of a terminal type pattern
3920 For example, to set the
3925 for all terminal types matching
3928 .Dl "rxvt*:clear=\ee[H\ee[2J"
3930 The terminal entry value is passed through
3932 before interpretation.
3933 .It Ic user-keys[] Ar key
3934 Set list of user-defined key escape sequences.
3935 Each item is associated with a key named
3941 .Bd -literal -offset indent
3942 set -s user-keys[0] "\ee[5;30012\[ti]"
3943 bind User0 resize-pane -L 3
3947 Available session options are:
3949 .It Xo Ic activity-action
3950 .Op Ic any | none | current | other
3952 Set action on window activity when
3953 .Ic monitor-activity
3956 means activity in any window linked to a session causes a bell or message
3958 .Ic visual-activity )
3959 in the current window of that session,
3961 means all activity is ignored (equivalent to
3962 .Ic monitor-activity
3965 means only activity in windows other than the current window are ignored and
3967 means activity in the current window is ignored but not those in other windows.
3968 .It Ic assume-paste-time Ar milliseconds
3969 If keys are entered faster than one in
3971 they are assumed to have been pasted rather than typed and
3973 key bindings are not processed.
3974 The default is one millisecond and zero disables.
3975 .It Ic base-index Ar index
3976 Set the base index from which an unused index should be searched when a new
3978 The default is zero.
3979 .It Xo Ic bell-action
3980 .Op Ic any | none | current | other
3982 Set action on a bell in a window when
3985 The values are the same as those for
3986 .Ic activity-action .
3987 .It Ic default-command Ar shell-command
3988 Set the command used for new windows (if not specified when the window is
3994 The default is an empty string, which instructs
3996 to create a login shell using the value of the
3999 .It Ic default-shell Ar path
4000 Specify the default shell.
4001 This is used as the login shell for new windows when the
4003 option is set to empty, and must be the full path of the executable.
4006 tries to set a default value from the first suitable of the
4008 environment variable, the shell returned by
4012 This option should be configured when
4014 is used as a login shell.
4015 .It Ic default-size Ar XxY
4016 Set the default size of new windows when the
4018 option is set to manual or when a session is created with
4021 The value is the width and height separated by an
4024 The default is 80x24.
4025 .It Xo Ic destroy-unattached
4026 .Op Ic off | on | keep-last | keep-group
4030 destroy the session after the last client has detached.
4033 (the default), leave the session orphaned.
4036 destroy the session only if it is in a group and has other sessions in that group.
4039 destroy the session unless it is in a group and is the only session in that group.
4040 .It Xo Ic detach-on-destroy
4041 .Op Ic off | on | no-detached | previous | next
4045 (the default), the client is detached when the session it is attached to
4049 the client is switched to the most recently active of the remaining
4053 the client is detached only if there are no detached sessions; if detached
4054 sessions exist, the client is switched to the most recently active.
4059 the client is switched to the previous or next session in alphabetical order.
4060 .It Ic display-panes-active-colour Ar colour
4061 Set the colour used by the
4063 command to show the indicator for the active pane.
4064 .It Ic display-panes-colour Ar colour
4065 Set the colour used by the
4067 command to show the indicators for inactive panes.
4068 .It Ic display-panes-time Ar time
4069 Set the time in milliseconds for which the indicators shown by the
4072 .It Ic display-time Ar time
4073 Set the amount of time for which status line messages and other on-screen
4074 indicators are displayed.
4075 If set to 0, messages and indicators are displayed until a key is pressed.
4078 .It Ic history-limit Ar lines
4079 Set the maximum number of lines held in window history.
4080 This setting applies only to new windows - existing window histories are not
4081 resized and retain the limit at the point they were created.
4082 .It Ic key-table Ar key-table
4083 Set the default key table to
4087 .It Ic lock-after-time Ar number
4088 Lock the session (like the
4092 seconds of inactivity.
4093 The default is not to lock (set to 0).
4094 .It Ic lock-command Ar shell-command
4095 Command to run when locking each client.
4096 The default is to run
4100 .It Ic menu-style Ar style
4104 section on how to specify
4106 Attributes are ignored.
4107 .It Ic menu-selected-style Ar style
4108 Set the selected menu item style.
4111 section on how to specify
4113 Attributes are ignored.
4114 .It Ic menu-border-style Ar style
4115 Set the menu border style.
4118 section on how to specify
4120 Attributes are ignored.
4121 .It Ic menu-border-lines Ar type
4122 Set the type of characters used for drawing menu borders.
4124 .Ic popup-border-lines
4125 for possible values for
4127 .It Ic message-command-style Ar style
4128 Set status line message command style.
4129 This is used for the command prompt with
4131 keys when in command mode.
4137 .It Xo Ic message-line
4138 .Op Ic 0 | 1 | 2 | 3 | 4
4140 Set line on which status line messages and the command prompt are shown.
4141 .It Ic message-style Ar style
4142 Set status line message style.
4143 This is used for messages and for the command prompt.
4154 captures the mouse and allows mouse events to be bound as key bindings.
4157 section for details.
4158 .It Ic prefix Ar key
4159 Set the key accepted as a prefix key.
4160 In addition to the standard keys described under
4163 can be set to the special key
4166 .It Ic prefix2 Ar key
4167 Set a secondary key accepted as a prefix key.
4173 .It Xo Ic renumber-windows
4176 If on, when a window is closed in a session, automatically renumber the other
4177 windows in numerical order.
4180 option if it has been set.
4181 If off, do not renumber the windows.
4182 .It Ic repeat-time Ar time
4183 Allow multiple commands to be entered without pressing the prefix-key again
4186 milliseconds (the default is 500).
4187 Whether a key repeats may be set when it is bound using the
4191 Repeat is enabled for the default keys bound to the
4194 .It Xo Ic set-titles
4197 Attempt to set the client terminal title using the
4202 entries if they exist.
4204 automatically sets these to the \ee]0;...\e007 sequence if
4205 the terminal appears to be
4207 This option is off by default.
4208 .It Ic set-titles-string Ar string
4209 String used to set the client terminal title if
4212 Formats are expanded, see the
4215 .It Xo Ic silence-action
4216 .Op Ic any | none | current | other
4218 Set action on window silence when
4221 The values are the same as those for
4222 .Ic activity-action .
4224 .Op Ic off | on | 2 | 3 | 4 | 5
4226 Show or hide the status line or specify its size.
4229 gives a status line one row in height;
4236 .It Ic status-format[] Ar format
4237 Specify the format to be used for each line of the status line.
4238 The default builds the top status line from the various individual status
4240 .It Ic status-interval Ar interval
4241 Update the status line every
4244 By default, updates will occur every 15 seconds.
4245 A setting of zero disables redrawing at interval.
4246 .It Xo Ic status-justify
4247 .Op Ic left | centre | right | absolute-centre
4249 Set the position of the window list in the status line: left, centre or right.
4250 centre puts the window list in the relative centre of the available free space;
4251 absolute-centre uses the centre of the entire horizontal space.
4252 .It Xo Ic status-keys
4255 Use vi or emacs-style
4256 key bindings in the status line, for example at the command prompt.
4257 The default is emacs, unless the
4261 environment variables are set and contain the string
4263 .It Ic status-left Ar string
4266 (by default the session name) to the left of the status line.
4268 will be passed through
4276 For details on how the names and titles can be set see the
4277 .Sx "NAMES AND TITLES"
4281 .Bd -literal -offset indent
4282 #(sysctl vm.loadavg)
4283 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
4288 .It Ic status-left-length Ar length
4291 of the left component of the status line.
4293 .It Ic status-left-style Ar style
4294 Set the style of the left part of the status line.
4300 .It Xo Ic status-position
4303 Set the position of the status line.
4304 .It Ic status-right Ar string
4307 to the right of the status line.
4308 By default, the current pane title in double quotes, the date and the time
4315 and character pairs are replaced.
4316 .It Ic status-right-length Ar length
4319 of the right component of the status line.
4321 .It Ic status-right-style Ar style
4322 Set the style of the right part of the status line.
4328 .It Ic status-style Ar style
4329 Set status line style.
4335 .It Ic update-environment[] Ar variable
4336 Set list of environment variables to be copied into the session environment
4337 when a new session is created or an existing session is attached.
4338 Any variables that do not exist in the source environment are set to be
4339 removed from the session environment (as if
4344 .It Xo Ic visual-activity
4345 .Op Ic on | off | both
4347 If on, display a message instead of sending a bell when activity occurs in a
4348 window for which the
4349 .Ic monitor-activity
4350 window option is enabled.
4351 If set to both, a bell and a message are produced.
4352 .It Xo Ic visual-bell
4353 .Op Ic on | off | both
4355 If on, a message is shown on a bell in a window for which the
4357 window option is enabled instead of it being passed through to the
4358 terminal (which normally makes a sound).
4359 If set to both, a bell and a message are produced.
4363 .It Xo Ic visual-silence
4364 .Op Ic on | off | both
4368 is enabled, prints a message after the interval has expired on a given window
4369 instead of sending a bell.
4370 If set to both, a bell and a message are produced.
4371 .It Ic word-separators Ar string
4372 Sets the session's conception of what characters are considered word
4373 separators, for the purposes of the next and previous word commands in
4377 Available window options are:
4379 .Bl -tag -width Ds -compact
4380 .It Xo Ic aggressive-resize
4383 Aggressively resize the chosen window.
4386 will resize the window to the size of the smallest or largest session
4389 option) for which it is the current window, rather than the session to
4390 which it is attached.
4391 The window may resize when the current window is changed on another
4392 session; this option is good for full-screen programs which support
4394 and poor for interactive programs such as shells.
4396 .It Xo Ic automatic-rename
4399 Control automatic window renaming.
4400 When this setting is enabled,
4402 will rename the window automatically using the format specified by
4403 .Ic automatic-rename-format .
4404 This flag is automatically disabled for an individual window when a name
4405 is specified at creation with
4411 or with a terminal escape sequence.
4412 It may be switched off globally with:
4413 .Bd -literal -offset indent
4414 set-option -wg automatic-rename off
4417 .It Ic automatic-rename-format Ar format
4421 .Ic automatic-rename
4424 .It Ic clock-mode-colour Ar colour
4427 .It Xo Ic clock-mode-style
4430 Set clock hour format.
4432 .It Ic fill-character Ar character
4433 Set the character used to fill areas of the terminal unused by a window.
4435 .It Ic main-pane-height Ar height
4436 .It Ic main-pane-width Ar width
4437 Set the width or height of the main (left or top) pane in the
4444 this is a percentage of the window size.
4446 .It Ic copy-mode-match-style Ar style
4447 Set the style of search matches in copy mode.
4454 .It Ic copy-mode-mark-style Ar style
4455 Set the style of the line containing the mark in copy mode.
4462 .It Ic copy-mode-current-match-style Ar style
4463 Set the style of the current search match in copy mode.
4473 Use vi or emacs-style key bindings in copy mode.
4474 The default is emacs, unless
4481 .It Ic mode-style Ar style
4482 Set window modes style.
4489 .It Xo Ic monitor-activity
4492 Monitor for activity in the window.
4493 Windows with activity are highlighted in the status line.
4495 .It Xo Ic monitor-bell
4498 Monitor for a bell in the window.
4499 Windows with a bell are highlighted in the status line.
4501 .It Xo Ic monitor-silence
4504 Monitor for silence (no activity) in the window within
4507 Windows that have been silent for the interval are highlighted in the
4509 An interval of zero disables the monitoring.
4511 .It Ic other-pane-height Ar height
4512 Set the height of the other panes (not the main pane) in the
4515 If this option is set to 0 (the default), it will have no effect.
4517 .Ic main-pane-height
4519 .Ic other-pane-height
4520 options are set, the main pane will grow taller to make the other panes the
4521 specified height, but will never shrink to do so.
4524 this is a percentage of the window size.
4526 .It Ic other-pane-width Ar width
4528 .Ic other-pane-height ,
4529 but set the width of other panes in the
4533 .It Ic pane-active-border-style Ar style
4534 Set the pane border style for the currently active pane.
4540 Attributes are ignored.
4542 .It Ic pane-base-index Ar index
4545 but set the starting index for pane numbers.
4547 .It Ic pane-border-format Ar format
4548 Set the text shown in pane border status lines.
4550 .It Xo Ic pane-border-indicators
4551 .Op Ic off | colour | arrows | both
4553 Indicate active pane by colouring only half of the border in windows with
4554 exactly two panes, by displaying arrow markers, by drawing both or neither.
4556 .It Ic pane-border-lines Ar type
4557 Set the type of characters used for drawing pane borders.
4562 single lines using ACS or UTF-8 characters
4564 double lines using UTF-8 characters
4566 heavy lines using UTF-8 characters
4568 simple ASCII characters
4576 will fall back to standard ACS line drawing when UTF-8 is not supported.
4578 .It Xo Ic pane-border-status
4579 .Op Ic off | top | bottom
4581 Turn pane border status lines off or set their position.
4583 .It Ic pane-border-style Ar style
4584 Set the pane border style for panes aside from the active pane.
4590 Attributes are ignored.
4592 .It Ic popup-style Ar style
4593 Set the popup style.
4596 section on how to specify
4598 Attributes are ignored.
4600 .It Ic popup-border-style Ar style
4601 Set the popup border style.
4604 section on how to specify
4606 Attributes are ignored.
4608 .It Ic popup-border-lines Ar type
4609 Set the type of characters used for drawing popup borders.
4614 single lines using ACS or UTF-8 characters (default)
4616 variation of single with rounded corners using UTF-8 characters
4618 double lines using UTF-8 characters
4620 heavy lines using UTF-8 characters
4622 simple ASCII characters
4624 simple ASCII space character
4632 will fall back to standard ACS line drawing when UTF-8 is not supported.
4634 .It Ic window-status-activity-style Ar style
4635 Set status line style for windows with an activity alert.
4642 .It Ic window-status-bell-style Ar style
4643 Set status line style for windows with a bell alert.
4650 .It Ic window-status-current-format Ar string
4652 .Ar window-status-format ,
4653 but is the format used when the window is the current window.
4655 .It Ic window-status-current-style Ar style
4656 Set status line style for the currently active window.
4663 .It Ic window-status-format Ar string
4664 Set the format in which the window is displayed in the status line window list.
4671 .It Ic window-status-last-style Ar style
4672 Set status line style for the last active window.
4679 .It Ic window-status-separator Ar string
4680 Sets the separator drawn between windows in the status line.
4681 The default is a single space character.
4683 .It Ic window-status-style Ar style
4684 Set status line style for a single window.
4691 .It Xo Ic window-size
4692 .Ar largest | Ar smallest | Ar manual | Ar latest
4696 determines the window size.
4699 the size of the largest attached session is used; if
4701 the size of the smallest.
4704 the size of a new window is set from the
4706 option and windows are resized automatically.
4710 uses the size of the client that had the most recent activity.
4714 .Ic aggressive-resize
4717 .It Xo Ic wrap-search
4720 If this option is set, searches will wrap around the end of the pane contents.
4724 Available pane options are:
4726 .Bl -tag -width Ds -compact
4727 .It Xo Ic allow-passthrough
4728 .Op Ic on | off | all
4730 Allow programs in the pane to bypass
4732 using a terminal escape sequence (\eePtmux;...\ee\e\e).
4735 passthrough sequences will be allowed only if the pane is visible.
4738 they will be allowed even if the pane is invisible.
4740 .It Xo Ic allow-rename
4743 Allow programs in the pane to change the window name using a terminal escape
4744 sequence (\eek...\ee\e\e).
4746 .It Xo Ic alternate-screen
4749 This option configures whether programs running inside the pane may use the
4750 terminal alternate screen feature, which allows the
4756 The alternate screen feature preserves the contents of the window when an
4757 interactive application starts and restores it on exit, so that any output
4758 visible before the application starts reappears unchanged after it exits.
4760 .It Ic cursor-colour Ar colour
4761 Set the colour of the cursor.
4763 .It Ic pane-colours[] Ar colour
4764 The default colour palette.
4765 Each entry in the array defines the colour
4767 uses when the colour with that index is requested.
4768 The index may be from zero to 255.
4770 .It Ic cursor-style Ar style
4771 Set the style of the cursor.
4772 Available styles are:
4774 .Ic blinking-block ,
4776 .Ic blinking-underline ,
4781 .It Xo Ic remain-on-exit
4782 .Op Ic on | off | failed
4784 A pane with this flag set is not destroyed when the program running in it
4788 then only when the program exit status is not zero.
4789 The pane may be reactivated with the
4793 .It Ic remain-on-exit-format Ar string
4794 Set the text shown at the bottom of exited panes when
4798 .It Xo Ic scroll-on-clear
4801 When the entire screen is cleared and this option is on, scroll the contents of
4802 the screen into history before clearing it.
4804 .It Xo Ic synchronize-panes
4807 Duplicate input to all other panes in the same window where this option is also
4808 on (only for panes that are not in any mode).
4810 .It Ic window-active-style Ar style
4811 Set the pane style when it is the active pane.
4818 .It Ic window-style Ar style
4828 allows commands to run on various triggers, called
4834 hook and there are a number of hooks not associated with commands.
4836 Hooks are stored as array options, members of the array are executed in
4837 order when the hook is triggered.
4838 Like options different hooks may be global or belong to a session, window or
4840 Hooks may be configured with the
4844 commands and displayed with
4849 The following two commands are equivalent:
4850 .Bd -literal -offset indent.
4851 set-hook -g pane-mode-changed[42] \[aq]set -g status-left-style bg=red\[aq]
4852 set-option -g pane-mode-changed[42] \[aq]set -g status-left-style bg=red\[aq]
4855 Setting a hook without specifying an array index clears the hook and sets the
4856 first member of the array.
4859 hook is run after it completes, except when the command is run as part of a hook
4861 They are named with an
4864 For example, the following command adds a hook to select the even-vertical
4867 .Bd -literal -offset indent
4868 set-hook -g after-split-window "selectl even-vertical"
4871 All the notifications listed in the
4873 section are hooks (without any arguments), except
4875 The following additional hooks are available:
4876 .Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX"
4878 Run when a window has activity.
4880 .Ic monitor-activity .
4882 Run when a window has received a bell.
4886 Run when a window has been silent.
4888 .Ic monitor-silence .
4890 Run when a client becomes the latest active client of its session.
4892 Run when a client is attached.
4894 Run when a client is detached
4896 Run when focus enters a client
4897 .It client-focus-out
4898 Run when focus exits a client
4900 Run when a client is resized.
4901 .It client-session-changed
4902 Run when a client's attached session is changed.
4904 Run when the program running in a pane exits, but
4906 is on so the pane has not closed.
4908 Run when the program running in a pane exits.
4910 Run when the focus enters a pane, if the
4914 Run when the focus exits a pane, if the
4917 .It pane-set-clipboard
4918 Run when the terminal clipboard is set using the
4922 Run when a new session created.
4924 Run when a session closed.
4926 Run when a session is renamed.
4928 Run when a window is linked into a session.
4930 Run when a window is renamed.
4932 Run when a window is resized.
4933 This may be after the
4937 Run when a window is unlinked from a session.
4940 Hooks are managed with these commands:
4944 .Op Fl t Ar target-pane
4956 The flags are the same as for
4964 .It Xo Ic show-hooks
4966 .Op Fl t Ar target-pane
4969 The flags are the same as for
4975 option is on (the default is off),
4977 allows mouse events to be bound as keys.
4978 The name of each key is made up of a mouse event (such as
4980 and a location suffix, one of the following:
4981 .Bl -column "XXXXXXXXXXXXX" -offset indent
4982 .It Li "Pane" Ta "the contents of a pane"
4983 .It Li "Border" Ta "a pane border"
4984 .It Li "Status" Ta "the status line window list"
4985 .It Li "StatusLeft" Ta "the left part of the status line"
4986 .It Li "StatusRight" Ta "the right part of the status line"
4987 .It Li "StatusDefault" Ta "any other part of the status line"
4990 The following mouse events are available:
4991 .Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
4992 .It Li "WheelUp" Ta "WheelDown" Ta ""
4993 .It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
4994 .It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
4995 .It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
4996 .It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3"
4997 .It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3"
4998 .It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3"
5003 events are fired for the second click of a double click, even if there may be a
5004 third click which will fire
5009 Each should be suffixed with a location, for example
5010 .Ql MouseDown1Status .
5020 in commands bound to mouse key bindings.
5021 It resolves to the window or pane over which the mouse event took place
5022 (for example, the window in the status line over which button 1 was released
5025 binding, or the pane over which the wheel was scrolled for a
5032 flag may be used to forward a mouse event to a pane.
5034 The default key bindings allow the mouse to be used to select and resize panes,
5035 to copy text and to change window using the status line.
5036 These take effect if the
5038 option is turned on.
5040 Certain commands accept the
5045 This is a string which controls the output format of the command.
5046 Format variables are enclosed in
5051 .Ql #{session_name} .
5052 The possible variables are listed in the table below, or the name of a
5054 option may be used for an option's value.
5055 Some variables have a shorter alias such as
5058 is replaced by a single
5068 Conditionals are available by prefixing with
5070 and separating two alternatives with a comma;
5071 if the specified variable exists and is not zero, the first alternative
5072 is chosen, otherwise the second is used.
5074 .Ql #{?session_attached,attached,not attached}
5075 will include the string
5077 if the session is attached and the string
5079 if it is unattached, or
5080 .Ql #{?automatic-rename,yes,no}
5084 .Ic automatic-rename
5088 Conditionals can be nested arbitrarily.
5089 Inside a conditional,
5097 unless they are part of a
5101 .Bd -literal -offset indent
5102 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
5105 String comparisons may be expressed by prefixing two comma-separated
5116 .Ql #{==:#{host},myhost}
5126 evaluate to true if either or both of two comma-separated alternatives are
5128 .Ql #{||:#{pane_in_mode},#{alternate_on}} .
5134 or regular expression comparison.
5135 The first argument is the pattern and the second the string to compare.
5136 An optional argument specifies flags:
5138 means the pattern is a regular expression instead of the default
5142 means to ignore case.
5144 .Ql #{m:*foo*,#{host}}
5146 .Ql #{m/ri:^A,MYVAR} .
5149 performs a search for an
5151 pattern or regular expression in the pane content and evaluates to zero if not
5152 found, or a line number if found.
5157 flag means search for a regular expression and
5163 Numeric operators may be performed by prefixing two comma-separated alternatives
5169 flag may be given after the operator to use floating point numbers, otherwise
5171 This may be followed by a number giving the number of decimal places to use for
5173 The available operators are:
5190 in formats which are also expanded by
5192 and numeric comparison operators
5201 .Ql #{e|*|f|4:5.5,3}
5202 multiplies 5.5 by 3 for a result with four decimal places and
5204 returns the modulus of 7 and 3.
5206 replaces a numeric argument by its ASCII equivalent, so
5213 colour by its six-digit hexadecimal RGB value.
5215 A limit may be placed on the length of the resultant string by prefixing it
5218 a number and a colon.
5219 Positive numbers count from the start of the string and negative from the end,
5221 .Ql #{=5:pane_title}
5222 will include at most the first five characters of the pane title, or
5223 .Ql #{=-5:pane_title}
5224 the last five characters.
5225 A suffix or prefix may be given as a second argument - if provided then it is
5226 appended or prepended to the string if the length has been trimmed, for example
5227 .Ql #{=/5/...:pane_title}
5230 if the pane title is more than five characters.
5233 pads the string to a given width, for example
5234 .Ql #{p10:pane_title}
5235 will result in a width of at least 10 characters.
5236 A positive width pads on the left, a negative on the right.
5238 expands to the length of the variable and
5240 to its width when displayed, for example
5241 .Ql #{n:window_name} .
5243 Prefixing a time variable with
5245 will convert it to a string, so if
5246 .Ql #{window_activity}
5249 .Ql #{t:window_activity}
5251 .Ql Sun Oct 25 09:25:02 2015 .
5255 will use shorter but less accurate time format for times in the past.
5256 A custom format may be given using an
5262 if the format is separately being passed through
5267 .Ql #{t/f/%%H#:%%M:window_activity} ,
5279 of the variable respectively.
5283 special characters or with a
5285 suffix, escape hash characters (so
5290 will expand the format twice, for example
5291 .Ql #{E:status-left}
5292 is the result of expanding the content of the
5294 option rather than the option itself.
5306 will loop over each session, window, pane or client and insert the format once
5308 For windows and panes, two comma-separated formats may be given:
5309 the second is used for the current window or active pane.
5310 For example, to get a list of windows formatted like the status line:
5311 .Bd -literal -offset indent
5312 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
5316 checks if a window (without any suffix or with the
5318 suffix) or a session (with the
5320 suffix) name exists, for example
5322 is replaced with 1 if a window named
5326 A prefix of the form
5333 The first argument may be an extended regular expression and a final argument
5336 to ignore case, for example
5337 .Ql s/a(.)/\e1x/i:\&
5342 A different delimiter character may also be used, to avoid collisions with
5343 literal slashes in the pattern.
5352 In addition, the last line of a shell command's output may be inserted using
5356 will insert the system's uptime.
5357 When constructing formats,
5361 commands to finish; instead, the previous result from running the same command
5362 is used, or a placeholder if the command has not been run before.
5363 If the command hasn't exited, the most recent line of output will be used, but
5364 the status line will not be updated more than once a second.
5365 Commands are executed using
5369 global environment set (see the
5370 .Sx GLOBAL AND SESSION ENVIRONMENT
5375 specifies that a string should be interpreted literally and not expanded.
5377 .Ql #{l:#{?pane_in_mode,yes,no}}
5379 .Ql #{?pane_in_mode,yes,no} .
5381 The following variables are available, where appropriate:
5382 .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
5383 .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
5384 .It Li "active_window_index" Ta "" Ta "Index of active window in session"
5385 .It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen"
5386 .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
5387 .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
5388 .It Li "buffer_created" Ta "" Ta "Time buffer created"
5389 .It Li "buffer_name" Ta "" Ta "Name of buffer"
5390 .It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
5391 .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
5392 .It Li "client_activity" Ta "" Ta "Time client last had activity"
5393 .It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels"
5394 .It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels"
5395 .It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
5396 .It Li "client_created" Ta "" Ta "Time client created"
5397 .It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind"
5398 .It Li "client_flags" Ta "" Ta "List of client flags"
5399 .It Li "client_height" Ta "" Ta "Height of client"
5400 .It Li "client_key_table" Ta "" Ta "Current key table"
5401 .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
5402 .It Li "client_name" Ta "" Ta "Name of client"
5403 .It Li "client_pid" Ta "" Ta "PID of client process"
5404 .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
5405 .It Li "client_readonly" Ta "" Ta "1 if client is read-only"
5406 .It Li "client_session" Ta "" Ta "Name of the client's session"
5407 .It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any"
5408 .It Li "client_termname" Ta "" Ta "Terminal name of client"
5409 .It Li "client_termtype" Ta "" Ta "Terminal type of client, if available"
5410 .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
5411 .It Li "client_uid" Ta "" Ta "UID of client process"
5412 .It Li "client_user" Ta "" Ta "User of client process"
5413 .It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8"
5414 .It Li "client_width" Ta "" Ta "Width of client"
5415 .It Li "client_written" Ta "" Ta "Bytes written to client"
5416 .It Li "command" Ta "" Ta "Name of command in use, if any"
5417 .It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
5418 .It Li "command_list_name" Ta "" Ta "Command name if listing commands"
5419 .It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
5420 .It Li "config_files" Ta "" Ta "List of configuration files loaded"
5421 .It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode"
5422 .It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode"
5423 .It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode"
5424 .It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode"
5425 .It Li "current_file" Ta "" Ta "Current configuration file"
5426 .It Li "cursor_character" Ta "" Ta "Character at cursor in pane"
5427 .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
5428 .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
5429 .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
5430 .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
5431 .It Li "history_limit" Ta "" Ta "Maximum window history lines"
5432 .It Li "history_size" Ta "" Ta "Size of history in lines"
5433 .It Li "hook" Ta "" Ta "Name of running hook, if any"
5434 .It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any"
5435 .It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
5436 .It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
5437 .It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
5438 .It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
5439 .It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
5440 .It Li "host" Ta "#H" Ta "Hostname of local host"
5441 .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
5442 .It Li "insert_flag" Ta "" Ta "Pane insert flag"
5443 .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
5444 .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
5445 .It Li "last_window_index" Ta "" Ta "Index of last window in session"
5446 .It Li "line" Ta "" Ta "Line number in the list"
5447 .It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
5448 .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
5449 .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
5450 .It Li "mouse_hyperlink" Ta "" Ta "Hyperlink under mouse, if any"
5451 .It Li "mouse_line" Ta "" Ta "Line under mouse, if any"
5452 .It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag"
5453 .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
5454 .It Li "mouse_status_line" Ta "" Ta "Status line on which mouse event took place"
5455 .It Li "mouse_status_range" Ta "" Ta "Range type or argument of mouse event on status line"
5456 .It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag"
5457 .It Li "mouse_word" Ta "" Ta "Word under mouse, if any"
5458 .It Li "mouse_x" Ta "" Ta "Mouse X position, if any"
5459 .It Li "mouse_y" Ta "" Ta "Mouse Y position, if any"
5460 .It Li "next_session_id" Ta "" Ta "Unique session ID for next new session"
5461 .It Li "origin_flag" Ta "" Ta "Pane origin flag"
5462 .It Li "pane_active" Ta "" Ta "1 if active pane"
5463 .It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window"
5464 .It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window"
5465 .It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window"
5466 .It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window"
5467 .It Li "pane_bg" Ta "" Ta "Pane background colour"
5468 .It Li "pane_bottom" Ta "" Ta "Bottom of pane"
5469 .It Li "pane_current_command" Ta "" Ta "Current command if available"
5470 .It Li "pane_current_path" Ta "" Ta "Current path if available"
5471 .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
5472 .It Li "pane_dead_signal" Ta "" Ta "Exit signal of process in dead pane"
5473 .It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
5474 .It Li "pane_dead_time" Ta "" Ta "Exit time of process in dead pane"
5475 .It Li "pane_fg" Ta "" Ta "Pane foreground colour"
5476 .It Li "pane_format" Ta "" Ta "1 if format is for a pane"
5477 .It Li "pane_height" Ta "" Ta "Height of pane"
5478 .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
5479 .It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode"
5480 .It Li "pane_index" Ta "#P" Ta "Index of pane"
5481 .It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled"
5482 .It Li "pane_last" Ta "" Ta "1 if last pane"
5483 .It Li "pane_left" Ta "" Ta "Left of pane"
5484 .It Li "pane_marked" Ta "" Ta "1 if this is the marked pane"
5485 .It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set"
5486 .It Li "pane_mode" Ta "" Ta "Name of pane mode, if any"
5487 .It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)"
5488 .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
5489 .It Li "pane_pipe" Ta "" Ta "1 if pane is being piped"
5490 .It Li "pane_right" Ta "" Ta "Right of pane"
5491 .It Li "pane_search_string" Ta "" Ta "Last search string in copy mode"
5492 .It Li "pane_start_command" Ta "" Ta "Command pane started with"
5493 .It Li "pane_start_path" Ta "" Ta "Path pane started with"
5494 .It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized"
5495 .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
5496 .It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)"
5497 .It Li "pane_top" Ta "" Ta "Top of pane"
5498 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
5499 .It Li "pane_unseen_changes" Ta "" Ta "1 if there were changes in pane while in mode"
5500 .It Li "pane_width" Ta "" Ta "Width of pane"
5501 .It Li "pid" Ta "" Ta "Server PID"
5502 .It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated"
5503 .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
5504 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
5505 .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
5506 .It Li "search_match" Ta "" Ta "Search match if any"
5507 .It Li "search_present" Ta "" Ta "1 if search started in copy mode"
5508 .It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode"
5509 .It Li "selection_end_x" Ta "" Ta "X position of the end of the selection"
5510 .It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection"
5511 .It Li "selection_present" Ta "" Ta "1 if selection started in copy mode"
5512 .It Li "selection_start_x" Ta "" Ta "X position of the start of the selection"
5513 .It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection"
5514 .It Li "server_sessions" Ta "" Ta "Number of sessions"
5515 .It Li "session_activity" Ta "" Ta "Time of session last activity"
5516 .It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
5517 .It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
5518 .It Li "session_attached_list" Ta "" Ta "List of clients session is attached to"
5519 .It Li "session_created" Ta "" Ta "Time session created"
5520 .It Li "session_format" Ta "" Ta "1 if format is for a session"
5521 .It Li "session_group" Ta "" Ta "Name of session group"
5522 .It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to"
5523 .It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to"
5524 .It Li "session_group_list" Ta "" Ta "List of sessions in group"
5525 .It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group"
5526 .It Li "session_group_size" Ta "" Ta "Size of session group"
5527 .It Li "session_grouped" Ta "" Ta "1 if session in a group"
5528 .It Li "session_id" Ta "" Ta "Unique session ID"
5529 .It Li "session_last_attached" Ta "" Ta "Time session last attached"
5530 .It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
5531 .It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane"
5532 .It Li "session_name" Ta "#S" Ta "Name of session"
5533 .It Li "session_path" Ta "" Ta "Working directory of session"
5534 .It Li "session_stack" Ta "" Ta "Window indexes in most recent order"
5535 .It Li "session_windows" Ta "" Ta "Number of windows in session"
5536 .It Li "socket_path" Ta "" Ta "Server socket path"
5537 .It Li "start_time" Ta "" Ta "Server start time"
5538 .It Li "uid" Ta "" Ta "Server UID"
5539 .It Li "user" Ta "" Ta "Server user"
5540 .It Li "version" Ta "" Ta "Server version"
5541 .It Li "window_active" Ta "" Ta "1 if window active"
5542 .It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window"
5543 .It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window"
5544 .It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active"
5545 .It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active"
5546 .It Li "window_activity" Ta "" Ta "Time of window last activity"
5547 .It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
5548 .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
5549 .It Li "window_bigger" Ta "" Ta "1 if window is larger than client"
5550 .It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels"
5551 .It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels"
5552 .It Li "window_end_flag" Ta "" Ta "1 if window has the highest index"
5553 .It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##"
5554 .It Li "window_format" Ta "" Ta "1 if format is for a window"
5555 .It Li "window_height" Ta "" Ta "Height of window"
5556 .It Li "window_id" Ta "" Ta "Unique window ID"
5557 .It Li "window_index" Ta "#I" Ta "Index of window"
5558 .It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
5559 .It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
5560 .It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
5561 .It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to"
5562 .It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to"
5563 .It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane"
5564 .It Li "window_name" Ta "#W" Ta "Name of window"
5565 .It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client"
5566 .It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client"
5567 .It Li "window_panes" Ta "" Ta "Number of panes in window"
5568 .It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped"
5569 .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
5570 .It Li "window_stack_index" Ta "" Ta "Index in session most recent stack"
5571 .It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index"
5572 .It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
5573 .It Li "window_width" Ta "" Ta "Width of window"
5574 .It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
5575 .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
5579 offers various options to specify the colour and attributes of aspects of the
5580 interface, for example
5582 for the status line.
5583 In addition, embedded styles may be specified in format options, such as
5585 by enclosing them in
5590 A style may be the single term
5592 to specify the default style (which may come from an option, for example
5594 in the status line) or a space
5595 or comma separated list of the following:
5598 Set the foreground colour.
5599 The colour is one of:
5608 if supported the bright variants
5615 from the 256-colour set;
5617 for the default colour;
5619 for the terminal default colour; or a hexadecimal RGB string such as
5622 Set the background colour.
5624 Set the underscore colour.
5626 Set no attributes (turn off any active attributes).
5639 .Ic double-underscore ,
5640 .Ic curly-underscore ,
5641 .Ic dotted-underscore ,
5642 .Ic dashed-underscore
5645 Any of the attributes may be prefixed with
5649 is the terminal alternate character set.
5650 .It Xo Ic align=left
5656 Align text to the left, centre or right of the available space if appropriate.
5658 Fill the available space with a background colour if appropriate.
5661 .Ic list=left-marker ,
5662 .Ic list=right-marker ,
5665 Mark the position of the various window list components in the
5669 marks the start of the list;
5671 is the part of the list that should be kept in focus if the entire list won't
5672 fit in the available space (typically the current window);
5673 .Ic list=left-marker
5675 .Ic list=right-marker
5676 mark the text to be used to mark that text has been trimmed from the left or
5677 right of the list if there is not enough space.
5678 .It Xo Ic push-default ,
5681 Store the current colours and attributes as the default or reset to the previous
5685 affects any subsequent use of the
5689 Only one default may be pushed (each
5691 replaces the previous saved default).
5692 .It Xo Ic range=left ,
5694 .Ic range=session|X ,
5695 .Ic range=window|X ,
5700 Mark a range for mouse events in the
5703 When a mouse event occurs in the
5711 key bindings are triggered.
5713 .Ic range=session|X ,
5717 are ranges for a session, window or pane.
5720 mouse key with the target session, window or pane given by the
5724 is a session ID, window index in the current session or a pane ID.
5726 .Ic mouse_status_range
5727 format variable will be set to
5734 is a user-defined range; it triggers the
5739 will be available in the
5740 .Ic mouse_status_range
5743 must be at most 15 bytes in length.
5747 .Bd -literal -offset indent
5748 fg=yellow bold underscore blink
5749 bg=black,fg=default,noreverse
5751 .Sh NAMES AND TITLES
5753 distinguishes between names and titles.
5754 Windows and sessions have names, which may be used to specify them in targets
5755 and are displayed in the status line and various lists: the name is the
5757 identifier for a window or session.
5758 Only panes have titles.
5759 A pane's title is typically set by the program running inside the pane using
5760 an escape sequence (like it would set the
5764 Windows themselves do not have titles - a window's title is the title of its
5767 itself may set the title of the terminal in which the client is running, see
5772 A session's name is set with the
5777 A window's name is set with one of:
5780 A command argument (such as
5787 An escape sequence (if the
5789 option is turned on):
5790 .Bd -literal -offset indent
5791 $ printf \[aq]\e033kWINDOW_NAME\e033\e\e\[aq]
5794 Automatic renaming, which sets the name to the active command in the window's
5797 .Ic automatic-rename
5801 When a pane is first created, its title is the hostname.
5802 A pane's title can be set via the title setting escape sequence, for example:
5803 .Bd -literal -offset indent
5804 $ printf \[aq]\e033]2;My Title\e033\e\e\[aq]
5807 It can also be modified with the
5811 .Sh GLOBAL AND SESSION ENVIRONMENT
5812 When the server is started,
5814 copies the environment into the
5815 .Em global environment ;
5816 in addition, each session has a
5817 .Em session environment .
5818 When a window is created, the session and global environments are merged.
5819 If a variable exists in both, the value from the session environment is used.
5820 The result is the initial environment passed to the new process.
5823 .Ic update-environment
5824 session option may be used to update the session environment from the client
5825 when a new session is created or an old reattached.
5827 also initialises the
5829 variable with some internal information to allow commands to be executed
5830 from inside, and the
5832 variable with the correct terminal setting of
5835 Variables in both session and global environments may be marked as hidden.
5836 Hidden variables are not passed into the environment of new processes and
5837 instead can only be used by tmux itself (for example in formats, see the
5841 Commands to alter and view the environment are:
5844 .It Xo Ic set-environment
5846 .Op Fl t Ar target-session
5847 .Ar name Op Ar value
5849 .D1 Pq alias: Ic setenv
5850 Set or unset an environment variable.
5853 is used, the change is made in the global environment; otherwise, it is applied
5854 to the session environment for
5855 .Ar target-session .
5860 is expanded as a format.
5863 flag unsets a variable.
5865 indicates the variable is to be removed from the environment before starting a
5868 marks the variable as hidden.
5870 .It Xo Ic show-environment
5872 .Op Fl t Ar target-session
5875 .D1 Pq alias: Ic showenv
5876 Display the environment for
5878 or the global environment with
5882 is omitted, all variables are shown.
5883 Variables removed from the environment are prefixed with
5887 is used, the output is formatted as a set of Bourne shell commands.
5889 shows hidden variables (omitted by default).
5893 includes an optional status line which is displayed in the bottom line of each
5896 By default, the status line is enabled and one line in height (it may be
5897 disabled or made multiple lines with the
5899 session option) and contains, from left-to-right: the name of the current
5900 session in square brackets; the window list; the title of the active pane
5901 in double quotes; and the time and date.
5903 Each line of the status line is configured with the
5906 The default is made of three parts: configurable left and right sections (which
5907 may contain dynamic content such as the time or output from a shell command,
5910 .Ic status-left-length ,
5913 .Ic status-right-length
5914 options below), and a central window list.
5915 By default, the window list shows the index, name and (if any) flag of the
5916 windows present in the current session in ascending numerical order.
5917 It may be customised with the
5918 .Ar window-status-format
5920 .Ar window-status-current-format
5922 The flag is one of the following symbols appended to the window name:
5923 .Bl -column "Symbol" "Meaning" -offset indent
5924 .It Sy "Symbol" Ta Sy "Meaning"
5925 .It Li "*" Ta "Denotes the current window."
5926 .It Li "-" Ta "Marks the last window (previously selected)."
5927 .It Li "#" Ta "Window activity is monitored and activity has been detected."
5928 .It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window."
5929 .It Li "\[ti]" Ta "The window has been silent for the monitor-silence interval."
5930 .It Li "M" Ta "The window contains the marked pane."
5931 .It Li "Z" Ta "The window's active pane is zoomed."
5934 The # symbol relates to the
5935 .Ic monitor-activity
5937 The window name is printed in inverted colours if an alert (bell, activity or
5938 silence) is present.
5940 The colour and attributes of the status line may be configured, the entire
5941 status line using the
5943 session option and individual windows using the
5944 .Ic window-status-style
5947 The status line is automatically refreshed at interval if it has changed, the
5948 interval may be controlled with the
5952 Commands related to the status line are as follows:
5955 .It Xo Ic clear-prompt-history
5956 .Op Fl T Ar prompt-type
5958 .D1 Pq alias: Ic clearphist
5959 Clear status prompt history for prompt type
5963 is omitted, then clear history for all types.
5966 for possible values for
5968 .It Xo Ic command-prompt
5972 .Op Fl t Ar target-client
5973 .Op Fl T Ar prompt-type
5976 Open the command prompt in a client.
5977 This may be used from inside
5979 to execute commands interactively.
5983 is specified, it is used as the command.
5987 is expanded as a format.
5991 is a comma-separated list of the initial text for each prompt.
5996 is a comma-separated list of prompts which are displayed in order; otherwise
5997 a single prompt is displayed, constructed from
5999 if it is present, or
6003 Before the command is executed, the first occurrence of the string
6005 and all occurrences of
6007 are replaced by the response to the first prompt, all
6009 are replaced with the response to the second prompt, and so on for further
6011 Up to nine prompt responses may be replaced
6020 but any quotation marks are escaped.
6023 makes the prompt only accept one key press, in this case the resulting input
6024 is a single character.
6028 but the key press is translated to a key name.
6030 makes the prompt only accept numeric key presses.
6032 executes the command every time the prompt input changes instead of when the
6033 user exits the command prompt.
6039 This affects what completions are offered when
6042 Available types are:
6049 The following keys have a special meaning in the command prompt, depending
6053 .Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
6054 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
6055 .It Li "Cancel command prompt" Ta "q" Ta "Escape"
6056 .It Li "Delete from cursor to start of word" Ta "" Ta "C-w"
6057 .It Li "Delete entire command" Ta "d" Ta "C-u"
6058 .It Li "Delete from cursor to end" Ta "D" Ta "C-k"
6059 .It Li "Execute command" Ta "Enter" Ta "Enter"
6060 .It Li "Get next command from history" Ta "" Ta "Down"
6061 .It Li "Get previous command from history" Ta "" Ta "Up"
6062 .It Li "Insert top paste buffer" Ta "p" Ta "C-y"
6063 .It Li "Look for completions" Ta "Tab" Ta "Tab"
6064 .It Li "Move cursor left" Ta "h" Ta "Left"
6065 .It Li "Move cursor right" Ta "l" Ta "Right"
6066 .It Li "Move cursor to end" Ta "$" Ta "C-e"
6067 .It Li "Move cursor to next word" Ta "w" Ta "M-f"
6068 .It Li "Move cursor to previous word" Ta "b" Ta "M-b"
6069 .It Li "Move cursor to start" Ta "0" Ta "C-a"
6070 .It Li "Transpose characters" Ta "" Ta "C-t"
6075 the prompt is shown in the background and the invoking client does not exit
6076 until it is dismissed.
6078 .It Xo Ic confirm-before
6080 .Op Fl c Ar confirm-key
6082 .Op Fl t Ar target-client
6085 .D1 Pq alias: Ic confirm
6086 Ask for confirmation before executing
6092 is the prompt to display; otherwise a prompt is constructed from
6094 It may contain the special character sequences supported by the
6099 the prompt is shown in the background and the invoking client does not exit
6100 until it is dismissed.
6102 changes the default behaviour (if Enter alone is pressed) of the prompt to
6105 changes the confirmation key to
6110 .It Xo Ic display-menu
6112 .Op Fl b Ar border-lines
6113 .Op Fl c Ar target-client
6114 .Op Fl C Ar starting-choice
6115 .Op Fl H Ar selected-style
6117 .Op Fl S Ar border-style
6118 .Op Fl t Ar target-pane
6120 .Op Fl x Ar position
6121 .Op Fl y Ar position
6124 .Ar command Op Ar argument ...
6126 .D1 Pq alias: Ic menu
6130 gives the target for any commands run from the menu.
6132 A menu is passed as a series of arguments: first the menu item name,
6133 second the key shortcut (or empty for none) and third the command
6134 to run when the menu item is chosen.
6135 The name and command are formats, see the
6140 If the name begins with a hyphen (-), then the item is disabled (shown dim) and
6142 The name may be empty for a separator line, in which case both the key and
6143 command should be omitted.
6146 sets the type of characters used for drawing menu borders.
6148 .Ic popup-border-lines
6149 for possible values for
6153 sets the style for the selected menu item (see
6157 sets the style for the menu and
6159 sets the style for the menu border (see
6163 is a format for the menu title (see
6167 sets the menu item selected by default, if the menu is not bound to a mouse key
6173 give the position of the menu.
6174 Both may be a row or column number, or one of the following special values:
6175 .Bl -column "XXXXX" "XXXX" -offset indent
6176 .It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning"
6177 .It Li "C" Ta "Both" Ta "The centre of the terminal"
6178 .It Li "R" Ta Fl x Ta "The right side of the terminal"
6179 .It Li "P" Ta "Both" Ta "The bottom left of the pane"
6180 .It Li "M" Ta "Both" Ta "The mouse position"
6181 .It Li "W" Ta "Both" Ta "The window position on the status line"
6182 .It Li "S" Ta Fl y Ta "The line above or below the status line"
6185 Or a format, which is expanded including the following additional variables:
6186 .Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
6187 .It Sy "Variable name" Ta Sy "Replaced with"
6188 .It Li "popup_centre_x" Ta "Centered in the client"
6189 .It Li "popup_centre_y" Ta "Centered in the client"
6190 .It Li "popup_height" Ta "Height of menu or popup"
6191 .It Li "popup_mouse_bottom" Ta "Bottom of at the mouse"
6192 .It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse"
6193 .It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse"
6194 .It Li "popup_mouse_top" Ta "Top at the mouse"
6195 .It Li "popup_mouse_x" Ta "Mouse X position"
6196 .It Li "popup_mouse_y" Ta "Mouse Y position"
6197 .It Li "popup_pane_bottom" Ta "Bottom of the pane"
6198 .It Li "popup_pane_left" Ta "Left of the pane"
6199 .It Li "popup_pane_right" Ta "Right of the pane"
6200 .It Li "popup_pane_top" Ta "Top of the pane"
6201 .It Li "popup_status_line_y" Ta "Above or below the status line"
6202 .It Li "popup_width" Ta "Width of menu or popup"
6203 .It Li "popup_window_status_line_x" Ta "At the window position in status line"
6204 .It Li "popup_window_status_line_y" Ta "At the status line showing the window"
6207 Each menu consists of items followed by a key shortcut shown in brackets.
6208 If the menu is too large to fit on the terminal, it is not displayed.
6209 Pressing the key shortcut chooses the corresponding item.
6210 If the mouse is enabled and the menu is opened from a mouse key binding,
6211 releasing the mouse button with an item selected chooses that item and
6212 releasing the mouse button without an item selected closes the menu.
6214 changes this behaviour so that the menu does not close when the mouse button is
6215 released without an item selected the menu is not closed and a mouse button
6216 must be clicked to choose an item.
6218 The following keys are also available:
6219 .Bl -column "Key" "Function" -offset indent
6220 .It Sy "Key" Ta Sy "Function"
6221 .It Li "Enter" Ta "Choose selected item"
6222 .It Li "Up" Ta "Select previous item"
6223 .It Li "Down" Ta "Select next item"
6224 .It Li "q" Ta "Exit menu"
6227 .It Xo Ic display-message
6229 .Op Fl c Ar target-client
6231 .Op Fl t Ar target-pane
6234 .D1 Pq alias: Ic display
6238 is given, the output is printed to stdout, otherwise it is displayed in the
6240 status line for up to
6247 option is used; a delay of zero waits for a key press.
6249 ignores key presses and closes only after the delay expires.
6254 is printed unchanged.
6255 Otherwise, the format of
6259 section; information is taken from
6263 is given, otherwise the active pane.
6266 prints verbose logging as the format is parsed and
6268 lists the format variables and their values.
6271 forwards any input read from stdin to the empty pane given by
6274 .It Xo Ic display-popup
6276 .Op Fl b Ar border-lines
6277 .Op Fl c Ar target-client
6278 .Op Fl d Ar start-directory
6279 .Op Fl e Ar environment
6281 .Op Fl s Ar border-style
6283 .Op Fl t Ar target-pane
6286 .Op Fl x Ar position
6287 .Op Fl y Ar position
6288 .Op Ar shell-command
6290 .D1 Pq alias: Ic popup
6291 Display a popup running
6295 A popup is a rectangular box drawn over the top of any panes.
6296 Panes are not updated while a popup is present.
6299 closes the popup automatically when
6304 closes the popup only if
6306 exited with success.
6311 give the position of the popup, they have the same meaning as for the
6317 give the width and height - both may be a percentage (followed by
6319 If omitted, half of the terminal size is used.
6322 does not surround the popup by a border.
6325 sets the type of characters used for drawing popup borders.
6332 .Ic popup-border-lines
6333 for possible values for
6337 sets the style for the popup and
6339 sets the style for the popup border (see
6345 and sets an environment variable for the popup; it may be specified multiple
6349 is a format for the popup title (see
6354 flag closes any popup on the client.
6356 .It Xo Ic show-prompt-history
6357 .Op Fl T Ar prompt-type
6359 .D1 Pq alias: Ic showphist
6360 Display status prompt history for prompt type
6364 is omitted, then show history for all types.
6367 for possible values for
6372 maintains a set of named
6374 Each buffer may be either explicitly or automatically named.
6375 Explicitly named buffers are named when created with the
6379 commands, or by renaming an automatically named buffer with
6382 Automatically named buffers are given a name such as
6388 option is reached, the oldest automatically named buffer is deleted.
6389 Explicitly named buffers are not subject to
6391 and may be deleted with the
6395 Buffers may be added using
6401 commands, and pasted into a window using the
6404 If a buffer command is used and no buffer is specified, the most
6405 recently added automatically named buffer is assumed.
6407 A configurable history buffer is also maintained for each window.
6408 By default, up to 2000 lines are kept; this can be altered with the
6414 The buffer commands are as follows:
6421 .Op Fl K Ar key-format
6422 .Op Fl O Ar sort-order
6423 .Op Fl t Ar target-pane
6426 Put a pane into buffer mode, where a buffer may be chosen interactively from
6428 Each buffer is shown on one line.
6429 A shortcut key is shown on the left in brackets allowing for immediate choice,
6430 or the list may be navigated and an item chosen or otherwise manipulated using
6434 The following keys may be used in buffer mode:
6435 .Bl -column "Key" "Function" -offset indent
6436 .It Sy "Key" Ta Sy "Function"
6437 .It Li "Enter" Ta "Paste selected buffer"
6438 .It Li "Up" Ta "Select previous buffer"
6439 .It Li "Down" Ta "Select next buffer"
6440 .It Li "C-s" Ta "Search by name or content"
6441 .It Li "n" Ta "Repeat last search"
6442 .It Li "t" Ta "Toggle if buffer is tagged"
6443 .It Li "T" Ta "Tag no buffers"
6444 .It Li "C-t" Ta "Tag all buffers"
6445 .It Li "p" Ta "Paste selected buffer"
6446 .It Li "P" Ta "Paste tagged buffers"
6447 .It Li "d" Ta "Delete selected buffer"
6448 .It Li "D" Ta "Delete tagged buffers"
6449 .It Li "e" Ta "Open the buffer in an editor"
6450 .It Li "f" Ta "Enter a format to filter items"
6451 .It Li "O" Ta "Change sort field"
6452 .It Li "r" Ta "Reverse sort order"
6453 .It Li "v" Ta "Toggle preview"
6454 .It Li "q" Ta "Exit mode"
6457 After a buffer is chosen,
6459 is replaced by the buffer name in
6461 and the result executed as a command.
6464 is not given, "paste-buffer -b \[aq]%%\[aq]" is used.
6467 specifies the initial sort field: one of
6474 reverses the sort order.
6476 specifies an initial filter: the filter is a format - if it evaluates to zero,
6477 the item in the list is not shown, otherwise it is shown.
6478 If a filter would lead to an empty list, it is ignored.
6480 specifies the format for each item in the list and
6482 a format for each shortcut key; both are evaluated once for each line.
6484 starts without the preview.
6485 This command works only if at least one client is attached.
6487 .It Xo Ic clear-history
6489 .Op Fl t Ar target-pane
6491 .D1 Pq alias: Ic clearhist
6492 Remove and free the history for the specified pane.
6494 also removes all hyperlinks.
6496 .It Ic delete-buffer Op Fl b Ar buffer-name
6497 .D1 Pq alias: Ic deleteb
6498 Delete the buffer named
6500 or the most recently added automatically named buffer if not specified.
6502 .It Xo Ic list-buffers
6506 .D1 Pq alias: Ic lsb
6507 List the global buffers.
6509 specifies the format of each line and
6512 Only buffers for which the filter is true are shown.
6516 .It Xo Ic load-buffer
6518 .Op Fl b Ar buffer-name
6519 .Op Fl t Ar target-client
6523 .D1 Pq alias: Ic loadb
6524 Load the contents of the specified paste buffer from
6528 is given, the buffer is also sent to the clipboard for
6532 escape sequence, if possible.
6534 .It Xo Ic paste-buffer
6536 .Op Fl b Ar buffer-name
6537 .Op Fl s Ar separator
6538 .Op Fl t Ar target-pane
6540 .D1 Pq alias: Ic pasteb
6541 Insert the contents of a paste buffer into the specified pane.
6542 If not specified, paste into the current one.
6545 also delete the paste buffer.
6546 When output, any linefeed (LF) characters in the paste buffer are replaced with
6547 a separator, by default carriage return (CR).
6548 A custom separator may be specified using the
6553 flag means to do no replacement (equivalent to a separator of LF).
6556 is specified, paste bracket control codes are inserted around the
6557 buffer if the application has requested bracketed paste mode.
6559 .It Xo Ic save-buffer
6561 .Op Fl b Ar buffer-name
6564 .D1 Pq alias: Ic saveb
6565 Save the contents of the specified paste buffer to
6569 option appends to rather than overwriting the file.
6570 .It Xo Ic set-buffer
6572 .Op Fl b Ar buffer-name
6573 .Op Fl t Ar target-client
6575 .Op Fl n Ar new-buffer-name
6578 .D1 Pq alias: Ic setb
6579 Set the contents of the specified buffer to
6583 is given, the buffer is also sent to the clipboard for
6587 escape sequence, if possible.
6590 option appends to rather than overwriting the buffer.
6593 option renames the buffer to
6594 .Ar new-buffer-name .
6596 .It Xo Ic show-buffer
6597 .Op Fl b Ar buffer-name
6599 .D1 Pq alias: Ic showb
6600 Display the contents of the specified buffer.
6603 Miscellaneous commands are as follows:
6605 .It Ic clock-mode Op Fl t Ar target-pane
6606 Display a large clock.
6610 .Op Fl t Ar target-pane
6611 .Ar shell-command command
6621 returns success or the second
6624 Before being executed,
6626 is expanded using the rules specified in the
6628 section, including those relevant to
6633 is run in the background.
6639 is not executed but considered success if neither empty nor zero (after formats
6643 .D1 Pq alias: Ic lock
6644 Lock each client individually by running the command specified by the
6650 .Op Fl c Ar start-directory
6652 .Op Fl t Ar target-pane
6653 .Op Ar shell-command
6655 .D1 Pq alias: Ic run
6664 command in the background without creating a window.
6665 Before being executed,
6667 is expanded using the rules specified in the
6672 the command is run in the background.
6676 seconds before starting the command.
6679 is given, the current working directory is set to
6680 .Ar start-directory .
6683 is not given, any output to stdout is displayed in view mode (in the pane
6686 or the current pane if omitted) after the command finishes.
6687 If the command fails, the exit status is also displayed.
6693 .D1 Pq alias: Ic wait
6694 When used without options, prevents the client from exiting until woken using
6697 with the same channel.
6700 is used, the channel is locked and any clients that try to lock the same
6701 channel are made to wait until the channel is unlocked with
6708 client detaches, it prints a message.
6711 .It detached (from session ...)
6712 The client was detached normally.
6713 .It detached and SIGHUP
6714 The client was detached and its parent sent the
6716 signal (for example with
6724 was unexpectedly destroyed.
6726 The client was killed with
6729 The client is in control mode and became unable to keep up with the data from
6732 The server exited when it had no sessions.
6734 The server exited when it received
6736 .It server exited unexpectedly
6737 The server crashed or otherwise exited without telling the client the reason.
6739 .Sh TERMINFO EXTENSIONS
6741 understands some unofficial extensions to
6743 It is not normally necessary to set these manually, instead the
6744 .Ic terminal-features
6745 option should be used.
6748 An existing extension that tells
6750 the terminal supports default colours.
6754 that the terminal supports the VTE bidirectional text extensions.
6756 Set the cursor colour.
6757 The first takes a single string argument and is used to set the colour;
6758 the second takes no arguments and restores the default cursor colour.
6759 If set, a sequence such as this may be used
6760 to change the cursor colour from inside
6762 .Bd -literal -offset indent
6763 $ printf \[aq]\e033]12;red\e033\e\e\[aq]
6770 .It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg
6771 Set, clear, disable or enable DECSLRM margins.
6772 These are set automatically if the terminal reports it is
6775 .It Em \&Dsbp , \&Enbp
6776 Disable and enable bracketed paste.
6777 These are set automatically if the
6779 capability is present.
6780 .It Em \&Dseks , \&Eneks
6781 Disable and enable extended keys.
6782 .It Em \&Dsfcs , \&Enfcs
6783 Disable and enable focus reporting.
6784 These are set automatically if the
6786 capability is present.
6788 Set or clear a hyperlink annotation.
6792 that the terminal does not use bright colors for bold display.
6796 that the terminal supports rectangle operations.
6798 Enable the overline attribute.
6800 Set a styled underscore.
6801 The single parameter is one of: 0 for no underscore, 1 for normal
6802 underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted
6803 underscore and 5 for dashed underscore.
6804 .It Em \&Setulc , \&Setulc1, \&ol
6805 Set the underscore colour or reset to the default.
6807 is for RGB colours and
6809 for ANSI or 256 colours.
6812 argument is (red * 65536) + (green * 256) + blue where each is between 0
6815 Set or reset the cursor style.
6816 If set, a sequence such as this may be used
6817 to change the cursor to an underline:
6818 .Bd -literal -offset indent
6819 $ printf \[aq]\e033[4 q\[aq]
6824 is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
6826 Set the opening sequence for the working directory notification.
6827 The sequence is terminated using the standard
6831 Indicates that the terminal supports SIXEL.
6833 Start (parameter is 1) or end (parameter is 2) a synchronized update.
6835 Indicate that the terminal supports the
6837 RGB escape sequence (for example, \ee[38;2;255;255;255m).
6839 If supported, this is used for the initialize colour escape sequence (which
6840 may be enabled by adding the
6849 This is equivalent to the
6854 Store the current buffer in the host terminal's selection (clipboard).
6857 option above and the
6861 This is an existing extension capability that tmux uses to mean that the
6862 terminal supports the
6864 title set sequences and to automatically set some of the capabilities above.
6868 offers a textual interface called
6870 This allows applications to communicate with
6872 using a simple text-only protocol.
6874 In control mode, a client sends
6876 commands or command sequences terminated by newlines on standard input.
6877 Each command will produce one block of output on standard output.
6878 An output block consists of a
6880 line followed by the output (which may be empty).
6881 The output block ends with a
6890 have three arguments: an integer time (as seconds from epoch), command number
6891 and flags (currently not used).
6893 .Bd -literal -offset indent
6894 %begin 1363006971 2 1
6895 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
6902 command may be used to set the size of a client in control mode.
6906 outputs notifications.
6907 A notification will never occur inside an output block.
6909 The following notifications are defined:
6911 .It Ic %client-detached Ar client
6912 The client has detached.
6913 .It Ic %client-session-changed Ar client session-id name
6914 The client is now attached to the session with ID
6918 .It Ic %config-error Ar error
6919 An error has happened in a configuration file.
6920 .It Ic %continue Ar pane-id
6921 The pane has been continued after being paused (if the
6926 .It Ic %exit Op Ar reason
6929 client is exiting immediately, either because it is not attached to any session
6930 or an error occurred.
6933 describes why the client exited.
6934 .It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value
6941 is the time in milliseconds for which tmux had buffered the output before it
6943 Any subsequent arguments up until a single
6945 are for future use and should be ignored.
6946 .It Xo Ic %layout-change
6949 .Ar window-visible-layout
6952 The layout of a window with ID
6957 The window's visible layout is
6958 .Ar window-visible-layout
6959 and the window flags are
6961 .It Ic %message Ar message
6962 A message sent with the
6965 .It Ic %output Ar pane-id Ar value
6966 A window pane produced output.
6968 escapes non-printable characters and backslash as octal \\xxx.
6969 .It Ic %pane-mode-changed Ar pane-id
6973 .It Ic %paste-buffer-changed Ar name
6977 .It Ic %paste-buffer-deleted Ar name
6981 .It Ic %pause Ar pane-id
6982 The pane has been paused (if the
6985 .It Ic %session-changed Ar session-id Ar name
6986 The client is now attached to the session with ID
6990 .It Ic %session-renamed Ar name
6991 The current session was renamed to
6993 .It Ic %session-window-changed Ar session-id Ar window-id
6996 changed its active window to the window with ID
6998 .It Ic %sessions-changed
6999 A session was created or destroyed.
7000 .It Xo Ic %subscription-changed
7005 .Ar pane-id ... \& :
7008 The value of the format associated with subscription
7019 are for future use and should be ignored.
7020 .It Ic %unlinked-window-add Ar window-id
7023 was created but is not linked to the current session.
7024 .It Ic %unlinked-window-close Ar window-id
7027 which is not linked to the current session, was closed.
7028 .It Ic %unlinked-window-renamed Ar window-id
7031 which is not linked to the current session, was renamed.
7032 .It Ic %window-add Ar window-id
7035 was linked to the current session.
7036 .It Ic %window-close Ar window-id
7040 .It Ic %window-pane-changed Ar window-id Ar pane-id
7041 The active pane in the window with ID
7043 changed to the pane with ID
7045 .It Ic %window-renamed Ar window-id Ar name
7054 is started, it inspects the following environment variables:
7055 .Bl -tag -width LC_CTYPE
7057 If the command specified in this variable contains the string
7061 is unset, use vi-style key bindings.
7068 The user's login directory.
7071 database is consulted.
7073 The character encoding
7075 It is used for two separate purposes.
7076 For output to the terminal, UTF-8 is used if the
7078 option is given or if
7084 Otherwise, only ASCII characters are written and non-ASCII characters
7085 are replaced with underscores
7089 always runs with a UTF-8 locale.
7090 If en_US.UTF-8 is provided by the operating system, it is used and
7092 is ignored for input.
7097 what the UTF-8 locale is called on the current system.
7098 If the locale specified by
7100 is not available or is not a UTF-8 locale,
7102 exits with an error message.
7104 The date and time format
7106 It is used for locale-dependent
7110 The current working directory to be set in the global environment.
7111 This may be useful if it contains symbolic links.
7112 If the value of the variable does not match the current working
7113 directory, the variable is ignored and the result of
7117 The absolute path to the default shell for new windows.
7122 The parent directory of the directory containing the server sockets.
7127 If the command specified in this variable contains the string
7129 use vi-style key bindings.
7137 .Bl -tag -width "/etc/tmux.confXXX" -compact
7138 .It Pa \[ti]/.tmux.conf
7142 .It Pa /etc/tmux.conf
7143 System-wide configuration file.
7151 .Dl $ tmux new-session vi
7153 Most commands have a shorter form, known as an alias.
7154 For new-session, this is
7159 Alternatively, the shortest unambiguous form of a command is accepted.
7160 If there are several options, they are listed:
7161 .Bd -literal -offset indent
7163 ambiguous command: n, could be: new-session, new-window, next-window
7166 Within an active session, a new window may be created by typing
7176 Windows may be navigated with:
7178 (to select window 0),
7180 (to select window 1), and so on;
7182 to select the next window; and
7184 to select the previous window.
7186 A session may be detached using
7188 (or by an external event such as
7190 disconnection) and reattached with:
7192 .Dl $ tmux attach-session
7196 lists the current key bindings in the current window; up and down may be used
7197 to navigate the list or
7201 Commands to be run when the
7203 server is started may be placed in the
7204 .Pa \[ti]/.tmux.conf
7206 Common examples include:
7208 Changing the default prefix key:
7209 .Bd -literal -offset indent
7210 set-option -g prefix C-a
7212 bind-key C-a send-prefix
7215 Turning the status line off, or changing its colour:
7216 .Bd -literal -offset indent
7217 set-option -g status off
7218 set-option -g status-style bg=blue
7221 Setting other options, such as the default command,
7222 or locking after 30 minutes of inactivity:
7223 .Bd -literal -offset indent
7224 set-option -g default-command "exec /bin/ksh"
7225 set-option -g lock-after-time 1800
7228 Creating new key bindings:
7229 .Bd -literal -offset indent
7230 bind-key b set-option status
7231 bind-key / command-prompt "split-window \[aq]exec man %%\[aq]"
7232 bind-key S command-prompt "new-window -n %1 \[aq]ssh %1\[aq]"
7237 .An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com