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 t Ar target-client
1349 .D1 Pq alias: Ic refresh
1350 Refresh the current client if bound to a key, or a single client if one is given
1355 is specified, only update the client's status line.
1364 flags allow the visible portion of a window which is larger than the client
1367 moves the visible part up by
1379 returns to tracking the cursor automatically.
1382 is omitted, 1 is used.
1383 Note that the visible position is a property of the client not of the
1384 window, changing the current window in the attached session will reset
1388 sets the width and height of a control mode client or of a window for a
1389 control mode client,
1394 .Ql window ID:widthxheight ,
1400 allows a control mode client to trigger actions on a pane.
1401 The argument is a pane ID (with leading
1403 a colon, then one of
1412 will not send output from the pane to the client and if all clients have turned
1413 the pane off, will stop reading from the pane.
1417 will return to sending output to the pane if it was paused (manually or with the
1423 will pause the pane.
1425 may be given multiple times for different panes.
1428 sets a subscription to a format for a control mode client.
1429 The argument is split into three items by colons:
1431 is a name for the subscription;
1433 is a type of item to subscribe to;
1436 After a subscription is added, changes to the format are reported with the
1437 .Ic %subscription-changed
1438 notification, at most once a second.
1439 If only the name is given, the subscription is removed.
1441 may be empty to check the format only for the attached session, or one of:
1445 for all panes in the attached session;
1450 for all windows in the attached session.
1453 sets a comma-separated list of client flags, see
1454 .Ic attach-session .
1457 requests the clipboard from the client using the
1459 escape sequence and stores it in a new paste buffer.
1466 move the visible portion of the window left, right, up or down
1469 if the window is larger than the client.
1471 resets so that the position follows the cursor.
1476 .It Xo Ic rename-session
1477 .Op Fl t Ar target-session
1480 .D1 Pq alias: Ic rename
1481 Rename the session to
1484 .It Xo Ic show-messages
1486 .Op Fl t Ar target-client
1488 .D1 Pq alias: Ic showmsgs
1489 Show server messages or information.
1490 Messages are stored, up to a maximum of the limit set by the
1496 show debugging information about jobs and terminals.
1498 .It Xo Ic source-file
1503 .D1 Pq alias: Ic source
1504 Execute commands from one or more files specified by
1513 is expanded as a format.
1516 is given, no error will be returned if
1521 the file is parsed but no commands are executed.
1523 shows the parsed commands and line numbers if possible.
1526 .D1 Pq alias: Ic start
1529 server, if not already running, without creating any sessions.
1531 Note that as by default the
1533 server will exit with no sessions, this is only useful if a session is created in
1536 is turned off, or another command is run as part of the same command sequence.
1538 .Bd -literal -offset indent
1539 $ tmux start \\; show -g
1542 .It Xo Ic suspend-client
1543 .Op Fl t Ar target-client
1545 .D1 Pq alias: Ic suspendc
1546 Suspend a client by sending
1550 .It Xo Ic switch-client
1552 .Op Fl c Ar target-client
1553 .Op Fl t Ar target-session
1554 .Op Fl T Ar key-table
1556 .D1 Pq alias: Ic switchc
1557 Switch the current session for client
1560 .Ar target-session .
1563 may refer to a pane (a target that contains
1568 to change session, window and pane.
1571 keeps the window zoomed if it was zoomed.
1577 is used, the client is moved to the last, next or previous session
1591 .Ic update-environment
1592 option will not be applied.
1595 sets the client's key table; the next key from the client will be interpreted
1598 This may be used to configure multiple prefix keys, or to bind commands to
1600 For example, to make typing
1605 .Bd -literal -offset indent
1606 bind-key -Ttable2 c list-keys
1607 bind-key -Ttable1 b switch-client -Ttable2
1608 bind-key -Troot a switch-client -Ttable1
1611 .Sh WINDOWS AND PANES
1612 Each window displayed by
1614 may be split into one or more
1616 each pane takes up a certain area of the display and is a separate terminal.
1617 A window may be split into panes using the
1620 Windows may be split horizontally (with the
1622 flag) or vertically.
1623 Panes may be resized with the
1631 by default), the current pane may be changed with the
1637 commands may be used to swap panes without changing their position.
1638 Panes are numbered beginning from zero in the order they are created.
1642 pane permits direct access to the terminal contained in the pane.
1643 A pane may also be put into one of several modes:
1644 .Bl -dash -offset indent
1646 Copy mode, which permits a section of a window or its
1647 history to be copied to a
1649 for later insertion into another window.
1650 This mode is entered with the
1655 Copied text can be pasted with the
1660 View mode, which is like copy mode but is entered when a command that produces
1663 is executed from a key binding.
1665 Choose mode, which allows an item to be chosen from a list.
1666 This may be a client, a session or window or pane, or a buffer.
1667 This mode is entered with the
1675 In copy mode an indicator is displayed in the top-right corner of the pane with
1676 the current position and the number of lines in the history.
1678 Commands are sent to copy mode using the
1683 When a key is pressed, copy mode automatically uses one of two key tables,
1691 Key tables may be viewed with the
1695 The following commands are supported in copy mode:
1696 .Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
1697 .It Sy "Command" Ta Sy "vi" Ta Sy "emacs"
1698 .It Li "append-selection" Ta "" Ta ""
1699 .It Li "append-selection-and-cancel" Ta "A" Ta ""
1700 .It Li "back-to-indentation" Ta "^" Ta "M-m"
1701 .It Li "begin-selection" Ta "Space" Ta "C-Space"
1702 .It Li "bottom-line" Ta "L" Ta ""
1703 .It Li "cancel" Ta "q" Ta "Escape"
1704 .It Li "clear-selection" Ta "Escape" Ta "C-g"
1705 .It Li "copy-end-of-line [<prefix>]" Ta "" Ta ""
1706 .It Li "copy-end-of-line-and-cancel [<prefix>]" Ta "" Ta ""
1707 .It Li "copy-pipe-end-of-line [<command>] [<prefix>]" Ta "" Ta ""
1708 .It Li "copy-pipe-end-of-line-and-cancel [<command>] [<prefix>]" Ta "D" Ta "C-k"
1709 .It Li "copy-line [<prefix>]" Ta "" Ta ""
1710 .It Li "copy-line-and-cancel [<prefix>]" Ta "" Ta ""
1711 .It Li "copy-pipe-line [<command>] [<prefix>]" Ta "" Ta ""
1712 .It Li "copy-pipe-line-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1713 .It Li "copy-pipe [<command>] [<prefix>]" Ta "" Ta ""
1714 .It Li "copy-pipe-no-clear [<command>] [<prefix>]" Ta "" Ta ""
1715 .It Li "copy-pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1716 .It Li "copy-selection [<prefix>]" Ta "" Ta ""
1717 .It Li "copy-selection-no-clear [<prefix>]" Ta "" Ta ""
1718 .It Li "copy-selection-and-cancel [<prefix>]" Ta "Enter" Ta "M-w"
1719 .It Li "cursor-down" Ta "j" Ta "Down"
1720 .It Li "cursor-down-and-cancel" Ta "" Ta ""
1721 .It Li "cursor-left" Ta "h" Ta "Left"
1722 .It Li "cursor-right" Ta "l" Ta "Right"
1723 .It Li "cursor-up" Ta "k" Ta "Up"
1724 .It Li "end-of-line" Ta "$" Ta "C-e"
1725 .It Li "goto-line <line>" Ta ":" Ta "g"
1726 .It Li "halfpage-down" Ta "C-d" Ta "M-Down"
1727 .It Li "halfpage-down-and-cancel" Ta "" Ta ""
1728 .It Li "halfpage-up" Ta "C-u" Ta "M-Up"
1729 .It Li "history-bottom" Ta "G" Ta "M->"
1730 .It Li "history-top" Ta "g" Ta "M-<"
1731 .It Li "jump-again" Ta ";" Ta ";"
1732 .It Li "jump-backward <to>" Ta "F" Ta "F"
1733 .It Li "jump-forward <to>" Ta "f" Ta "f"
1734 .It Li "jump-reverse" Ta "," Ta ","
1735 .It Li "jump-to-backward <to>" Ta "T" Ta ""
1736 .It Li "jump-to-forward <to>" Ta "t" Ta ""
1737 .It Li "jump-to-mark" Ta "M-x" Ta "M-x"
1738 .It Li "middle-line" Ta "M" Ta "M-r"
1739 .It Li "next-matching-bracket" Ta "%" Ta "M-C-f"
1740 .It Li "next-paragraph" Ta "}" Ta "M-}"
1741 .It Li "next-space" Ta "W" Ta ""
1742 .It Li "next-space-end" Ta "E" Ta ""
1743 .It Li "next-word" Ta "w" Ta ""
1744 .It Li "next-word-end" Ta "e" Ta "M-f"
1745 .It Li "other-end" Ta "o" Ta ""
1746 .It Li "page-down" Ta "C-f" Ta "PageDown"
1747 .It Li "page-down-and-cancel" Ta "" Ta ""
1748 .It Li "page-up" Ta "C-b" Ta "PageUp"
1749 .It Li "pipe [<command>] [<prefix>]" Ta "" Ta ""
1750 .It Li "pipe-no-clear [<command>] [<prefix>]" Ta "" Ta ""
1751 .It Li "pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1752 .It Li "previous-matching-bracket" Ta "" Ta "M-C-b"
1753 .It Li "previous-paragraph" Ta "{" Ta "M-{"
1754 .It Li "previous-space" Ta "B" Ta ""
1755 .It Li "previous-word" Ta "b" Ta "M-b"
1756 .It Li "rectangle-on" Ta "" Ta ""
1757 .It Li "rectangle-off" Ta "" Ta ""
1758 .It Li "rectangle-toggle" Ta "v" Ta "R"
1759 .It Li "refresh-from-pane" Ta "r" Ta "r"
1760 .It Li "scroll-down" Ta "C-e" Ta "C-Down"
1761 .It Li "scroll-down-and-cancel" Ta "" Ta ""
1762 .It Li "scroll-up" Ta "C-y" Ta "C-Up"
1763 .It Li "search-again" Ta "n" Ta "n"
1764 .It Li "search-backward <for>" Ta "?" Ta ""
1765 .It Li "search-backward-incremental <for>" Ta "" Ta "C-r"
1766 .It Li "search-backward-text <for>" Ta "" Ta ""
1767 .It Li "search-forward <for>" Ta "/" Ta ""
1768 .It Li "search-forward-incremental <for>" Ta "" Ta "C-s"
1769 .It Li "search-forward-text <for>" Ta "" Ta ""
1770 .It Li "search-reverse" Ta "N" Ta "N"
1771 .It Li "select-line" Ta "V" Ta ""
1772 .It Li "select-word" Ta "" Ta ""
1773 .It Li "set-mark" Ta "X" Ta "X"
1774 .It Li "start-of-line" Ta "0" Ta "C-a"
1775 .It Li "stop-selection" Ta "" Ta ""
1776 .It Li "toggle-position" Ta "P" Ta "P"
1777 .It Li "top-line" Ta "H" Ta "M-R"
1780 The search commands come in several varieties:
1784 search for a regular expression;
1787 variants search for a plain text string rather than a regular expression;
1789 perform an incremental search and expect to be used with the
1795 repeats the last search and
1797 does the same but reverses the direction (forward becomes backward and backward
1800 Copy commands may take an optional buffer prefix argument which is used
1801 to generate the buffer name (the default is
1803 so buffers are named
1807 Pipe commands take a command argument which is the command to which the
1808 selected text is piped.
1810 variants also copy the selection.
1813 variants of some commands exit copy mode after they have completed (for copy
1814 commands) or when the cursor reaches the bottom (for scrolling commands).
1816 variants do not clear the selection.
1818 The next and previous word keys skip over whitespace and treat consecutive
1819 runs of either word separators or other letters as words.
1820 Word separators can be customized with the
1823 Next word moves to the start of the next word, next word end to the end of the
1824 next word and previous word to the start of the previous word.
1825 The three next and previous space keys work similarly but use a space alone as
1829 to the empty string makes next/previous word equivalent to next/previous space.
1831 The jump commands enable quick movement within a line.
1832 For instance, typing
1836 will move the cursor to the next
1838 character on the current line.
1841 will then jump to the next occurrence.
1843 Commands in copy mode may be prefaced by an optional repeat count.
1844 With vi key bindings, a prefix is entered using the number keys; with
1845 emacs, the Alt (meta) key and a number begins prefix entry.
1847 The synopsis for the
1853 .Op Fl s Ar src-pane
1854 .Op Fl t Ar target-pane
1859 option scrolls one page up.
1861 begins a mouse drag (only valid if bound to a mouse key binding, see
1862 .Sx MOUSE SUPPORT ) .
1864 hides the position indicator in the top right.
1866 cancels copy mode and any other modes.
1874 specifies that scrolling to the bottom of the history (to the visible screen)
1875 should exit copy mode.
1876 While in copy mode, pressing a key other than those used for scrolling will
1877 disable this behaviour.
1878 This is intended to allow fast scrolling through a pane's history, for
1880 .Bd -literal -offset indent
1881 bind PageUp copy-mode -eu
1885 A number of preset arrangements of panes are available, these are called layouts.
1886 These may be selected with the
1888 command or cycled with
1892 by default); once a layout is chosen, panes within it may be moved and resized
1895 The following layouts are supported:
1897 .It Ic even-horizontal
1898 Panes are spread out evenly from left to right across the window.
1899 .It Ic even-vertical
1900 Panes are spread evenly from top to bottom.
1901 .It Ic main-horizontal
1902 A large (main) pane is shown at the top of the window and the remaining panes
1903 are spread from left to right in the leftover space at the bottom.
1905 .Em main-pane-height
1906 window option to specify the height of the top pane.
1907 .It Ic main-vertical
1910 but the large pane is placed on the left and the others spread from top to
1911 bottom along the right.
1916 Panes are spread out as evenly as possible over the window in both rows and
1922 may be used to apply a previously used layout - the
1924 command displays the layout of each window in a form suitable for use with
1927 .Bd -literal -offset indent
1930 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1931 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1935 automatically adjusts the size of the layout for the current window size.
1936 Note that a layout cannot be applied to a window with more panes than that
1937 from which the layout was originally defined.
1939 Commands related to windows and panes are as follows:
1942 .It Xo Ic break-pane
1945 .Op Fl n Ar window-name
1946 .Op Fl s Ar src-pane
1947 .Op Fl t Ar dst-window
1949 .D1 Pq alias: Ic breakp
1952 off from its containing window to make it the only pane in
1958 the window is moved to the next index after or before (existing windows are
1959 moved if necessary).
1962 is given, the new window does not become the current window.
1965 option prints information about the new window after it has been created.
1966 By default, it uses the format
1967 .Ql #{session_name}:#{window_index}.#{pane_index}
1968 but a different format may be specified with
1971 .It Xo Ic capture-pane
1973 .Op Fl b Ar buffer-name
1974 .Op Fl E Ar end-line
1975 .Op Fl S Ar start-line
1976 .Op Fl t Ar target-pane
1978 .D1 Pq alias: Ic capturep
1979 Capture the contents of a pane.
1982 is given, the output goes to stdout, otherwise to the buffer specified with
1984 or a new buffer if omitted.
1987 is given, the alternate screen is used, and the history is not accessible.
1988 If no alternate screen exists, an error will be returned unless
1993 is given, the output includes escape sequences for text and background
1996 also escapes non-printable characters as octal \exxx.
1998 preserves trailing spaces at each line's end and
2000 preserves trailing spaces and joins any wrapped lines.
2002 captures only any output that the pane has received that is the beginning of an
2003 as-yet incomplete escape sequence.
2008 specify the starting and ending line numbers, zero is the first line of the
2009 visible pane and negative numbers are lines in the history.
2013 is the start of the history and to
2015 the end of the visible pane.
2016 The default is to capture only the visible contents of the pane.
2022 .Op Fl K Ar key-format
2023 .Op Fl O Ar sort-order
2024 .Op Fl t Ar target-pane
2027 Put a pane into client mode, allowing a client to be selected interactively from
2029 Each client is shown on one line.
2030 A shortcut key is shown on the left in brackets allowing for immediate choice,
2031 or the list may be navigated and an item chosen or otherwise manipulated using
2035 The following keys may be used in client mode:
2036 .Bl -column "Key" "Function" -offset indent
2037 .It Sy "Key" Ta Sy "Function"
2038 .It Li "Enter" Ta "Choose selected client"
2039 .It Li "Up" Ta "Select previous client"
2040 .It Li "Down" Ta "Select next client"
2041 .It Li "C-s" Ta "Search by name"
2042 .It Li "n" Ta "Repeat last search"
2043 .It Li "t" Ta "Toggle if client is tagged"
2044 .It Li "T" Ta "Tag no clients"
2045 .It Li "C-t" Ta "Tag all clients"
2046 .It Li "d" Ta "Detach selected client"
2047 .It Li "D" Ta "Detach tagged clients"
2048 .It Li "x" Ta "Detach and HUP selected client"
2049 .It Li "X" Ta "Detach and HUP tagged clients"
2050 .It Li "z" Ta "Suspend selected client"
2051 .It Li "Z" Ta "Suspend tagged clients"
2052 .It Li "f" Ta "Enter a format to filter items"
2053 .It Li "O" Ta "Change sort field"
2054 .It Li "r" Ta "Reverse sort order"
2055 .It Li "v" Ta "Toggle preview"
2056 .It Li "q" Ta "Exit mode"
2059 After a client is chosen,
2061 is replaced by the client name in
2063 and the result executed as a command.
2066 is not given, "detach-client -t '%%'" is used.
2069 specifies the initial sort field: one of
2076 reverses the sort order.
2078 specifies an initial filter: the filter is a format - if it evaluates to zero,
2079 the item in the list is not shown, otherwise it is shown.
2080 If a filter would lead to an empty list, it is ignored.
2082 specifies the format for each item in the list and
2084 a format for each shortcut key; both are evaluated once for each line.
2086 starts without the preview.
2087 This command works only if at least one client is attached.
2093 .Op Fl K Ar key-format
2094 .Op Fl O Ar sort-order
2095 .Op Fl t Ar target-pane
2098 Put a pane into tree mode, where a session, window or pane may be chosen
2099 interactively from a tree.
2100 Each session, window or pane is shown on one line.
2101 A shortcut key is shown on the left in brackets allowing for immediate choice,
2102 or the tree may be navigated and an item chosen or otherwise manipulated using
2105 starts with sessions collapsed and
2107 with windows collapsed.
2110 The following keys may be used in tree mode:
2111 .Bl -column "Key" "Function" -offset indent
2112 .It Sy "Key" Ta Sy "Function"
2113 .It Li "Enter" Ta "Choose selected item"
2114 .It Li "Up" Ta "Select previous item"
2115 .It Li "Down" Ta "Select next item"
2116 .It Li "+" Ta "Expand selected item"
2117 .It Li "-" Ta "Collapse selected item"
2118 .It Li "M-+" Ta "Expand all items"
2119 .It Li "M--" Ta "Collapse all items"
2120 .It Li "x" Ta "Kill selected item"
2121 .It Li "X" Ta "Kill tagged items"
2122 .It Li "<" Ta "Scroll list of previews left"
2123 .It Li ">" Ta "Scroll list of previews right"
2124 .It Li "C-s" Ta "Search by name"
2125 .It Li "m" Ta "Set the marked pane"
2126 .It Li "M" Ta "Clear the marked pane"
2127 .It Li "n" Ta "Repeat last search"
2128 .It Li "t" Ta "Toggle if item is tagged"
2129 .It Li "T" Ta "Tag no items"
2130 .It Li "C-t" Ta "Tag all items"
2131 .It Li "\&:" Ta "Run a command for each tagged item"
2132 .It Li "f" Ta "Enter a format to filter items"
2133 .It Li "H" Ta "Jump to the starting pane"
2134 .It Li "O" Ta "Change sort field"
2135 .It Li "r" Ta "Reverse sort order"
2136 .It Li "v" Ta "Toggle preview"
2137 .It Li "q" Ta "Exit mode"
2140 After a session, window or pane is chosen, the first instance of
2142 and all instances of
2144 are replaced by the target in
2146 and the result executed as a command.
2149 is not given, "switch-client -t '%%'" is used.
2152 specifies the initial sort field: one of
2158 reverses the sort order.
2160 specifies an initial filter: the filter is a format - if it evaluates to zero,
2161 the item in the list is not shown, otherwise it is shown.
2162 If a filter would lead to an empty list, it is ignored.
2164 specifies the format for each item in the tree and
2166 a format for each shortcut key; both are evaluated once for each line.
2168 starts without the preview.
2170 includes all sessions in any session groups in the tree rather than only the
2172 This command works only if at least one client is attached.
2178 .Op Fl t Ar target-pane
2181 Put a pane into customize mode, where options and key bindings may be browsed
2182 and modified from a list.
2183 Option values in the list are shown for the active pane in the current window.
2186 The following keys may be used in customize mode:
2187 .Bl -column "Key" "Function" -offset indent
2188 .It Sy "Key" Ta Sy "Function"
2189 .It Li "Enter" Ta "Set pane, window, session or global option value"
2190 .It Li "Up" Ta "Select previous item"
2191 .It Li "Down" Ta "Select next item"
2192 .It Li "+" Ta "Expand selected item"
2193 .It Li "-" Ta "Collapse selected item"
2194 .It Li "M-+" Ta "Expand all items"
2195 .It Li "M--" Ta "Collapse all items"
2196 .It Li "s" Ta "Set option value or key attribute"
2197 .It Li "S" Ta "Set global option value"
2198 .It Li "w" Ta "Set window option value, if option is for pane and window"
2199 .It Li "d" Ta "Set an option or key to the default"
2200 .It Li "D" Ta "Set tagged options and tagged keys to the default"
2201 .It Li "u" Ta "Unset an option (set to default value if global) or unbind a key"
2202 .It Li "U" Ta "Unset tagged options and unbind tagged keys"
2203 .It Li "C-s" Ta "Search by name"
2204 .It Li "n" Ta "Repeat last search"
2205 .It Li "t" Ta "Toggle if item is tagged"
2206 .It Li "T" Ta "Tag no items"
2207 .It Li "C-t" Ta "Tag all items"
2208 .It Li "f" Ta "Enter a format to filter items"
2209 .It Li "v" Ta "Toggle option information"
2210 .It Li "q" Ta "Exit mode"
2214 specifies an initial filter: the filter is a format - if it evaluates to zero,
2215 the item in the list is not shown, otherwise it is shown.
2216 If a filter would lead to an empty list, it is ignored.
2218 specifies the format for each item in the tree.
2220 starts without the option information.
2221 This command works only if at least one client is attached.
2226 .Op Fl d Ar duration
2227 .Op Fl t Ar target-client
2230 .D1 Pq alias: Ic displayp
2231 Display a visible indicator of each pane shown by
2234 .Ic display-panes-colour
2236 .Ic display-panes-active-colour
2238 The indicator is closed when a key is pressed (unless
2242 milliseconds have passed.
2246 .Ic display-panes-time
2248 A duration of zero means the indicator stays until a key is pressed.
2249 While the indicator is on screen, a pane may be chosen with the
2253 keys, which will cause
2255 to be executed as a command with
2257 substituted by the pane ID.
2260 is "select-pane -t '%%'".
2263 other commands are not blocked from running until the indicator is closed.
2265 .It Xo Ic find-window
2267 .Op Fl t Ar target-pane
2270 .D1 Pq alias: Ic findw
2277 in window names, titles, and visible content (but not history).
2278 The flags control matching behavior:
2280 matches only visible window contents,
2282 matches only the window name and
2284 matches only the window title.
2286 makes the search ignore case.
2292 This command works only if at least one client is attached.
2297 .Op Fl s Ar src-pane
2298 .Op Fl t Ar dst-pane
2300 .D1 Pq alias: Ic joinp
2303 but instead of splitting
2305 and creating a new pane, split it and move
2308 This can be used to reverse
2314 to be joined to left of or above
2319 is omitted and a marked pane is present (see
2322 the marked pane is used rather than the current pane.
2326 .Op Fl t Ar target-pane
2328 .D1 Pq alias: Ic killp
2329 Destroy the given pane.
2330 If no panes remain in the containing window, it is also destroyed.
2333 option kills all but the pane given with
2336 .It Xo Ic kill-window
2338 .Op Fl t Ar target-window
2340 .D1 Pq alias: Ic killw
2341 Kill the current window or the window at
2343 removing it from any sessions to which it is linked.
2346 option kills all but the window given with
2351 .Op Fl t Ar target-window
2353 .D1 Pq alias: Ic lastp
2354 Select the last (previously selected) pane.
2356 keeps the window zoomed if it was zoomed.
2360 disables input to the pane.
2362 .It Ic last-window Op Fl t Ar target-session
2363 .D1 Pq alias: Ic last
2364 Select the last (previously selected) window.
2367 is specified, select the last window of the current session.
2369 .It Xo Ic link-window
2371 .Op Fl s Ar src-window
2372 .Op Fl t Ar dst-window
2374 .D1 Pq alias: Ic linkw
2381 is specified and no such window exists, the
2388 the window is moved to the next index after or before
2390 (existing windows are moved if necessary).
2395 exists, it is killed, otherwise an error is generated.
2398 is given, the newly linked window is not selected.
2400 .It Xo Ic list-panes
2406 .D1 Pq alias: Ic lsp
2411 is ignored and all panes on the server are listed.
2416 is a session (or the current session).
2417 If neither is given,
2419 is a window (or the current window).
2421 specifies the format of each line and
2424 Only panes for which the filter is true are shown.
2429 .It Xo Ic list-windows
2433 .Op Fl t Ar target-session
2435 .D1 Pq alias: Ic lsw
2438 is given, list all windows on the server.
2439 Otherwise, list windows in the current session or in
2440 .Ar target-session .
2442 specifies the format of each line and
2445 Only windows for which the filter is true are shown.
2453 .Op Fl s Ar src-pane
2454 .Op Fl t Ar dst-pane
2456 .D1 Pq alias: Ic movep
2460 .It Xo Ic move-window
2462 .Op Fl s Ar src-window
2463 .Op Fl t Ar dst-window
2465 .D1 Pq alias: Ic movew
2468 except the window at
2474 all windows in the session are renumbered in sequential order, respecting
2479 .It Xo Ic new-window
2481 .Op Fl c Ar start-directory
2482 .Op Fl e Ar environment
2484 .Op Fl n Ar window-name
2485 .Op Fl t Ar target-window
2486 .Op Ar shell-command
2488 .D1 Pq alias: Ic neww
2489 Create a new window.
2494 the new window is inserted at the next index after or before the specified
2496 moving windows up if necessary;
2499 is the new window location.
2503 is given, the session does not make the new window the current window.
2505 represents the window to be created; if the target already exists an error is
2508 flag is used, in which case it is destroyed.
2511 is given and a window named
2513 already exists, it is selected (unless
2515 is also given in which case the command does nothing).
2518 is the command to execute.
2521 is not specified, the value of the
2525 specifies the working directory in which the new window is created.
2527 When the shell command completes, the window closes.
2530 option to change this behaviour.
2535 and sets an environment variable for the newly created window; it may be
2536 specified multiple times.
2540 environment variable must be set to
2544 for all programs running
2547 New windows will automatically have
2549 added to their environment, but care must be taken not to reset this in shell
2550 start-up files or by the
2556 option prints information about the new window after it has been created.
2557 By default, it uses the format
2558 .Ql #{session_name}:#{window_index}
2559 but a different format may be specified with
2562 .It Ic next-layout Op Fl t Ar target-window
2563 .D1 Pq alias: Ic nextl
2564 Move a window to the next layout and rearrange the panes to fit.
2566 .It Xo Ic next-window
2568 .Op Fl t Ar target-session
2570 .D1 Pq alias: Ic next
2571 Move to the next window in the session.
2574 is used, move to the next window with an alert.
2578 .Op Fl t Ar target-pane
2579 .Op Ar shell-command
2581 .D1 Pq alias: Ic pipep
2582 Pipe output sent by the program in
2584 to a shell command or vice versa.
2585 A pane may only be connected to one command at a time, any existing pipe is
2591 string may contain the special character sequences supported by the
2596 is given, the current pipe (if any) is closed.
2601 specify which of the
2603 output streams are connected to the pane:
2606 stdout is connected (so anything
2608 prints is written to the pane as if it were typed);
2611 stdin is connected (so any output in the pane is piped to
2612 .Ar shell-command ) .
2613 Both may be used together and if neither are specified,
2619 option only opens a new pipe if no previous pipe exists, allowing a pipe to
2620 be toggled with a single key, for example:
2621 .Bd -literal -offset indent
2622 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
2625 .It Xo Ic previous-layout
2626 .Op Fl t Ar target-window
2628 .D1 Pq alias: Ic prevl
2629 Move to the previous layout in the session.
2631 .It Xo Ic previous-window
2633 .Op Fl t Ar target-session
2635 .D1 Pq alias: Ic prev
2636 Move to the previous window in the session.
2639 move to the previous window with an alert.
2641 .It Xo Ic rename-window
2642 .Op Fl t Ar target-window
2645 .D1 Pq alias: Ic renamew
2646 Rename the current window, or the window at
2651 .It Xo Ic resize-pane
2653 .Op Fl t Ar target-pane
2658 .D1 Pq alias: Ic resizep
2659 Resize a pane, up, down, left or right by
2675 is given in lines or columns (the default is 1);
2679 may be a given as a number of lines or columns or followed by
2681 for a percentage of the window size (for example
2685 the active pane is toggled between zoomed (occupying the whole of the window)
2686 and unzoomed (its normal position in the layout).
2689 begins mouse resizing (only valid if bound to a mouse key binding, see
2690 .Sx MOUSE SUPPORT ) .
2693 trims all lines below the current cursor position and moves lines out of the
2694 history to replace them.
2696 .It Xo Ic resize-window
2698 .Op Fl t Ar target-window
2703 .D1 Pq alias: Ic resizew
2704 Resize a window, up, down, left or right by
2720 is given in lines or cells (the default is 1).
2722 sets the size of the largest session containing the window;
2724 the size of the smallest.
2725 This command will automatically set
2727 to manual in the window options.
2729 .It Xo Ic respawn-pane
2731 .Op Fl c Ar start-directory
2732 .Op Fl e Ar environment
2733 .Op Fl t Ar target-pane
2734 .Op Ar shell-command
2736 .D1 Pq alias: Ic respawnp
2737 Reactivate a pane in which the command has exited (see the
2742 is not given, the command used when the pane was created or last respawned is
2744 The pane must be already inactive, unless
2746 is given, in which case any existing command is killed.
2748 specifies a new working directory for the pane.
2751 option has the same meaning as for the
2755 .It Xo Ic respawn-window
2757 .Op Fl c Ar start-directory
2758 .Op Fl e Ar environment
2759 .Op Fl t Ar target-window
2760 .Op Ar shell-command
2762 .D1 Pq alias: Ic respawnw
2763 Reactivate a window in which the command has exited (see the
2768 is not given, the command used when the window was created or last respawned is
2770 The window must be already inactive, unless
2772 is given, in which case any existing command is killed.
2774 specifies a new working directory for the window.
2777 option has the same meaning as for the
2781 .It Xo Ic rotate-window
2783 .Op Fl t Ar target-window
2785 .D1 Pq alias: Ic rotatew
2786 Rotate the positions of the panes within a window, either upward (numerically
2789 or downward (numerically higher).
2791 keeps the window zoomed if it was zoomed.
2793 .It Xo Ic select-layout
2795 .Op Fl t Ar target-pane
2798 .D1 Pq alias: Ic selectl
2799 Choose a specific layout for a window.
2802 is not given, the last preset layout used (if any) is reapplied.
2806 are equivalent to the
2812 applies the last set layout if possible (undoes the most recent layout change).
2814 spreads the current pane and any panes next to it out evenly.
2816 .It Xo Ic select-pane
2819 .Op Fl t Ar target-pane
2821 .D1 Pq alias: Ic selectp
2824 the active pane in its window.
2831 is used, respectively the pane below, to the left, to the right, or above the
2832 target pane is used.
2834 keeps the window zoomed if it was zoomed.
2836 is the same as using the
2842 disables input to the pane.
2844 sets the pane title.
2849 are used to set and clear the
2851 There is one marked pane at a time, setting a new marked pane clears the last.
2852 The marked pane is the default target for
2861 .It Xo Ic select-window
2863 .Op Fl t Ar target-window
2865 .D1 Pq alias: Ic selectw
2866 Select the window at
2872 are equivalent to the
2880 is given and the selected window is already the current window,
2881 the command behaves like
2884 .It Xo Ic split-window
2886 .Op Fl c Ar start-directory
2887 .Op Fl e Ar environment
2889 .Op Fl t Ar target-pane
2890 .Op Ar shell-command
2893 .D1 Pq alias: Ic splitw
2894 Create a new pane by splitting
2897 does a horizontal split and
2899 a vertical split; if neither is specified,
2904 option specifies the size of the new pane in lines (for vertical split) or in
2905 columns (for horizontal split);
2909 to specify a percentage of the available space.
2912 option causes the new pane to be created to the left of or above
2916 option creates a new pane spanning the full window height (with
2918 or full window width (with
2920 instead of splitting the active pane.
2922 zooms if the window is not zoomed, or keeps it zoomed if already zoomed.
2926 ('') will create a pane with no command running in it.
2927 Output can be sent to such a pane with the
2934 is not specified or empty)
2935 will create an empty pane and forward any output from stdin to it.
2937 .Bd -literal -offset indent
2938 $ make 2>&1|tmux splitw -dI &
2941 All other options have the same meaning as for the
2947 .Op Fl s Ar src-pane
2948 .Op Fl t Ar dst-pane
2950 .D1 Pq alias: Ic swapp
2954 is used and no source pane is specified with
2957 is swapped with the previous pane (before it numerically);
2959 swaps with the next pane (after it numerically).
2963 not to change the active pane and
2965 keeps the window zoomed if it was zoomed.
2969 is omitted and a marked pane is present (see
2972 the marked pane is used rather than the current pane.
2974 .It Xo Ic swap-window
2976 .Op Fl s Ar src-window
2977 .Op Fl t Ar dst-window
2979 .D1 Pq alias: Ic swapw
2982 except the source and destination windows are swapped.
2983 It is an error if no window exists at
2987 is given, the new window does not become the current window.
2991 is omitted and a marked pane is present (see
2994 the window containing the marked pane is used rather than the current window.
2996 .It Xo Ic unlink-window
2998 .Op Fl t Ar target-window
3000 .D1 Pq alias: Ic unlinkw
3005 is given, a window may be unlinked only if it is linked to multiple sessions -
3006 windows may not be linked to no sessions;
3009 is specified and the window is linked to only one session, it is unlinked and
3014 allows a command to be bound to most keys, with or without a prefix key.
3015 When specifying keys, most represent themselves (for example
3019 Ctrl keys may be prefixed with
3027 In addition, the following special key names are accepted:
3045 .Em NPage/PageDown/PgDn ,
3046 .Em PPage/PageUp/PgUp ,
3050 Note that to bind the
3054 keys, quotation marks are necessary, for example:
3055 .Bd -literal -offset indent
3056 bind-key '"' split-window
3057 bind-key "'" new-window
3060 A command bound to the
3062 key will execute for all keys which do not have a more specific binding.
3064 Commands related to key bindings are as follows:
3070 .Op Fl T Ar key-table
3071 .Ar key command Op Ar arguments
3073 .D1 Pq alias: Ic bind
3078 Keys are bound in a key table.
3079 By default (without -T), the key is bound in
3083 This table is used for keys pressed after the prefix key (for example,
3092 creates a new window).
3095 table is used for keys pressed without the prefix key: binding
3101 table (not recommended) means a plain
3103 will create a new window.
3108 Keys may also be bound in custom key tables and the
3111 command used to switch to them from a key binding.
3114 flag indicates this key may repeat, see the
3118 attaches a note to the key (shown with
3122 To view the default bindings and possible commands, see the
3128 .Op Fl P Ar prefix-string Fl T Ar key-table
3131 .D1 Pq alias: Ic lsk
3133 There are two forms: the default lists keys as
3137 lists only keys with attached notes and shows only the key and note for each
3140 With the default form, all key tables are listed by default.
3147 form, only keys in the
3151 key tables are listed by default;
3153 also lists only keys in
3156 specifies a prefix to print before each key and
3158 lists only the first matching key.
3160 lists the command for keys that do not have a note rather than skipping them.
3164 .Op Fl N Ar repeat-count
3165 .Op Fl t Ar target-pane
3168 .D1 Pq alias: Ic send
3169 Send a key or keys to a window.
3172 is the name of the key (such as
3176 to send; if the string is not recognised as a key, it is sent as a series of
3178 All arguments are sent sequentially from first to last.
3179 If no keys are given and the command is bound to a key, then that key is used.
3183 flag disables key name lookup and processes the keys as literal UTF-8
3187 flag expects each key to be a hexadecimal number for an ASCII character.
3191 flag causes the terminal state to be reset.
3194 passes through a mouse event (only valid if bound to a mouse key binding, see
3195 .Sx MOUSE SUPPORT ) .
3198 is used to send a command into copy mode - see
3200 .Sx WINDOWS AND PANES
3203 specifies a repeat count and
3205 expands formats in arguments where appropriate.
3206 .It Xo Ic send-prefix
3208 .Op Fl t Ar target-pane
3210 Send the prefix key, or with
3212 the secondary prefix key, to a window as if it was pressed.
3214 .It Xo Ic unbind-key
3216 .Op Fl T Ar key-table
3219 .D1 Pq alias: Ic unbind
3220 Unbind the command bound to
3229 is present, all key bindings are removed.
3232 option prevents errors being returned.
3235 The appearance and behaviour of
3237 may be modified by changing the value of various options.
3238 There are four types of option:
3239 .Em server options ,
3240 .Em session options ,
3241 .Em window options ,
3247 server has a set of global server options which do not apply to any particular
3248 window or session or pane.
3249 These are altered with the
3252 command, or displayed with the
3257 In addition, each individual session may have a set of session options, and
3258 there is a separate set of global session options.
3259 Sessions which do not have a particular option configured inherit the value
3260 from the global session options.
3261 Session options are set or unset with the
3263 command and may be listed with the
3266 The available server and session options are listed under the
3270 Similarly, a set of window options is attached to each window and a set of pane
3271 options to each pane.
3272 Pane options inherit from window options.
3273 This means any pane option may be set as a window option to apply the option to
3274 all panes in the window without the option set, for example these commands will
3275 set the background colour to red for all panes except pane 0:
3276 .Bd -literal -offset indent
3277 set -w window-style bg=red
3278 set -pt:.0 window-style bg=blue
3281 There is also a set of global window options from which any unset window or
3282 pane options are inherited.
3283 Window and pane options are altered with
3288 commands and displayed with
3295 also supports user options which are prefixed with a
3297 User options may have any name, so long as they are prefixed with
3299 and be set to any string.
3301 .Bd -literal -offset indent
3302 $ tmux set -wq @foo "abc123"
3303 $ tmux show -wv @foo
3307 Commands which set options are as follows:
3310 .It Xo Ic set-option
3312 .Op Fl t Ar target-pane
3315 .D1 Pq alias: Ic set
3316 Set a pane option with
3318 a window option with
3320 a server option with
3322 otherwise a session option.
3323 If the option is not a user option,
3327 may be unnecessary -
3329 will infer the type from the option name, assuming
3334 is given, the global session or window option is set.
3337 expands formats in the option value.
3340 flag unsets an option, so a session inherits the option from the global
3343 restores a global option to the default).
3345 unsets an option (like
3347 but if the option is a pane option also unsets the option on any panes in the
3350 depends on the option and may be a number, a string, or a flag (on, off, or
3355 flag prevents setting an option that is already set and the
3357 flag suppresses errors about unknown or ambiguous options.
3361 and if the option expects a string or a style,
3363 is appended to the existing setting.
3365 .Bd -literal -offset indent
3366 set -g status-left "foo"
3367 set -ag status-left "bar"
3373 .Bd -literal -offset indent
3374 set -g status-style "bg=red"
3375 set -ag status-style "fg=blue"
3378 Will result in a red background
3383 the result would be the default background and a blue foreground.
3385 .It Xo Ic show-options
3387 .Op Fl t Ar target-pane
3390 .D1 Pq alias: Ic show
3391 Show the pane options (or a single option if
3395 the window options with
3397 the server options with
3399 otherwise the session options.
3400 If the option is not a user option,
3404 may be unnecessary -
3406 will infer the type from the option name, assuming
3409 Global session or window options are listed if
3413 shows only the option value, not the name.
3416 is set, no error will be returned if
3420 includes hooks (omitted by default).
3422 includes options inherited from a parent set of options, such options are
3423 marked with an asterisk.
3426 Available server options are:
3428 .It Ic backspace Ar key
3432 .It Ic buffer-limit Ar number
3433 Set the number of buffers; as new buffers are added to the top of the stack,
3434 old ones are removed from the bottom if necessary to maintain this maximum
3436 .It Xo Ic command-alias[]
3439 This is an array of custom aliases for commands.
3440 If an unknown command matches
3446 .Dl set -s command-alias[100] zoom='resize-pane -Z'
3454 .Dl resize-pane -Z -t:.1
3456 Note that aliases are expanded when a command is parsed rather than when it is
3457 executed, so binding an alias with
3459 will bind the expanded form.
3460 .It Ic default-terminal Ar terminal
3461 Set the default terminal for new windows created in this session - the
3462 default value of the
3464 environment variable.
3467 to work correctly, this
3472 or a derivative of them.
3473 .It Ic copy-command Ar shell-command
3474 Give the command to pipe to if the
3476 copy mode command is used without arguments.
3477 .It Ic escape-time Ar time
3478 Set the time in milliseconds for which
3480 waits after an escape is input to determine if it is part of a function or meta
3482 The default is 500 milliseconds.
3483 .It Ic editor Ar shell-command
3484 Set the command used when
3487 .It Xo Ic exit-empty
3490 If enabled (the default), the server will exit when there are no active
3492 .It Xo Ic exit-unattached
3495 If enabled, the server will exit when there are no attached clients.
3496 .It Xo Ic extended-keys
3497 .Op Ic on | off | always
3503 the escape sequence to enable extended keys is sent to the terminal, if
3505 knows that it is supported.
3507 always recognises extended keys itself.
3511 will only forward extended keys to applications when they request them; if
3514 will always forward the keys.
3515 .It Xo Ic focus-events
3518 When enabled, focus events are requested from the terminal if supported and
3519 passed through to applications running in
3521 Attached clients should be detached and attached again after changing this
3523 .It Ic history-file Ar path
3524 If not empty, a file to which
3526 will write command prompt history on exit and load it from on start.
3527 .It Ic message-limit Ar number
3528 Set the number of error or information messages to save in the message log for
3530 .It Ic prompt-history-limit Ar number
3531 Set the number of history items to save in the history file for each type of
3533 .It Xo Ic set-clipboard
3534 .Op Ic on | external | off
3536 Attempt to set the terminal clipboard content using the
3538 escape sequence, if there is an
3542 description (see the
3543 .Sx TERMINFO EXTENSIONS
3549 will both accept the escape sequence to create a buffer and attempt to set
3550 the terminal clipboard.
3554 will attempt to set the terminal clipboard but ignore attempts
3555 by applications to set
3561 will neither accept the clipboard escape sequence nor attempt to set the
3564 Note that this feature needs to be enabled in
3566 by setting the resource:
3567 .Bd -literal -offset indent
3568 disallowedWindowOps: 20,21,SetXprop
3571 Or changing this property from the
3573 interactive menu when required.
3574 .It Ic terminal-features[] Ar string
3575 Set terminal features for terminal types read from
3578 has a set of named terminal features.
3579 Each will apply appropriate changes to the
3584 can detect features for a few common terminals; this option can be used to
3585 easily tell tmux about features supported by terminals it cannot detect.
3587 .Ic terminal-overrides
3588 option allows individual
3590 capabilities to be set instead,
3591 .Ic terminal-features
3592 is intended for classes of functionality supported in a standard way but not
3595 Care must be taken to configure this only with features the terminal actually
3598 This is an array option where each entry is a colon-separated string made up
3599 of a terminal type pattern (matched using
3601 followed by a list of terminal features.
3602 The available features are:
3605 Supports 256 colours with the SGR escape sequences.
3607 Allows setting the system clipboard.
3609 Allows setting the cursor colour.
3611 Allows setting the cursor style.
3613 Supports extended keys.
3615 Supports focus reporting.
3617 Supports DECSLRM margins.
3623 Supports the overline SGR attribute.
3625 Supports the DECFRA rectangle fill escape sequence.
3627 Supports RGB colour with the SGR escape sequences.
3629 Supports the strikethrough SGR escape sequence.
3631 Supports synchronized updates.
3637 Allows underscore style and colour to be set.
3639 .It Ic terminal-overrides[] Ar string
3640 Allow terminal descriptions read using
3643 Each entry is a colon-separated string made up of a terminal type pattern
3650 For example, to set the
3655 for all terminal types matching
3658 .Dl "rxvt*:clear=\ee[H\ee[2J"
3660 The terminal entry value is passed through
3662 before interpretation.
3663 .It Ic user-keys[] Ar key
3664 Set list of user-defined key escape sequences.
3665 Each item is associated with a key named
3671 .Bd -literal -offset indent
3672 set -s user-keys[0] "\ee[5;30012~"
3673 bind User0 resize-pane -L 3
3677 Available session options are:
3679 .It Xo Ic activity-action
3680 .Op Ic any | none | current | other
3682 Set action on window activity when
3683 .Ic monitor-activity
3686 means activity in any window linked to a session causes a bell or message
3688 .Ic visual-activity )
3689 in the current window of that session,
3691 means all activity is ignored (equivalent to
3692 .Ic monitor-activity
3695 means only activity in windows other than the current window are ignored and
3697 means activity in the current window is ignored but not those in other windows.
3698 .It Ic assume-paste-time Ar milliseconds
3699 If keys are entered faster than one in
3701 they are assumed to have been pasted rather than typed and
3703 key bindings are not processed.
3704 The default is one millisecond and zero disables.
3705 .It Ic base-index Ar index
3706 Set the base index from which an unused index should be searched when a new
3708 The default is zero.
3709 .It Xo Ic bell-action
3710 .Op Ic any | none | current | other
3712 Set action on a bell in a window when
3715 The values are the same as those for
3716 .Ic activity-action .
3717 .It Ic default-command Ar shell-command
3718 Set the command used for new windows (if not specified when the window is
3724 The default is an empty string, which instructs
3726 to create a login shell using the value of the
3729 .It Ic default-shell Ar path
3730 Specify the default shell.
3731 This is used as the login shell for new windows when the
3733 option is set to empty, and must be the full path of the executable.
3736 tries to set a default value from the first suitable of the
3738 environment variable, the shell returned by
3742 This option should be configured when
3744 is used as a login shell.
3745 .It Ic default-size Ar XxY
3746 Set the default size of new windows when the
3748 option is set to manual or when a session is created with
3751 The value is the width and height separated by an
3754 The default is 80x24.
3755 .It Xo Ic destroy-unattached
3758 If enabled and the session is no longer attached to any clients, it is
3760 .It Xo Ic detach-on-destroy
3761 .Op Ic off | on | no-detached
3763 If on (the default), the client is detached when the session it is attached to
3765 If off, the client is switched to the most recently active of the remaining
3769 the client is detached only if there are no detached sessions; if detached
3770 sessions exist, the client is switched to the most recently active.
3771 .It Ic display-panes-active-colour Ar colour
3772 Set the colour used by the
3774 command to show the indicator for the active pane.
3775 .It Ic display-panes-colour Ar colour
3776 Set the colour used by the
3778 command to show the indicators for inactive panes.
3779 .It Ic display-panes-time Ar time
3780 Set the time in milliseconds for which the indicators shown by the
3783 .It Ic display-time Ar time
3784 Set the amount of time for which status line messages and other on-screen
3785 indicators are displayed.
3786 If set to 0, messages and indicators are displayed until a key is pressed.
3789 .It Ic history-limit Ar lines
3790 Set the maximum number of lines held in window history.
3791 This setting applies only to new windows - existing window histories are not
3792 resized and retain the limit at the point they were created.
3793 .It Ic key-table Ar key-table
3794 Set the default key table to
3798 .It Ic lock-after-time Ar number
3799 Lock the session (like the
3803 seconds of inactivity.
3804 The default is not to lock (set to 0).
3805 .It Ic lock-command Ar shell-command
3806 Command to run when locking each client.
3807 The default is to run
3811 .It Ic message-command-style Ar style
3812 Set status line message command style.
3813 This is used for the command prompt with
3815 keys when in command mode.
3821 .It Ic message-style Ar style
3822 Set status line message style.
3823 This is used for messages and for the command prompt.
3834 captures the mouse and allows mouse events to be bound as key bindings.
3837 section for details.
3838 .It Ic prefix Ar key
3839 Set the key accepted as a prefix key.
3840 In addition to the standard keys described under
3843 can be set to the special key
3846 .It Ic prefix2 Ar key
3847 Set a secondary key accepted as a prefix key.
3853 .It Xo Ic renumber-windows
3856 If on, when a window is closed in a session, automatically renumber the other
3857 windows in numerical order.
3860 option if it has been set.
3861 If off, do not renumber the windows.
3862 .It Ic repeat-time Ar time
3863 Allow multiple commands to be entered without pressing the prefix-key again
3866 milliseconds (the default is 500).
3867 Whether a key repeats may be set when it is bound using the
3871 Repeat is enabled for the default keys bound to the
3874 .It Xo Ic set-titles
3877 Attempt to set the client terminal title using the
3882 entries if they exist.
3884 automatically sets these to the \ee]0;...\e007 sequence if
3885 the terminal appears to be
3887 This option is off by default.
3888 .It Ic set-titles-string Ar string
3889 String used to set the client terminal title if
3892 Formats are expanded, see the
3895 .It Xo Ic silence-action
3896 .Op Ic any | none | current | other
3898 Set action on window silence when
3901 The values are the same as those for
3902 .Ic activity-action .
3904 .Op Ic off | on | 2 | 3 | 4 | 5
3906 Show or hide the status line or specify its size.
3909 gives a status line one row in height;
3916 .It Ic status-format[] Ar format
3917 Specify the format to be used for each line of the status line.
3918 The default builds the top status line from the various individual status
3920 .It Ic status-interval Ar interval
3921 Update the status line every
3924 By default, updates will occur every 15 seconds.
3925 A setting of zero disables redrawing at interval.
3926 .It Xo Ic status-justify
3927 .Op Ic left | centre | right | absolute-centre
3929 Set the position of the window list in the status line: left, centre or right.
3930 centre puts the window list in the relative centre of the available free space;
3931 absolute-centre uses the centre of the entire horizontal space.
3932 .It Xo Ic status-keys
3935 Use vi or emacs-style
3936 key bindings in the status line, for example at the command prompt.
3937 The default is emacs, unless the
3941 environment variables are set and contain the string
3943 .It Ic status-left Ar string
3946 (by default the session name) to the left of the status line.
3948 will be passed through
3956 For details on how the names and titles can be set see the
3957 .Sx "NAMES AND TITLES"
3961 .Bd -literal -offset indent
3962 #(sysctl vm.loadavg)
3963 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
3968 .It Ic status-left-length Ar length
3971 of the left component of the status line.
3973 .It Ic status-left-style Ar style
3974 Set the style of the left part of the status line.
3980 .It Xo Ic status-position
3983 Set the position of the status line.
3984 .It Ic status-right Ar string
3987 to the right of the status line.
3988 By default, the current pane title in double quotes, the date and the time
3995 and character pairs are replaced.
3996 .It Ic status-right-length Ar length
3999 of the right component of the status line.
4001 .It Ic status-right-style Ar style
4002 Set the style of the right part of the status line.
4008 .It Ic status-style Ar style
4009 Set status line style.
4015 .It Ic update-environment[] Ar variable
4016 Set list of environment variables to be copied into the session environment
4017 when a new session is created or an existing session is attached.
4018 Any variables that do not exist in the source environment are set to be
4019 removed from the session environment (as if
4024 .It Xo Ic visual-activity
4025 .Op Ic on | off | both
4027 If on, display a message instead of sending a bell when activity occurs in a
4028 window for which the
4029 .Ic monitor-activity
4030 window option is enabled.
4031 If set to both, a bell and a message are produced.
4032 .It Xo Ic visual-bell
4033 .Op Ic on | off | both
4035 If on, a message is shown on a bell in a window for which the
4037 window option is enabled instead of it being passed through to the
4038 terminal (which normally makes a sound).
4039 If set to both, a bell and a message are produced.
4043 .It Xo Ic visual-silence
4044 .Op Ic on | off | both
4048 is enabled, prints a message after the interval has expired on a given window
4049 instead of sending a bell.
4050 If set to both, a bell and a message are produced.
4051 .It Ic word-separators Ar string
4052 Sets the session's conception of what characters are considered word
4053 separators, for the purposes of the next and previous word commands in
4057 Available window options are:
4059 .Bl -tag -width Ds -compact
4060 .It Xo Ic aggressive-resize
4063 Aggressively resize the chosen window.
4066 will resize the window to the size of the smallest or largest session
4069 option) for which it is the current window, rather than the session to
4070 which it is attached.
4071 The window may resize when the current window is changed on another
4072 session; this option is good for full-screen programs which support
4074 and poor for interactive programs such as shells.
4076 .It Xo Ic automatic-rename
4079 Control automatic window renaming.
4080 When this setting is enabled,
4082 will rename the window automatically using the format specified by
4083 .Ic automatic-rename-format .
4084 This flag is automatically disabled for an individual window when a name
4085 is specified at creation with
4091 or with a terminal escape sequence.
4092 It may be switched off globally with:
4093 .Bd -literal -offset indent
4094 set-option -wg automatic-rename off
4097 .It Ic automatic-rename-format Ar format
4101 .Ic automatic-rename
4104 .It Ic clock-mode-colour Ar colour
4107 .It Xo Ic clock-mode-style
4110 Set clock hour format.
4112 .It Ic main-pane-height Ar height
4113 .It Ic main-pane-width Ar width
4114 Set the width or height of the main (left or top) pane in the
4121 this is a percentage of the window size.
4123 .It Ic copy-mode-match-style Ar style
4124 Set the style of search matches in copy mode.
4131 .It Ic copy-mode-mark-style Ar style
4132 Set the style of the line containing the mark in copy mode.
4139 .It Ic copy-mode-current-match-style Ar style
4140 Set the style of the current search match in copy mode.
4150 Use vi or emacs-style key bindings in copy mode.
4151 The default is emacs, unless
4158 .It Ic mode-style Ar style
4159 Set window modes style.
4166 .It Xo Ic monitor-activity
4169 Monitor for activity in the window.
4170 Windows with activity are highlighted in the status line.
4172 .It Xo Ic monitor-bell
4175 Monitor for a bell in the window.
4176 Windows with a bell are highlighted in the status line.
4178 .It Xo Ic monitor-silence
4181 Monitor for silence (no activity) in the window within
4184 Windows that have been silent for the interval are highlighted in the
4186 An interval of zero disables the monitoring.
4188 .It Ic other-pane-height Ar height
4189 Set the height of the other panes (not the main pane) in the
4192 If this option is set to 0 (the default), it will have no effect.
4194 .Ic main-pane-height
4196 .Ic other-pane-height
4197 options are set, the main pane will grow taller to make the other panes the
4198 specified height, but will never shrink to do so.
4201 this is a percentage of the window size.
4203 .It Ic other-pane-width Ar width
4205 .Ic other-pane-height ,
4206 but set the width of other panes in the
4210 .It Ic pane-active-border-style Ar style
4211 Set the pane border style for the currently active pane.
4217 Attributes are ignored.
4219 .It Ic pane-base-index Ar index
4222 but set the starting index for pane numbers.
4224 .It Ic pane-border-format Ar format
4225 Set the text shown in pane border status lines.
4227 .It Xo Ic pane-border-indicators
4228 .Op Ic off | colour | arrows | both
4230 Indicate active pane by colouring only half of the border in windows with
4231 exactly two panes, by displaying arrow markers, by drawing both or neither.
4233 .It Ic pane-border-lines Ar type
4234 Set the type of characters used for drawing pane borders.
4239 single lines using ACS or UTF-8 characters
4241 double lines using UTF-8 characters
4243 heavy lines using UTF-8 characters
4245 simple ASCII characters
4253 will fall back to standard ACS line drawing when UTF-8 is not supported.
4255 .It Xo Ic pane-border-status
4256 .Op Ic off | top | bottom
4258 Turn pane border status lines off or set their position.
4260 .It Ic pane-border-style Ar style
4261 Set the pane border style for panes aside from the active pane.
4267 Attributes are ignored.
4269 .It Ic popup-style Ar style
4270 Set the popup style.
4276 Attributes are ignored.
4278 .It Ic popup-border-style Ar style
4279 Set the popup border style.
4285 Attributes are ignored.
4287 .It Ic popup-border-lines Ar type
4288 Set the type of characters used for drawing popup borders.
4293 single lines using ACS or UTF-8 characters (default)
4295 variation of single with rounded corners using UTF-8 characters
4297 double lines using UTF-8 characters
4299 heavy lines using UTF-8 characters
4301 simple ASCII characters
4303 simple ASCII space character
4311 will fall back to standard ACS line drawing when UTF-8 is not supported.
4313 .It Ic window-status-activity-style Ar style
4314 Set status line style for windows with an activity alert.
4321 .It Ic window-status-bell-style Ar style
4322 Set status line style for windows with a bell alert.
4329 .It Ic window-status-current-format Ar string
4331 .Ar window-status-format ,
4332 but is the format used when the window is the current window.
4334 .It Ic window-status-current-style Ar style
4335 Set status line style for the currently active window.
4342 .It Ic window-status-format Ar string
4343 Set the format in which the window is displayed in the status line window list.
4350 .It Ic window-status-last-style Ar style
4351 Set status line style for the last active window.
4358 .It Ic window-status-separator Ar string
4359 Sets the separator drawn between windows in the status line.
4360 The default is a single space character.
4362 .It Ic window-status-style Ar style
4363 Set status line style for a single window.
4370 .It Xo Ic window-size
4371 .Ar largest | Ar smallest | Ar manual | Ar latest
4375 determines the window size.
4378 the size of the largest attached session is used; if
4380 the size of the smallest.
4383 the size of a new window is set from the
4385 option and windows are resized automatically.
4389 uses the size of the client that had the most recent activity.
4393 .Ic aggressive-resize
4396 .It Xo Ic wrap-search
4399 If this option is set, searches will wrap around the end of the pane contents.
4403 Available pane options are:
4405 .Bl -tag -width Ds -compact
4406 .It Xo Ic allow-rename
4409 Allow programs in the pane to change the window name using a terminal escape
4410 sequence (\eek...\ee\e\e).
4412 .It Xo Ic alternate-screen
4415 This option configures whether programs running inside the pane may use the
4416 terminal alternate screen feature, which allows the
4422 The alternate screen feature preserves the contents of the window when an
4423 interactive application starts and restores it on exit, so that any output
4424 visible before the application starts reappears unchanged after it exits.
4426 .It Ic cursor-colour Ar colour
4427 Set the colour of the cursor.
4429 .It Ic pane-colours[] Ar colour
4430 The default colour palette.
4431 Each entry in the array defines the colour
4433 uses when the colour with that index is requested.
4434 The index may be from zero to 255.
4436 .It Ic cursor-style Ar style
4437 Set the style of the cursor.
4438 Available styles are:
4440 .Ic blinking-block ,
4442 .Ic blinking-underline ,
4447 .It Xo Ic remain-on-exit
4448 .Op Ic on | off | failed
4450 A pane with this flag set is not destroyed when the program running in it
4454 then only when the program exit status is not zero.
4455 The pane may be reactivated with the
4459 .It Xo Ic synchronize-panes
4462 Duplicate input to all other panes in the same window where this option is also
4463 on (only for panes that are not in any mode).
4465 .It Ic window-active-style Ar style
4466 Set the pane style when it is the active pane.
4473 .It Ic window-style Ar style
4483 allows commands to run on various triggers, called
4489 hook and there are a number of hooks not associated with commands.
4491 Hooks are stored as array options, members of the array are executed in
4492 order when the hook is triggered.
4493 Like options different hooks may be global or belong to a session, window or pane.
4494 Hooks may be configured with the
4498 commands and displayed with
4503 The following two commands are equivalent:
4504 .Bd -literal -offset indent.
4505 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
4506 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
4509 Setting a hook without specifying an array index clears the hook and sets the
4510 first member of the array.
4513 hook is run after it completes, except when the command is run as part of a hook
4515 They are named with an
4518 For example, the following command adds a hook to select the even-vertical
4521 .Bd -literal -offset indent
4522 set-hook -g after-split-window "selectl even-vertical"
4525 All the notifications listed in the
4527 section are hooks (without any arguments), except
4529 The following additional hooks are available:
4530 .Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX"
4532 Run when a window has activity.
4534 .Ic monitor-activity .
4536 Run when a window has received a bell.
4540 Run when a window has been silent.
4542 .Ic monitor-silence .
4544 Run when a client becomes the latest active client of its session.
4546 Run when a client is attached.
4548 Run when a client is detached
4550 Run when focus enters a client
4551 .It client-focus-out
4552 Run when focus exits a client
4554 Run when a client is resized.
4555 .It client-session-changed
4556 Run when a client's attached session is changed.
4558 Run when the program running in a pane exits, but
4560 is on so the pane has not closed.
4562 Run when the program running in a pane exits.
4564 Run when the focus enters a pane, if the
4568 Run when the focus exits a pane, if the
4571 .It pane-set-clipboard
4572 Run when the terminal clipboard is set using the
4576 Run when a new session created.
4578 Run when a session closed.
4580 Run when a session is renamed.
4582 Run when a window is linked into a session.
4584 Run when a window is renamed.
4586 Run when a window is unlinked from a session.
4589 Hooks are managed with these commands:
4593 .Op Fl t Ar target-pane
4605 The flags are the same as for
4613 .It Xo Ic show-hooks
4615 .Op Fl t Ar target-pane
4618 The flags are the same as for
4624 option is on (the default is off),
4626 allows mouse events to be bound as keys.
4627 The name of each key is made up of a mouse event (such as
4629 and a location suffix, one of the following:
4630 .Bl -column "XXXXXXXXXXXXX" -offset indent
4631 .It Li "Pane" Ta "the contents of a pane"
4632 .It Li "Border" Ta "a pane border"
4633 .It Li "Status" Ta "the status line window list"
4634 .It Li "StatusLeft" Ta "the left part of the status line"
4635 .It Li "StatusRight" Ta "the right part of the status line"
4636 .It Li "StatusDefault" Ta "any other part of the status line"
4639 The following mouse events are available:
4640 .Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
4641 .It Li "WheelUp" Ta "WheelDown" Ta ""
4642 .It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
4643 .It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
4644 .It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
4645 .It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3"
4646 .It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3"
4647 .It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3"
4652 events are fired for the second click of a double click, even if there may be a
4653 third click which will fire
4658 Each should be suffixed with a location, for example
4659 .Ql MouseDown1Status .
4669 in commands bound to mouse key bindings.
4670 It resolves to the window or pane over which the mouse event took place
4671 (for example, the window in the status line over which button 1 was released for a
4673 binding, or the pane over which the wheel was scrolled for a
4680 flag may be used to forward a mouse event to a pane.
4682 The default key bindings allow the mouse to be used to select and resize panes,
4683 to copy text and to change window using the status line.
4684 These take effect if the
4686 option is turned on.
4688 Certain commands accept the
4693 This is a string which controls the output format of the command.
4694 Format variables are enclosed in
4699 .Ql #{session_name} .
4700 The possible variables are listed in the table below, or the name of a
4702 option may be used for an option's value.
4703 Some variables have a shorter alias such as
4706 is replaced by a single
4716 Conditionals are available by prefixing with
4718 and separating two alternatives with a comma;
4719 if the specified variable exists and is not zero, the first alternative
4720 is chosen, otherwise the second is used.
4722 .Ql #{?session_attached,attached,not attached}
4723 will include the string
4725 if the session is attached and the string
4727 if it is unattached, or
4728 .Ql #{?automatic-rename,yes,no}
4732 .Ic automatic-rename
4736 Conditionals can be nested arbitrarily.
4737 Inside a conditional,
4745 unless they are part of a
4749 .Bd -literal -offset indent
4750 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
4753 String comparisons may be expressed by prefixing two comma-separated
4764 .Ql #{==:#{host},myhost}
4774 evaluate to true if either or both of two comma-separated alternatives are
4776 .Ql #{||:#{pane_in_mode},#{alternate_on}} .
4782 or regular expression comparison.
4783 The first argument is the pattern and the second the string to compare.
4784 An optional argument specifies flags:
4786 means the pattern is a regular expression instead of the default
4790 means to ignore case.
4792 .Ql #{m:*foo*,#{host}}
4794 .Ql #{m/ri:^A,MYVAR} .
4797 performs a search for an
4799 pattern or regular expression in the pane content and evaluates to zero if not
4800 found, or a line number if found.
4805 flag means search for a regular expression and
4811 Numeric operators may be performed by prefixing two comma-separated alternatives with an
4816 flag may be given after the operator to use floating point numbers, otherwise integers are used.
4817 This may be followed by a number giving the number of decimal places to use for the result.
4818 The available operators are:
4835 in formats which are also expanded by
4837 and numeric comparison operators
4846 .Ql #{e|*|f|4:5.5,3}
4847 multiplies 5.5 by 3 for a result with four decimal places and
4849 returns the modulus of 7 and 3.
4851 replaces a numeric argument by its ASCII equivalent, so
4858 colour by its six-digit hexadecimal RGB value.
4860 A limit may be placed on the length of the resultant string by prefixing it
4863 a number and a colon.
4864 Positive numbers count from the start of the string and negative from the end,
4866 .Ql #{=5:pane_title}
4867 will include at most the first five characters of the pane title, or
4868 .Ql #{=-5:pane_title}
4869 the last five characters.
4870 A suffix or prefix may be given as a second argument - if provided then it is
4871 appended or prepended to the string if the length has been trimmed, for example
4872 .Ql #{=/5/...:pane_title}
4875 if the pane title is more than five characters.
4878 pads the string to a given width, for example
4879 .Ql #{p10:pane_title}
4880 will result in a width of at least 10 characters.
4881 A positive width pads on the left, a negative on the right.
4883 expands to the length of the variable and
4885 to its width when displayed, for example
4886 .Ql #{n:window_name} .
4888 Prefixing a time variable with
4890 will convert it to a string, so if
4891 .Ql #{window_activity}
4894 .Ql #{t:window_activity}
4896 .Ql Sun Oct 25 09:25:02 2015 .
4900 will use shorter but less accurate time format for times in the past.
4901 A custom format may be given using an
4907 if the format is separately being passed through
4912 .Ql #{t/f/%%H#:%%M:window_activity} ,
4924 of the variable respectively.
4928 special characters or with a
4930 suffix, escape hash characters (so
4935 will expand the format twice, for example
4936 .Ql #{E:status-left}
4937 is the result of expanding the content of the
4939 option rather than the option itself.
4950 will loop over each session, window or pane and insert the format once
4952 For windows and panes, two comma-separated formats may be given:
4953 the second is used for the current window or active pane.
4954 For example, to get a list of windows formatted like the status line:
4955 .Bd -literal -offset indent
4956 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
4960 checks if a window (without any suffix or with the
4962 suffix) or a session (with the
4964 suffix) name exists, for example
4966 is replaced with 1 if a window named
4970 A prefix of the form
4977 The first argument may be an extended regular expression and a final argument may be
4979 to ignore case, for example
4980 .Ql s/a(.)/\e1x/i:\&
4986 In addition, the last line of a shell command's output may be inserted using
4990 will insert the system's uptime.
4991 When constructing formats,
4995 commands to finish; instead, the previous result from running the same command is used,
4996 or a placeholder if the command has not been run before.
4997 If the command hasn't exited, the most recent line of output will be used, but the status
4998 line will not be updated more than once a second.
4999 Commands are executed using
5003 global environment set (see the
5004 .Sx GLOBAL AND SESSION ENVIRONMENT
5009 specifies that a string should be interpreted literally and not expanded.
5011 .Ql #{l:#{?pane_in_mode,yes,no}}
5013 .Ql #{?pane_in_mode,yes,no} .
5015 The following variables are available, where appropriate:
5016 .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
5017 .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
5018 .It Li "active_window_index" Ta "" Ta "Index of active window in session"
5019 .It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen"
5020 .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
5021 .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
5022 .It Li "buffer_created" Ta "" Ta "Time buffer created"
5023 .It Li "buffer_name" Ta "" Ta "Name of buffer"
5024 .It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
5025 .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
5026 .It Li "client_activity" Ta "" Ta "Time client last had activity"
5027 .It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels"
5028 .It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels"
5029 .It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
5030 .It Li "client_created" Ta "" Ta "Time client created"
5031 .It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind"
5032 .It Li "client_flags" Ta "" Ta "List of client flags"
5033 .It Li "client_height" Ta "" Ta "Height of client"
5034 .It Li "client_key_table" Ta "" Ta "Current key table"
5035 .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
5036 .It Li "client_name" Ta "" Ta "Name of client"
5037 .It Li "client_pid" Ta "" Ta "PID of client process"
5038 .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
5039 .It Li "client_readonly" Ta "" Ta "1 if client is readonly"
5040 .It Li "client_session" Ta "" Ta "Name of the client's session"
5041 .It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any"
5042 .It Li "client_termname" Ta "" Ta "Terminal name of client"
5043 .It Li "client_termtype" Ta "" Ta "Terminal type of client, if available"
5044 .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
5045 .It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8"
5046 .It Li "client_width" Ta "" Ta "Width of client"
5047 .It Li "client_written" Ta "" Ta "Bytes written to client"
5048 .It Li "command" Ta "" Ta "Name of command in use, if any"
5049 .It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
5050 .It Li "command_list_name" Ta "" Ta "Command name if listing commands"
5051 .It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
5052 .It Li "config_files" Ta "" Ta "List of configuration files loaded"
5053 .It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode"
5054 .It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode"
5055 .It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode"
5056 .It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode"
5057 .It Li "current_file" Ta "" Ta "Current configuration file"
5058 .It Li "cursor_character" Ta "" Ta "Character at cursor in pane"
5059 .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
5060 .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
5061 .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
5062 .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
5063 .It Li "history_limit" Ta "" Ta "Maximum window history lines"
5064 .It Li "history_size" Ta "" Ta "Size of history in lines"
5065 .It Li "hook" Ta "" Ta "Name of running hook, if any"
5066 .It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any"
5067 .It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
5068 .It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
5069 .It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
5070 .It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
5071 .It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
5072 .It Li "host" Ta "#H" Ta "Hostname of local host"
5073 .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
5074 .It Li "insert_flag" Ta "" Ta "Pane insert flag"
5075 .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
5076 .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
5077 .It Li "last_window_index" Ta "" Ta "Index of last window in session"
5078 .It Li "line" Ta "" Ta "Line number in the list"
5079 .It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
5080 .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
5081 .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
5082 .It Li "mouse_line" Ta "" Ta "Line under mouse, if any"
5083 .It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag"
5084 .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
5085 .It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag"
5086 .It Li "mouse_word" Ta "" Ta "Word under mouse, if any"
5087 .It Li "mouse_x" Ta "" Ta "Mouse X position, if any"
5088 .It Li "mouse_y" Ta "" Ta "Mouse Y position, if any"
5089 .It Li "origin_flag" Ta "" Ta "Pane origin flag"
5090 .It Li "pane_active" Ta "" Ta "1 if active pane"
5091 .It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window"
5092 .It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window"
5093 .It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window"
5094 .It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window"
5095 .It Li "pane_bg" Ta "" Ta "Pane background colour"
5096 .It Li "pane_bottom" Ta "" Ta "Bottom of pane"
5097 .It Li "pane_current_command" Ta "" Ta "Current command if available"
5098 .It Li "pane_current_path" Ta "" Ta "Current path if available"
5099 .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
5100 .It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
5101 .It Li "pane_fg" Ta "" Ta "Pane foreground colour"
5102 .It Li "pane_format" Ta "" Ta "1 if format is for a pane"
5103 .It Li "pane_height" Ta "" Ta "Height of pane"
5104 .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
5105 .It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode"
5106 .It Li "pane_index" Ta "#P" Ta "Index of pane"
5107 .It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled"
5108 .It Li "pane_last" Ta "" Ta "1 if last pane"
5109 .It Li "pane_left" Ta "" Ta "Left of pane"
5110 .It Li "pane_marked" Ta "" Ta "1 if this is the marked pane"
5111 .It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set"
5112 .It Li "pane_mode" Ta "" Ta "Name of pane mode, if any"
5113 .It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)"
5114 .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
5115 .It Li "pane_pipe" Ta "" Ta "1 if pane is being piped"
5116 .It Li "pane_right" Ta "" Ta "Right of pane"
5117 .It Li "pane_search_string" Ta "" Ta "Last search string in copy mode"
5118 .It Li "pane_start_command" Ta "" Ta "Command pane started with"
5119 .It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized"
5120 .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
5121 .It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)"
5122 .It Li "pane_top" Ta "" Ta "Top of pane"
5123 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
5124 .It Li "pane_width" Ta "" Ta "Width of pane"
5125 .It Li "pid" Ta "" Ta "Server PID"
5126 .It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated"
5127 .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
5128 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
5129 .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
5130 .It Li "search_match" Ta "" Ta "Search match if any"
5131 .It Li "search_present" Ta "" Ta "1 if search started in copy mode"
5132 .It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode"
5133 .It Li "selection_end_x" Ta "" Ta "X position of the end of the selection"
5134 .It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection"
5135 .It Li "selection_present" Ta "" Ta "1 if selection started in copy mode"
5136 .It Li "selection_start_x" Ta "" Ta "X position of the start of the selection"
5137 .It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection"
5138 .It Li "session_activity" Ta "" Ta "Time of session last activity"
5139 .It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
5140 .It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
5141 .It Li "session_attached_list" Ta "" Ta "List of clients session is attached to"
5142 .It Li "session_created" Ta "" Ta "Time session created"
5143 .It Li "session_format" Ta "" Ta "1 if format is for a session"
5144 .It Li "session_group" Ta "" Ta "Name of session group"
5145 .It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to"
5146 .It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to"
5147 .It Li "session_group_list" Ta "" Ta "List of sessions in group"
5148 .It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group"
5149 .It Li "session_group_size" Ta "" Ta "Size of session group"
5150 .It Li "session_grouped" Ta "" Ta "1 if session in a group"
5151 .It Li "session_id" Ta "" Ta "Unique session ID"
5152 .It Li "session_last_attached" Ta "" Ta "Time session last attached"
5153 .It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
5154 .It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane"
5155 .It Li "session_name" Ta "#S" Ta "Name of session"
5156 .It Li "session_path" Ta "" Ta "Working directory of session"
5157 .It Li "session_stack" Ta "" Ta "Window indexes in most recent order"
5158 .It Li "session_windows" Ta "" Ta "Number of windows in session"
5159 .It Li "socket_path" Ta "" Ta "Server socket path"
5160 .It Li "start_time" Ta "" Ta "Server start time"
5161 .It Li "version" Ta "" Ta "Server version"
5162 .It Li "window_active" Ta "" Ta "1 if window active"
5163 .It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window"
5164 .It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window"
5165 .It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active"
5166 .It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active"
5167 .It Li "window_activity" Ta "" Ta "Time of window last activity"
5168 .It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
5169 .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
5170 .It Li "window_bigger" Ta "" Ta "1 if window is larger than client"
5171 .It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels"
5172 .It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels"
5173 .It Li "window_end_flag" Ta "" Ta "1 if window has the highest index"
5174 .It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##"
5175 .It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped"
5176 .It Li "window_format" Ta "" Ta "1 if format is for a window"
5177 .It Li "window_height" Ta "" Ta "Height of window"
5178 .It Li "window_id" Ta "" Ta "Unique window ID"
5179 .It Li "window_index" Ta "#I" Ta "Index of window"
5180 .It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
5181 .It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
5182 .It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
5183 .It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to"
5184 .It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to"
5185 .It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane"
5186 .It Li "window_name" Ta "#W" Ta "Name of window"
5187 .It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client"
5188 .It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client"
5189 .It Li "window_panes" Ta "" Ta "Number of panes in window"
5190 .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
5191 .It Li "window_stack_index" Ta "" Ta "Index in session most recent stack"
5192 .It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index"
5193 .It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
5194 .It Li "window_width" Ta "" Ta "Width of window"
5195 .It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
5196 .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
5200 offers various options to specify the colour and attributes of aspects of the
5201 interface, for example
5203 for the status line.
5204 In addition, embedded styles may be specified in format options, such as
5206 by enclosing them in
5211 A style may be the single term
5213 to specify the default style (which may come from an option, for example
5215 in the status line) or a space
5216 or comma separated list of the following:
5219 Set the foreground colour.
5220 The colour is one of:
5229 if supported the bright variants
5236 from the 256-colour set;
5238 for the default colour;
5240 for the terminal default colour; or a hexadecimal RGB string such as
5243 Set the background colour.
5245 Set no attributes (turn off any active attributes).
5258 .Ic double-underscore ,
5259 .Ic curly-underscore ,
5260 .Ic dotted-underscore ,
5261 .Ic dashed-underscore
5264 Any of the attributes may be prefixed with
5268 is the terminal alternate character set.
5269 .It Xo Ic align=left
5275 Align text to the left, centre or right of the available space if appropriate.
5277 Fill the available space with a background colour if appropriate.
5280 .Ic list=left-marker ,
5281 .Ic list=right-marker ,
5284 Mark the position of the various window list components in the
5288 marks the start of the list;
5290 is the part of the list that should be kept in focus if the entire list won't fit
5291 in the available space (typically the current window);
5292 .Ic list=left-marker
5294 .Ic list=right-marker
5295 mark the text to be used to mark that text has been trimmed from the left or
5296 right of the list if there is not enough space.
5297 .It Xo Ic push-default ,
5300 Store the current colours and attributes as the default or reset to the previous
5304 affects any subsequent use of the
5308 Only one default may be pushed (each
5310 replaces the previous saved default).
5311 .It Xo Ic range=left ,
5313 .Ic range=window|X ,
5322 are the text used for the
5328 is the range for a window passed to the
5336 .Bd -literal -offset indent
5337 fg=yellow bold underscore blink
5338 bg=black,fg=default,noreverse
5340 .Sh NAMES AND TITLES
5342 distinguishes between names and titles.
5343 Windows and sessions have names, which may be used to specify them in targets
5344 and are displayed in the status line and various lists: the name is the
5346 identifier for a window or session.
5347 Only panes have titles.
5348 A pane's title is typically set by the program running inside the pane using
5349 an escape sequence (like it would set the
5353 Windows themselves do not have titles - a window's title is the title of its
5356 itself may set the title of the terminal in which the client is running, see
5361 A session's name is set with the
5366 A window's name is set with one of:
5369 A command argument (such as
5376 An escape sequence (if the
5378 option is turned on):
5379 .Bd -literal -offset indent
5380 $ printf '\e033kWINDOW_NAME\e033\e\e'
5383 Automatic renaming, which sets the name to the active command in the window's
5386 .Ic automatic-rename
5390 When a pane is first created, its title is the hostname.
5391 A pane's title can be set via the title setting escape sequence, for example:
5392 .Bd -literal -offset indent
5393 $ printf '\e033]2;My Title\e033\e\e'
5396 It can also be modified with the
5400 .Sh GLOBAL AND SESSION ENVIRONMENT
5401 When the server is started,
5403 copies the environment into the
5404 .Em global environment ;
5405 in addition, each session has a
5406 .Em session environment .
5407 When a window is created, the session and global environments are merged.
5408 If a variable exists in both, the value from the session environment is used.
5409 The result is the initial environment passed to the new process.
5412 .Ic update-environment
5413 session option may be used to update the session environment from the client
5414 when a new session is created or an old reattached.
5416 also initialises the
5418 variable with some internal information to allow commands to be executed
5419 from inside, and the
5421 variable with the correct terminal setting of
5424 Variables in both session and global environments may be marked as hidden.
5425 Hidden variables are not passed into the environment of new processes and
5426 instead can only be used by tmux itself (for example in formats, see the
5430 Commands to alter and view the environment are:
5433 .It Xo Ic set-environment
5435 .Op Fl t Ar target-session
5436 .Ar name Op Ar value
5438 .D1 Pq alias: Ic setenv
5439 Set or unset an environment variable.
5442 is used, the change is made in the global environment; otherwise, it is applied
5443 to the session environment for
5444 .Ar target-session .
5449 is expanded as a format.
5452 flag unsets a variable.
5454 indicates the variable is to be removed from the environment before starting a
5457 marks the variable as hidden.
5459 .It Xo Ic show-environment
5461 .Op Fl t Ar target-session
5464 .D1 Pq alias: Ic showenv
5465 Display the environment for
5467 or the global environment with
5471 is omitted, all variables are shown.
5472 Variables removed from the environment are prefixed with
5476 is used, the output is formatted as a set of Bourne shell commands.
5478 shows hidden variables (omitted by default).
5482 includes an optional status line which is displayed in the bottom line of each
5485 By default, the status line is enabled and one line in height (it may be
5486 disabled or made multiple lines with the
5488 session option) and contains, from left-to-right: the name of the current
5489 session in square brackets; the window list; the title of the active pane
5490 in double quotes; and the time and date.
5492 Each line of the status line is configured with the
5495 The default is made of three parts: configurable left and right sections (which
5496 may contain dynamic content such as the time or output from a shell command,
5499 .Ic status-left-length ,
5502 .Ic status-right-length
5503 options below), and a central window list.
5504 By default, the window list shows the index, name and (if any) flag of the
5505 windows present in the current session in ascending numerical order.
5506 It may be customised with the
5507 .Ar window-status-format
5509 .Ar window-status-current-format
5511 The flag is one of the following symbols appended to the window name:
5512 .Bl -column "Symbol" "Meaning" -offset indent
5513 .It Sy "Symbol" Ta Sy "Meaning"
5514 .It Li "*" Ta "Denotes the current window."
5515 .It Li "-" Ta "Marks the last window (previously selected)."
5516 .It Li "#" Ta "Window activity is monitored and activity has been detected."
5517 .It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window."
5518 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
5519 .It Li "M" Ta "The window contains the marked pane."
5520 .It Li "Z" Ta "The window's active pane is zoomed."
5523 The # symbol relates to the
5524 .Ic monitor-activity
5526 The window name is printed in inverted colours if an alert (bell, activity or
5527 silence) is present.
5529 The colour and attributes of the status line may be configured, the entire
5530 status line using the
5532 session option and individual windows using the
5533 .Ic window-status-style
5536 The status line is automatically refreshed at interval if it has changed, the
5537 interval may be controlled with the
5541 Commands related to the status line are as follows:
5544 .It Xo Ic clear-prompt-history
5545 .Op Fl T Ar prompt-type
5547 .D1 Pq alias: Ic clrphist
5548 Clear status prompt history for prompt type
5552 is omitted, then clear history for all types.
5555 for possible values for
5557 .It Xo Ic command-prompt
5561 .Op Fl t Ar target-client
5562 .Op Fl T Ar prompt-type
5565 Open the command prompt in a client.
5566 This may be used from inside
5568 to execute commands interactively.
5572 is specified, it is used as the command.
5576 is expanded as a format.
5580 is a comma-separated list of the initial text for each prompt.
5585 is a comma-separated list of prompts which are displayed in order; otherwise
5586 a single prompt is displayed, constructed from
5588 if it is present, or
5592 Before the command is executed, the first occurrence of the string
5594 and all occurrences of
5596 are replaced by the response to the first prompt, all
5598 are replaced with the response to the second prompt, and so on for further
5600 Up to nine prompt responses may be replaced
5609 but any quotation marks are escaped.
5612 makes the prompt only accept one key press, in this case the resulting input
5613 is a single character.
5617 but the key press is translated to a key name.
5619 makes the prompt only accept numeric key presses.
5621 executes the command every time the prompt input changes instead of when the
5622 user exits the command prompt.
5628 This affects what completions are offered when
5631 Available types are:
5638 The following keys have a special meaning in the command prompt, depending
5642 .Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
5643 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
5644 .It Li "Cancel command prompt" Ta "q" Ta "Escape"
5645 .It Li "Delete from cursor to start of word" Ta "" Ta "C-w"
5646 .It Li "Delete entire command" Ta "d" Ta "C-u"
5647 .It Li "Delete from cursor to end" Ta "D" Ta "C-k"
5648 .It Li "Execute command" Ta "Enter" Ta "Enter"
5649 .It Li "Get next command from history" Ta "" Ta "Down"
5650 .It Li "Get previous command from history" Ta "" Ta "Up"
5651 .It Li "Insert top paste buffer" Ta "p" Ta "C-y"
5652 .It Li "Look for completions" Ta "Tab" Ta "Tab"
5653 .It Li "Move cursor left" Ta "h" Ta "Left"
5654 .It Li "Move cursor right" Ta "l" Ta "Right"
5655 .It Li "Move cursor to end" Ta "$" Ta "C-e"
5656 .It Li "Move cursor to next word" Ta "w" Ta "M-f"
5657 .It Li "Move cursor to previous word" Ta "b" Ta "M-b"
5658 .It Li "Move cursor to start" Ta "0" Ta "C-a"
5659 .It Li "Transpose characters" Ta "" Ta "C-t"
5664 the prompt is shown in the background and the invoking client does not exit
5665 until it is dismissed.
5667 .It Xo Ic confirm-before
5670 .Op Fl t Ar target-client
5673 .D1 Pq alias: Ic confirm
5674 Ask for confirmation before executing
5680 is the prompt to display; otherwise a prompt is constructed from
5682 It may contain the special character sequences supported by the
5687 the prompt is shown in the background and the invoking client does not exit
5688 until it is dismissed.
5690 .It Xo Ic display-menu
5692 .Op Fl c Ar target-client
5693 .Op Fl t Ar target-pane
5695 .Op Fl x Ar position
5696 .Op Fl y Ar position
5702 .D1 Pq alias: Ic menu
5706 gives the target for any commands run from the menu.
5708 A menu is passed as a series of arguments: first the menu item name,
5709 second the key shortcut (or empty for none) and third the command
5710 to run when the menu item is chosen.
5711 The name and command are formats, see the
5716 If the name begins with a hyphen (-), then the item is disabled (shown dim) and
5718 The name may be empty for a separator line, in which case both the key and
5719 command should be omitted.
5722 is a format for the menu title (see
5728 give the position of the menu.
5729 Both may be a row or column number, or one of the following special values:
5730 .Bl -column "XXXXX" "XXXX" -offset indent
5731 .It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning"
5732 .It Li "C" Ta "Both" Ta "The centre of the terminal"
5733 .It Li "R" Ta Fl x Ta "The right side of the terminal"
5734 .It Li "P" Ta "Both" Ta "The bottom left of the pane"
5735 .It Li "M" Ta "Both" Ta "The mouse position"
5736 .It Li "W" Ta "Both" Ta "The window position on the status line"
5737 .It Li "S" Ta Fl y Ta "The line above or below the status line"
5740 Or a format, which is expanded including the following additional variables:
5741 .Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
5742 .It Sy "Variable name" Ta Sy "Replaced with"
5743 .It Li "popup_centre_x" Ta "Centered in the client"
5744 .It Li "popup_centre_y" Ta "Centered in the client"
5745 .It Li "popup_height" Ta "Height of menu or popup"
5746 .It Li "popup_mouse_bottom" Ta "Bottom of at the mouse"
5747 .It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse"
5748 .It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse"
5749 .It Li "popup_mouse_top" Ta "Top at the mouse"
5750 .It Li "popup_mouse_x" Ta "Mouse X position"
5751 .It Li "popup_mouse_y" Ta "Mouse Y position"
5752 .It Li "popup_pane_bottom" Ta "Bottom of the pane"
5753 .It Li "popup_pane_left" Ta "Left of the pane"
5754 .It Li "popup_pane_right" Ta "Right of the pane"
5755 .It Li "popup_pane_top" Ta "Top of the pane"
5756 .It Li "popup_status_line_y" Ta "Above or below the status line"
5757 .It Li "popup_width" Ta "Width of menu or popup"
5758 .It Li "popup_window_status_line_x" Ta "At the window position in status line"
5759 .It Li "popup_window_status_line_y" Ta "At the status line showing the window"
5762 Each menu consists of items followed by a key shortcut shown in brackets.
5763 If the menu is too large to fit on the terminal, it is not displayed.
5764 Pressing the key shortcut chooses the corresponding item.
5765 If the mouse is enabled and the menu is opened from a mouse key binding,
5766 releasing the mouse button with an item selected chooses that item and
5767 releasing the mouse button without an item selected closes the menu.
5769 changes this behaviour so that the menu does not close when the mouse button is
5770 released without an item selected the menu is not closed and a mouse button
5771 must be clicked to choose an item.
5773 The following keys are also available:
5774 .Bl -column "Key" "Function" -offset indent
5775 .It Sy "Key" Ta Sy "Function"
5776 .It Li "Enter" Ta "Choose selected item"
5777 .It Li "Up" Ta "Select previous item"
5778 .It Li "Down" Ta "Select next item"
5779 .It Li "q" Ta "Exit menu"
5782 .It Xo Ic display-message
5784 .Op Fl c Ar target-client
5786 .Op Fl t Ar target-pane
5789 .D1 Pq alias: Ic display
5793 is given, the output is printed to stdout, otherwise it is displayed in the
5795 status line for up to
5802 option is used; a delay of zero waits for a key press.
5804 ignores key presses and closes only after the delay expires.
5809 section; information is taken from
5813 is given, otherwise the active pane.
5816 prints verbose logging as the format is parsed and
5818 lists the format variables and their values.
5821 forwards any input read from stdin to the empty pane given by
5824 .It Xo Ic display-popup
5826 .Op Fl b Ar border-lines
5827 .Op Fl c Ar target-client
5828 .Op Fl d Ar start-directory
5829 .Op Fl e Ar environment
5832 .Op Fl S Ar border-style
5833 .Op Fl t Ar target-pane
5836 .Op Fl x Ar position
5837 .Op Fl y Ar position
5838 .Op Ar shell-command
5840 .D1 Pq alias: Ic popup
5841 Display a popup running
5845 A popup is a rectangular box drawn over the top of any panes.
5846 Panes are not updated while a popup is present.
5849 closes the popup automatically when
5854 closes the popup only if
5856 exited with success.
5861 give the position of the popup, they have the same meaning as for the
5867 give the width and height - both may be a percentage (followed by
5869 If omitted, half of the terminal size is used.
5872 does not surround the popup by a border.
5875 sets the type of border line for the popup.
5882 .Ic popup-border-lines
5883 for possible values for
5887 sets the style for the popup and
5889 sets the style for the popup border.
5899 and sets an environment variable for the popup; it may be specified multiple
5903 is a format for the popup title (see
5908 flag closes any popup on the client.
5910 .It Xo Ic show-prompt-history
5911 .Op Fl T Ar prompt-type
5913 .D1 Pq alias: Ic showphist
5914 Display status prompt history for prompt type
5918 is omitted, then show history for all types.
5921 for possible values for
5926 maintains a set of named
5928 Each buffer may be either explicitly or automatically named.
5929 Explicitly named buffers are named when created with the
5933 commands, or by renaming an automatically named buffer with
5936 Automatically named buffers are given a name such as
5942 option is reached, the oldest automatically named buffer is deleted.
5943 Explicitly named buffers are not subject to
5945 and may be deleted with the
5949 Buffers may be added using
5955 commands, and pasted into a window using the
5958 If a buffer command is used and no buffer is specified, the most
5959 recently added automatically named buffer is assumed.
5961 A configurable history buffer is also maintained for each window.
5962 By default, up to 2000 lines are kept; this can be altered with the
5968 The buffer commands are as follows:
5975 .Op Fl K Ar key-format
5976 .Op Fl O Ar sort-order
5977 .Op Fl t Ar target-pane
5980 Put a pane into buffer mode, where a buffer may be chosen interactively from
5982 Each buffer is shown on one line.
5983 A shortcut key is shown on the left in brackets allowing for immediate choice,
5984 or the list may be navigated and an item chosen or otherwise manipulated using
5988 The following keys may be used in buffer mode:
5989 .Bl -column "Key" "Function" -offset indent
5990 .It Sy "Key" Ta Sy "Function"
5991 .It Li "Enter" Ta "Paste selected buffer"
5992 .It Li "Up" Ta "Select previous buffer"
5993 .It Li "Down" Ta "Select next buffer"
5994 .It Li "C-s" Ta "Search by name or content"
5995 .It Li "n" Ta "Repeat last search"
5996 .It Li "t" Ta "Toggle if buffer is tagged"
5997 .It Li "T" Ta "Tag no buffers"
5998 .It Li "C-t" Ta "Tag all buffers"
5999 .It Li "p" Ta "Paste selected buffer"
6000 .It Li "P" Ta "Paste tagged buffers"
6001 .It Li "d" Ta "Delete selected buffer"
6002 .It Li "D" Ta "Delete tagged buffers"
6003 .It Li "e" Ta "Open the buffer in an editor"
6004 .It Li "f" Ta "Enter a format to filter items"
6005 .It Li "O" Ta "Change sort field"
6006 .It Li "r" Ta "Reverse sort order"
6007 .It Li "v" Ta "Toggle preview"
6008 .It Li "q" Ta "Exit mode"
6011 After a buffer is chosen,
6013 is replaced by the buffer name in
6015 and the result executed as a command.
6018 is not given, "paste-buffer -b '%%'" is used.
6021 specifies the initial sort field: one of
6027 reverses the sort order.
6029 specifies an initial filter: the filter is a format - if it evaluates to zero,
6030 the item in the list is not shown, otherwise it is shown.
6031 If a filter would lead to an empty list, it is ignored.
6033 specifies the format for each item in the list and
6035 a format for each shortcut key; both are evaluated once for each line.
6037 starts without the preview.
6038 This command works only if at least one client is attached.
6040 .It Ic clear-history Op Fl t Ar target-pane
6041 .D1 Pq alias: Ic clearhist
6042 Remove and free the history for the specified pane.
6044 .It Ic delete-buffer Op Fl b Ar buffer-name
6045 .D1 Pq alias: Ic deleteb
6046 Delete the buffer named
6048 or the most recently added automatically named buffer if not specified.
6050 .It Xo Ic list-buffers
6054 .D1 Pq alias: Ic lsb
6055 List the global buffers.
6057 specifies the format of each line and
6060 Only buffers for which the filter is true are shown.
6064 .It Xo Ic load-buffer
6066 .Op Fl b Ar buffer-name
6067 .Op Fl t Ar target-client
6071 .D1 Pq alias: Ic loadb
6072 Load the contents of the specified paste buffer from
6076 is given, the buffer is also sent to the clipboard for
6080 escape sequence, if possible.
6082 .It Xo Ic paste-buffer
6084 .Op Fl b Ar buffer-name
6085 .Op Fl s Ar separator
6086 .Op Fl t Ar target-pane
6088 .D1 Pq alias: Ic pasteb
6089 Insert the contents of a paste buffer into the specified pane.
6090 If not specified, paste into the current one.
6093 also delete the paste buffer.
6094 When output, any linefeed (LF) characters in the paste buffer are replaced with
6095 a separator, by default carriage return (CR).
6096 A custom separator may be specified using the
6101 flag means to do no replacement (equivalent to a separator of LF).
6104 is specified, paste bracket control codes are inserted around the
6105 buffer if the application has requested bracketed paste mode.
6107 .It Xo Ic save-buffer
6109 .Op Fl b Ar buffer-name
6112 .D1 Pq alias: Ic saveb
6113 Save the contents of the specified paste buffer to
6117 option appends to rather than overwriting the file.
6118 .It Xo Ic set-buffer
6120 .Op Fl b Ar buffer-name
6121 .Op Fl t Ar target-client
6123 .Op Fl n Ar new-buffer-name
6126 .D1 Pq alias: Ic setb
6127 Set the contents of the specified buffer to
6131 is given, the buffer is also sent to the clipboard for
6135 escape sequence, if possible.
6138 option appends to rather than overwriting the buffer.
6141 option renames the buffer to
6142 .Ar new-buffer-name .
6144 .It Xo Ic show-buffer
6145 .Op Fl b Ar buffer-name
6147 .D1 Pq alias: Ic showb
6148 Display the contents of the specified buffer.
6151 Miscellaneous commands are as follows:
6153 .It Ic clock-mode Op Fl t Ar target-pane
6154 Display a large clock.
6158 .Op Fl t Ar target-pane
6159 .Ar shell-command command
6169 returns success or the second
6172 Before being executed,
6174 is expanded using the rules specified in the
6176 section, including those relevant to
6181 is run in the background.
6187 is not executed but considered success if neither empty nor zero (after formats
6191 .D1 Pq alias: Ic lock
6192 Lock each client individually by running the command specified by the
6199 .Op Fl t Ar target-pane
6200 .Op Ar shell-command
6202 .D1 Pq alias: Ic run
6211 command in the background without creating a window.
6212 Before being executed,
6214 is expanded using the rules specified in the
6219 the command is run in the background.
6223 seconds before starting the command.
6226 is not given, any output to stdout is displayed in view mode (in the pane
6229 or the current pane if omitted) after the command finishes.
6230 If the command fails, the exit status is also displayed.
6236 .D1 Pq alias: Ic wait
6237 When used without options, prevents the client from exiting until woken using
6240 with the same channel.
6243 is used, the channel is locked and any clients that try to lock the same
6244 channel are made to wait until the channel is unlocked with
6251 client detaches, it prints a message.
6254 .It detached (from session ...)
6255 The client was detached normally.
6256 .It detached and SIGHUP
6257 The client was detached and its parent sent the
6259 signal (for example with
6267 was unexpectedly destroyed.
6269 The client was killed with
6272 The client is in control mode and became unable to keep up with the data from
6275 The server exited when it had no sessions.
6277 The server exited when it received
6279 .It server exited unexpectedly
6280 The server crashed or otherwise exited without telling the client the reason.
6282 .Sh TERMINFO EXTENSIONS
6284 understands some unofficial extensions to
6286 It is not normally necessary to set these manually, instead the
6287 .Ic terminal-features
6288 option should be used.
6291 An existing extension that tells
6293 the terminal supports default colours.
6297 that the terminal supports the VTE bidirectional text extensions.
6299 Set the cursor colour.
6300 The first takes a single string argument and is used to set the colour;
6301 the second takes no arguments and restores the default cursor colour.
6302 If set, a sequence such as this may be used
6303 to change the cursor colour from inside
6305 .Bd -literal -offset indent
6306 $ printf '\e033]12;red\e033\e\e'
6313 .It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg
6314 Set, clear, disable or enable DECSLRM margins.
6315 These are set automatically if the terminal reports it is
6318 .It Em \&Dsbp , \&Enbp
6319 Disable and enable bracketed paste.
6320 These are set automatically if the
6322 capability is present.
6323 .It Em \&Dseks , \&Eneks
6324 Disable and enable extended keys.
6325 .It Em \&Dsfcs , \&Enfcs
6326 Disable and enable focus reporting.
6327 These are set automatically if the
6329 capability is present.
6333 that the terminal supports rectangle operations.
6335 Enable the overline attribute.
6337 Set a styled underscore.
6338 The single parameter is one of: 0 for no underscore, 1 for normal
6339 underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted
6340 underscore and 5 for dashed underscore.
6341 .It Em \&Setulc , \&ol
6342 Set the underscore colour or reset to the default.
6343 The argument is (red * 65536) + (green * 256) + blue where each is between 0
6346 Set or reset the cursor style.
6347 If set, a sequence such as this may be used
6348 to change the cursor to an underline:
6349 .Bd -literal -offset indent
6350 $ printf '\e033[4 q'
6355 is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
6357 Start (parameter is 1) or end (parameter is 2) a synchronized update.
6359 Indicate that the terminal supports the
6361 RGB escape sequence (for example, \ee[38;2;255;255;255m).
6363 If supported, this is used for the initialize colour escape sequence (which
6364 may be enabled by adding the
6373 This is equivalent to the
6378 Store the current buffer in the host terminal's selection (clipboard).
6381 option above and the
6385 This is an existing extension capability that tmux uses to mean that the
6386 terminal supports the
6388 title set sequences and to automatically set some of the capabilities above.
6392 offers a textual interface called
6394 This allows applications to communicate with
6396 using a simple text-only protocol.
6398 In control mode, a client sends
6400 commands or command sequences terminated by newlines on standard input.
6401 Each command will produce one block of output on standard output.
6402 An output block consists of a
6404 line followed by the output (which may be empty).
6405 The output block ends with a
6414 have three arguments: an integer time (as seconds from epoch), command number and
6415 flags (currently not used).
6417 .Bd -literal -offset indent
6418 %begin 1363006971 2 1
6419 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
6426 command may be used to set the size of a client in control mode.
6430 outputs notifications.
6431 A notification will never occur inside an output block.
6433 The following notifications are defined:
6435 .It Ic %client-detached Ar client
6436 The client has detached.
6437 .It Ic %client-session-changed Ar client session-id name
6438 The client is now attached to the session with ID
6442 .It Ic %continue Ar pane-id
6443 The pane has been continued after being paused (if the
6448 .It Ic %exit Op Ar reason
6451 client is exiting immediately, either because it is not attached to any session
6452 or an error occurred.
6455 describes why the client exited.
6456 .It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value
6463 is the time in milliseconds for which tmux had buffered the output before it was sent.
6464 Any subsequent arguments up until a single
6466 are for future use and should be ignored.
6467 .It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags
6468 The layout of a window with ID
6473 The window's visible layout is
6474 .Ar window-visible-layout
6475 and the window flags are
6477 .It Ic %output Ar pane-id Ar value
6478 A window pane produced output.
6480 escapes non-printable characters and backslash as octal \\xxx.
6481 .It Ic %pane-mode-changed Ar pane-id
6485 .It Ic %pause Ar pane-id
6486 The pane has been paused (if the
6489 .It Ic %session-changed Ar session-id Ar name
6490 The client is now attached to the session with ID
6494 .It Ic %session-renamed Ar name
6495 The current session was renamed to
6497 .It Ic %session-window-changed Ar session-id Ar window-id
6500 changed its active window to the window with ID
6502 .It Ic %sessions-changed
6503 A session was created or destroyed.
6504 .It Xo Ic %subscription-changed
6509 .Ar pane-id ... \& :
6512 The value of the format associated with subscription
6523 are for future use and should be ignored.
6524 .It Ic %unlinked-window-add Ar window-id
6527 was created but is not linked to the current session.
6528 .It Ic %unlinked-window-close Ar window-id
6531 which is not linked to the current session, was closed.
6532 .It Ic %unlinked-window-renamed Ar window-id
6535 which is not linked to the current session, was renamed.
6536 .It Ic %window-add Ar window-id
6539 was linked to the current session.
6540 .It Ic %window-close Ar window-id
6544 .It Ic %window-pane-changed Ar window-id Ar pane-id
6545 The active pane in the window with ID
6547 changed to the pane with ID
6549 .It Ic %window-renamed Ar window-id Ar name
6558 is started, it inspects the following environment variables:
6559 .Bl -tag -width LC_CTYPE
6561 If the command specified in this variable contains the string
6565 is unset, use vi-style key bindings.
6572 The user's login directory.
6575 database is consulted.
6577 The character encoding
6579 It is used for two separate purposes.
6580 For output to the terminal, UTF-8 is used if the
6582 option is given or if
6588 Otherwise, only ASCII characters are written and non-ASCII characters
6589 are replaced with underscores
6593 always runs with a UTF-8 locale.
6594 If en_US.UTF-8 is provided by the operating system it is used and
6596 is ignored for input.
6601 what the UTF-8 locale is called on the current system.
6602 If the locale specified by
6604 is not available or is not a UTF-8 locale,
6606 exits with an error message.
6608 The date and time format
6610 It is used for locale-dependent
6614 The current working directory to be set in the global environment.
6615 This may be useful if it contains symbolic links.
6616 If the value of the variable does not match the current working
6617 directory, the variable is ignored and the result of
6621 The absolute path to the default shell for new windows.
6626 The parent directory of the directory containing the server sockets.
6631 If the command specified in this variable contains the string
6633 use vi-style key bindings.
6641 .Bl -tag -width "/etc/tmux.confXXX" -compact
6646 .It Pa /etc/tmux.conf
6647 System-wide configuration file.
6655 .Dl $ tmux new-session vi
6657 Most commands have a shorter form, known as an alias.
6658 For new-session, this is
6663 Alternatively, the shortest unambiguous form of a command is accepted.
6664 If there are several options, they are listed:
6665 .Bd -literal -offset indent
6667 ambiguous command: n, could be: new-session, new-window, next-window
6670 Within an active session, a new window may be created by typing
6680 Windows may be navigated with:
6682 (to select window 0),
6684 (to select window 1), and so on;
6686 to select the next window; and
6688 to select the previous window.
6690 A session may be detached using
6692 (or by an external event such as
6694 disconnection) and reattached with:
6696 .Dl $ tmux attach-session
6700 lists the current key bindings in the current window; up and down may be used
6701 to navigate the list or
6705 Commands to be run when the
6707 server is started may be placed in the
6710 Common examples include:
6712 Changing the default prefix key:
6713 .Bd -literal -offset indent
6714 set-option -g prefix C-a
6716 bind-key C-a send-prefix
6719 Turning the status line off, or changing its colour:
6720 .Bd -literal -offset indent
6721 set-option -g status off
6722 set-option -g status-style bg=blue
6725 Setting other options, such as the default command,
6726 or locking after 30 minutes of inactivity:
6727 .Bd -literal -offset indent
6728 set-option -g default-command "exec /bin/ksh"
6729 set-option -g lock-after-time 1800
6732 Creating new key bindings:
6733 .Bd -literal -offset indent
6734 bind-key b set-option status
6735 bind-key / command-prompt "split-window 'exec man %%'"
6736 bind-key S command-prompt "new-window -n %1 'ssh %1'"
6741 .An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com