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
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 Write UTF-8 output to the terminal even if the first environment
213 that is set does not contain
217 This is equivalent to
220 Set terminal features for the client.
221 This is a comma-separated list of features.
223 .Ic terminal-features
226 Request verbose logging.
227 Log messages will be saved into
228 .Pa tmux-client-PID.log
230 .Pa tmux-server-PID.log
231 files in the current directory, where
233 is the PID of the server or client process.
236 is specified twice, an additional
238 file is generated with a copy of everything
240 writes to the terminal.
244 signal may be sent to the
246 server process to toggle logging between on (as if
253 .It Ar command Op Ar flags
254 This specifies one of a set of commands used to control
256 as described in the following sections.
257 If no commands are specified, the
261 .Sh DEFAULT KEY BINDINGS
263 may be controlled from an attached client by using a key combination of a
266 (Ctrl-b) by default, followed by a command key.
268 The default command key bindings are:
270 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
272 Send the prefix key (C-b) through to the application.
274 Rotate the panes in the current window forwards.
280 Break the current pane out of the window.
283 Split the current pane into two, top and bottom.
285 List all paste buffers.
287 Rename the current session.
289 Split the current pane into two, left and right.
291 Kill the current window.
293 Prompt for a window index to select.
295 Switch the attached client to the previous session.
297 Switch the attached client to the next session.
299 Rename the current window.
301 Delete the most recently copied buffer of text.
303 Prompt for an index to move the current window.
305 Select windows 0 to 9.
311 Move to the previously active pane.
313 Choose which buffer to paste interactively from a list.
315 List all key bindings.
317 Choose a client to detach.
319 Switch the attached client back to the last session.
321 Enter copy mode to copy text or view the history.
323 Paste the most recently copied buffer of text.
327 Detach the current client.
329 Prompt to search for text in open windows.
331 Display some information about the current window.
333 Move to the previously selected window.
335 Mark the current pane (see
339 Clear the marked pane.
341 Change to the next window.
343 Select the next pane in the current window.
345 Change to the previous window.
347 Briefly display pane indexes.
349 Force redraw of the attached client.
351 Select a new session for the attached client interactively.
355 Choose the current window interactively.
357 Kill the current pane.
359 Toggle zoom state of the current pane.
361 Swap the current pane with the previous pane.
363 Swap the current pane with the next pane.
365 Show previous messages from
369 Enter copy mode and scroll one page up.
372 Change to the pane above, below, to the left, or to the right of the current
375 Arrange panes in one of the five preset layouts: even-horizontal,
376 even-vertical, main-horizontal, main-vertical, or tiled.
378 Arrange the current window in the next preset layout.
380 Move to the next window with a bell or activity marker.
382 Rotate the panes in the current window backwards.
384 Move to the previous window with a bell or activity marker.
387 Resize the current pane in steps of one cell.
390 Resize the current pane in steps of five cells.
393 Key bindings may be changed with the
398 .Sh COMMAND PARSING AND EXECUTION
400 supports a large number of commands which can be used to control its
402 Each command is named and can accept zero or more flags and arguments.
403 They may be bound to a key with the
405 command or run from the shell prompt, a shell script, a configuration file or
407 For example, the same
409 command run from the shell prompt, from
411 and bound to a key may look like:
412 .Bd -literal -offset indent
413 $ tmux set-option -g status-style bg=cyan
415 set-option -g status-style bg=cyan
417 bind-key C set-option -g status-style bg=cyan
420 Here, the command name is
430 distinguishes between command parsing and execution.
431 In order to execute a command,
433 needs it to be split up into its name and arguments.
434 This is command parsing.
435 If a command is run from the shell, the shell parses it; from inside
437 or from a configuration file,
443 .Bl -dash -offset indent
445 in a configuration file;
447 typed at the command prompt (see
448 .Ic command-prompt ) ;
453 passed as arguments to
459 To execute commands, each client has a
461 A global command queue not attached to any client is used on startup
462 for configuration files like
464 Parsed commands added to the queue are executed in order.
469 parse their argument to create a new command which is inserted immediately
471 This means that arguments can be parsed twice or more - once when the parent command (such as
473 is parsed and again when it parses and executes its command.
479 stop execution of subsequent commands on the queue until something happens -
483 until a shell command finishes and
485 until a key is pressed.
486 For example, the following commands:
487 .Bd -literal -offset indent
488 new-session; new-window
489 if-shell "true" "split-window"
508 commands and their arguments.
510 This section describes the syntax of commands parsed by
512 for example in a configuration file or at the command prompt.
513 Note that when commands are entered into the shell, they are parsed by the shell
519 Each command is terminated by a newline or a semicolon (;).
520 Commands separated by semicolons together form a
522 - if a command in the sequence encounters an error, no subsequent commands are
525 It is recommended that a semicolon used as a command separator should be
526 written as an individual token, for example from
528 .Bd -literal -offset indent
529 $ tmux neww \\; splitw
533 .Bd -literal -offset indent
534 $ tmux neww ';' splitw
537 Or from the tmux command prompt:
538 .Bd -literal -offset indent
542 However, a trailing semicolon is also interpreted as a command separator,
546 .Bd -literal -offset indent
547 $ tmux neww\e\e; splitw
551 .Bd -literal -offset indent
552 $ tmux 'neww;' splitw
555 As in these examples, when running tmux from the shell extra care must be taken
556 to properly quote semicolons:
559 Semicolons that should be interpreted as a command separator
560 should be escaped according to the shell conventions.
563 this typically means quoted (such as
564 .Ql neww ';' splitw )
566 .Ql neww \e\e\e\e; splitw ) .
568 Individual semicolons or trailing semicolons that should be interpreted as
569 arguments should be escaped twice: once according to the shell conventions and
573 .Bd -literal -offset indent
574 $ tmux neww 'foo\e\e;' bar
575 $ tmux neww foo\e\e\e\e; bar
578 Semicolons that are not individual tokens or trailing another token should only
579 be escaped once according to shell conventions; for example:
580 .Bd -literal -offset indent
581 $ tmux neww 'foo-;-bar'
582 $ tmux neww foo-\e\e;-bar
586 Comments are marked by the unquoted # character - any remaining text after a
587 comment is ignored until the end of the line.
589 If the last character of a line is \e, the line is joined with the following
590 line (the \e and the newline are completely removed).
591 This is called line continuation and applies both inside and outside quoted
592 strings and in comments, but not inside braces.
594 Command arguments may be specified as strings surrounded by single (') quotes,
595 double quotes (") or braces ({}).
597 This is required when the argument contains any special character.
598 Single and double quoted strings cannot span multiple lines except with line
600 Braces can span multiple lines.
602 Outside of quotes and inside double quotes, these replacements are performed:
603 .Bl -dash -offset indent
605 Environment variables preceded by $ are replaced with their value from the
606 global environment (see the
607 .Sx GLOBAL AND SESSION ENVIRONMENT
610 A leading ~ or ~user is expanded to the home directory of the current or
613 \euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to
614 the given four or eight digit hexadecimal number.
616 When preceded (escaped) by a \e, the following characters are replaced: \ee by
617 the escape character; \er by a carriage return; \en by a newline; and \et by a
620 \eooo is replaced by a character of the octal value ooo.
621 Three octal digits are required, for example \e001.
622 The largest valid character is \e377.
624 Any other characters preceded by \e are replaced by themselves (that is, the \e
625 is removed) and are not treated as having any special meaning - so for example
626 \e; will not mark a command sequence and \e$ will not expand an environment
630 Braces are parsed as a configuration file (so conditions such as
632 are processed) and then converted into a string.
633 They are designed to avoid the need for additional escaping when passing a
636 commands as an argument (for example to
638 These two examples produce an identical command - note that no escaping is
639 needed when using {}:
640 .Bd -literal -offset indent
642 display -p 'brace-dollar-foo: }$foo'
645 if-shell true "display -p 'brace-dollar-foo: }\e$foo'"
648 Braces may be enclosed inside braces, for example:
649 .Bd -literal -offset indent
650 bind x if-shell "true" {
657 Environment variables may be set by using the syntax
660 .Ql HOME=/home/user .
661 Variables set during parsing are added to the global environment.
662 A hidden variable may be set with
665 .Bd -literal -offset indent
669 Hidden variables are not passed to the environment of processes created
672 .Sx GLOBAL AND SESSION ENVIRONMENT
675 Commands may be parsed conditionally by surrounding them with
685 is expanded as a format (see
687 and if it evaluates to false (zero or empty), subsequent text is ignored until
694 .Bd -literal -offset indent
695 %if "#{==:#{host},myhost}"
696 set -g status-style bg=red
697 %elif "#{==:#{host},myotherhost}"
698 set -g status-style bg=green
700 set -g status-style bg=blue
704 Will change the status line to red if running on
708 or blue if running on another host.
709 Conditionals may be given on one line, for example:
710 .Bd -literal -offset indent
711 %if #{==:#{host},myhost} set -g status-style bg=red %endif
714 This section describes the commands supported by
716 Most commands accept the optional
726 These specify the client, session, window or pane which a command should affect.
729 should be the name of the client,
732 file to which the client is connected, for example either of
736 for the client attached to
738 If no client is specified,
740 attempts to work out the client currently in use; if that fails, an error is
742 Clients may be listed with the
747 is tried as, in order:
750 A session ID prefixed with a $.
752 An exact name of a session (as listed by the
756 The start of a session name, for example
758 would match a session named
763 pattern which is matched against the session name.
766 If the session name is prefixed with an
768 only an exact match is accepted (so
770 will only match exactly
775 If a single session is found, it is used as the target session; multiple matches
777 If a session is omitted, the current session is used if available; if no
778 current session is available, the most recently used is chosen.
785 specifies a window in the form
786 .Em session Ns \&: Ns Em window .
788 follows the same rules as for
792 is looked for in order as:
795 A special token, listed below.
797 A window index, for example
799 is window 1 in session
802 A window ID, such as @1.
804 An exact window name, such as
805 .Ql mysession:mywindow .
807 The start of a window name, such as
808 .Ql mysession:mywin .
812 pattern matched against the window name.
817 prefix will do an exact match only.
818 An empty window name specifies the next unused index if appropriate (for
824 otherwise the current window in
828 The following special tokens are available to indicate particular windows.
829 Each has a single-character alternative form.
830 .Bl -column "XXXXXXXXXX" "X"
831 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
832 .It Li "{start}" Ta "^" Ta "The lowest-numbered window"
833 .It Li "{end}" Ta "$" Ta "The highest-numbered window"
834 .It Li "{last}" Ta "!" Ta "The last (previously current) window"
835 .It Li "{next}" Ta "+" Ta "The next window by number"
836 .It Li "{previous}" Ta "-" Ta "The previous window by number"
844 may be a pane ID or takes a similar form to
846 but with the optional addition of a period followed by a pane index or pane ID,
848 .Ql mysession:mywindow.1 .
849 If the pane index is omitted, the currently active pane in the specified
851 The following special tokens are available for the pane index:
852 .Bl -column "XXXXXXXXXXXXXX" "X"
853 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
854 .It Li "{last}" Ta "!" Ta "The last (previously active) pane"
855 .It Li "{next}" Ta "+" Ta "The next pane by number"
856 .It Li "{previous}" Ta "-" Ta "The previous pane by number"
857 .It Li "{top}" Ta "" Ta "The top pane"
858 .It Li "{bottom}" Ta "" Ta "The bottom pane"
859 .It Li "{left}" Ta "" Ta "The leftmost pane"
860 .It Li "{right}" Ta "" Ta "The rightmost pane"
861 .It Li "{top-left}" Ta "" Ta "The top-left pane"
862 .It Li "{top-right}" Ta "" Ta "The top-right pane"
863 .It Li "{bottom-left}" Ta "" Ta "The bottom-left pane"
864 .It Li "{bottom-right}" Ta "" Ta "The bottom-right pane"
865 .It Li "{up-of}" Ta "" Ta "The pane above the active pane"
866 .It Li "{down-of}" Ta "" Ta "The pane below the active pane"
867 .It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane"
868 .It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane"
875 may be followed by an offset, for example:
876 .Bd -literal -offset indent
885 may consist entirely of the token
889 to specify the session, window or pane where the most recent mouse event occurred
897 to specify the marked pane (see
901 Sessions, window and panes are each numbered with a unique ID; session IDs are
908 These are unique and are unchanged for the life of the session, window or pane
912 The pane ID is passed to the child process of the pane in the
914 environment variable.
915 IDs may be displayed using the
923 .Ic display-message ,
934 This may be a single argument passed to the shell, for example:
935 .Bd -literal -offset indent
936 new-window 'vi ~/.tmux.conf'
940 .Bd -literal -offset indent
941 /bin/sh -c 'vi ~/.tmux.conf'
953 to be given as multiple arguments and executed directly (without
955 This can avoid issues with shell quoting.
957 .Bd -literal -offset indent
958 $ tmux new-window vi ~/.tmux.conf
963 directly without invoking the shell.
969 command, either passed with the command and arguments separately, for example:
970 .Bd -literal -offset indent
971 bind-key F1 set-option status off
974 Or passed as a single string argument in
977 .Bd -literal -offset indent
978 bind-key F1 { set-option status off }
984 .Bd -literal -offset indent
985 refresh-client -t/dev/ttyp2
987 rename-session -tfirst newname
989 set-option -wt:0 monitor-activity on
991 new-window ; split-window -d
993 bind-key R source-file ~/.tmux.conf \e; \e
994 display-message "source-file done"
999 .Bd -literal -offset indent
1000 $ tmux kill-window -t :1
1002 $ tmux new-window \e; split-window -d
1004 $ tmux new-session -d 'vi ~/.tmux.conf' \e; split-window -d \e; attach
1006 .Sh CLIENTS AND SESSIONS
1009 server manages clients, sessions, windows and panes.
1010 Clients are attached to sessions to interact with them, either
1011 when they are created with the
1013 command, or later with the
1016 Each session has one or more windows
1019 Windows may be linked to multiple sessions and are made up of one or
1021 each of which contains a pseudo terminal.
1022 Commands for creating, linking and otherwise manipulating windows
1025 .Sx WINDOWS AND PANES
1028 The following commands are available to manage clients and sessions:
1031 .It Xo Ic attach-session
1033 .Op Fl c Ar working-directory
1035 .Op Fl t Ar target-session
1037 .D1 Pq alias: Ic attach
1040 create a new client in the current terminal and attach it to
1041 .Ar target-session .
1042 If used from inside, switch the current client.
1045 is specified, any other clients attached to the session are detached.
1050 to the parent process of the client as well as
1051 detaching the client, typically causing it to exit.
1053 sets a comma-separated list of client flags.
1057 the client has an independent active pane
1059 the client does not affect the size of other clients
1061 the client does not receive pane output in control mode
1062 .It pause-after=seconds
1063 output is paused once the pane is
1065 behind in control mode
1067 the client is read-only
1069 wait for an empty line input before exiting in control mode
1074 turns a flag off if the client is already attached.
1078 .Ar read-only,ignore-size .
1079 When a client is read-only, only keys bound to the
1083 commands have any effect.
1086 flag allows the active pane to be selected independently of the window's active
1087 pane used by clients without the flag.
1088 This only affects the cursor position and commands issued from the client;
1089 other features such as hooks and styles continue to use the window's active
1092 If no server is started,
1094 will attempt to start it; this will fail unless sessions are created in the
1101 are slightly adjusted: if
1103 needs to select the most recently used session, it will prefer the most
1109 will set the session working directory (used for new windows) to
1110 .Ar working-directory .
1115 .Ic update-environment
1116 option will not be applied.
1118 .It Xo Ic detach-client
1120 .Op Fl E Ar shell-command
1121 .Op Fl s Ar target-session
1122 .Op Fl t Ar target-client
1124 .D1 Pq alias: Ic detach
1125 Detach the current client if bound to a key, the client specified with
1127 or all clients currently attached to the session specified by
1131 option kills all but the client given with
1137 to the parent process of the client, typically causing it
1143 to replace the client.
1145 .It Ic has-session Op Fl t Ar target-session
1146 .D1 Pq alias: Ic has
1147 Report an error and exit with 1 if the specified session does not exist.
1148 If it does exist, exit with 0.
1152 server and clients and destroy all sessions.
1153 .It Xo Ic kill-session
1155 .Op Fl t Ar target-session
1157 Destroy the given session, closing any windows linked to it and no other
1158 sessions, and detaching all clients attached to it.
1161 is given, all sessions but the specified one is killed.
1164 flag clears alerts (bell, activity, or silence) in all windows linked to the
1167 .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.
1173 For the meaning of the
1180 is specified, list only clients connected to that session.
1182 .It Xo Ic list-commands
1186 .D1 Pq alias: Ic lscm
1189 or - if omitted - of all commands supported by
1192 .It Xo Ic list-sessions
1197 List all sessions managed by the server.
1199 specifies the format of each line and
1202 Only sessions for which the filter is true are shown.
1207 .It Ic lock-client Op Fl t Ar target-client
1208 .D1 Pq alias: Ic lockc
1215 .It Ic lock-session Op Fl t Ar target-session
1216 .D1 Pq alias: Ic locks
1217 Lock all clients attached to
1218 .Ar target-session .
1220 .It Xo Ic new-session
1222 .Op Fl c Ar start-directory
1223 .Op Fl e Ar environment
1226 .Op Fl n Ar window-name
1227 .Op Fl s Ar session-name
1228 .Op Fl t Ar group-name
1231 .Op Ar shell-command
1233 .D1 Pq alias: Ic new
1234 Create a new session with name
1237 The new session is attached to the current terminal unless
1243 are the name of and shell command to execute in the initial window.
1246 the initial size comes from the global
1252 can be used to specify a different size.
1254 uses the size of the current client if any.
1261 option is set for the session.
1263 sets a comma-separated list of client flags (see
1264 .Ic attach-session ) .
1266 If run from a terminal, any
1268 special characters are saved and used for new windows in the new session.
1278 already exists; in this case,
1283 .Ic attach-session ,
1289 .Ic attach-session .
1293 is given, it specifies a
1295 Sessions in the same group share the same set of windows - new windows are
1296 linked to all sessions in the group and any windows closed removed from all
1298 The current and previous window and any session options remain independent and
1299 any session in a group may be killed without affecting the others.
1305 the name of an existing group, in which case the new session is added to that
1308 the name of an existing session - the new session is added to the same group
1309 as that session, creating a new group if necessary;
1311 the name for a new group containing only the new session.
1323 option prints information about the new session after it has been created.
1324 By default, it uses the format
1325 .Ql #{session_name}:\&
1326 but a different format may be specified with
1332 .Ic update-environment
1333 option will not be applied.
1337 and sets an environment variable for the newly created session; it may be
1338 specified multiple times.
1340 .It Xo Ic refresh-client
1342 .Op Fl A Ar pane:state
1343 .Op Fl B Ar name:what:format
1346 .Op Fl l Op Ar target-pane
1347 .Op Fl t Ar target-client
1350 .D1 Pq alias: Ic refresh
1351 Refresh the current client if bound to a key, or a single client if one is given
1356 is specified, only update the client's status line.
1365 flags allow the visible portion of a window which is larger than the client
1368 moves the visible part up by
1380 returns to tracking the cursor automatically.
1383 is omitted, 1 is used.
1384 Note that the visible position is a property of the client not of the
1385 window, changing the current window in the attached session will reset
1389 sets the width and height of a control mode client or of a window for a
1390 control mode client,
1395 .Ql window ID:widthxheight ,
1401 allows a control mode client to trigger actions on a pane.
1402 The argument is a pane ID (with leading
1404 a colon, then one of
1413 will not send output from the pane to the client and if all clients have turned
1414 the pane off, will stop reading from the pane.
1418 will return to sending output to the pane if it was paused (manually or with the
1424 will pause the pane.
1426 may be given multiple times for different panes.
1429 sets a subscription to a format for a control mode client.
1430 The argument is split into three items by colons:
1432 is a name for the subscription;
1434 is a type of item to subscribe to;
1437 After a subscription is added, changes to the format are reported with the
1438 .Ic %subscription-changed
1439 notification, at most once a second.
1440 If only the name is given, the subscription is removed.
1442 may be empty to check the format only for the attached session, or one of:
1446 for all panes in the attached session;
1451 for all windows in the attached session.
1454 sets a comma-separated list of client flags, see
1455 .Ic attach-session .
1458 requests the clipboard from the client using the
1463 is given, the clipboard is sent (in encoded form), otherwise it is stored in a
1471 move the visible portion of the window left, right, up or down
1474 if the window is larger than the client.
1476 resets so that the position follows the cursor.
1481 .It Xo Ic rename-session
1482 .Op Fl t Ar target-session
1485 .D1 Pq alias: Ic rename
1486 Rename the session to
1489 .It Xo Ic show-messages
1491 .Op Fl t Ar target-client
1493 .D1 Pq alias: Ic showmsgs
1494 Show server messages or information.
1495 Messages are stored, up to a maximum of the limit set by the
1501 show debugging information about jobs and terminals.
1503 .It Xo Ic source-file
1508 .D1 Pq alias: Ic source
1509 Execute commands from one or more files specified by
1518 is expanded as a format.
1521 is given, no error will be returned if
1526 the file is parsed but no commands are executed.
1528 shows the parsed commands and line numbers if possible.
1531 .D1 Pq alias: Ic start
1534 server, if not already running, without creating any sessions.
1536 Note that as by default the
1538 server will exit with no sessions, this is only useful if a session is created in
1541 is turned off, or another command is run as part of the same command sequence.
1543 .Bd -literal -offset indent
1544 $ tmux start \\; show -g
1547 .It Xo Ic suspend-client
1548 .Op Fl t Ar target-client
1550 .D1 Pq alias: Ic suspendc
1551 Suspend a client by sending
1555 .It Xo Ic switch-client
1557 .Op Fl c Ar target-client
1558 .Op Fl t Ar target-session
1559 .Op Fl T Ar key-table
1561 .D1 Pq alias: Ic switchc
1562 Switch the current session for client
1565 .Ar target-session .
1568 may refer to a pane (a target that contains
1573 to change session, window and pane.
1576 keeps the window zoomed if it was zoomed.
1582 is used, the client is moved to the last, next or previous session
1596 .Ic update-environment
1597 option will not be applied.
1600 sets the client's key table; the next key from the client will be interpreted
1603 This may be used to configure multiple prefix keys, or to bind commands to
1605 For example, to make typing
1610 .Bd -literal -offset indent
1611 bind-key -Ttable2 c list-keys
1612 bind-key -Ttable1 b switch-client -Ttable2
1613 bind-key -Troot a switch-client -Ttable1
1616 .Sh WINDOWS AND PANES
1617 Each window displayed by
1619 may be split into one or more
1621 each pane takes up a certain area of the display and is a separate terminal.
1622 A window may be split into panes using the
1625 Windows may be split horizontally (with the
1627 flag) or vertically.
1628 Panes may be resized with the
1636 by default), the current pane may be changed with the
1642 commands may be used to swap panes without changing their position.
1643 Panes are numbered beginning from zero in the order they are created.
1647 pane permits direct access to the terminal contained in the pane.
1648 A pane may also be put into one of several modes:
1649 .Bl -dash -offset indent
1651 Copy mode, which permits a section of a window or its
1652 history to be copied to a
1654 for later insertion into another window.
1655 This mode is entered with the
1660 Copied text can be pasted with the
1665 View mode, which is like copy mode but is entered when a command that produces
1668 is executed from a key binding.
1670 Choose mode, which allows an item to be chosen from a list.
1671 This may be a client, a session or window or pane, or a buffer.
1672 This mode is entered with the
1680 In copy mode an indicator is displayed in the top-right corner of the pane with
1681 the current position and the number of lines in the history.
1683 Commands are sent to copy mode using the
1688 When a key is pressed, copy mode automatically uses one of two key tables,
1696 Key tables may be viewed with the
1700 The following commands are supported in copy mode:
1701 .Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
1702 .It Sy "Command" Ta Sy "vi" Ta Sy "emacs"
1703 .It Li "append-selection" Ta "" Ta ""
1704 .It Li "append-selection-and-cancel" Ta "A" Ta ""
1705 .It Li "back-to-indentation" Ta "^" Ta "M-m"
1706 .It Li "begin-selection" Ta "Space" Ta "C-Space"
1707 .It Li "bottom-line" Ta "L" Ta ""
1708 .It Li "cancel" Ta "q" Ta "Escape"
1709 .It Li "clear-selection" Ta "Escape" Ta "C-g"
1710 .It Li "copy-end-of-line [<prefix>]" Ta "" Ta ""
1711 .It Li "copy-end-of-line-and-cancel [<prefix>]" Ta "" Ta ""
1712 .It Li "copy-pipe-end-of-line [<command>] [<prefix>]" Ta "" Ta ""
1713 .It Li "copy-pipe-end-of-line-and-cancel [<command>] [<prefix>]" Ta "D" Ta "C-k"
1714 .It Li "copy-line [<prefix>]" Ta "" Ta ""
1715 .It Li "copy-line-and-cancel [<prefix>]" Ta "" Ta ""
1716 .It Li "copy-pipe-line [<command>] [<prefix>]" Ta "" Ta ""
1717 .It Li "copy-pipe-line-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1718 .It Li "copy-pipe [<command>] [<prefix>]" Ta "" Ta ""
1719 .It Li "copy-pipe-no-clear [<command>] [<prefix>]" Ta "" Ta ""
1720 .It Li "copy-pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1721 .It Li "copy-selection [<prefix>]" Ta "" Ta ""
1722 .It Li "copy-selection-no-clear [<prefix>]" Ta "" Ta ""
1723 .It Li "copy-selection-and-cancel [<prefix>]" Ta "Enter" Ta "M-w"
1724 .It Li "cursor-down" Ta "j" Ta "Down"
1725 .It Li "cursor-down-and-cancel" Ta "" Ta ""
1726 .It Li "cursor-left" Ta "h" Ta "Left"
1727 .It Li "cursor-right" Ta "l" Ta "Right"
1728 .It Li "cursor-up" Ta "k" Ta "Up"
1729 .It Li "end-of-line" Ta "$" Ta "C-e"
1730 .It Li "goto-line <line>" Ta ":" Ta "g"
1731 .It Li "halfpage-down" Ta "C-d" Ta "M-Down"
1732 .It Li "halfpage-down-and-cancel" Ta "" Ta ""
1733 .It Li "halfpage-up" Ta "C-u" Ta "M-Up"
1734 .It Li "history-bottom" Ta "G" Ta "M->"
1735 .It Li "history-top" Ta "g" Ta "M-<"
1736 .It Li "jump-again" Ta ";" Ta ";"
1737 .It Li "jump-backward <to>" Ta "F" Ta "F"
1738 .It Li "jump-forward <to>" Ta "f" Ta "f"
1739 .It Li "jump-reverse" Ta "," Ta ","
1740 .It Li "jump-to-backward <to>" Ta "T" Ta ""
1741 .It Li "jump-to-forward <to>" Ta "t" Ta ""
1742 .It Li "jump-to-mark" Ta "M-x" Ta "M-x"
1743 .It Li "middle-line" Ta "M" Ta "M-r"
1744 .It Li "next-matching-bracket" Ta "%" Ta "M-C-f"
1745 .It Li "next-paragraph" Ta "}" Ta "M-}"
1746 .It Li "next-space" Ta "W" Ta ""
1747 .It Li "next-space-end" Ta "E" Ta ""
1748 .It Li "next-word" Ta "w" Ta ""
1749 .It Li "next-word-end" Ta "e" Ta "M-f"
1750 .It Li "other-end" Ta "o" Ta ""
1751 .It Li "page-down" Ta "C-f" Ta "PageDown"
1752 .It Li "page-down-and-cancel" Ta "" Ta ""
1753 .It Li "page-up" Ta "C-b" Ta "PageUp"
1754 .It Li "pipe [<command>] [<prefix>]" Ta "" Ta ""
1755 .It Li "pipe-no-clear [<command>] [<prefix>]" Ta "" Ta ""
1756 .It Li "pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1757 .It Li "previous-matching-bracket" Ta "" Ta "M-C-b"
1758 .It Li "previous-paragraph" Ta "{" Ta "M-{"
1759 .It Li "previous-space" Ta "B" Ta ""
1760 .It Li "previous-word" Ta "b" Ta "M-b"
1761 .It Li "rectangle-on" Ta "" Ta ""
1762 .It Li "rectangle-off" Ta "" Ta ""
1763 .It Li "rectangle-toggle" Ta "v" Ta "R"
1764 .It Li "refresh-from-pane" Ta "r" Ta "r"
1765 .It Li "scroll-down" Ta "C-e" Ta "C-Down"
1766 .It Li "scroll-down-and-cancel" Ta "" Ta ""
1767 .It Li "scroll-up" Ta "C-y" Ta "C-Up"
1768 .It Li "search-again" Ta "n" Ta "n"
1769 .It Li "search-backward <for>" Ta "?" Ta ""
1770 .It Li "search-backward-incremental <for>" Ta "" Ta "C-r"
1771 .It Li "search-backward-text <for>" Ta "" Ta ""
1772 .It Li "search-forward <for>" Ta "/" Ta ""
1773 .It Li "search-forward-incremental <for>" Ta "" Ta "C-s"
1774 .It Li "search-forward-text <for>" Ta "" Ta ""
1775 .It Li "search-reverse" Ta "N" Ta "N"
1776 .It Li "select-line" Ta "V" Ta ""
1777 .It Li "select-word" Ta "" Ta ""
1778 .It Li "set-mark" Ta "X" Ta "X"
1779 .It Li "start-of-line" Ta "0" Ta "C-a"
1780 .It Li "stop-selection" Ta "" Ta ""
1781 .It Li "toggle-position" Ta "P" Ta "P"
1782 .It Li "top-line" Ta "H" Ta "M-R"
1785 The search commands come in several varieties:
1789 search for a regular expression;
1792 variants search for a plain text string rather than a regular expression;
1794 perform an incremental search and expect to be used with the
1800 repeats the last search and
1802 does the same but reverses the direction (forward becomes backward and backward
1805 Copy commands may take an optional buffer prefix argument which is used
1806 to generate the buffer name (the default is
1808 so buffers are named
1812 Pipe commands take a command argument which is the command to which the
1813 selected text is piped.
1815 variants also copy the selection.
1818 variants of some commands exit copy mode after they have completed (for copy
1819 commands) or when the cursor reaches the bottom (for scrolling commands).
1821 variants do not clear the selection.
1823 The next and previous word keys skip over whitespace and treat consecutive
1824 runs of either word separators or other letters as words.
1825 Word separators can be customized with the
1828 Next word moves to the start of the next word, next word end to the end of the
1829 next word and previous word to the start of the previous word.
1830 The three next and previous space keys work similarly but use a space alone as
1834 to the empty string makes next/previous word equivalent to next/previous space.
1836 The jump commands enable quick movement within a line.
1837 For instance, typing
1841 will move the cursor to the next
1843 character on the current line.
1846 will then jump to the next occurrence.
1848 Commands in copy mode may be prefaced by an optional repeat count.
1849 With vi key bindings, a prefix is entered using the number keys; with
1850 emacs, the Alt (meta) key and a number begins prefix entry.
1852 The synopsis for the
1858 .Op Fl s Ar src-pane
1859 .Op Fl t Ar target-pane
1864 option scrolls one page up.
1866 begins a mouse drag (only valid if bound to a mouse key binding, see
1867 .Sx MOUSE SUPPORT ) .
1869 hides the position indicator in the top right.
1871 cancels copy mode and any other modes.
1879 specifies that scrolling to the bottom of the history (to the visible screen)
1880 should exit copy mode.
1881 While in copy mode, pressing a key other than those used for scrolling will
1882 disable this behaviour.
1883 This is intended to allow fast scrolling through a pane's history, for
1885 .Bd -literal -offset indent
1886 bind PageUp copy-mode -eu
1890 A number of preset arrangements of panes are available, these are called layouts.
1891 These may be selected with the
1893 command or cycled with
1897 by default); once a layout is chosen, panes within it may be moved and resized
1900 The following layouts are supported:
1902 .It Ic even-horizontal
1903 Panes are spread out evenly from left to right across the window.
1904 .It Ic even-vertical
1905 Panes are spread evenly from top to bottom.
1906 .It Ic main-horizontal
1907 A large (main) pane is shown at the top of the window and the remaining panes
1908 are spread from left to right in the leftover space at the bottom.
1910 .Em main-pane-height
1911 window option to specify the height of the top pane.
1912 .It Ic main-vertical
1915 but the large pane is placed on the left and the others spread from top to
1916 bottom along the right.
1921 Panes are spread out as evenly as possible over the window in both rows and
1927 may be used to apply a previously used layout - the
1929 command displays the layout of each window in a form suitable for use with
1932 .Bd -literal -offset indent
1935 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1936 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1940 automatically adjusts the size of the layout for the current window size.
1941 Note that a layout cannot be applied to a window with more panes than that
1942 from which the layout was originally defined.
1944 Commands related to windows and panes are as follows:
1947 .It Xo Ic break-pane
1950 .Op Fl n Ar window-name
1951 .Op Fl s Ar src-pane
1952 .Op Fl t Ar dst-window
1954 .D1 Pq alias: Ic breakp
1957 off from its containing window to make it the only pane in
1963 the window is moved to the next index after or before (existing windows are
1964 moved if necessary).
1967 is given, the new window does not become the current window.
1970 option prints information about the new window after it has been created.
1971 By default, it uses the format
1972 .Ql #{session_name}:#{window_index}.#{pane_index}
1973 but a different format may be specified with
1976 .It Xo Ic capture-pane
1978 .Op Fl b Ar buffer-name
1979 .Op Fl E Ar end-line
1980 .Op Fl S Ar start-line
1981 .Op Fl t Ar target-pane
1983 .D1 Pq alias: Ic capturep
1984 Capture the contents of a pane.
1987 is given, the output goes to stdout, otherwise to the buffer specified with
1989 or a new buffer if omitted.
1992 is given, the alternate screen is used, and the history is not accessible.
1993 If no alternate screen exists, an error will be returned unless
1998 is given, the output includes escape sequences for text and background
2001 also escapes non-printable characters as octal \exxx.
2003 preserves trailing spaces at each line's end and
2005 preserves trailing spaces and joins any wrapped lines.
2007 captures only any output that the pane has received that is the beginning of an
2008 as-yet incomplete escape sequence.
2013 specify the starting and ending line numbers, zero is the first line of the
2014 visible pane and negative numbers are lines in the history.
2018 is the start of the history and to
2020 the end of the visible pane.
2021 The default is to capture only the visible contents of the pane.
2027 .Op Fl K Ar key-format
2028 .Op Fl O Ar sort-order
2029 .Op Fl t Ar target-pane
2032 Put a pane into client mode, allowing a client to be selected interactively from
2034 Each client is shown on one line.
2035 A shortcut key is shown on the left in brackets allowing for immediate choice,
2036 or the list may be navigated and an item chosen or otherwise manipulated using
2040 The following keys may be used in client mode:
2041 .Bl -column "Key" "Function" -offset indent
2042 .It Sy "Key" Ta Sy "Function"
2043 .It Li "Enter" Ta "Choose selected client"
2044 .It Li "Up" Ta "Select previous client"
2045 .It Li "Down" Ta "Select next client"
2046 .It Li "C-s" Ta "Search by name"
2047 .It Li "n" Ta "Repeat last search"
2048 .It Li "t" Ta "Toggle if client is tagged"
2049 .It Li "T" Ta "Tag no clients"
2050 .It Li "C-t" Ta "Tag all clients"
2051 .It Li "d" Ta "Detach selected client"
2052 .It Li "D" Ta "Detach tagged clients"
2053 .It Li "x" Ta "Detach and HUP selected client"
2054 .It Li "X" Ta "Detach and HUP tagged clients"
2055 .It Li "z" Ta "Suspend selected client"
2056 .It Li "Z" Ta "Suspend tagged clients"
2057 .It Li "f" Ta "Enter a format to filter items"
2058 .It Li "O" Ta "Change sort field"
2059 .It Li "r" Ta "Reverse sort order"
2060 .It Li "v" Ta "Toggle preview"
2061 .It Li "q" Ta "Exit mode"
2064 After a client is chosen,
2066 is replaced by the client name in
2068 and the result executed as a command.
2071 is not given, "detach-client -t '%%'" is used.
2074 specifies the initial sort field: one of
2081 reverses the sort order.
2083 specifies an initial filter: the filter is a format - if it evaluates to zero,
2084 the item in the list is not shown, otherwise it is shown.
2085 If a filter would lead to an empty list, it is ignored.
2087 specifies the format for each item in the list and
2089 a format for each shortcut key; both are evaluated once for each line.
2091 starts without the preview.
2092 This command works only if at least one client is attached.
2098 .Op Fl K Ar key-format
2099 .Op Fl O Ar sort-order
2100 .Op Fl t Ar target-pane
2103 Put a pane into tree mode, where a session, window or pane may be chosen
2104 interactively from a tree.
2105 Each session, window or pane is shown on one line.
2106 A shortcut key is shown on the left in brackets allowing for immediate choice,
2107 or the tree may be navigated and an item chosen or otherwise manipulated using
2110 starts with sessions collapsed and
2112 with windows collapsed.
2115 The following keys may be used in tree mode:
2116 .Bl -column "Key" "Function" -offset indent
2117 .It Sy "Key" Ta Sy "Function"
2118 .It Li "Enter" Ta "Choose selected item"
2119 .It Li "Up" Ta "Select previous item"
2120 .It Li "Down" Ta "Select next item"
2121 .It Li "+" Ta "Expand selected item"
2122 .It Li "-" Ta "Collapse selected item"
2123 .It Li "M-+" Ta "Expand all items"
2124 .It Li "M--" Ta "Collapse all items"
2125 .It Li "x" Ta "Kill selected item"
2126 .It Li "X" Ta "Kill tagged items"
2127 .It Li "<" Ta "Scroll list of previews left"
2128 .It Li ">" Ta "Scroll list of previews right"
2129 .It Li "C-s" Ta "Search by name"
2130 .It Li "m" Ta "Set the marked pane"
2131 .It Li "M" Ta "Clear the marked pane"
2132 .It Li "n" Ta "Repeat last search"
2133 .It Li "t" Ta "Toggle if item is tagged"
2134 .It Li "T" Ta "Tag no items"
2135 .It Li "C-t" Ta "Tag all items"
2136 .It Li "\&:" Ta "Run a command for each tagged item"
2137 .It Li "f" Ta "Enter a format to filter items"
2138 .It Li "H" Ta "Jump to the starting pane"
2139 .It Li "O" Ta "Change sort field"
2140 .It Li "r" Ta "Reverse sort order"
2141 .It Li "v" Ta "Toggle preview"
2142 .It Li "q" Ta "Exit mode"
2145 After a session, window or pane is chosen, the first instance of
2147 and all instances of
2149 are replaced by the target in
2151 and the result executed as a command.
2154 is not given, "switch-client -t '%%'" is used.
2157 specifies the initial sort field: one of
2163 reverses the sort order.
2165 specifies an initial filter: the filter is a format - if it evaluates to zero,
2166 the item in the list is not shown, otherwise it is shown.
2167 If a filter would lead to an empty list, it is ignored.
2169 specifies the format for each item in the tree and
2171 a format for each shortcut key; both are evaluated once for each line.
2173 starts without the preview.
2175 includes all sessions in any session groups in the tree rather than only the
2177 This command works only if at least one client is attached.
2183 .Op Fl t Ar target-pane
2186 Put a pane into customize mode, where options and key bindings may be browsed
2187 and modified from a list.
2188 Option values in the list are shown for the active pane in the current window.
2191 The following keys may be used in customize mode:
2192 .Bl -column "Key" "Function" -offset indent
2193 .It Sy "Key" Ta Sy "Function"
2194 .It Li "Enter" Ta "Set pane, window, session or global option value"
2195 .It Li "Up" Ta "Select previous item"
2196 .It Li "Down" Ta "Select next item"
2197 .It Li "+" Ta "Expand selected item"
2198 .It Li "-" Ta "Collapse selected item"
2199 .It Li "M-+" Ta "Expand all items"
2200 .It Li "M--" Ta "Collapse all items"
2201 .It Li "s" Ta "Set option value or key attribute"
2202 .It Li "S" Ta "Set global option value"
2203 .It Li "w" Ta "Set window option value, if option is for pane and window"
2204 .It Li "d" Ta "Set an option or key to the default"
2205 .It Li "D" Ta "Set tagged options and tagged keys to the default"
2206 .It Li "u" Ta "Unset an option (set to default value if global) or unbind a key"
2207 .It Li "U" Ta "Unset tagged options and unbind tagged keys"
2208 .It Li "C-s" Ta "Search by name"
2209 .It Li "n" Ta "Repeat last search"
2210 .It Li "t" Ta "Toggle if item is tagged"
2211 .It Li "T" Ta "Tag no items"
2212 .It Li "C-t" Ta "Tag all items"
2213 .It Li "f" Ta "Enter a format to filter items"
2214 .It Li "v" Ta "Toggle option information"
2215 .It Li "q" Ta "Exit mode"
2219 specifies an initial filter: the filter is a format - if it evaluates to zero,
2220 the item in the list is not shown, otherwise it is shown.
2221 If a filter would lead to an empty list, it is ignored.
2223 specifies the format for each item in the tree.
2225 starts without the option information.
2226 This command works only if at least one client is attached.
2231 .Op Fl d Ar duration
2232 .Op Fl t Ar target-client
2235 .D1 Pq alias: Ic displayp
2236 Display a visible indicator of each pane shown by
2239 .Ic display-panes-colour
2241 .Ic display-panes-active-colour
2243 The indicator is closed when a key is pressed (unless
2247 milliseconds have passed.
2251 .Ic display-panes-time
2253 A duration of zero means the indicator stays until a key is pressed.
2254 While the indicator is on screen, a pane may be chosen with the
2258 keys, which will cause
2260 to be executed as a command with
2262 substituted by the pane ID.
2265 is "select-pane -t '%%'".
2268 other commands are not blocked from running until the indicator is closed.
2270 .It Xo Ic find-window
2272 .Op Fl t Ar target-pane
2275 .D1 Pq alias: Ic findw
2282 in window names, titles, and visible content (but not history).
2283 The flags control matching behavior:
2285 matches only visible window contents,
2287 matches only the window name and
2289 matches only the window title.
2291 makes the search ignore case.
2297 This command works only if at least one client is attached.
2302 .Op Fl s Ar src-pane
2303 .Op Fl t Ar dst-pane
2305 .D1 Pq alias: Ic joinp
2308 but instead of splitting
2310 and creating a new pane, split it and move
2313 This can be used to reverse
2319 to be joined to left of or above
2324 is omitted and a marked pane is present (see
2327 the marked pane is used rather than the current pane.
2331 .Op Fl t Ar target-pane
2333 .D1 Pq alias: Ic killp
2334 Destroy the given pane.
2335 If no panes remain in the containing window, it is also destroyed.
2338 option kills all but the pane given with
2341 .It Xo Ic kill-window
2343 .Op Fl t Ar target-window
2345 .D1 Pq alias: Ic killw
2346 Kill the current window or the window at
2348 removing it from any sessions to which it is linked.
2351 option kills all but the window given with
2356 .Op Fl t Ar target-window
2358 .D1 Pq alias: Ic lastp
2359 Select the last (previously selected) pane.
2361 keeps the window zoomed if it was zoomed.
2365 disables input to the pane.
2367 .It Ic last-window Op Fl t Ar target-session
2368 .D1 Pq alias: Ic last
2369 Select the last (previously selected) window.
2372 is specified, select the last window of the current session.
2374 .It Xo Ic link-window
2376 .Op Fl s Ar src-window
2377 .Op Fl t Ar dst-window
2379 .D1 Pq alias: Ic linkw
2386 is specified and no such window exists, the
2393 the window is moved to the next index after or before
2395 (existing windows are moved if necessary).
2400 exists, it is killed, otherwise an error is generated.
2403 is given, the newly linked window is not selected.
2405 .It Xo Ic list-panes
2411 .D1 Pq alias: Ic lsp
2416 is ignored and all panes on the server are listed.
2421 is a session (or the current session).
2422 If neither is given,
2424 is a window (or the current window).
2426 specifies the format of each line and
2429 Only panes for which the filter is true are shown.
2434 .It Xo Ic list-windows
2438 .Op Fl t Ar target-session
2440 .D1 Pq alias: Ic lsw
2443 is given, list all windows on the server.
2444 Otherwise, list windows in the current session or in
2445 .Ar target-session .
2447 specifies the format of each line and
2450 Only windows for which the filter is true are shown.
2458 .Op Fl s Ar src-pane
2459 .Op Fl t Ar dst-pane
2461 .D1 Pq alias: Ic movep
2465 .It Xo Ic move-window
2467 .Op Fl s Ar src-window
2468 .Op Fl t Ar dst-window
2470 .D1 Pq alias: Ic movew
2473 except the window at
2479 all windows in the session are renumbered in sequential order, respecting
2484 .It Xo Ic new-window
2486 .Op Fl c Ar start-directory
2487 .Op Fl e Ar environment
2489 .Op Fl n Ar window-name
2490 .Op Fl t Ar target-window
2491 .Op Ar shell-command
2493 .D1 Pq alias: Ic neww
2494 Create a new window.
2499 the new window is inserted at the next index after or before the specified
2501 moving windows up if necessary;
2504 is the new window location.
2508 is given, the session does not make the new window the current window.
2510 represents the window to be created; if the target already exists an error is
2513 flag is used, in which case it is destroyed.
2516 is given and a window named
2518 already exists, it is selected (unless
2520 is also given in which case the command does nothing).
2523 is the command to execute.
2526 is not specified, the value of the
2530 specifies the working directory in which the new window is created.
2532 When the shell command completes, the window closes.
2535 option to change this behaviour.
2540 and sets an environment variable for the newly created window; it may be
2541 specified multiple times.
2545 environment variable must be set to
2549 for all programs running
2552 New windows will automatically have
2554 added to their environment, but care must be taken not to reset this in shell
2555 start-up files or by the
2561 option prints information about the new window after it has been created.
2562 By default, it uses the format
2563 .Ql #{session_name}:#{window_index}
2564 but a different format may be specified with
2567 .It Ic next-layout Op Fl t Ar target-window
2568 .D1 Pq alias: Ic nextl
2569 Move a window to the next layout and rearrange the panes to fit.
2571 .It Xo Ic next-window
2573 .Op Fl t Ar target-session
2575 .D1 Pq alias: Ic next
2576 Move to the next window in the session.
2579 is used, move to the next window with an alert.
2583 .Op Fl t Ar target-pane
2584 .Op Ar shell-command
2586 .D1 Pq alias: Ic pipep
2587 Pipe output sent by the program in
2589 to a shell command or vice versa.
2590 A pane may only be connected to one command at a time, any existing pipe is
2596 string may contain the special character sequences supported by the
2601 is given, the current pipe (if any) is closed.
2606 specify which of the
2608 output streams are connected to the pane:
2611 stdout is connected (so anything
2613 prints is written to the pane as if it were typed);
2616 stdin is connected (so any output in the pane is piped to
2617 .Ar shell-command ) .
2618 Both may be used together and if neither are specified,
2624 option only opens a new pipe if no previous pipe exists, allowing a pipe to
2625 be toggled with a single key, for example:
2626 .Bd -literal -offset indent
2627 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
2630 .It Xo Ic previous-layout
2631 .Op Fl t Ar target-window
2633 .D1 Pq alias: Ic prevl
2634 Move to the previous layout in the session.
2636 .It Xo Ic previous-window
2638 .Op Fl t Ar target-session
2640 .D1 Pq alias: Ic prev
2641 Move to the previous window in the session.
2644 move to the previous window with an alert.
2646 .It Xo Ic rename-window
2647 .Op Fl t Ar target-window
2650 .D1 Pq alias: Ic renamew
2651 Rename the current window, or the window at
2656 .It Xo Ic resize-pane
2658 .Op Fl t Ar target-pane
2663 .D1 Pq alias: Ic resizep
2664 Resize a pane, up, down, left or right by
2680 is given in lines or columns (the default is 1);
2684 may be a given as a number of lines or columns or followed by
2686 for a percentage of the window size (for example
2690 the active pane is toggled between zoomed (occupying the whole of the window)
2691 and unzoomed (its normal position in the layout).
2694 begins mouse resizing (only valid if bound to a mouse key binding, see
2695 .Sx MOUSE SUPPORT ) .
2698 trims all lines below the current cursor position and moves lines out of the
2699 history to replace them.
2701 .It Xo Ic resize-window
2703 .Op Fl t Ar target-window
2708 .D1 Pq alias: Ic resizew
2709 Resize a window, up, down, left or right by
2725 is given in lines or cells (the default is 1).
2727 sets the size of the largest session containing the window;
2729 the size of the smallest.
2730 This command will automatically set
2732 to manual in the window options.
2734 .It Xo Ic respawn-pane
2736 .Op Fl c Ar start-directory
2737 .Op Fl e Ar environment
2738 .Op Fl t Ar target-pane
2739 .Op Ar shell-command
2741 .D1 Pq alias: Ic respawnp
2742 Reactivate a pane in which the command has exited (see the
2747 is not given, the command used when the pane was created or last respawned is
2749 The pane must be already inactive, unless
2751 is given, in which case any existing command is killed.
2753 specifies a new working directory for the pane.
2756 option has the same meaning as for the
2760 .It Xo Ic respawn-window
2762 .Op Fl c Ar start-directory
2763 .Op Fl e Ar environment
2764 .Op Fl t Ar target-window
2765 .Op Ar shell-command
2767 .D1 Pq alias: Ic respawnw
2768 Reactivate a window in which the command has exited (see the
2773 is not given, the command used when the window was created or last respawned is
2775 The window must be already inactive, unless
2777 is given, in which case any existing command is killed.
2779 specifies a new working directory for the window.
2782 option has the same meaning as for the
2786 .It Xo Ic rotate-window
2788 .Op Fl t Ar target-window
2790 .D1 Pq alias: Ic rotatew
2791 Rotate the positions of the panes within a window, either upward (numerically
2794 or downward (numerically higher).
2796 keeps the window zoomed if it was zoomed.
2798 .It Xo Ic select-layout
2800 .Op Fl t Ar target-pane
2803 .D1 Pq alias: Ic selectl
2804 Choose a specific layout for a window.
2807 is not given, the last preset layout used (if any) is reapplied.
2811 are equivalent to the
2817 applies the last set layout if possible (undoes the most recent layout change).
2819 spreads the current pane and any panes next to it out evenly.
2821 .It Xo Ic select-pane
2824 .Op Fl t Ar target-pane
2826 .D1 Pq alias: Ic selectp
2829 the active pane in its window.
2836 is used, respectively the pane below, to the left, to the right, or above the
2837 target pane is used.
2839 keeps the window zoomed if it was zoomed.
2841 is the same as using the
2847 disables input to the pane.
2849 sets the pane title.
2854 are used to set and clear the
2856 There is one marked pane at a time, setting a new marked pane clears the last.
2857 The marked pane is the default target for
2866 .It Xo Ic select-window
2868 .Op Fl t Ar target-window
2870 .D1 Pq alias: Ic selectw
2871 Select the window at
2877 are equivalent to the
2885 is given and the selected window is already the current window,
2886 the command behaves like
2889 .It Xo Ic split-window
2891 .Op Fl c Ar start-directory
2892 .Op Fl e Ar environment
2894 .Op Fl t Ar target-pane
2895 .Op Ar shell-command
2898 .D1 Pq alias: Ic splitw
2899 Create a new pane by splitting
2902 does a horizontal split and
2904 a vertical split; if neither is specified,
2909 option specifies the size of the new pane in lines (for vertical split) or in
2910 columns (for horizontal split);
2914 to specify a percentage of the available space.
2917 option causes the new pane to be created to the left of or above
2921 option creates a new pane spanning the full window height (with
2923 or full window width (with
2925 instead of splitting the active pane.
2927 zooms if the window is not zoomed, or keeps it zoomed if already zoomed.
2931 ('') will create a pane with no command running in it.
2932 Output can be sent to such a pane with the
2939 is not specified or empty)
2940 will create an empty pane and forward any output from stdin to it.
2942 .Bd -literal -offset indent
2943 $ make 2>&1|tmux splitw -dI &
2946 All other options have the same meaning as for the
2952 .Op Fl s Ar src-pane
2953 .Op Fl t Ar dst-pane
2955 .D1 Pq alias: Ic swapp
2959 is used and no source pane is specified with
2962 is swapped with the previous pane (before it numerically);
2964 swaps with the next pane (after it numerically).
2968 not to change the active pane and
2970 keeps the window zoomed if it was zoomed.
2974 is omitted and a marked pane is present (see
2977 the marked pane is used rather than the current pane.
2979 .It Xo Ic swap-window
2981 .Op Fl s Ar src-window
2982 .Op Fl t Ar dst-window
2984 .D1 Pq alias: Ic swapw
2987 except the source and destination windows are swapped.
2988 It is an error if no window exists at
2992 is given, the new window does not become the current window.
2996 is omitted and a marked pane is present (see
2999 the window containing the marked pane is used rather than the current window.
3001 .It Xo Ic unlink-window
3003 .Op Fl t Ar target-window
3005 .D1 Pq alias: Ic unlinkw
3010 is given, a window may be unlinked only if it is linked to multiple sessions -
3011 windows may not be linked to no sessions;
3014 is specified and the window is linked to only one session, it is unlinked and
3019 allows a command to be bound to most keys, with or without a prefix key.
3020 When specifying keys, most represent themselves (for example
3024 Ctrl keys may be prefixed with
3032 In addition, the following special key names are accepted:
3050 .Em NPage/PageDown/PgDn ,
3051 .Em PPage/PageUp/PgUp ,
3055 Note that to bind the
3059 keys, quotation marks are necessary, for example:
3060 .Bd -literal -offset indent
3061 bind-key '"' split-window
3062 bind-key "'" new-window
3065 A command bound to the
3067 key will execute for all keys which do not have a more specific binding.
3069 Commands related to key bindings are as follows:
3075 .Op Fl T Ar key-table
3076 .Ar key command Op Ar arguments
3078 .D1 Pq alias: Ic bind
3083 Keys are bound in a key table.
3084 By default (without -T), the key is bound in
3088 This table is used for keys pressed after the prefix key (for example,
3097 creates a new window).
3100 table is used for keys pressed without the prefix key: binding
3106 table (not recommended) means a plain
3108 will create a new window.
3113 Keys may also be bound in custom key tables and the
3116 command used to switch to them from a key binding.
3119 flag indicates this key may repeat, see the
3123 attaches a note to the key (shown with
3127 To view the default bindings and possible commands, see the
3133 .Op Fl P Ar prefix-string Fl T Ar key-table
3136 .D1 Pq alias: Ic lsk
3138 There are two forms: the default lists keys as
3142 lists only keys with attached notes and shows only the key and note for each
3145 With the default form, all key tables are listed by default.
3152 form, only keys in the
3156 key tables are listed by default;
3158 also lists only keys in
3161 specifies a prefix to print before each key and
3163 lists only the first matching key.
3165 lists the command for keys that do not have a note rather than skipping them.
3169 .Op Fl N Ar repeat-count
3170 .Op Fl t Ar target-pane
3173 .D1 Pq alias: Ic send
3174 Send a key or keys to a window.
3177 is the name of the key (such as
3181 to send; if the string is not recognised as a key, it is sent as a series of
3183 All arguments are sent sequentially from first to last.
3184 If no keys are given and the command is bound to a key, then that key is used.
3188 flag disables key name lookup and processes the keys as literal UTF-8
3192 flag expects each key to be a hexadecimal number for an ASCII character.
3196 flag causes the terminal state to be reset.
3199 passes through a mouse event (only valid if bound to a mouse key binding, see
3200 .Sx MOUSE SUPPORT ) .
3203 is used to send a command into copy mode - see
3205 .Sx WINDOWS AND PANES
3208 specifies a repeat count and
3210 expands formats in arguments where appropriate.
3211 .It Xo Ic send-prefix
3213 .Op Fl t Ar target-pane
3215 Send the prefix key, or with
3217 the secondary prefix key, to a window as if it was pressed.
3219 .It Xo Ic unbind-key
3221 .Op Fl T Ar key-table
3224 .D1 Pq alias: Ic unbind
3225 Unbind the command bound to
3234 is present, all key bindings are removed.
3237 option prevents errors being returned.
3240 The appearance and behaviour of
3242 may be modified by changing the value of various options.
3243 There are four types of option:
3244 .Em server options ,
3245 .Em session options ,
3246 .Em window options ,
3252 server has a set of global server options which do not apply to any particular
3253 window or session or pane.
3254 These are altered with the
3257 command, or displayed with the
3262 In addition, each individual session may have a set of session options, and
3263 there is a separate set of global session options.
3264 Sessions which do not have a particular option configured inherit the value
3265 from the global session options.
3266 Session options are set or unset with the
3268 command and may be listed with the
3271 The available server and session options are listed under the
3275 Similarly, a set of window options is attached to each window and a set of pane
3276 options to each pane.
3277 Pane options inherit from window options.
3278 This means any pane option may be set as a window option to apply the option to
3279 all panes in the window without the option set, for example these commands will
3280 set the background colour to red for all panes except pane 0:
3281 .Bd -literal -offset indent
3282 set -w window-style bg=red
3283 set -pt:.0 window-style bg=blue
3286 There is also a set of global window options from which any unset window or
3287 pane options are inherited.
3288 Window and pane options are altered with
3293 commands and displayed with
3300 also supports user options which are prefixed with a
3302 User options may have any name, so long as they are prefixed with
3304 and be set to any string.
3306 .Bd -literal -offset indent
3307 $ tmux set -wq @foo "abc123"
3308 $ tmux show -wv @foo
3312 Commands which set options are as follows:
3315 .It Xo Ic set-option
3317 .Op Fl t Ar target-pane
3320 .D1 Pq alias: Ic set
3321 Set a pane option with
3323 a window option with
3325 a server option with
3327 otherwise a session option.
3328 If the option is not a user option,
3332 may be unnecessary -
3334 will infer the type from the option name, assuming
3339 is given, the global session or window option is set.
3342 expands formats in the option value.
3345 flag unsets an option, so a session inherits the option from the global
3348 restores a global option to the default).
3350 unsets an option (like
3352 but if the option is a pane option also unsets the option on any panes in the
3355 depends on the option and may be a number, a string, or a flag (on, off, or
3360 flag prevents setting an option that is already set and the
3362 flag suppresses errors about unknown or ambiguous options.
3366 and if the option expects a string or a style,
3368 is appended to the existing setting.
3370 .Bd -literal -offset indent
3371 set -g status-left "foo"
3372 set -ag status-left "bar"
3378 .Bd -literal -offset indent
3379 set -g status-style "bg=red"
3380 set -ag status-style "fg=blue"
3383 Will result in a red background
3388 the result would be the default background and a blue foreground.
3390 .It Xo Ic show-options
3392 .Op Fl t Ar target-pane
3395 .D1 Pq alias: Ic show
3396 Show the pane options (or a single option if
3400 the window options with
3402 the server options with
3404 otherwise the session options.
3405 If the option is not a user option,
3409 may be unnecessary -
3411 will infer the type from the option name, assuming
3414 Global session or window options are listed if
3418 shows only the option value, not the name.
3421 is set, no error will be returned if
3425 includes hooks (omitted by default).
3427 includes options inherited from a parent set of options, such options are
3428 marked with an asterisk.
3431 Available server options are:
3433 .It Ic backspace Ar key
3437 .It Ic buffer-limit Ar number
3438 Set the number of buffers; as new buffers are added to the top of the stack,
3439 old ones are removed from the bottom if necessary to maintain this maximum
3441 .It Xo Ic command-alias[]
3444 This is an array of custom aliases for commands.
3445 If an unknown command matches
3451 .Dl set -s command-alias[100] zoom='resize-pane -Z'
3459 .Dl resize-pane -Z -t:.1
3461 Note that aliases are expanded when a command is parsed rather than when it is
3462 executed, so binding an alias with
3464 will bind the expanded form.
3465 .It Ic default-terminal Ar terminal
3466 Set the default terminal for new windows created in this session - the
3467 default value of the
3469 environment variable.
3472 to work correctly, this
3477 or a derivative of them.
3478 .It Ic copy-command Ar shell-command
3479 Give the command to pipe to if the
3481 copy mode command is used without arguments.
3482 .It Ic escape-time Ar time
3483 Set the time in milliseconds for which
3485 waits after an escape is input to determine if it is part of a function or meta
3487 The default is 500 milliseconds.
3488 .It Ic editor Ar shell-command
3489 Set the command used when
3492 .It Xo Ic exit-empty
3495 If enabled (the default), the server will exit when there are no active
3497 .It Xo Ic exit-unattached
3500 If enabled, the server will exit when there are no attached clients.
3501 .It Xo Ic extended-keys
3502 .Op Ic on | off | always
3508 the escape sequence to enable extended keys is sent to the terminal, if
3510 knows that it is supported.
3512 always recognises extended keys itself.
3516 will only forward extended keys to applications when they request them; if
3519 will always forward the keys.
3520 .It Xo Ic focus-events
3523 When enabled, focus events are requested from the terminal if supported and
3524 passed through to applications running in
3526 Attached clients should be detached and attached again after changing this
3528 .It Ic history-file Ar path
3529 If not empty, a file to which
3531 will write command prompt history on exit and load it from on start.
3532 .It Ic message-limit Ar number
3533 Set the number of error or information messages to save in the message log for
3535 .It Ic prompt-history-limit Ar number
3536 Set the number of history items to save in the history file for each type of
3538 .It Xo Ic set-clipboard
3539 .Op Ic on | external | off
3541 Attempt to set the terminal clipboard content using the
3543 escape sequence, if there is an
3547 description (see the
3548 .Sx TERMINFO EXTENSIONS
3554 will both accept the escape sequence to create a buffer and attempt to set
3555 the terminal clipboard.
3559 will attempt to set the terminal clipboard but ignore attempts
3560 by applications to set
3566 will neither accept the clipboard escape sequence nor attempt to set the
3569 Note that this feature needs to be enabled in
3571 by setting the resource:
3572 .Bd -literal -offset indent
3573 disallowedWindowOps: 20,21,SetXprop
3576 Or changing this property from the
3578 interactive menu when required.
3579 .It Ic terminal-features[] Ar string
3580 Set terminal features for terminal types read from
3583 has a set of named terminal features.
3584 Each will apply appropriate changes to the
3589 can detect features for a few common terminals; this option can be used to
3590 easily tell tmux about features supported by terminals it cannot detect.
3592 .Ic terminal-overrides
3593 option allows individual
3595 capabilities to be set instead,
3596 .Ic terminal-features
3597 is intended for classes of functionality supported in a standard way but not
3600 Care must be taken to configure this only with features the terminal actually
3603 This is an array option where each entry is a colon-separated string made up
3604 of a terminal type pattern (matched using
3606 followed by a list of terminal features.
3607 The available features are:
3610 Supports 256 colours with the SGR escape sequences.
3612 Allows setting the system clipboard.
3614 Allows setting the cursor colour.
3616 Allows setting the cursor style.
3618 Supports extended keys.
3620 Supports focus reporting.
3622 Supports DECSLRM margins.
3628 Supports the OSC 7 working directory extension.
3630 Supports the overline SGR attribute.
3632 Supports the DECFRA rectangle fill escape sequence.
3634 Supports RGB colour with the SGR escape sequences.
3636 Supports the strikethrough SGR escape sequence.
3638 Supports synchronized updates.
3644 Allows underscore style and colour to be set.
3646 .It Ic terminal-overrides[] Ar string
3647 Allow terminal descriptions read using
3650 Each entry is a colon-separated string made up of a terminal type pattern
3657 For example, to set the
3662 for all terminal types matching
3665 .Dl "rxvt*:clear=\ee[H\ee[2J"
3667 The terminal entry value is passed through
3669 before interpretation.
3670 .It Ic user-keys[] Ar key
3671 Set list of user-defined key escape sequences.
3672 Each item is associated with a key named
3678 .Bd -literal -offset indent
3679 set -s user-keys[0] "\ee[5;30012~"
3680 bind User0 resize-pane -L 3
3684 Available session options are:
3686 .It Xo Ic activity-action
3687 .Op Ic any | none | current | other
3689 Set action on window activity when
3690 .Ic monitor-activity
3693 means activity in any window linked to a session causes a bell or message
3695 .Ic visual-activity )
3696 in the current window of that session,
3698 means all activity is ignored (equivalent to
3699 .Ic monitor-activity
3702 means only activity in windows other than the current window are ignored and
3704 means activity in the current window is ignored but not those in other windows.
3705 .It Ic assume-paste-time Ar milliseconds
3706 If keys are entered faster than one in
3708 they are assumed to have been pasted rather than typed and
3710 key bindings are not processed.
3711 The default is one millisecond and zero disables.
3712 .It Ic base-index Ar index
3713 Set the base index from which an unused index should be searched when a new
3715 The default is zero.
3716 .It Xo Ic bell-action
3717 .Op Ic any | none | current | other
3719 Set action on a bell in a window when
3722 The values are the same as those for
3723 .Ic activity-action .
3724 .It Ic default-command Ar shell-command
3725 Set the command used for new windows (if not specified when the window is
3731 The default is an empty string, which instructs
3733 to create a login shell using the value of the
3736 .It Ic default-shell Ar path
3737 Specify the default shell.
3738 This is used as the login shell for new windows when the
3740 option is set to empty, and must be the full path of the executable.
3743 tries to set a default value from the first suitable of the
3745 environment variable, the shell returned by
3749 This option should be configured when
3751 is used as a login shell.
3752 .It Ic default-size Ar XxY
3753 Set the default size of new windows when the
3755 option is set to manual or when a session is created with
3758 The value is the width and height separated by an
3761 The default is 80x24.
3762 .It Xo Ic destroy-unattached
3765 If enabled and the session is no longer attached to any clients, it is
3767 .It Xo Ic detach-on-destroy
3768 .Op Ic off | on | no-detached
3770 If on (the default), the client is detached when the session it is attached to
3772 If off, the client is switched to the most recently active of the remaining
3776 the client is detached only if there are no detached sessions; if detached
3777 sessions exist, the client is switched to the most recently active.
3778 .It Ic display-panes-active-colour Ar colour
3779 Set the colour used by the
3781 command to show the indicator for the active pane.
3782 .It Ic display-panes-colour Ar colour
3783 Set the colour used by the
3785 command to show the indicators for inactive panes.
3786 .It Ic display-panes-time Ar time
3787 Set the time in milliseconds for which the indicators shown by the
3790 .It Ic display-time Ar time
3791 Set the amount of time for which status line messages and other on-screen
3792 indicators are displayed.
3793 If set to 0, messages and indicators are displayed until a key is pressed.
3796 .It Ic history-limit Ar lines
3797 Set the maximum number of lines held in window history.
3798 This setting applies only to new windows - existing window histories are not
3799 resized and retain the limit at the point they were created.
3800 .It Ic key-table Ar key-table
3801 Set the default key table to
3805 .It Ic lock-after-time Ar number
3806 Lock the session (like the
3810 seconds of inactivity.
3811 The default is not to lock (set to 0).
3812 .It Ic lock-command Ar shell-command
3813 Command to run when locking each client.
3814 The default is to run
3818 .It Ic message-command-style Ar style
3819 Set status line message command style.
3820 This is used for the command prompt with
3822 keys when in command mode.
3828 .It Ic message-style Ar style
3829 Set status line message style.
3830 This is used for messages and for the command prompt.
3841 captures the mouse and allows mouse events to be bound as key bindings.
3844 section for details.
3845 .It Ic prefix Ar key
3846 Set the key accepted as a prefix key.
3847 In addition to the standard keys described under
3850 can be set to the special key
3853 .It Ic prefix2 Ar key
3854 Set a secondary key accepted as a prefix key.
3860 .It Xo Ic renumber-windows
3863 If on, when a window is closed in a session, automatically renumber the other
3864 windows in numerical order.
3867 option if it has been set.
3868 If off, do not renumber the windows.
3869 .It Ic repeat-time Ar time
3870 Allow multiple commands to be entered without pressing the prefix-key again
3873 milliseconds (the default is 500).
3874 Whether a key repeats may be set when it is bound using the
3878 Repeat is enabled for the default keys bound to the
3881 .It Xo Ic set-titles
3884 Attempt to set the client terminal title using the
3889 entries if they exist.
3891 automatically sets these to the \ee]0;...\e007 sequence if
3892 the terminal appears to be
3894 This option is off by default.
3895 .It Ic set-titles-string Ar string
3896 String used to set the client terminal title if
3899 Formats are expanded, see the
3902 .It Xo Ic silence-action
3903 .Op Ic any | none | current | other
3905 Set action on window silence when
3908 The values are the same as those for
3909 .Ic activity-action .
3911 .Op Ic off | on | 2 | 3 | 4 | 5
3913 Show or hide the status line or specify its size.
3916 gives a status line one row in height;
3923 .It Ic status-format[] Ar format
3924 Specify the format to be used for each line of the status line.
3925 The default builds the top status line from the various individual status
3927 .It Ic status-interval Ar interval
3928 Update the status line every
3931 By default, updates will occur every 15 seconds.
3932 A setting of zero disables redrawing at interval.
3933 .It Xo Ic status-justify
3934 .Op Ic left | centre | right | absolute-centre
3936 Set the position of the window list in the status line: left, centre or right.
3937 centre puts the window list in the relative centre of the available free space;
3938 absolute-centre uses the centre of the entire horizontal space.
3939 .It Xo Ic status-keys
3942 Use vi or emacs-style
3943 key bindings in the status line, for example at the command prompt.
3944 The default is emacs, unless the
3948 environment variables are set and contain the string
3950 .It Ic status-left Ar string
3953 (by default the session name) to the left of the status line.
3955 will be passed through
3963 For details on how the names and titles can be set see the
3964 .Sx "NAMES AND TITLES"
3968 .Bd -literal -offset indent
3969 #(sysctl vm.loadavg)
3970 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
3975 .It Ic status-left-length Ar length
3978 of the left component of the status line.
3980 .It Ic status-left-style Ar style
3981 Set the style of the left part of the status line.
3987 .It Xo Ic status-position
3990 Set the position of the status line.
3991 .It Ic status-right Ar string
3994 to the right of the status line.
3995 By default, the current pane title in double quotes, the date and the time
4002 and character pairs are replaced.
4003 .It Ic status-right-length Ar length
4006 of the right component of the status line.
4008 .It Ic status-right-style Ar style
4009 Set the style of the right part of the status line.
4015 .It Ic status-style Ar style
4016 Set status line style.
4022 .It Ic update-environment[] Ar variable
4023 Set list of environment variables to be copied into the session environment
4024 when a new session is created or an existing session is attached.
4025 Any variables that do not exist in the source environment are set to be
4026 removed from the session environment (as if
4031 .It Xo Ic visual-activity
4032 .Op Ic on | off | both
4034 If on, display a message instead of sending a bell when activity occurs in a
4035 window for which the
4036 .Ic monitor-activity
4037 window option is enabled.
4038 If set to both, a bell and a message are produced.
4039 .It Xo Ic visual-bell
4040 .Op Ic on | off | both
4042 If on, a message is shown on a bell in a window for which the
4044 window option is enabled instead of it being passed through to the
4045 terminal (which normally makes a sound).
4046 If set to both, a bell and a message are produced.
4050 .It Xo Ic visual-silence
4051 .Op Ic on | off | both
4055 is enabled, prints a message after the interval has expired on a given window
4056 instead of sending a bell.
4057 If set to both, a bell and a message are produced.
4058 .It Ic word-separators Ar string
4059 Sets the session's conception of what characters are considered word
4060 separators, for the purposes of the next and previous word commands in
4064 Available window options are:
4066 .Bl -tag -width Ds -compact
4067 .It Xo Ic aggressive-resize
4070 Aggressively resize the chosen window.
4073 will resize the window to the size of the smallest or largest session
4076 option) for which it is the current window, rather than the session to
4077 which it is attached.
4078 The window may resize when the current window is changed on another
4079 session; this option is good for full-screen programs which support
4081 and poor for interactive programs such as shells.
4083 .It Xo Ic automatic-rename
4086 Control automatic window renaming.
4087 When this setting is enabled,
4089 will rename the window automatically using the format specified by
4090 .Ic automatic-rename-format .
4091 This flag is automatically disabled for an individual window when a name
4092 is specified at creation with
4098 or with a terminal escape sequence.
4099 It may be switched off globally with:
4100 .Bd -literal -offset indent
4101 set-option -wg automatic-rename off
4104 .It Ic automatic-rename-format Ar format
4108 .Ic automatic-rename
4111 .It Ic clock-mode-colour Ar colour
4114 .It Xo Ic clock-mode-style
4117 Set clock hour format.
4119 .It Ic fill-character Ar character
4120 Set the character used to fill areas of the terminal unused by a window.
4122 .It Ic main-pane-height Ar height
4123 .It Ic main-pane-width Ar width
4124 Set the width or height of the main (left or top) pane in the
4131 this is a percentage of the window size.
4133 .It Ic copy-mode-match-style Ar style
4134 Set the style of search matches in copy mode.
4141 .It Ic copy-mode-mark-style Ar style
4142 Set the style of the line containing the mark in copy mode.
4149 .It Ic copy-mode-current-match-style Ar style
4150 Set the style of the current search match in copy mode.
4160 Use vi or emacs-style key bindings in copy mode.
4161 The default is emacs, unless
4168 .It Ic mode-style Ar style
4169 Set window modes style.
4176 .It Xo Ic monitor-activity
4179 Monitor for activity in the window.
4180 Windows with activity are highlighted in the status line.
4182 .It Xo Ic monitor-bell
4185 Monitor for a bell in the window.
4186 Windows with a bell are highlighted in the status line.
4188 .It Xo Ic monitor-silence
4191 Monitor for silence (no activity) in the window within
4194 Windows that have been silent for the interval are highlighted in the
4196 An interval of zero disables the monitoring.
4198 .It Ic other-pane-height Ar height
4199 Set the height of the other panes (not the main pane) in the
4202 If this option is set to 0 (the default), it will have no effect.
4204 .Ic main-pane-height
4206 .Ic other-pane-height
4207 options are set, the main pane will grow taller to make the other panes the
4208 specified height, but will never shrink to do so.
4211 this is a percentage of the window size.
4213 .It Ic other-pane-width Ar width
4215 .Ic other-pane-height ,
4216 but set the width of other panes in the
4220 .It Ic pane-active-border-style Ar style
4221 Set the pane border style for the currently active pane.
4227 Attributes are ignored.
4229 .It Ic pane-base-index Ar index
4232 but set the starting index for pane numbers.
4234 .It Ic pane-border-format Ar format
4235 Set the text shown in pane border status lines.
4237 .It Xo Ic pane-border-indicators
4238 .Op Ic off | colour | arrows | both
4240 Indicate active pane by colouring only half of the border in windows with
4241 exactly two panes, by displaying arrow markers, by drawing both or neither.
4243 .It Ic pane-border-lines Ar type
4244 Set the type of characters used for drawing pane borders.
4249 single lines using ACS or UTF-8 characters
4251 double lines using UTF-8 characters
4253 heavy lines using UTF-8 characters
4255 simple ASCII characters
4263 will fall back to standard ACS line drawing when UTF-8 is not supported.
4265 .It Xo Ic pane-border-status
4266 .Op Ic off | top | bottom
4268 Turn pane border status lines off or set their position.
4270 .It Ic pane-border-style Ar style
4271 Set the pane border style for panes aside from the active pane.
4277 Attributes are ignored.
4279 .It Ic popup-style Ar style
4280 Set the popup style.
4286 Attributes are ignored.
4288 .It Ic popup-border-style Ar style
4289 Set the popup border style.
4295 Attributes are ignored.
4297 .It Ic popup-border-lines Ar type
4298 Set the type of characters used for drawing popup borders.
4303 single lines using ACS or UTF-8 characters (default)
4305 variation of single with rounded corners using UTF-8 characters
4307 double lines using UTF-8 characters
4309 heavy lines using UTF-8 characters
4311 simple ASCII characters
4313 simple ASCII space character
4321 will fall back to standard ACS line drawing when UTF-8 is not supported.
4323 .It Ic window-status-activity-style Ar style
4324 Set status line style for windows with an activity alert.
4331 .It Ic window-status-bell-style Ar style
4332 Set status line style for windows with a bell alert.
4339 .It Ic window-status-current-format Ar string
4341 .Ar window-status-format ,
4342 but is the format used when the window is the current window.
4344 .It Ic window-status-current-style Ar style
4345 Set status line style for the currently active window.
4352 .It Ic window-status-format Ar string
4353 Set the format in which the window is displayed in the status line window list.
4360 .It Ic window-status-last-style Ar style
4361 Set status line style for the last active window.
4368 .It Ic window-status-separator Ar string
4369 Sets the separator drawn between windows in the status line.
4370 The default is a single space character.
4372 .It Ic window-status-style Ar style
4373 Set status line style for a single window.
4380 .It Xo Ic window-size
4381 .Ar largest | Ar smallest | Ar manual | Ar latest
4385 determines the window size.
4388 the size of the largest attached session is used; if
4390 the size of the smallest.
4393 the size of a new window is set from the
4395 option and windows are resized automatically.
4399 uses the size of the client that had the most recent activity.
4403 .Ic aggressive-resize
4406 .It Xo Ic wrap-search
4409 If this option is set, searches will wrap around the end of the pane contents.
4413 Available pane options are:
4415 .Bl -tag -width Ds -compact
4416 .It Xo Ic allow-passthrough
4419 Allow programs in the pane to bypass
4421 using a terminal escape sequence (\eePtmux;...\ee\e\e).
4423 .It Xo Ic allow-rename
4426 Allow programs in the pane to change the window name using a terminal escape
4427 sequence (\eek...\ee\e\e).
4429 .It Xo Ic alternate-screen
4432 This option configures whether programs running inside the pane may use the
4433 terminal alternate screen feature, which allows the
4439 The alternate screen feature preserves the contents of the window when an
4440 interactive application starts and restores it on exit, so that any output
4441 visible before the application starts reappears unchanged after it exits.
4443 .It Ic cursor-colour Ar colour
4444 Set the colour of the cursor.
4446 .It Ic pane-colours[] Ar colour
4447 The default colour palette.
4448 Each entry in the array defines the colour
4450 uses when the colour with that index is requested.
4451 The index may be from zero to 255.
4453 .It Ic cursor-style Ar style
4454 Set the style of the cursor.
4455 Available styles are:
4457 .Ic blinking-block ,
4459 .Ic blinking-underline ,
4464 .It Xo Ic remain-on-exit
4465 .Op Ic on | off | failed
4467 A pane with this flag set is not destroyed when the program running in it
4471 then only when the program exit status is not zero.
4472 The pane may be reactivated with the
4476 .It Ic remain-on-exit-format Ar string
4477 Set the text shown at the bottom of exited panes when
4481 .It Xo Ic scroll-on-clear
4484 When the entire screen is cleared and this option is on, scroll the contents of
4485 the screen into history before clearing it.
4487 .It Xo Ic synchronize-panes
4490 Duplicate input to all other panes in the same window where this option is also
4491 on (only for panes that are not in any mode).
4493 .It Ic window-active-style Ar style
4494 Set the pane style when it is the active pane.
4501 .It Ic window-style Ar style
4511 allows commands to run on various triggers, called
4517 hook and there are a number of hooks not associated with commands.
4519 Hooks are stored as array options, members of the array are executed in
4520 order when the hook is triggered.
4521 Like options different hooks may be global or belong to a session, window or pane.
4522 Hooks may be configured with the
4526 commands and displayed with
4531 The following two commands are equivalent:
4532 .Bd -literal -offset indent.
4533 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
4534 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
4537 Setting a hook without specifying an array index clears the hook and sets the
4538 first member of the array.
4541 hook is run after it completes, except when the command is run as part of a hook
4543 They are named with an
4546 For example, the following command adds a hook to select the even-vertical
4549 .Bd -literal -offset indent
4550 set-hook -g after-split-window "selectl even-vertical"
4553 All the notifications listed in the
4555 section are hooks (without any arguments), except
4557 The following additional hooks are available:
4558 .Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX"
4560 Run when a window has activity.
4562 .Ic monitor-activity .
4564 Run when a window has received a bell.
4568 Run when a window has been silent.
4570 .Ic monitor-silence .
4572 Run when a client becomes the latest active client of its session.
4574 Run when a client is attached.
4576 Run when a client is detached
4578 Run when focus enters a client
4579 .It client-focus-out
4580 Run when focus exits a client
4582 Run when a client is resized.
4583 .It client-session-changed
4584 Run when a client's attached session is changed.
4586 Run when the program running in a pane exits, but
4588 is on so the pane has not closed.
4590 Run when the program running in a pane exits.
4592 Run when the focus enters a pane, if the
4596 Run when the focus exits a pane, if the
4599 .It pane-set-clipboard
4600 Run when the terminal clipboard is set using the
4604 Run when a new session created.
4606 Run when a session closed.
4608 Run when a session is renamed.
4610 Run when a window is linked into a session.
4612 Run when a window is renamed.
4614 Run when a window is resized.
4615 This may be after the
4619 Run when a window is unlinked from a session.
4622 Hooks are managed with these commands:
4626 .Op Fl t Ar target-pane
4638 The flags are the same as for
4646 .It Xo Ic show-hooks
4648 .Op Fl t Ar target-pane
4651 The flags are the same as for
4657 option is on (the default is off),
4659 allows mouse events to be bound as keys.
4660 The name of each key is made up of a mouse event (such as
4662 and a location suffix, one of the following:
4663 .Bl -column "XXXXXXXXXXXXX" -offset indent
4664 .It Li "Pane" Ta "the contents of a pane"
4665 .It Li "Border" Ta "a pane border"
4666 .It Li "Status" Ta "the status line window list"
4667 .It Li "StatusLeft" Ta "the left part of the status line"
4668 .It Li "StatusRight" Ta "the right part of the status line"
4669 .It Li "StatusDefault" Ta "any other part of the status line"
4672 The following mouse events are available:
4673 .Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
4674 .It Li "WheelUp" Ta "WheelDown" Ta ""
4675 .It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
4676 .It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
4677 .It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
4678 .It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3"
4679 .It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3"
4680 .It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3"
4685 events are fired for the second click of a double click, even if there may be a
4686 third click which will fire
4691 Each should be suffixed with a location, for example
4692 .Ql MouseDown1Status .
4702 in commands bound to mouse key bindings.
4703 It resolves to the window or pane over which the mouse event took place
4704 (for example, the window in the status line over which button 1 was released for a
4706 binding, or the pane over which the wheel was scrolled for a
4713 flag may be used to forward a mouse event to a pane.
4715 The default key bindings allow the mouse to be used to select and resize panes,
4716 to copy text and to change window using the status line.
4717 These take effect if the
4719 option is turned on.
4721 Certain commands accept the
4726 This is a string which controls the output format of the command.
4727 Format variables are enclosed in
4732 .Ql #{session_name} .
4733 The possible variables are listed in the table below, or the name of a
4735 option may be used for an option's value.
4736 Some variables have a shorter alias such as
4739 is replaced by a single
4749 Conditionals are available by prefixing with
4751 and separating two alternatives with a comma;
4752 if the specified variable exists and is not zero, the first alternative
4753 is chosen, otherwise the second is used.
4755 .Ql #{?session_attached,attached,not attached}
4756 will include the string
4758 if the session is attached and the string
4760 if it is unattached, or
4761 .Ql #{?automatic-rename,yes,no}
4765 .Ic automatic-rename
4769 Conditionals can be nested arbitrarily.
4770 Inside a conditional,
4778 unless they are part of a
4782 .Bd -literal -offset indent
4783 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
4786 String comparisons may be expressed by prefixing two comma-separated
4797 .Ql #{==:#{host},myhost}
4807 evaluate to true if either or both of two comma-separated alternatives are
4809 .Ql #{||:#{pane_in_mode},#{alternate_on}} .
4815 or regular expression comparison.
4816 The first argument is the pattern and the second the string to compare.
4817 An optional argument specifies flags:
4819 means the pattern is a regular expression instead of the default
4823 means to ignore case.
4825 .Ql #{m:*foo*,#{host}}
4827 .Ql #{m/ri:^A,MYVAR} .
4830 performs a search for an
4832 pattern or regular expression in the pane content and evaluates to zero if not
4833 found, or a line number if found.
4838 flag means search for a regular expression and
4844 Numeric operators may be performed by prefixing two comma-separated alternatives with an
4849 flag may be given after the operator to use floating point numbers, otherwise integers are used.
4850 This may be followed by a number giving the number of decimal places to use for the result.
4851 The available operators are:
4868 in formats which are also expanded by
4870 and numeric comparison operators
4879 .Ql #{e|*|f|4:5.5,3}
4880 multiplies 5.5 by 3 for a result with four decimal places and
4882 returns the modulus of 7 and 3.
4884 replaces a numeric argument by its ASCII equivalent, so
4891 colour by its six-digit hexadecimal RGB value.
4893 A limit may be placed on the length of the resultant string by prefixing it
4896 a number and a colon.
4897 Positive numbers count from the start of the string and negative from the end,
4899 .Ql #{=5:pane_title}
4900 will include at most the first five characters of the pane title, or
4901 .Ql #{=-5:pane_title}
4902 the last five characters.
4903 A suffix or prefix may be given as a second argument - if provided then it is
4904 appended or prepended to the string if the length has been trimmed, for example
4905 .Ql #{=/5/...:pane_title}
4908 if the pane title is more than five characters.
4911 pads the string to a given width, for example
4912 .Ql #{p10:pane_title}
4913 will result in a width of at least 10 characters.
4914 A positive width pads on the left, a negative on the right.
4916 expands to the length of the variable and
4918 to its width when displayed, for example
4919 .Ql #{n:window_name} .
4921 Prefixing a time variable with
4923 will convert it to a string, so if
4924 .Ql #{window_activity}
4927 .Ql #{t:window_activity}
4929 .Ql Sun Oct 25 09:25:02 2015 .
4933 will use shorter but less accurate time format for times in the past.
4934 A custom format may be given using an
4940 if the format is separately being passed through
4945 .Ql #{t/f/%%H#:%%M:window_activity} ,
4957 of the variable respectively.
4961 special characters or with a
4963 suffix, escape hash characters (so
4968 will expand the format twice, for example
4969 .Ql #{E:status-left}
4970 is the result of expanding the content of the
4972 option rather than the option itself.
4983 will loop over each session, window or pane and insert the format once
4985 For windows and panes, two comma-separated formats may be given:
4986 the second is used for the current window or active pane.
4987 For example, to get a list of windows formatted like the status line:
4988 .Bd -literal -offset indent
4989 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
4993 checks if a window (without any suffix or with the
4995 suffix) or a session (with the
4997 suffix) name exists, for example
4999 is replaced with 1 if a window named
5003 A prefix of the form
5010 The first argument may be an extended regular expression and a final argument may be
5012 to ignore case, for example
5013 .Ql s/a(.)/\e1x/i:\&
5019 In addition, the last line of a shell command's output may be inserted using
5023 will insert the system's uptime.
5024 When constructing formats,
5028 commands to finish; instead, the previous result from running the same command is used,
5029 or a placeholder if the command has not been run before.
5030 If the command hasn't exited, the most recent line of output will be used, but the status
5031 line will not be updated more than once a second.
5032 Commands are executed using
5036 global environment set (see the
5037 .Sx GLOBAL AND SESSION ENVIRONMENT
5042 specifies that a string should be interpreted literally and not expanded.
5044 .Ql #{l:#{?pane_in_mode,yes,no}}
5046 .Ql #{?pane_in_mode,yes,no} .
5048 The following variables are available, where appropriate:
5049 .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
5050 .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
5051 .It Li "active_window_index" Ta "" Ta "Index of active window in session"
5052 .It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen"
5053 .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
5054 .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
5055 .It Li "buffer_created" Ta "" Ta "Time buffer created"
5056 .It Li "buffer_name" Ta "" Ta "Name of buffer"
5057 .It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
5058 .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
5059 .It Li "client_activity" Ta "" Ta "Time client last had activity"
5060 .It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels"
5061 .It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels"
5062 .It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
5063 .It Li "client_created" Ta "" Ta "Time client created"
5064 .It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind"
5065 .It Li "client_flags" Ta "" Ta "List of client flags"
5066 .It Li "client_height" Ta "" Ta "Height of client"
5067 .It Li "client_key_table" Ta "" Ta "Current key table"
5068 .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
5069 .It Li "client_name" Ta "" Ta "Name of client"
5070 .It Li "client_pid" Ta "" Ta "PID of client process"
5071 .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
5072 .It Li "client_readonly" Ta "" Ta "1 if client is readonly"
5073 .It Li "client_session" Ta "" Ta "Name of the client's session"
5074 .It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any"
5075 .It Li "client_termname" Ta "" Ta "Terminal name of client"
5076 .It Li "client_termtype" Ta "" Ta "Terminal type of client, if available"
5077 .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
5078 .It Li "client_uid" Ta "" Ta "UID of client process"
5079 .It Li "client_user" Ta "" Ta "User of client process"
5080 .It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8"
5081 .It Li "client_width" Ta "" Ta "Width of client"
5082 .It Li "client_written" Ta "" Ta "Bytes written to client"
5083 .It Li "command" Ta "" Ta "Name of command in use, if any"
5084 .It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
5085 .It Li "command_list_name" Ta "" Ta "Command name if listing commands"
5086 .It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
5087 .It Li "config_files" Ta "" Ta "List of configuration files loaded"
5088 .It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode"
5089 .It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode"
5090 .It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode"
5091 .It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode"
5092 .It Li "current_file" Ta "" Ta "Current configuration file"
5093 .It Li "cursor_character" Ta "" Ta "Character at cursor in pane"
5094 .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
5095 .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
5096 .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
5097 .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
5098 .It Li "history_limit" Ta "" Ta "Maximum window history lines"
5099 .It Li "history_size" Ta "" Ta "Size of history in lines"
5100 .It Li "hook" Ta "" Ta "Name of running hook, if any"
5101 .It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any"
5102 .It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
5103 .It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
5104 .It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
5105 .It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
5106 .It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
5107 .It Li "host" Ta "#H" Ta "Hostname of local host"
5108 .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
5109 .It Li "insert_flag" Ta "" Ta "Pane insert flag"
5110 .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
5111 .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
5112 .It Li "last_window_index" Ta "" Ta "Index of last window in session"
5113 .It Li "line" Ta "" Ta "Line number in the list"
5114 .It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
5115 .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
5116 .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
5117 .It Li "mouse_line" Ta "" Ta "Line under mouse, if any"
5118 .It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag"
5119 .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
5120 .It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag"
5121 .It Li "mouse_word" Ta "" Ta "Word under mouse, if any"
5122 .It Li "mouse_x" Ta "" Ta "Mouse X position, if any"
5123 .It Li "mouse_y" Ta "" Ta "Mouse Y position, if any"
5124 .It Li "next_session_id" Ta "" Ta "Unique session ID for next new session"
5125 .It Li "origin_flag" Ta "" Ta "Pane origin flag"
5126 .It Li "pane_active" Ta "" Ta "1 if active pane"
5127 .It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window"
5128 .It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window"
5129 .It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window"
5130 .It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window"
5131 .It Li "pane_bg" Ta "" Ta "Pane background colour"
5132 .It Li "pane_bottom" Ta "" Ta "Bottom of pane"
5133 .It Li "pane_current_command" Ta "" Ta "Current command if available"
5134 .It Li "pane_current_path" Ta "" Ta "Current path if available"
5135 .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
5136 .It Li "pane_dead_signal" Ta "" Ta "Exit signal of process in dead pane"
5137 .It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
5138 .It Li "pane_dead_time" Ta "" Ta "Exit time of process in dead pane"
5139 .It Li "pane_fg" Ta "" Ta "Pane foreground colour"
5140 .It Li "pane_format" Ta "" Ta "1 if format is for a pane"
5141 .It Li "pane_height" Ta "" Ta "Height of pane"
5142 .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
5143 .It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode"
5144 .It Li "pane_index" Ta "#P" Ta "Index of pane"
5145 .It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled"
5146 .It Li "pane_last" Ta "" Ta "1 if last pane"
5147 .It Li "pane_left" Ta "" Ta "Left of pane"
5148 .It Li "pane_marked" Ta "" Ta "1 if this is the marked pane"
5149 .It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set"
5150 .It Li "pane_mode" Ta "" Ta "Name of pane mode, if any"
5151 .It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)"
5152 .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
5153 .It Li "pane_pipe" Ta "" Ta "1 if pane is being piped"
5154 .It Li "pane_right" Ta "" Ta "Right of pane"
5155 .It Li "pane_search_string" Ta "" Ta "Last search string in copy mode"
5156 .It Li "pane_start_command" Ta "" Ta "Command pane started with"
5157 .It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized"
5158 .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
5159 .It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)"
5160 .It Li "pane_top" Ta "" Ta "Top of pane"
5161 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
5162 .It Li "pane_width" Ta "" Ta "Width of pane"
5163 .It Li "pid" Ta "" Ta "Server PID"
5164 .It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated"
5165 .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
5166 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
5167 .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
5168 .It Li "search_match" Ta "" Ta "Search match if any"
5169 .It Li "search_present" Ta "" Ta "1 if search started in copy mode"
5170 .It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode"
5171 .It Li "selection_end_x" Ta "" Ta "X position of the end of the selection"
5172 .It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection"
5173 .It Li "selection_present" Ta "" Ta "1 if selection started in copy mode"
5174 .It Li "selection_start_x" Ta "" Ta "X position of the start of the selection"
5175 .It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection"
5176 .It Li "session_activity" Ta "" Ta "Time of session last activity"
5177 .It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
5178 .It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
5179 .It Li "session_attached_list" Ta "" Ta "List of clients session is attached to"
5180 .It Li "session_created" Ta "" Ta "Time session created"
5181 .It Li "session_format" Ta "" Ta "1 if format is for a session"
5182 .It Li "session_group" Ta "" Ta "Name of session group"
5183 .It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to"
5184 .It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to"
5185 .It Li "session_group_list" Ta "" Ta "List of sessions in group"
5186 .It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group"
5187 .It Li "session_group_size" Ta "" Ta "Size of session group"
5188 .It Li "session_grouped" Ta "" Ta "1 if session in a group"
5189 .It Li "session_id" Ta "" Ta "Unique session ID"
5190 .It Li "session_last_attached" Ta "" Ta "Time session last attached"
5191 .It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
5192 .It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane"
5193 .It Li "session_name" Ta "#S" Ta "Name of session"
5194 .It Li "session_path" Ta "" Ta "Working directory of session"
5195 .It Li "session_stack" Ta "" Ta "Window indexes in most recent order"
5196 .It Li "session_windows" Ta "" Ta "Number of windows in session"
5197 .It Li "socket_path" Ta "" Ta "Server socket path"
5198 .It Li "start_time" Ta "" Ta "Server start time"
5199 .It Li "uid" Ta "" Ta "Server UID"
5200 .It Li "user" Ta "" Ta "Server user"
5201 .It Li "version" Ta "" Ta "Server version"
5202 .It Li "window_active" Ta "" Ta "1 if window active"
5203 .It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window"
5204 .It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window"
5205 .It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active"
5206 .It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active"
5207 .It Li "window_activity" Ta "" Ta "Time of window last activity"
5208 .It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
5209 .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
5210 .It Li "window_bigger" Ta "" Ta "1 if window is larger than client"
5211 .It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels"
5212 .It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels"
5213 .It Li "window_end_flag" Ta "" Ta "1 if window has the highest index"
5214 .It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##"
5215 .It Li "window_format" Ta "" Ta "1 if format is for a window"
5216 .It Li "window_height" Ta "" Ta "Height of window"
5217 .It Li "window_id" Ta "" Ta "Unique window ID"
5218 .It Li "window_index" Ta "#I" Ta "Index of window"
5219 .It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
5220 .It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
5221 .It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
5222 .It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to"
5223 .It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to"
5224 .It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane"
5225 .It Li "window_name" Ta "#W" Ta "Name of window"
5226 .It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client"
5227 .It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client"
5228 .It Li "window_panes" Ta "" Ta "Number of panes in window"
5229 .It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped"
5230 .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
5231 .It Li "window_stack_index" Ta "" Ta "Index in session most recent stack"
5232 .It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index"
5233 .It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
5234 .It Li "window_width" Ta "" Ta "Width of window"
5235 .It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
5236 .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
5240 offers various options to specify the colour and attributes of aspects of the
5241 interface, for example
5243 for the status line.
5244 In addition, embedded styles may be specified in format options, such as
5246 by enclosing them in
5251 A style may be the single term
5253 to specify the default style (which may come from an option, for example
5255 in the status line) or a space
5256 or comma separated list of the following:
5259 Set the foreground colour.
5260 The colour is one of:
5269 if supported the bright variants
5276 from the 256-colour set;
5278 for the default colour;
5280 for the terminal default colour; or a hexadecimal RGB string such as
5283 Set the background colour.
5285 Set no attributes (turn off any active attributes).
5298 .Ic double-underscore ,
5299 .Ic curly-underscore ,
5300 .Ic dotted-underscore ,
5301 .Ic dashed-underscore
5304 Any of the attributes may be prefixed with
5308 is the terminal alternate character set.
5309 .It Xo Ic align=left
5315 Align text to the left, centre or right of the available space if appropriate.
5317 Fill the available space with a background colour if appropriate.
5320 .Ic list=left-marker ,
5321 .Ic list=right-marker ,
5324 Mark the position of the various window list components in the
5328 marks the start of the list;
5330 is the part of the list that should be kept in focus if the entire list won't fit
5331 in the available space (typically the current window);
5332 .Ic list=left-marker
5334 .Ic list=right-marker
5335 mark the text to be used to mark that text has been trimmed from the left or
5336 right of the list if there is not enough space.
5337 .It Xo Ic push-default ,
5340 Store the current colours and attributes as the default or reset to the previous
5344 affects any subsequent use of the
5348 Only one default may be pushed (each
5350 replaces the previous saved default).
5351 .It Xo Ic range=left ,
5353 .Ic range=window|X ,
5362 are the text used for the
5368 is the range for a window passed to the
5376 .Bd -literal -offset indent
5377 fg=yellow bold underscore blink
5378 bg=black,fg=default,noreverse
5380 .Sh NAMES AND TITLES
5382 distinguishes between names and titles.
5383 Windows and sessions have names, which may be used to specify them in targets
5384 and are displayed in the status line and various lists: the name is the
5386 identifier for a window or session.
5387 Only panes have titles.
5388 A pane's title is typically set by the program running inside the pane using
5389 an escape sequence (like it would set the
5393 Windows themselves do not have titles - a window's title is the title of its
5396 itself may set the title of the terminal in which the client is running, see
5401 A session's name is set with the
5406 A window's name is set with one of:
5409 A command argument (such as
5416 An escape sequence (if the
5418 option is turned on):
5419 .Bd -literal -offset indent
5420 $ printf '\e033kWINDOW_NAME\e033\e\e'
5423 Automatic renaming, which sets the name to the active command in the window's
5426 .Ic automatic-rename
5430 When a pane is first created, its title is the hostname.
5431 A pane's title can be set via the title setting escape sequence, for example:
5432 .Bd -literal -offset indent
5433 $ printf '\e033]2;My Title\e033\e\e'
5436 It can also be modified with the
5440 .Sh GLOBAL AND SESSION ENVIRONMENT
5441 When the server is started,
5443 copies the environment into the
5444 .Em global environment ;
5445 in addition, each session has a
5446 .Em session environment .
5447 When a window is created, the session and global environments are merged.
5448 If a variable exists in both, the value from the session environment is used.
5449 The result is the initial environment passed to the new process.
5452 .Ic update-environment
5453 session option may be used to update the session environment from the client
5454 when a new session is created or an old reattached.
5456 also initialises the
5458 variable with some internal information to allow commands to be executed
5459 from inside, and the
5461 variable with the correct terminal setting of
5464 Variables in both session and global environments may be marked as hidden.
5465 Hidden variables are not passed into the environment of new processes and
5466 instead can only be used by tmux itself (for example in formats, see the
5470 Commands to alter and view the environment are:
5473 .It Xo Ic set-environment
5475 .Op Fl t Ar target-session
5476 .Ar name Op Ar value
5478 .D1 Pq alias: Ic setenv
5479 Set or unset an environment variable.
5482 is used, the change is made in the global environment; otherwise, it is applied
5483 to the session environment for
5484 .Ar target-session .
5489 is expanded as a format.
5492 flag unsets a variable.
5494 indicates the variable is to be removed from the environment before starting a
5497 marks the variable as hidden.
5499 .It Xo Ic show-environment
5501 .Op Fl t Ar target-session
5504 .D1 Pq alias: Ic showenv
5505 Display the environment for
5507 or the global environment with
5511 is omitted, all variables are shown.
5512 Variables removed from the environment are prefixed with
5516 is used, the output is formatted as a set of Bourne shell commands.
5518 shows hidden variables (omitted by default).
5522 includes an optional status line which is displayed in the bottom line of each
5525 By default, the status line is enabled and one line in height (it may be
5526 disabled or made multiple lines with the
5528 session option) and contains, from left-to-right: the name of the current
5529 session in square brackets; the window list; the title of the active pane
5530 in double quotes; and the time and date.
5532 Each line of the status line is configured with the
5535 The default is made of three parts: configurable left and right sections (which
5536 may contain dynamic content such as the time or output from a shell command,
5539 .Ic status-left-length ,
5542 .Ic status-right-length
5543 options below), and a central window list.
5544 By default, the window list shows the index, name and (if any) flag of the
5545 windows present in the current session in ascending numerical order.
5546 It may be customised with the
5547 .Ar window-status-format
5549 .Ar window-status-current-format
5551 The flag is one of the following symbols appended to the window name:
5552 .Bl -column "Symbol" "Meaning" -offset indent
5553 .It Sy "Symbol" Ta Sy "Meaning"
5554 .It Li "*" Ta "Denotes the current window."
5555 .It Li "-" Ta "Marks the last window (previously selected)."
5556 .It Li "#" Ta "Window activity is monitored and activity has been detected."
5557 .It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window."
5558 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
5559 .It Li "M" Ta "The window contains the marked pane."
5560 .It Li "Z" Ta "The window's active pane is zoomed."
5563 The # symbol relates to the
5564 .Ic monitor-activity
5566 The window name is printed in inverted colours if an alert (bell, activity or
5567 silence) is present.
5569 The colour and attributes of the status line may be configured, the entire
5570 status line using the
5572 session option and individual windows using the
5573 .Ic window-status-style
5576 The status line is automatically refreshed at interval if it has changed, the
5577 interval may be controlled with the
5581 Commands related to the status line are as follows:
5584 .It Xo Ic clear-prompt-history
5585 .Op Fl T Ar prompt-type
5587 .D1 Pq alias: Ic clrphist
5588 Clear status prompt history for prompt type
5592 is omitted, then clear history for all types.
5595 for possible values for
5597 .It Xo Ic command-prompt
5601 .Op Fl t Ar target-client
5602 .Op Fl T Ar prompt-type
5605 Open the command prompt in a client.
5606 This may be used from inside
5608 to execute commands interactively.
5612 is specified, it is used as the command.
5616 is expanded as a format.
5620 is a comma-separated list of the initial text for each prompt.
5625 is a comma-separated list of prompts which are displayed in order; otherwise
5626 a single prompt is displayed, constructed from
5628 if it is present, or
5632 Before the command is executed, the first occurrence of the string
5634 and all occurrences of
5636 are replaced by the response to the first prompt, all
5638 are replaced with the response to the second prompt, and so on for further
5640 Up to nine prompt responses may be replaced
5649 but any quotation marks are escaped.
5652 makes the prompt only accept one key press, in this case the resulting input
5653 is a single character.
5657 but the key press is translated to a key name.
5659 makes the prompt only accept numeric key presses.
5661 executes the command every time the prompt input changes instead of when the
5662 user exits the command prompt.
5668 This affects what completions are offered when
5671 Available types are:
5678 The following keys have a special meaning in the command prompt, depending
5682 .Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
5683 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
5684 .It Li "Cancel command prompt" Ta "q" Ta "Escape"
5685 .It Li "Delete from cursor to start of word" Ta "" Ta "C-w"
5686 .It Li "Delete entire command" Ta "d" Ta "C-u"
5687 .It Li "Delete from cursor to end" Ta "D" Ta "C-k"
5688 .It Li "Execute command" Ta "Enter" Ta "Enter"
5689 .It Li "Get next command from history" Ta "" Ta "Down"
5690 .It Li "Get previous command from history" Ta "" Ta "Up"
5691 .It Li "Insert top paste buffer" Ta "p" Ta "C-y"
5692 .It Li "Look for completions" Ta "Tab" Ta "Tab"
5693 .It Li "Move cursor left" Ta "h" Ta "Left"
5694 .It Li "Move cursor right" Ta "l" Ta "Right"
5695 .It Li "Move cursor to end" Ta "$" Ta "C-e"
5696 .It Li "Move cursor to next word" Ta "w" Ta "M-f"
5697 .It Li "Move cursor to previous word" Ta "b" Ta "M-b"
5698 .It Li "Move cursor to start" Ta "0" Ta "C-a"
5699 .It Li "Transpose characters" Ta "" Ta "C-t"
5704 the prompt is shown in the background and the invoking client does not exit
5705 until it is dismissed.
5707 .It Xo Ic confirm-before
5710 .Op Fl t Ar target-client
5713 .D1 Pq alias: Ic confirm
5714 Ask for confirmation before executing
5720 is the prompt to display; otherwise a prompt is constructed from
5722 It may contain the special character sequences supported by the
5727 the prompt is shown in the background and the invoking client does not exit
5728 until it is dismissed.
5730 .It Xo Ic display-menu
5732 .Op Fl c Ar target-client
5733 .Op Fl t Ar target-pane
5735 .Op Fl x Ar position
5736 .Op Fl y Ar position
5742 .D1 Pq alias: Ic menu
5746 gives the target for any commands run from the menu.
5748 A menu is passed as a series of arguments: first the menu item name,
5749 second the key shortcut (or empty for none) and third the command
5750 to run when the menu item is chosen.
5751 The name and command are formats, see the
5756 If the name begins with a hyphen (-), then the item is disabled (shown dim) and
5758 The name may be empty for a separator line, in which case both the key and
5759 command should be omitted.
5762 is a format for the menu title (see
5768 give the position of the menu.
5769 Both may be a row or column number, or one of the following special values:
5770 .Bl -column "XXXXX" "XXXX" -offset indent
5771 .It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning"
5772 .It Li "C" Ta "Both" Ta "The centre of the terminal"
5773 .It Li "R" Ta Fl x Ta "The right side of the terminal"
5774 .It Li "P" Ta "Both" Ta "The bottom left of the pane"
5775 .It Li "M" Ta "Both" Ta "The mouse position"
5776 .It Li "W" Ta "Both" Ta "The window position on the status line"
5777 .It Li "S" Ta Fl y Ta "The line above or below the status line"
5780 Or a format, which is expanded including the following additional variables:
5781 .Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
5782 .It Sy "Variable name" Ta Sy "Replaced with"
5783 .It Li "popup_centre_x" Ta "Centered in the client"
5784 .It Li "popup_centre_y" Ta "Centered in the client"
5785 .It Li "popup_height" Ta "Height of menu or popup"
5786 .It Li "popup_mouse_bottom" Ta "Bottom of at the mouse"
5787 .It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse"
5788 .It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse"
5789 .It Li "popup_mouse_top" Ta "Top at the mouse"
5790 .It Li "popup_mouse_x" Ta "Mouse X position"
5791 .It Li "popup_mouse_y" Ta "Mouse Y position"
5792 .It Li "popup_pane_bottom" Ta "Bottom of the pane"
5793 .It Li "popup_pane_left" Ta "Left of the pane"
5794 .It Li "popup_pane_right" Ta "Right of the pane"
5795 .It Li "popup_pane_top" Ta "Top of the pane"
5796 .It Li "popup_status_line_y" Ta "Above or below the status line"
5797 .It Li "popup_width" Ta "Width of menu or popup"
5798 .It Li "popup_window_status_line_x" Ta "At the window position in status line"
5799 .It Li "popup_window_status_line_y" Ta "At the status line showing the window"
5802 Each menu consists of items followed by a key shortcut shown in brackets.
5803 If the menu is too large to fit on the terminal, it is not displayed.
5804 Pressing the key shortcut chooses the corresponding item.
5805 If the mouse is enabled and the menu is opened from a mouse key binding,
5806 releasing the mouse button with an item selected chooses that item and
5807 releasing the mouse button without an item selected closes the menu.
5809 changes this behaviour so that the menu does not close when the mouse button is
5810 released without an item selected the menu is not closed and a mouse button
5811 must be clicked to choose an item.
5813 The following keys are also available:
5814 .Bl -column "Key" "Function" -offset indent
5815 .It Sy "Key" Ta Sy "Function"
5816 .It Li "Enter" Ta "Choose selected item"
5817 .It Li "Up" Ta "Select previous item"
5818 .It Li "Down" Ta "Select next item"
5819 .It Li "q" Ta "Exit menu"
5822 .It Xo Ic display-message
5824 .Op Fl c Ar target-client
5826 .Op Fl t Ar target-pane
5829 .D1 Pq alias: Ic display
5833 is given, the output is printed to stdout, otherwise it is displayed in the
5835 status line for up to
5842 option is used; a delay of zero waits for a key press.
5844 ignores key presses and closes only after the delay expires.
5849 section; information is taken from
5853 is given, otherwise the active pane.
5856 prints verbose logging as the format is parsed and
5858 lists the format variables and their values.
5861 forwards any input read from stdin to the empty pane given by
5864 .It Xo Ic display-popup
5866 .Op Fl b Ar border-lines
5867 .Op Fl c Ar target-client
5868 .Op Fl d Ar start-directory
5869 .Op Fl e Ar environment
5872 .Op Fl S Ar border-style
5873 .Op Fl t Ar target-pane
5876 .Op Fl x Ar position
5877 .Op Fl y Ar position
5878 .Op Ar shell-command
5880 .D1 Pq alias: Ic popup
5881 Display a popup running
5885 A popup is a rectangular box drawn over the top of any panes.
5886 Panes are not updated while a popup is present.
5889 closes the popup automatically when
5894 closes the popup only if
5896 exited with success.
5901 give the position of the popup, they have the same meaning as for the
5907 give the width and height - both may be a percentage (followed by
5909 If omitted, half of the terminal size is used.
5912 does not surround the popup by a border.
5915 sets the type of border line for the popup.
5922 .Ic popup-border-lines
5923 for possible values for
5927 sets the style for the popup and
5929 sets the style for the popup border.
5939 and sets an environment variable for the popup; it may be specified multiple
5943 is a format for the popup title (see
5948 flag closes any popup on the client.
5950 .It Xo Ic show-prompt-history
5951 .Op Fl T Ar prompt-type
5953 .D1 Pq alias: Ic showphist
5954 Display status prompt history for prompt type
5958 is omitted, then show history for all types.
5961 for possible values for
5966 maintains a set of named
5968 Each buffer may be either explicitly or automatically named.
5969 Explicitly named buffers are named when created with the
5973 commands, or by renaming an automatically named buffer with
5976 Automatically named buffers are given a name such as
5982 option is reached, the oldest automatically named buffer is deleted.
5983 Explicitly named buffers are not subject to
5985 and may be deleted with the
5989 Buffers may be added using
5995 commands, and pasted into a window using the
5998 If a buffer command is used and no buffer is specified, the most
5999 recently added automatically named buffer is assumed.
6001 A configurable history buffer is also maintained for each window.
6002 By default, up to 2000 lines are kept; this can be altered with the
6008 The buffer commands are as follows:
6015 .Op Fl K Ar key-format
6016 .Op Fl O Ar sort-order
6017 .Op Fl t Ar target-pane
6020 Put a pane into buffer mode, where a buffer may be chosen interactively from
6022 Each buffer is shown on one line.
6023 A shortcut key is shown on the left in brackets allowing for immediate choice,
6024 or the list may be navigated and an item chosen or otherwise manipulated using
6028 The following keys may be used in buffer mode:
6029 .Bl -column "Key" "Function" -offset indent
6030 .It Sy "Key" Ta Sy "Function"
6031 .It Li "Enter" Ta "Paste selected buffer"
6032 .It Li "Up" Ta "Select previous buffer"
6033 .It Li "Down" Ta "Select next buffer"
6034 .It Li "C-s" Ta "Search by name or content"
6035 .It Li "n" Ta "Repeat last search"
6036 .It Li "t" Ta "Toggle if buffer is tagged"
6037 .It Li "T" Ta "Tag no buffers"
6038 .It Li "C-t" Ta "Tag all buffers"
6039 .It Li "p" Ta "Paste selected buffer"
6040 .It Li "P" Ta "Paste tagged buffers"
6041 .It Li "d" Ta "Delete selected buffer"
6042 .It Li "D" Ta "Delete tagged buffers"
6043 .It Li "e" Ta "Open the buffer in an editor"
6044 .It Li "f" Ta "Enter a format to filter items"
6045 .It Li "O" Ta "Change sort field"
6046 .It Li "r" Ta "Reverse sort order"
6047 .It Li "v" Ta "Toggle preview"
6048 .It Li "q" Ta "Exit mode"
6051 After a buffer is chosen,
6053 is replaced by the buffer name in
6055 and the result executed as a command.
6058 is not given, "paste-buffer -b '%%'" is used.
6061 specifies the initial sort field: one of
6067 reverses the sort order.
6069 specifies an initial filter: the filter is a format - if it evaluates to zero,
6070 the item in the list is not shown, otherwise it is shown.
6071 If a filter would lead to an empty list, it is ignored.
6073 specifies the format for each item in the list and
6075 a format for each shortcut key; both are evaluated once for each line.
6077 starts without the preview.
6078 This command works only if at least one client is attached.
6080 .It Ic clear-history Op Fl t Ar target-pane
6081 .D1 Pq alias: Ic clearhist
6082 Remove and free the history for the specified pane.
6084 .It Ic delete-buffer Op Fl b Ar buffer-name
6085 .D1 Pq alias: Ic deleteb
6086 Delete the buffer named
6088 or the most recently added automatically named buffer if not specified.
6090 .It Xo Ic list-buffers
6094 .D1 Pq alias: Ic lsb
6095 List the global buffers.
6097 specifies the format of each line and
6100 Only buffers for which the filter is true are shown.
6104 .It Xo Ic load-buffer
6106 .Op Fl b Ar buffer-name
6107 .Op Fl t Ar target-client
6111 .D1 Pq alias: Ic loadb
6112 Load the contents of the specified paste buffer from
6116 is given, the buffer is also sent to the clipboard for
6120 escape sequence, if possible.
6122 .It Xo Ic paste-buffer
6124 .Op Fl b Ar buffer-name
6125 .Op Fl s Ar separator
6126 .Op Fl t Ar target-pane
6128 .D1 Pq alias: Ic pasteb
6129 Insert the contents of a paste buffer into the specified pane.
6130 If not specified, paste into the current one.
6133 also delete the paste buffer.
6134 When output, any linefeed (LF) characters in the paste buffer are replaced with
6135 a separator, by default carriage return (CR).
6136 A custom separator may be specified using the
6141 flag means to do no replacement (equivalent to a separator of LF).
6144 is specified, paste bracket control codes are inserted around the
6145 buffer if the application has requested bracketed paste mode.
6147 .It Xo Ic save-buffer
6149 .Op Fl b Ar buffer-name
6152 .D1 Pq alias: Ic saveb
6153 Save the contents of the specified paste buffer to
6157 option appends to rather than overwriting the file.
6158 .It Xo Ic set-buffer
6160 .Op Fl b Ar buffer-name
6161 .Op Fl t Ar target-client
6163 .Op Fl n Ar new-buffer-name
6166 .D1 Pq alias: Ic setb
6167 Set the contents of the specified buffer to
6171 is given, the buffer is also sent to the clipboard for
6175 escape sequence, if possible.
6178 option appends to rather than overwriting the buffer.
6181 option renames the buffer to
6182 .Ar new-buffer-name .
6184 .It Xo Ic show-buffer
6185 .Op Fl b Ar buffer-name
6187 .D1 Pq alias: Ic showb
6188 Display the contents of the specified buffer.
6191 Miscellaneous commands are as follows:
6193 .It Ic clock-mode Op Fl t Ar target-pane
6194 Display a large clock.
6198 .Op Fl t Ar target-pane
6199 .Ar shell-command command
6209 returns success or the second
6212 Before being executed,
6214 is expanded using the rules specified in the
6216 section, including those relevant to
6221 is run in the background.
6227 is not executed but considered success if neither empty nor zero (after formats
6231 .D1 Pq alias: Ic lock
6232 Lock each client individually by running the command specified by the
6239 .Op Fl t Ar target-pane
6240 .Op Ar shell-command
6242 .D1 Pq alias: Ic run
6251 command in the background without creating a window.
6252 Before being executed,
6254 is expanded using the rules specified in the
6259 the command is run in the background.
6263 seconds before starting the command.
6266 is not given, any output to stdout is displayed in view mode (in the pane
6269 or the current pane if omitted) after the command finishes.
6270 If the command fails, the exit status is also displayed.
6276 .D1 Pq alias: Ic wait
6277 When used without options, prevents the client from exiting until woken using
6280 with the same channel.
6283 is used, the channel is locked and any clients that try to lock the same
6284 channel are made to wait until the channel is unlocked with
6291 client detaches, it prints a message.
6294 .It detached (from session ...)
6295 The client was detached normally.
6296 .It detached and SIGHUP
6297 The client was detached and its parent sent the
6299 signal (for example with
6307 was unexpectedly destroyed.
6309 The client was killed with
6312 The client is in control mode and became unable to keep up with the data from
6315 The server exited when it had no sessions.
6317 The server exited when it received
6319 .It server exited unexpectedly
6320 The server crashed or otherwise exited without telling the client the reason.
6322 .Sh TERMINFO EXTENSIONS
6324 understands some unofficial extensions to
6326 It is not normally necessary to set these manually, instead the
6327 .Ic terminal-features
6328 option should be used.
6331 An existing extension that tells
6333 the terminal supports default colours.
6337 that the terminal supports the VTE bidirectional text extensions.
6339 Set the cursor colour.
6340 The first takes a single string argument and is used to set the colour;
6341 the second takes no arguments and restores the default cursor colour.
6342 If set, a sequence such as this may be used
6343 to change the cursor colour from inside
6345 .Bd -literal -offset indent
6346 $ printf '\e033]12;red\e033\e\e'
6353 .It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg
6354 Set, clear, disable or enable DECSLRM margins.
6355 These are set automatically if the terminal reports it is
6358 .It Em \&Dsbp , \&Enbp
6359 Disable and enable bracketed paste.
6360 These are set automatically if the
6362 capability is present.
6363 .It Em \&Dseks , \&Eneks
6364 Disable and enable extended keys.
6365 .It Em \&Dsfcs , \&Enfcs
6366 Disable and enable focus reporting.
6367 These are set automatically if the
6369 capability is present.
6373 that the terminal supports rectangle operations.
6375 Enable the overline attribute.
6377 Set a styled underscore.
6378 The single parameter is one of: 0 for no underscore, 1 for normal
6379 underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted
6380 underscore and 5 for dashed underscore.
6381 .It Em \&Setulc , \&ol
6382 Set the underscore colour or reset to the default.
6383 The argument is (red * 65536) + (green * 256) + blue where each is between 0
6386 Set or reset the cursor style.
6387 If set, a sequence such as this may be used
6388 to change the cursor to an underline:
6389 .Bd -literal -offset indent
6390 $ printf '\e033[4 q'
6395 is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
6397 Set the opening sequence for the working directory notification.
6398 The sequence is terminated using the standard
6402 Start (parameter is 1) or end (parameter is 2) a synchronized update.
6404 Indicate that the terminal supports the
6406 RGB escape sequence (for example, \ee[38;2;255;255;255m).
6408 If supported, this is used for the initialize colour escape sequence (which
6409 may be enabled by adding the
6418 This is equivalent to the
6423 Store the current buffer in the host terminal's selection (clipboard).
6426 option above and the
6430 This is an existing extension capability that tmux uses to mean that the
6431 terminal supports the
6433 title set sequences and to automatically set some of the capabilities above.
6437 offers a textual interface called
6439 This allows applications to communicate with
6441 using a simple text-only protocol.
6443 In control mode, a client sends
6445 commands or command sequences terminated by newlines on standard input.
6446 Each command will produce one block of output on standard output.
6447 An output block consists of a
6449 line followed by the output (which may be empty).
6450 The output block ends with a
6459 have three arguments: an integer time (as seconds from epoch), command number and
6460 flags (currently not used).
6462 .Bd -literal -offset indent
6463 %begin 1363006971 2 1
6464 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
6471 command may be used to set the size of a client in control mode.
6475 outputs notifications.
6476 A notification will never occur inside an output block.
6478 The following notifications are defined:
6480 .It Ic %client-detached Ar client
6481 The client has detached.
6482 .It Ic %client-session-changed Ar client session-id name
6483 The client is now attached to the session with ID
6487 .It Ic %continue Ar pane-id
6488 The pane has been continued after being paused (if the
6493 .It Ic %exit Op Ar reason
6496 client is exiting immediately, either because it is not attached to any session
6497 or an error occurred.
6500 describes why the client exited.
6501 .It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value
6508 is the time in milliseconds for which tmux had buffered the output before it was sent.
6509 Any subsequent arguments up until a single
6511 are for future use and should be ignored.
6512 .It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags
6513 The layout of a window with ID
6518 The window's visible layout is
6519 .Ar window-visible-layout
6520 and the window flags are
6522 .It Ic %output Ar pane-id Ar value
6523 A window pane produced output.
6525 escapes non-printable characters and backslash as octal \\xxx.
6526 .It Ic %pane-mode-changed Ar pane-id
6530 .It Ic %pause Ar pane-id
6531 The pane has been paused (if the
6534 .It Ic %session-changed Ar session-id Ar name
6535 The client is now attached to the session with ID
6539 .It Ic %session-renamed Ar name
6540 The current session was renamed to
6542 .It Ic %session-window-changed Ar session-id Ar window-id
6545 changed its active window to the window with ID
6547 .It Ic %sessions-changed
6548 A session was created or destroyed.
6549 .It Xo Ic %subscription-changed
6554 .Ar pane-id ... \& :
6557 The value of the format associated with subscription
6568 are for future use and should be ignored.
6569 .It Ic %unlinked-window-add Ar window-id
6572 was created but is not linked to the current session.
6573 .It Ic %unlinked-window-close Ar window-id
6576 which is not linked to the current session, was closed.
6577 .It Ic %unlinked-window-renamed Ar window-id
6580 which is not linked to the current session, was renamed.
6581 .It Ic %window-add Ar window-id
6584 was linked to the current session.
6585 .It Ic %window-close Ar window-id
6589 .It Ic %window-pane-changed Ar window-id Ar pane-id
6590 The active pane in the window with ID
6592 changed to the pane with ID
6594 .It Ic %window-renamed Ar window-id Ar name
6603 is started, it inspects the following environment variables:
6604 .Bl -tag -width LC_CTYPE
6606 If the command specified in this variable contains the string
6610 is unset, use vi-style key bindings.
6617 The user's login directory.
6620 database is consulted.
6622 The character encoding
6624 It is used for two separate purposes.
6625 For output to the terminal, UTF-8 is used if the
6627 option is given or if
6633 Otherwise, only ASCII characters are written and non-ASCII characters
6634 are replaced with underscores
6638 always runs with a UTF-8 locale.
6639 If en_US.UTF-8 is provided by the operating system it is used and
6641 is ignored for input.
6646 what the UTF-8 locale is called on the current system.
6647 If the locale specified by
6649 is not available or is not a UTF-8 locale,
6651 exits with an error message.
6653 The date and time format
6655 It is used for locale-dependent
6659 The current working directory to be set in the global environment.
6660 This may be useful if it contains symbolic links.
6661 If the value of the variable does not match the current working
6662 directory, the variable is ignored and the result of
6666 The absolute path to the default shell for new windows.
6671 The parent directory of the directory containing the server sockets.
6676 If the command specified in this variable contains the string
6678 use vi-style key bindings.
6686 .Bl -tag -width "/etc/tmux.confXXX" -compact
6691 .It Pa /etc/tmux.conf
6692 System-wide configuration file.
6700 .Dl $ tmux new-session vi
6702 Most commands have a shorter form, known as an alias.
6703 For new-session, this is
6708 Alternatively, the shortest unambiguous form of a command is accepted.
6709 If there are several options, they are listed:
6710 .Bd -literal -offset indent
6712 ambiguous command: n, could be: new-session, new-window, next-window
6715 Within an active session, a new window may be created by typing
6725 Windows may be navigated with:
6727 (to select window 0),
6729 (to select window 1), and so on;
6731 to select the next window; and
6733 to select the previous window.
6735 A session may be detached using
6737 (or by an external event such as
6739 disconnection) and reattached with:
6741 .Dl $ tmux attach-session
6745 lists the current key bindings in the current window; up and down may be used
6746 to navigate the list or
6750 Commands to be run when the
6752 server is started may be placed in the
6755 Common examples include:
6757 Changing the default prefix key:
6758 .Bd -literal -offset indent
6759 set-option -g prefix C-a
6761 bind-key C-a send-prefix
6764 Turning the status line off, or changing its colour:
6765 .Bd -literal -offset indent
6766 set-option -g status off
6767 set-option -g status-style bg=blue
6770 Setting other options, such as the default command,
6771 or locking after 30 minutes of inactivity:
6772 .Bd -literal -offset indent
6773 set-option -g default-command "exec /bin/ksh"
6774 set-option -g lock-after-time 1800
6777 Creating new key bindings:
6778 .Bd -literal -offset indent
6779 bind-key b set-option status
6780 bind-key / command-prompt "split-window 'exec man %%'"
6781 bind-key S command-prompt "new-window -n %1 'ssh %1'"
6786 .An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com