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 Set terminal features for the client.
208 This is a comma-separated list of features.
210 .Ic terminal-features
213 Write UTF-8 output to the terminal even if the first environment
219 that is set does not contain
228 Request verbose logging.
229 Log messages will be saved into
230 .Pa tmux-client-PID.log
232 .Pa tmux-server-PID.log
233 files in the current directory, where
235 is the PID of the server or client process.
238 is specified twice, an additional
240 file is generated with a copy of everything
242 writes to the terminal.
246 signal may be sent to the
248 server process to toggle logging between on (as if
251 .It Ar command Op Ar flags
252 This specifies one of a set of commands used to control
254 as described in the following sections.
255 If no commands are specified, the
259 .Sh DEFAULT KEY BINDINGS
261 may be controlled from an attached client by using a key combination of a
264 (Ctrl-b) by default, followed by a command key.
266 The default command key bindings are:
268 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
270 Send the prefix key (C-b) through to the application.
272 Rotate the panes in the current window forwards.
278 Break the current pane out of the window.
281 Split the current pane into two, top and bottom.
283 List all paste buffers.
285 Rename the current session.
287 Split the current pane into two, left and right.
289 Kill the current window.
291 Prompt for a window index to select.
293 Switch the attached client to the previous session.
295 Switch the attached client to the next session.
297 Rename the current window.
299 Delete the most recently copied buffer of text.
301 Prompt for an index to move the current window.
303 Select windows 0 to 9.
309 Move to the previously active pane.
311 Choose which buffer to paste interactively from a list.
313 List all key bindings.
315 Choose a client to detach.
317 Switch the attached client back to the last session.
319 Enter copy mode to copy text or view the history.
321 Paste the most recently copied buffer of text.
325 Detach the current client.
327 Prompt to search for text in open windows.
329 Display some information about the current window.
331 Move to the previously selected window.
333 Mark the current pane (see
337 Clear the marked pane.
339 Change to the next window.
341 Select the next pane in the current window.
343 Change to the previous window.
345 Briefly display pane indexes.
347 Force redraw of the attached client.
349 Select a new session for the attached client interactively.
353 Choose the current window interactively.
355 Kill the current pane.
357 Toggle zoom state of the current pane.
359 Swap the current pane with the previous pane.
361 Swap the current pane with the next pane.
363 Show previous messages from
367 Enter copy mode and scroll one page up.
370 Change to the pane above, below, to the left, or to the right of the current
373 Arrange panes in one of the five preset layouts: even-horizontal,
374 even-vertical, main-horizontal, main-vertical, or tiled.
376 Arrange the current window in the next preset layout.
378 Move to the next window with a bell or activity marker.
380 Rotate the panes in the current window backwards.
382 Move to the previous window with a bell or activity marker.
385 Resize the current pane in steps of one cell.
388 Resize the current pane in steps of five cells.
391 Key bindings may be changed with the
396 .Sh COMMAND PARSING AND EXECUTION
398 supports a large number of commands which can be used to control its
400 Each command is named and can accept zero or more flags and arguments.
401 They may be bound to a key with the
403 command or run from the shell prompt, a shell script, a configuration file or
405 For example, the same
407 command run from the shell prompt, from
409 and bound to a key may look like:
410 .Bd -literal -offset indent
411 $ tmux set-option -g status-style bg=cyan
413 set-option -g status-style bg=cyan
415 bind-key C set-option -g status-style bg=cyan
418 Here, the command name is
428 distinguishes between command parsing and execution.
429 In order to execute a command,
431 needs it to be split up into its name and arguments.
432 This is command parsing.
433 If a command is run from the shell, the shell parses it; from inside
435 or from a configuration file,
441 .Bl -dash -offset indent
443 in a configuration file;
445 typed at the command prompt (see
446 .Ic command-prompt ) ;
451 passed as arguments to
457 To execute commands, each client has a
459 A global command queue not attached to any client is used on startup
460 for configuration files like
462 Parsed commands added to the queue are executed in order.
467 parse their argument to create a new command which is inserted immediately
469 This means that arguments can be parsed twice or more - once when the parent command (such as
471 is parsed and again when it parses and executes its command.
477 stop execution of subsequent commands on the queue until something happens -
481 until a shell command finishes and
483 until a key is pressed.
484 For example, the following commands:
485 .Bd -literal -offset indent
486 new-session; new-window
487 if-shell "true" "split-window"
506 commands and their arguments.
508 This section describes the syntax of commands parsed by
510 for example in a configuration file or at the command prompt.
511 Note that when commands are entered into the shell, they are parsed by the shell
517 Each command is terminated by a newline or a semicolon (;).
518 Commands separated by semicolons together form a
520 - if a command in the sequence encounters an error, no subsequent commands are
523 It is recommended that a semicolon used as a command separator should be
524 written as an individual token, for example from
526 .Bd -literal -offset indent
527 $ tmux neww \\; splitw
531 .Bd -literal -offset indent
532 $ tmux neww ';' splitw
535 Or from the tmux command prompt:
536 .Bd -literal -offset indent
540 However, a trailing semicolon is also interpreted as a command separator,
544 .Bd -literal -offset indent
545 $ tmux neww\e\e; splitw
549 .Bd -literal -offset indent
550 $ tmux 'neww;' splitw
553 As in these examples, when running tmux from the shell extra care must be taken
554 to properly quote semicolons:
557 Semicolons that should be interpreted as a command separator
558 should be escaped according to the shell conventions.
561 this typically means quoted (such as
562 .Ql neww ';' splitw )
564 .Ql neww \e\e\e\e; splitw ) .
566 Individual semicolons or trailing semicolons that should be interpreted as
567 arguments should be escaped twice: once according to the shell conventions and
571 .Bd -literal -offset indent
572 $ tmux neww 'foo\e\e;' bar
573 $ tmux neww foo\e\e\e\e; bar
576 Semicolons that are not individual tokens or trailing another token should only
577 be escaped once according to shell conventions; for example:
578 .Bd -literal -offset indent
579 $ tmux neww 'foo-;-bar'
580 $ tmux neww foo-\e\e;-bar
584 Comments are marked by the unquoted # character - any remaining text after a
585 comment is ignored until the end of the line.
587 If the last character of a line is \e, the line is joined with the following
588 line (the \e and the newline are completely removed).
589 This is called line continuation and applies both inside and outside quoted
590 strings and in comments, but not inside braces.
592 Command arguments may be specified as strings surrounded by single (') quotes,
593 double quotes (") or braces ({}).
595 This is required when the argument contains any special character.
596 Single and double quoted strings cannot span multiple lines except with line
598 Braces can span multiple lines.
600 Outside of quotes and inside double quotes, these replacements are performed:
601 .Bl -dash -offset indent
603 Environment variables preceded by $ are replaced with their value from the
604 global environment (see the
605 .Sx GLOBAL AND SESSION ENVIRONMENT
608 A leading ~ or ~user is expanded to the home directory of the current or
611 \euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to
612 the given four or eight digit hexadecimal number.
614 When preceded (escaped) by a \e, the following characters are replaced: \ee by
615 the escape character; \er by a carriage return; \en by a newline; and \et by a
618 \eooo is replaced by a character of the octal value ooo.
619 Three octal digits are required, for example \e001.
620 The largest valid character is \e377.
622 Any other characters preceded by \e are replaced by themselves (that is, the \e
623 is removed) and are not treated as having any special meaning - so for example
624 \e; will not mark a command sequence and \e$ will not expand an environment
628 Braces are parsed as a configuration file (so conditions such as
630 are processed) and then converted into a string.
631 They are designed to avoid the need for additional escaping when passing a
634 commands as an argument (for example to
636 These two examples produce an identical command - note that no escaping is
637 needed when using {}:
638 .Bd -literal -offset indent
640 display -p 'brace-dollar-foo: }$foo'
643 if-shell true "display -p 'brace-dollar-foo: }\e$foo'"
646 Braces may be enclosed inside braces, for example:
647 .Bd -literal -offset indent
648 bind x if-shell "true" {
655 Environment variables may be set by using the syntax
658 .Ql HOME=/home/user .
659 Variables set during parsing are added to the global environment.
660 A hidden variable may be set with
663 .Bd -literal -offset indent
667 Hidden variables are not passed to the environment of processes created
670 .Sx GLOBAL AND SESSION ENVIRONMENT
673 Commands may be parsed conditionally by surrounding them with
683 is expanded as a format (see
685 and if it evaluates to false (zero or empty), subsequent text is ignored until
692 .Bd -literal -offset indent
693 %if "#{==:#{host},myhost}"
694 set -g status-style bg=red
695 %elif "#{==:#{host},myotherhost}"
696 set -g status-style bg=green
698 set -g status-style bg=blue
702 Will change the status line to red if running on
706 or blue if running on another host.
707 Conditionals may be given on one line, for example:
708 .Bd -literal -offset indent
709 %if #{==:#{host},myhost} set -g status-style bg=red %endif
712 This section describes the commands supported by
714 Most commands accept the optional
724 These specify the client, session, window or pane which a command should affect.
727 should be the name of the client,
730 file to which the client is connected, for example either of
734 for the client attached to
736 If no client is specified,
738 attempts to work out the client currently in use; if that fails, an error is
740 Clients may be listed with the
745 is tried as, in order:
748 A session ID prefixed with a $.
750 An exact name of a session (as listed by the
754 The start of a session name, for example
756 would match a session named
761 pattern which is matched against the session name.
764 If the session name is prefixed with an
766 only an exact match is accepted (so
768 will only match exactly
773 If a single session is found, it is used as the target session; multiple matches
775 If a session is omitted, the current session is used if available; if no
776 current session is available, the most recently used is chosen.
783 specifies a window in the form
784 .Em session Ns \&: Ns Em window .
786 follows the same rules as for
790 is looked for in order as:
793 A special token, listed below.
795 A window index, for example
797 is window 1 in session
800 A window ID, such as @1.
802 An exact window name, such as
803 .Ql mysession:mywindow .
805 The start of a window name, such as
806 .Ql mysession:mywin .
810 pattern matched against the window name.
815 prefix will do an exact match only.
816 An empty window name specifies the next unused index if appropriate (for
822 otherwise the current window in
826 The following special tokens are available to indicate particular windows.
827 Each has a single-character alternative form.
828 .Bl -column "XXXXXXXXXX" "X"
829 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
830 .It Li "{start}" Ta "^" Ta "The lowest-numbered window"
831 .It Li "{end}" Ta "$" Ta "The highest-numbered window"
832 .It Li "{last}" Ta "!" Ta "The last (previously current) window"
833 .It Li "{next}" Ta "+" Ta "The next window by number"
834 .It Li "{previous}" Ta "-" Ta "The previous window by number"
842 may be a pane ID or takes a similar form to
844 but with the optional addition of a period followed by a pane index or pane ID,
846 .Ql mysession:mywindow.1 .
847 If the pane index is omitted, the currently active pane in the specified
849 The following special tokens are available for the pane index:
850 .Bl -column "XXXXXXXXXXXXXX" "X"
851 .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
852 .It Li "{last}" Ta "!" Ta "The last (previously active) pane"
853 .It Li "{next}" Ta "+" Ta "The next pane by number"
854 .It Li "{previous}" Ta "-" Ta "The previous pane by number"
855 .It Li "{top}" Ta "" Ta "The top pane"
856 .It Li "{bottom}" Ta "" Ta "The bottom pane"
857 .It Li "{left}" Ta "" Ta "The leftmost pane"
858 .It Li "{right}" Ta "" Ta "The rightmost pane"
859 .It Li "{top-left}" Ta "" Ta "The top-left pane"
860 .It Li "{top-right}" Ta "" Ta "The top-right pane"
861 .It Li "{bottom-left}" Ta "" Ta "The bottom-left pane"
862 .It Li "{bottom-right}" Ta "" Ta "The bottom-right pane"
863 .It Li "{up-of}" Ta "" Ta "The pane above the active pane"
864 .It Li "{down-of}" Ta "" Ta "The pane below the active pane"
865 .It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane"
866 .It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane"
873 may be followed by an offset, for example:
874 .Bd -literal -offset indent
883 may consist entirely of the token
887 to specify the session, window or pane where the most recent mouse event occurred
895 to specify the marked pane (see
899 Sessions, window and panes are each numbered with a unique ID; session IDs are
906 These are unique and are unchanged for the life of the session, window or pane
910 The pane ID is passed to the child process of the pane in the
912 environment variable.
913 IDs may be displayed using the
921 .Ic display-message ,
932 This may be a single argument passed to the shell, for example:
933 .Bd -literal -offset indent
934 new-window 'vi ~/.tmux.conf'
938 .Bd -literal -offset indent
939 /bin/sh -c 'vi ~/.tmux.conf'
951 to be given as multiple arguments and executed directly (without
953 This can avoid issues with shell quoting.
955 .Bd -literal -offset indent
956 $ tmux new-window vi ~/.tmux.conf
961 directly without invoking the shell.
967 command, either passed with the command and arguments separately, for example:
968 .Bd -literal -offset indent
969 bind-key F1 set-option status off
972 Or passed as a single string argument in
975 .Bd -literal -offset indent
976 bind-key F1 { set-option status off }
982 .Bd -literal -offset indent
983 refresh-client -t/dev/ttyp2
985 rename-session -tfirst newname
987 set-option -wt:0 monitor-activity on
989 new-window ; split-window -d
991 bind-key R source-file ~/.tmux.conf \e; \e
992 display-message "source-file done"
997 .Bd -literal -offset indent
998 $ tmux kill-window -t :1
1000 $ tmux new-window \e; split-window -d
1002 $ tmux new-session -d 'vi ~/.tmux.conf' \e; split-window -d \e; attach
1004 .Sh CLIENTS AND SESSIONS
1007 server manages clients, sessions, windows and panes.
1008 Clients are attached to sessions to interact with them, either
1009 when they are created with the
1011 command, or later with the
1014 Each session has one or more windows
1017 Windows may be linked to multiple sessions and are made up of one or
1019 each of which contains a pseudo terminal.
1020 Commands for creating, linking and otherwise manipulating windows
1023 .Sx WINDOWS AND PANES
1026 The following commands are available to manage clients and sessions:
1029 .It Xo Ic attach-session
1031 .Op Fl c Ar working-directory
1033 .Op Fl t Ar target-session
1035 .D1 Pq alias: Ic attach
1038 create a new client in the current terminal and attach it to
1039 .Ar target-session .
1040 If used from inside, switch the current client.
1043 is specified, any other clients attached to the session are detached.
1048 to the parent process of the client as well as
1049 detaching the client, typically causing it to exit.
1051 sets a comma-separated list of client flags.
1055 the client has an independent active pane
1057 the client does not affect the size of other clients
1059 the client does not receive pane output in control mode
1060 .It pause-after=seconds
1061 output is paused once the pane is
1063 behind in control mode
1065 the client is read-only
1067 wait for an empty line input before exiting in control mode
1072 turns a flag off if the client is already attached.
1076 .Ar read-only,ignore-size .
1077 When a client is read-only, only keys bound to the
1081 commands have any effect.
1084 flag allows the active pane to be selected independently of the window's active
1085 pane used by clients without the flag.
1086 This only affects the cursor position and commands issued from the client;
1087 other features such as hooks and styles continue to use the window's active
1090 If no server is started,
1092 will attempt to start it; this will fail unless sessions are created in the
1099 are slightly adjusted: if
1101 needs to select the most recently used session, it will prefer the most
1107 will set the session working directory (used for new windows) to
1108 .Ar working-directory .
1113 .Ic update-environment
1114 option will not be applied.
1116 .It Xo Ic detach-client
1118 .Op Fl E Ar shell-command
1119 .Op Fl s Ar target-session
1120 .Op Fl t Ar target-client
1122 .D1 Pq alias: Ic detach
1123 Detach the current client if bound to a key, the client specified with
1125 or all clients currently attached to the session specified by
1129 option kills all but the client given with
1135 to the parent process of the client, typically causing it
1141 to replace the client.
1143 .It Ic has-session Op Fl t Ar target-session
1144 .D1 Pq alias: Ic has
1145 Report an error and exit with 1 if the specified session does not exist.
1146 If it does exist, exit with 0.
1150 server and clients and destroy all sessions.
1151 .It Xo Ic kill-session
1153 .Op Fl t Ar target-session
1155 Destroy the given session, closing any windows linked to it and no other
1156 sessions, and detaching all clients attached to it.
1159 is given, all sessions but the specified one is killed.
1162 flag clears alerts (bell, activity, or silence) in all windows linked to the
1165 .It Xo Ic list-clients
1167 .Op Fl t Ar target-session
1169 .D1 Pq alias: Ic lsc
1170 List all clients attached to the server.
1171 For the meaning of the
1178 is specified, list only clients connected to that session.
1180 .It Xo Ic list-commands
1184 .D1 Pq alias: Ic lscm
1187 or - if omitted - of all commands supported by
1190 .It Xo Ic list-sessions
1195 List all sessions managed by the server.
1197 specifies the format of each line and
1200 Only sessions for which the filter is true are shown.
1205 .It Ic lock-client Op Fl t Ar target-client
1206 .D1 Pq alias: Ic lockc
1213 .It Ic lock-session Op Fl t Ar target-session
1214 .D1 Pq alias: Ic locks
1215 Lock all clients attached to
1216 .Ar target-session .
1218 .It Xo Ic new-session
1220 .Op Fl c Ar start-directory
1221 .Op Fl e Ar environment
1224 .Op Fl n Ar window-name
1225 .Op Fl s Ar session-name
1226 .Op Fl t Ar group-name
1229 .Op Ar shell-command
1231 .D1 Pq alias: Ic new
1232 Create a new session with name
1235 The new session is attached to the current terminal unless
1241 are the name of and shell command to execute in the initial window.
1244 the initial size comes from the global
1250 can be used to specify a different size.
1252 uses the size of the current client if any.
1259 option is set for the session.
1261 sets a comma-separated list of client flags (see
1262 .Ic attach-session ) .
1264 If run from a terminal, any
1266 special characters are saved and used for new windows in the new session.
1276 already exists; in this case,
1281 .Ic attach-session ,
1287 .Ic attach-session .
1291 is given, it specifies a
1293 Sessions in the same group share the same set of windows - new windows are
1294 linked to all sessions in the group and any windows closed removed from all
1296 The current and previous window and any session options remain independent and
1297 any session in a group may be killed without affecting the others.
1303 the name of an existing group, in which case the new session is added to that
1306 the name of an existing session - the new session is added to the same group
1307 as that session, creating a new group if necessary;
1309 the name for a new group containing only the new session.
1321 option prints information about the new session after it has been created.
1322 By default, it uses the format
1323 .Ql #{session_name}:\&
1324 but a different format may be specified with
1330 .Ic update-environment
1331 option will not be applied.
1335 and sets an environment variable for the newly created session; it may be
1336 specified multiple times.
1338 .It Xo Ic refresh-client
1340 .Op Fl A Ar pane:state
1341 .Op Fl B Ar name:what:format
1344 .Op Fl l Op Ar target-pane
1345 .Op Fl t Ar target-client
1348 .D1 Pq alias: Ic refresh
1349 Refresh the current client if bound to a key, or a single client if one is given
1354 is specified, only update the client's status line.
1363 flags allow the visible portion of a window which is larger than the client
1366 moves the visible part up by
1378 returns to tracking the cursor automatically.
1381 is omitted, 1 is used.
1382 Note that the visible position is a property of the client not of the
1383 window, changing the current window in the attached session will reset
1387 sets the width and height of a control mode client or of a window for a
1388 control mode client,
1393 .Ql window ID:widthxheight ,
1399 allows a control mode client to trigger actions on a pane.
1400 The argument is a pane ID (with leading
1402 a colon, then one of
1411 will not send output from the pane to the client and if all clients have turned
1412 the pane off, will stop reading from the pane.
1416 will return to sending output to the pane if it was paused (manually or with the
1422 will pause the pane.
1424 may be given multiple times for different panes.
1427 sets a subscription to a format for a control mode client.
1428 The argument is split into three items by colons:
1430 is a name for the subscription;
1432 is a type of item to subscribe to;
1435 After a subscription is added, changes to the format are reported with the
1436 .Ic %subscription-changed
1437 notification, at most once a second.
1438 If only the name is given, the subscription is removed.
1440 may be empty to check the format only for the attached session, or one of:
1444 for all panes in the attached session;
1449 for all windows in the attached session.
1452 sets a comma-separated list of client flags, see
1453 .Ic attach-session .
1456 requests the clipboard from the client using the
1461 is given, the clipboard is sent (in encoded form), otherwise it is stored in a
1469 move the visible portion of the window left, right, up or down
1472 if the window is larger than the client.
1474 resets so that the position follows the cursor.
1479 .It Xo Ic rename-session
1480 .Op Fl t Ar target-session
1483 .D1 Pq alias: Ic rename
1484 Rename the session to
1486 .It Xo Ic server-access
1490 Change the access or read/write permission of
1492 The user running the
1494 server (its owner) and the root user cannot be changed and are always
1500 are used to give or revoke access for the specified user.
1501 If the user is already attached, the
1503 flag causes their clients to be detached.
1508 change the permissions for
1511 makes their clients read-only and
1515 lists current access permissions.
1517 By default, the access list is empty and
1519 creates sockets with file system permissions preventing access by any user
1520 other than the owner (and root).
1521 These permissions must be changed manually.
1522 Great care should be taken not to allow access to untrusted users even
1525 .It Xo Ic show-messages
1527 .Op Fl t Ar target-client
1529 .D1 Pq alias: Ic showmsgs
1530 Show server messages or information.
1531 Messages are stored, up to a maximum of the limit set by the
1537 show debugging information about jobs and terminals.
1539 .It Xo Ic source-file
1544 .D1 Pq alias: Ic source
1545 Execute commands from one or more files specified by
1554 is expanded as a format.
1557 is given, no error will be returned if
1562 the file is parsed but no commands are executed.
1564 shows the parsed commands and line numbers if possible.
1567 .D1 Pq alias: Ic start
1570 server, if not already running, without creating any sessions.
1572 Note that as by default the
1574 server will exit with no sessions, this is only useful if a session is created in
1577 is turned off, or another command is run as part of the same command sequence.
1579 .Bd -literal -offset indent
1580 $ tmux start \\; show -g
1583 .It Xo Ic suspend-client
1584 .Op Fl t Ar target-client
1586 .D1 Pq alias: Ic suspendc
1587 Suspend a client by sending
1591 .It Xo Ic switch-client
1593 .Op Fl c Ar target-client
1594 .Op Fl t Ar target-session
1595 .Op Fl T Ar key-table
1597 .D1 Pq alias: Ic switchc
1598 Switch the current session for client
1601 .Ar target-session .
1604 may refer to a pane (a target that contains
1609 to change session, window and pane.
1612 keeps the window zoomed if it was zoomed.
1618 is used, the client is moved to the last, next or previous session
1632 .Ic update-environment
1633 option will not be applied.
1636 sets the client's key table; the next key from the client will be interpreted
1639 This may be used to configure multiple prefix keys, or to bind commands to
1641 For example, to make typing
1646 .Bd -literal -offset indent
1647 bind-key -Ttable2 c list-keys
1648 bind-key -Ttable1 b switch-client -Ttable2
1649 bind-key -Troot a switch-client -Ttable1
1652 .Sh WINDOWS AND PANES
1653 Each window displayed by
1655 may be split into one or more
1657 each pane takes up a certain area of the display and is a separate terminal.
1658 A window may be split into panes using the
1661 Windows may be split horizontally (with the
1663 flag) or vertically.
1664 Panes may be resized with the
1672 by default), the current pane may be changed with the
1678 commands may be used to swap panes without changing their position.
1679 Panes are numbered beginning from zero in the order they are created.
1683 pane permits direct access to the terminal contained in the pane.
1684 A pane may also be put into one of several modes:
1685 .Bl -dash -offset indent
1687 Copy mode, which permits a section of a window or its
1688 history to be copied to a
1690 for later insertion into another window.
1691 This mode is entered with the
1696 Copied text can be pasted with the
1701 View mode, which is like copy mode but is entered when a command that produces
1704 is executed from a key binding.
1706 Choose mode, which allows an item to be chosen from a list.
1707 This may be a client, a session or window or pane, or a buffer.
1708 This mode is entered with the
1716 In copy mode an indicator is displayed in the top-right corner of the pane with
1717 the current position and the number of lines in the history.
1719 Commands are sent to copy mode using the
1724 When a key is pressed, copy mode automatically uses one of two key tables,
1732 Key tables may be viewed with the
1736 The following commands are supported in copy mode:
1737 .Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
1738 .It Sy "Command" Ta Sy "vi" Ta Sy "emacs"
1739 .It Li "append-selection" Ta "" Ta ""
1740 .It Li "append-selection-and-cancel" Ta "A" Ta ""
1741 .It Li "back-to-indentation" Ta "^" Ta "M-m"
1742 .It Li "begin-selection" Ta "Space" Ta "C-Space"
1743 .It Li "bottom-line" Ta "L" Ta ""
1744 .It Li "cancel" Ta "q" Ta "Escape"
1745 .It Li "clear-selection" Ta "Escape" Ta "C-g"
1746 .It Li "copy-end-of-line [<prefix>]" Ta "" Ta ""
1747 .It Li "copy-end-of-line-and-cancel [<prefix>]" Ta "" Ta ""
1748 .It Li "copy-pipe-end-of-line [<command>] [<prefix>]" Ta "" Ta ""
1749 .It Li "copy-pipe-end-of-line-and-cancel [<command>] [<prefix>]" Ta "D" Ta "C-k"
1750 .It Li "copy-line [<prefix>]" Ta "" Ta ""
1751 .It Li "copy-line-and-cancel [<prefix>]" Ta "" Ta ""
1752 .It Li "copy-pipe-line [<command>] [<prefix>]" Ta "" Ta ""
1753 .It Li "copy-pipe-line-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1754 .It Li "copy-pipe [<command>] [<prefix>]" Ta "" Ta ""
1755 .It Li "copy-pipe-no-clear [<command>] [<prefix>]" Ta "" Ta ""
1756 .It Li "copy-pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1757 .It Li "copy-selection [<prefix>]" Ta "" Ta ""
1758 .It Li "copy-selection-no-clear [<prefix>]" Ta "" Ta ""
1759 .It Li "copy-selection-and-cancel [<prefix>]" Ta "Enter" Ta "M-w"
1760 .It Li "cursor-down" Ta "j" Ta "Down"
1761 .It Li "cursor-down-and-cancel" Ta "" Ta ""
1762 .It Li "cursor-left" Ta "h" Ta "Left"
1763 .It Li "cursor-right" Ta "l" Ta "Right"
1764 .It Li "cursor-up" Ta "k" Ta "Up"
1765 .It Li "end-of-line" Ta "$" Ta "C-e"
1766 .It Li "goto-line <line>" Ta ":" Ta "g"
1767 .It Li "halfpage-down" Ta "C-d" Ta "M-Down"
1768 .It Li "halfpage-down-and-cancel" Ta "" Ta ""
1769 .It Li "halfpage-up" Ta "C-u" Ta "M-Up"
1770 .It Li "history-bottom" Ta "G" Ta "M->"
1771 .It Li "history-top" Ta "g" Ta "M-<"
1772 .It Li "jump-again" Ta ";" Ta ";"
1773 .It Li "jump-backward <to>" Ta "F" Ta "F"
1774 .It Li "jump-forward <to>" Ta "f" Ta "f"
1775 .It Li "jump-reverse" Ta "," Ta ","
1776 .It Li "jump-to-backward <to>" Ta "T" Ta ""
1777 .It Li "jump-to-forward <to>" Ta "t" Ta ""
1778 .It Li "jump-to-mark" Ta "M-x" Ta "M-x"
1779 .It Li "middle-line" Ta "M" Ta "M-r"
1780 .It Li "next-matching-bracket" Ta "%" Ta "M-C-f"
1781 .It Li "next-paragraph" Ta "}" Ta "M-}"
1782 .It Li "next-space" Ta "W" Ta ""
1783 .It Li "next-space-end" Ta "E" Ta ""
1784 .It Li "next-word" Ta "w" Ta ""
1785 .It Li "next-word-end" Ta "e" Ta "M-f"
1786 .It Li "other-end" Ta "o" Ta ""
1787 .It Li "page-down" Ta "C-f" Ta "PageDown"
1788 .It Li "page-down-and-cancel" Ta "" Ta ""
1789 .It Li "page-up" Ta "C-b" Ta "PageUp"
1790 .It Li "pipe [<command>] [<prefix>]" Ta "" Ta ""
1791 .It Li "pipe-no-clear [<command>] [<prefix>]" Ta "" Ta ""
1792 .It Li "pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta ""
1793 .It Li "previous-matching-bracket" Ta "" Ta "M-C-b"
1794 .It Li "previous-paragraph" Ta "{" Ta "M-{"
1795 .It Li "previous-space" Ta "B" Ta ""
1796 .It Li "previous-word" Ta "b" Ta "M-b"
1797 .It Li "rectangle-on" Ta "" Ta ""
1798 .It Li "rectangle-off" Ta "" Ta ""
1799 .It Li "rectangle-toggle" Ta "v" Ta "R"
1800 .It Li "refresh-from-pane" Ta "r" Ta "r"
1801 .It Li "scroll-down" Ta "C-e" Ta "C-Down"
1802 .It Li "scroll-down-and-cancel" Ta "" Ta ""
1803 .It Li "scroll-up" Ta "C-y" Ta "C-Up"
1804 .It Li "search-again" Ta "n" Ta "n"
1805 .It Li "search-backward <for>" Ta "?" Ta ""
1806 .It Li "search-backward-incremental <for>" Ta "" Ta "C-r"
1807 .It Li "search-backward-text <for>" Ta "" Ta ""
1808 .It Li "search-forward <for>" Ta "/" Ta ""
1809 .It Li "search-forward-incremental <for>" Ta "" Ta "C-s"
1810 .It Li "search-forward-text <for>" Ta "" Ta ""
1811 .It Li "scroll-bottom" Ta "" Ta ""
1812 .It Li "scroll-middle" Ta "z" Ta ""
1813 .It Li "scroll-top" Ta "" Ta ""
1814 .It Li "search-reverse" Ta "N" Ta "N"
1815 .It Li "select-line" Ta "V" Ta ""
1816 .It Li "select-word" Ta "" Ta ""
1817 .It Li "set-mark" Ta "X" Ta "X"
1818 .It Li "start-of-line" Ta "0" Ta "C-a"
1819 .It Li "stop-selection" Ta "" Ta ""
1820 .It Li "toggle-position" Ta "P" Ta "P"
1821 .It Li "top-line" Ta "H" Ta "M-R"
1824 The search commands come in several varieties:
1828 search for a regular expression;
1831 variants search for a plain text string rather than a regular expression;
1833 perform an incremental search and expect to be used with the
1839 repeats the last search and
1841 does the same but reverses the direction (forward becomes backward and backward
1844 Copy commands may take an optional buffer prefix argument which is used
1845 to generate the buffer name (the default is
1847 so buffers are named
1851 Pipe commands take a command argument which is the command to which the
1852 selected text is piped.
1854 variants also copy the selection.
1857 variants of some commands exit copy mode after they have completed (for copy
1858 commands) or when the cursor reaches the bottom (for scrolling commands).
1860 variants do not clear the selection.
1862 The next and previous word keys skip over whitespace and treat consecutive
1863 runs of either word separators or other letters as words.
1864 Word separators can be customized with the
1867 Next word moves to the start of the next word, next word end to the end of the
1868 next word and previous word to the start of the previous word.
1869 The three next and previous space keys work similarly but use a space alone as
1873 to the empty string makes next/previous word equivalent to next/previous space.
1875 The jump commands enable quick movement within a line.
1876 For instance, typing
1880 will move the cursor to the next
1882 character on the current line.
1885 will then jump to the next occurrence.
1887 Commands in copy mode may be prefaced by an optional repeat count.
1888 With vi key bindings, a prefix is entered using the number keys; with
1889 emacs, the Alt (meta) key and a number begins prefix entry.
1891 The synopsis for the
1897 .Op Fl s Ar src-pane
1898 .Op Fl t Ar target-pane
1903 option scrolls one page up.
1905 begins a mouse drag (only valid if bound to a mouse key binding, see
1906 .Sx MOUSE SUPPORT ) .
1908 hides the position indicator in the top right.
1910 cancels copy mode and any other modes.
1918 specifies that scrolling to the bottom of the history (to the visible screen)
1919 should exit copy mode.
1920 While in copy mode, pressing a key other than those used for scrolling will
1921 disable this behaviour.
1922 This is intended to allow fast scrolling through a pane's history, for
1924 .Bd -literal -offset indent
1925 bind PageUp copy-mode -eu
1929 A number of preset arrangements of panes are available, these are called layouts.
1930 These may be selected with the
1932 command or cycled with
1936 by default); once a layout is chosen, panes within it may be moved and resized
1939 The following layouts are supported:
1941 .It Ic even-horizontal
1942 Panes are spread out evenly from left to right across the window.
1943 .It Ic even-vertical
1944 Panes are spread evenly from top to bottom.
1945 .It Ic main-horizontal
1946 A large (main) pane is shown at the top of the window and the remaining panes
1947 are spread from left to right in the leftover space at the bottom.
1949 .Em main-pane-height
1950 window option to specify the height of the top pane.
1951 .It Ic main-vertical
1954 but the large pane is placed on the left and the others spread from top to
1955 bottom along the right.
1960 Panes are spread out as evenly as possible over the window in both rows and
1966 may be used to apply a previously used layout - the
1968 command displays the layout of each window in a form suitable for use with
1971 .Bd -literal -offset indent
1974 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1975 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1979 automatically adjusts the size of the layout for the current window size.
1980 Note that a layout cannot be applied to a window with more panes than that
1981 from which the layout was originally defined.
1983 Commands related to windows and panes are as follows:
1986 .It Xo Ic break-pane
1989 .Op Fl n Ar window-name
1990 .Op Fl s Ar src-pane
1991 .Op Fl t Ar dst-window
1993 .D1 Pq alias: Ic breakp
1996 off from its containing window to make it the only pane in
2002 the window is moved to the next index after or before (existing windows are
2003 moved if necessary).
2006 is given, the new window does not become the current window.
2009 option prints information about the new window after it has been created.
2010 By default, it uses the format
2011 .Ql #{session_name}:#{window_index}.#{pane_index}
2012 but a different format may be specified with
2015 .It Xo Ic capture-pane
2017 .Op Fl b Ar buffer-name
2018 .Op Fl E Ar end-line
2019 .Op Fl S Ar start-line
2020 .Op Fl t Ar target-pane
2022 .D1 Pq alias: Ic capturep
2023 Capture the contents of a pane.
2026 is given, the output goes to stdout, otherwise to the buffer specified with
2028 or a new buffer if omitted.
2031 is given, the alternate screen is used, and the history is not accessible.
2032 If no alternate screen exists, an error will be returned unless
2037 is given, the output includes escape sequences for text and background
2040 also escapes non-printable characters as octal \exxx.
2042 ignores trailing positions that do not contain a character.
2044 preserves trailing spaces at each line's end and
2046 preserves trailing spaces and joins any wrapped lines;
2051 captures only any output that the pane has received that is the beginning of an
2052 as-yet incomplete escape sequence.
2057 specify the starting and ending line numbers, zero is the first line of the
2058 visible pane and negative numbers are lines in the history.
2062 is the start of the history and to
2064 the end of the visible pane.
2065 The default is to capture only the visible contents of the pane.
2071 .Op Fl K Ar key-format
2072 .Op Fl O Ar sort-order
2073 .Op Fl t Ar target-pane
2076 Put a pane into client mode, allowing a client to be selected interactively from
2078 Each client is shown on one line.
2079 A shortcut key is shown on the left in brackets allowing for immediate choice,
2080 or the list may be navigated and an item chosen or otherwise manipulated using
2084 The following keys may be used in client mode:
2085 .Bl -column "Key" "Function" -offset indent
2086 .It Sy "Key" Ta Sy "Function"
2087 .It Li "Enter" Ta "Choose selected client"
2088 .It Li "Up" Ta "Select previous client"
2089 .It Li "Down" Ta "Select next client"
2090 .It Li "C-s" Ta "Search by name"
2091 .It Li "n" Ta "Repeat last search"
2092 .It Li "t" Ta "Toggle if client is tagged"
2093 .It Li "T" Ta "Tag no clients"
2094 .It Li "C-t" Ta "Tag all clients"
2095 .It Li "d" Ta "Detach selected client"
2096 .It Li "D" Ta "Detach tagged clients"
2097 .It Li "x" Ta "Detach and HUP selected client"
2098 .It Li "X" Ta "Detach and HUP tagged clients"
2099 .It Li "z" Ta "Suspend selected client"
2100 .It Li "Z" Ta "Suspend tagged clients"
2101 .It Li "f" Ta "Enter a format to filter items"
2102 .It Li "O" Ta "Change sort field"
2103 .It Li "r" Ta "Reverse sort order"
2104 .It Li "v" Ta "Toggle preview"
2105 .It Li "q" Ta "Exit mode"
2108 After a client is chosen,
2110 is replaced by the client name in
2112 and the result executed as a command.
2115 is not given, "detach-client -t '%%'" is used.
2118 specifies the initial sort field: one of
2127 reverses the sort order.
2129 specifies an initial filter: the filter is a format - if it evaluates to zero,
2130 the item in the list is not shown, otherwise it is shown.
2131 If a filter would lead to an empty list, it is ignored.
2133 specifies the format for each item in the list and
2135 a format for each shortcut key; both are evaluated once for each line.
2137 starts without the preview.
2138 This command works only if at least one client is attached.
2144 .Op Fl K Ar key-format
2145 .Op Fl O Ar sort-order
2146 .Op Fl t Ar target-pane
2149 Put a pane into tree mode, where a session, window or pane may be chosen
2150 interactively from a tree.
2151 Each session, window or pane is shown on one line.
2152 A shortcut key is shown on the left in brackets allowing for immediate choice,
2153 or the tree may be navigated and an item chosen or otherwise manipulated using
2156 starts with sessions collapsed and
2158 with windows collapsed.
2161 The following keys may be used in tree mode:
2162 .Bl -column "Key" "Function" -offset indent
2163 .It Sy "Key" Ta Sy "Function"
2164 .It Li "Enter" Ta "Choose selected item"
2165 .It Li "Up" Ta "Select previous item"
2166 .It Li "Down" Ta "Select next item"
2167 .It Li "+" Ta "Expand selected item"
2168 .It Li "-" Ta "Collapse selected item"
2169 .It Li "M-+" Ta "Expand all items"
2170 .It Li "M--" Ta "Collapse all items"
2171 .It Li "x" Ta "Kill selected item"
2172 .It Li "X" Ta "Kill tagged items"
2173 .It Li "<" Ta "Scroll list of previews left"
2174 .It Li ">" Ta "Scroll list of previews right"
2175 .It Li "C-s" Ta "Search by name"
2176 .It Li "m" Ta "Set the marked pane"
2177 .It Li "M" Ta "Clear the marked pane"
2178 .It Li "n" Ta "Repeat last search"
2179 .It Li "t" Ta "Toggle if item is tagged"
2180 .It Li "T" Ta "Tag no items"
2181 .It Li "C-t" Ta "Tag all items"
2182 .It Li "\&:" Ta "Run a command for each tagged item"
2183 .It Li "f" Ta "Enter a format to filter items"
2184 .It Li "H" Ta "Jump to the starting pane"
2185 .It Li "O" Ta "Change sort field"
2186 .It Li "r" Ta "Reverse sort order"
2187 .It Li "v" Ta "Toggle preview"
2188 .It Li "q" Ta "Exit mode"
2191 After a session, window or pane is chosen, the first instance of
2193 and all instances of
2195 are replaced by the target in
2197 and the result executed as a command.
2200 is not given, "switch-client -t '%%'" is used.
2203 specifies the initial sort field: one of
2210 reverses the sort order.
2212 specifies an initial filter: the filter is a format - if it evaluates to zero,
2213 the item in the list is not shown, otherwise it is shown.
2214 If a filter would lead to an empty list, it is ignored.
2216 specifies the format for each item in the tree and
2218 a format for each shortcut key; both are evaluated once for each line.
2220 starts without the preview.
2222 includes all sessions in any session groups in the tree rather than only the
2224 This command works only if at least one client is attached.
2230 .Op Fl t Ar target-pane
2233 Put a pane into customize mode, where options and key bindings may be browsed
2234 and modified from a list.
2235 Option values in the list are shown for the active pane in the current window.
2238 The following keys may be used in customize mode:
2239 .Bl -column "Key" "Function" -offset indent
2240 .It Sy "Key" Ta Sy "Function"
2241 .It Li "Enter" Ta "Set pane, window, session or global option value"
2242 .It Li "Up" Ta "Select previous item"
2243 .It Li "Down" Ta "Select next item"
2244 .It Li "+" Ta "Expand selected item"
2245 .It Li "-" Ta "Collapse selected item"
2246 .It Li "M-+" Ta "Expand all items"
2247 .It Li "M--" Ta "Collapse all items"
2248 .It Li "s" Ta "Set option value or key attribute"
2249 .It Li "S" Ta "Set global option value"
2250 .It Li "w" Ta "Set window option value, if option is for pane and window"
2251 .It Li "d" Ta "Set an option or key to the default"
2252 .It Li "D" Ta "Set tagged options and tagged keys to the default"
2253 .It Li "u" Ta "Unset an option (set to default value if global) or unbind a key"
2254 .It Li "U" Ta "Unset tagged options and unbind tagged keys"
2255 .It Li "C-s" Ta "Search by name"
2256 .It Li "n" Ta "Repeat last search"
2257 .It Li "t" Ta "Toggle if item is tagged"
2258 .It Li "T" Ta "Tag no items"
2259 .It Li "C-t" Ta "Tag all items"
2260 .It Li "f" Ta "Enter a format to filter items"
2261 .It Li "v" Ta "Toggle option information"
2262 .It Li "q" Ta "Exit mode"
2266 specifies an initial filter: the filter is a format - if it evaluates to zero,
2267 the item in the list is not shown, otherwise it is shown.
2268 If a filter would lead to an empty list, it is ignored.
2270 specifies the format for each item in the tree.
2272 starts without the option information.
2273 This command works only if at least one client is attached.
2278 .Op Fl d Ar duration
2279 .Op Fl t Ar target-client
2282 .D1 Pq alias: Ic displayp
2283 Display a visible indicator of each pane shown by
2286 .Ic display-panes-colour
2288 .Ic display-panes-active-colour
2290 The indicator is closed when a key is pressed (unless
2294 milliseconds have passed.
2298 .Ic display-panes-time
2300 A duration of zero means the indicator stays until a key is pressed.
2301 While the indicator is on screen, a pane may be chosen with the
2305 keys, which will cause
2307 to be executed as a command with
2309 substituted by the pane ID.
2312 is "select-pane -t '%%'".
2315 other commands are not blocked from running until the indicator is closed.
2317 .It Xo Ic find-window
2319 .Op Fl t Ar target-pane
2322 .D1 Pq alias: Ic findw
2329 in window names, titles, and visible content (but not history).
2330 The flags control matching behavior:
2332 matches only visible window contents,
2334 matches only the window name and
2336 matches only the window title.
2338 makes the search ignore case.
2344 This command works only if at least one client is attached.
2349 .Op Fl s Ar src-pane
2350 .Op Fl t Ar dst-pane
2352 .D1 Pq alias: Ic joinp
2355 but instead of splitting
2357 and creating a new pane, split it and move
2360 This can be used to reverse
2366 to be joined to left of or above
2371 is omitted and a marked pane is present (see
2374 the marked pane is used rather than the current pane.
2378 .Op Fl t Ar target-pane
2380 .D1 Pq alias: Ic killp
2381 Destroy the given pane.
2382 If no panes remain in the containing window, it is also destroyed.
2385 option kills all but the pane given with
2388 .It Xo Ic kill-window
2390 .Op Fl t Ar target-window
2392 .D1 Pq alias: Ic killw
2393 Kill the current window or the window at
2395 removing it from any sessions to which it is linked.
2398 option kills all but the window given with
2403 .Op Fl t Ar target-window
2405 .D1 Pq alias: Ic lastp
2406 Select the last (previously selected) pane.
2408 keeps the window zoomed if it was zoomed.
2412 disables input to the pane.
2414 .It Ic last-window Op Fl t Ar target-session
2415 .D1 Pq alias: Ic last
2416 Select the last (previously selected) window.
2419 is specified, select the last window of the current session.
2421 .It Xo Ic link-window
2423 .Op Fl s Ar src-window
2424 .Op Fl t Ar dst-window
2426 .D1 Pq alias: Ic linkw
2433 is specified and no such window exists, the
2440 the window is moved to the next index after or before
2442 (existing windows are moved if necessary).
2447 exists, it is killed, otherwise an error is generated.
2450 is given, the newly linked window is not selected.
2452 .It Xo Ic list-panes
2458 .D1 Pq alias: Ic lsp
2463 is ignored and all panes on the server are listed.
2468 is a session (or the current session).
2469 If neither is given,
2471 is a window (or the current window).
2473 specifies the format of each line and
2476 Only panes for which the filter is true are shown.
2481 .It Xo Ic list-windows
2485 .Op Fl t Ar target-session
2487 .D1 Pq alias: Ic lsw
2490 is given, list all windows on the server.
2491 Otherwise, list windows in the current session or in
2492 .Ar target-session .
2494 specifies the format of each line and
2497 Only windows for which the filter is true are shown.
2505 .Op Fl s Ar src-pane
2506 .Op Fl t Ar dst-pane
2508 .D1 Pq alias: Ic movep
2512 .It Xo Ic move-window
2514 .Op Fl s Ar src-window
2515 .Op Fl t Ar dst-window
2517 .D1 Pq alias: Ic movew
2520 except the window at
2526 all windows in the session are renumbered in sequential order, respecting
2531 .It Xo Ic new-window
2533 .Op Fl c Ar start-directory
2534 .Op Fl e Ar environment
2536 .Op Fl n Ar window-name
2537 .Op Fl t Ar target-window
2538 .Op Ar shell-command
2540 .D1 Pq alias: Ic neww
2541 Create a new window.
2546 the new window is inserted at the next index after or before the specified
2548 moving windows up if necessary;
2551 is the new window location.
2555 is given, the session does not make the new window the current window.
2557 represents the window to be created; if the target already exists an error is
2560 flag is used, in which case it is destroyed.
2563 is given and a window named
2565 already exists, it is selected (unless
2567 is also given in which case the command does nothing).
2570 is the command to execute.
2573 is not specified, the value of the
2577 specifies the working directory in which the new window is created.
2579 When the shell command completes, the window closes.
2582 option to change this behaviour.
2587 and sets an environment variable for the newly created window; it may be
2588 specified multiple times.
2592 environment variable must be set to
2596 for all programs running
2599 New windows will automatically have
2601 added to their environment, but care must be taken not to reset this in shell
2602 start-up files or by the
2608 option prints information about the new window after it has been created.
2609 By default, it uses the format
2610 .Ql #{session_name}:#{window_index}
2611 but a different format may be specified with
2614 .It Ic next-layout Op Fl t Ar target-window
2615 .D1 Pq alias: Ic nextl
2616 Move a window to the next layout and rearrange the panes to fit.
2618 .It Xo Ic next-window
2620 .Op Fl t Ar target-session
2622 .D1 Pq alias: Ic next
2623 Move to the next window in the session.
2626 is used, move to the next window with an alert.
2630 .Op Fl t Ar target-pane
2631 .Op Ar shell-command
2633 .D1 Pq alias: Ic pipep
2634 Pipe output sent by the program in
2636 to a shell command or vice versa.
2637 A pane may only be connected to one command at a time, any existing pipe is
2643 string may contain the special character sequences supported by the
2648 is given, the current pipe (if any) is closed.
2653 specify which of the
2655 output streams are connected to the pane:
2658 stdout is connected (so anything
2660 prints is written to the pane as if it were typed);
2663 stdin is connected (so any output in the pane is piped to
2664 .Ar shell-command ) .
2665 Both may be used together and if neither are specified,
2671 option only opens a new pipe if no previous pipe exists, allowing a pipe to
2672 be toggled with a single key, for example:
2673 .Bd -literal -offset indent
2674 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
2677 .It Xo Ic previous-layout
2678 .Op Fl t Ar target-window
2680 .D1 Pq alias: Ic prevl
2681 Move to the previous layout in the session.
2683 .It Xo Ic previous-window
2685 .Op Fl t Ar target-session
2687 .D1 Pq alias: Ic prev
2688 Move to the previous window in the session.
2691 move to the previous window with an alert.
2693 .It Xo Ic rename-window
2694 .Op Fl t Ar target-window
2697 .D1 Pq alias: Ic renamew
2698 Rename the current window, or the window at
2703 .It Xo Ic resize-pane
2705 .Op Fl t Ar target-pane
2710 .D1 Pq alias: Ic resizep
2711 Resize a pane, up, down, left or right by
2727 is given in lines or columns (the default is 1);
2731 may be a given as a number of lines or columns or followed by
2733 for a percentage of the window size (for example
2737 the active pane is toggled between zoomed (occupying the whole of the window)
2738 and unzoomed (its normal position in the layout).
2741 begins mouse resizing (only valid if bound to a mouse key binding, see
2742 .Sx MOUSE SUPPORT ) .
2745 trims all lines below the current cursor position and moves lines out of the
2746 history to replace them.
2748 .It Xo Ic resize-window
2750 .Op Fl t Ar target-window
2755 .D1 Pq alias: Ic resizew
2756 Resize a window, up, down, left or right by
2772 is given in lines or cells (the default is 1).
2774 sets the size of the largest session containing the window;
2776 the size of the smallest.
2777 This command will automatically set
2779 to manual in the window options.
2781 .It Xo Ic respawn-pane
2783 .Op Fl c Ar start-directory
2784 .Op Fl e Ar environment
2785 .Op Fl t Ar target-pane
2786 .Op Ar shell-command
2788 .D1 Pq alias: Ic respawnp
2789 Reactivate a pane in which the command has exited (see the
2794 is not given, the command used when the pane was created or last respawned is
2796 The pane must be already inactive, unless
2798 is given, in which case any existing command is killed.
2800 specifies a new working directory for the pane.
2803 option has the same meaning as for the
2807 .It Xo Ic respawn-window
2809 .Op Fl c Ar start-directory
2810 .Op Fl e Ar environment
2811 .Op Fl t Ar target-window
2812 .Op Ar shell-command
2814 .D1 Pq alias: Ic respawnw
2815 Reactivate a window in which the command has exited (see the
2820 is not given, the command used when the window was created or last respawned is
2822 The window must be already inactive, unless
2824 is given, in which case any existing command is killed.
2826 specifies a new working directory for the window.
2829 option has the same meaning as for the
2833 .It Xo Ic rotate-window
2835 .Op Fl t Ar target-window
2837 .D1 Pq alias: Ic rotatew
2838 Rotate the positions of the panes within a window, either upward (numerically
2841 or downward (numerically higher).
2843 keeps the window zoomed if it was zoomed.
2845 .It Xo Ic select-layout
2847 .Op Fl t Ar target-pane
2850 .D1 Pq alias: Ic selectl
2851 Choose a specific layout for a window.
2854 is not given, the last preset layout used (if any) is reapplied.
2858 are equivalent to the
2864 applies the last set layout if possible (undoes the most recent layout change).
2866 spreads the current pane and any panes next to it out evenly.
2868 .It Xo Ic select-pane
2871 .Op Fl t Ar target-pane
2873 .D1 Pq alias: Ic selectp
2876 the active pane in its window.
2883 is used, respectively the pane below, to the left, to the right, or above the
2884 target pane is used.
2886 keeps the window zoomed if it was zoomed.
2888 is the same as using the
2894 disables input to the pane.
2896 sets the pane title.
2901 are used to set and clear the
2903 There is one marked pane at a time, setting a new marked pane clears the last.
2904 The marked pane is the default target for
2913 .It Xo Ic select-window
2915 .Op Fl t Ar target-window
2917 .D1 Pq alias: Ic selectw
2918 Select the window at
2924 are equivalent to the
2932 is given and the selected window is already the current window,
2933 the command behaves like
2936 .It Xo Ic split-window
2938 .Op Fl c Ar start-directory
2939 .Op Fl e Ar environment
2941 .Op Fl t Ar target-pane
2942 .Op Ar shell-command
2945 .D1 Pq alias: Ic splitw
2946 Create a new pane by splitting
2949 does a horizontal split and
2951 a vertical split; if neither is specified,
2956 option specifies the size of the new pane in lines (for vertical split) or in
2957 columns (for horizontal split);
2961 to specify a percentage of the available space.
2964 option causes the new pane to be created to the left of or above
2968 option creates a new pane spanning the full window height (with
2970 or full window width (with
2972 instead of splitting the active pane.
2974 zooms if the window is not zoomed, or keeps it zoomed if already zoomed.
2978 ('') will create a pane with no command running in it.
2979 Output can be sent to such a pane with the
2986 is not specified or empty)
2987 will create an empty pane and forward any output from stdin to it.
2989 .Bd -literal -offset indent
2990 $ make 2>&1|tmux splitw -dI &
2993 All other options have the same meaning as for the
2999 .Op Fl s Ar src-pane
3000 .Op Fl t Ar dst-pane
3002 .D1 Pq alias: Ic swapp
3006 is used and no source pane is specified with
3009 is swapped with the previous pane (before it numerically);
3011 swaps with the next pane (after it numerically).
3015 not to change the active pane and
3017 keeps the window zoomed if it was zoomed.
3021 is omitted and a marked pane is present (see
3024 the marked pane is used rather than the current pane.
3026 .It Xo Ic swap-window
3028 .Op Fl s Ar src-window
3029 .Op Fl t Ar dst-window
3031 .D1 Pq alias: Ic swapw
3034 except the source and destination windows are swapped.
3035 It is an error if no window exists at
3039 is given, the new window does not become the current window.
3043 is omitted and a marked pane is present (see
3046 the window containing the marked pane is used rather than the current window.
3048 .It Xo Ic unlink-window
3050 .Op Fl t Ar target-window
3052 .D1 Pq alias: Ic unlinkw
3057 is given, a window may be unlinked only if it is linked to multiple sessions -
3058 windows may not be linked to no sessions;
3061 is specified and the window is linked to only one session, it is unlinked and
3066 allows a command to be bound to most keys, with or without a prefix key.
3067 When specifying keys, most represent themselves (for example
3071 Ctrl keys may be prefixed with
3079 In addition, the following special key names are accepted:
3097 .Em NPage/PageDown/PgDn ,
3098 .Em PPage/PageUp/PgUp ,
3102 Note that to bind the
3106 keys, quotation marks are necessary, for example:
3107 .Bd -literal -offset indent
3108 bind-key '"' split-window
3109 bind-key "'" new-window
3112 A command bound to the
3114 key will execute for all keys which do not have a more specific binding.
3116 Commands related to key bindings are as follows:
3122 .Op Fl T Ar key-table
3123 .Ar key command Op Ar arguments
3125 .D1 Pq alias: Ic bind
3130 Keys are bound in a key table.
3131 By default (without -T), the key is bound in
3135 This table is used for keys pressed after the prefix key (for example,
3144 creates a new window).
3147 table is used for keys pressed without the prefix key: binding
3153 table (not recommended) means a plain
3155 will create a new window.
3160 Keys may also be bound in custom key tables and the
3163 command used to switch to them from a key binding.
3166 flag indicates this key may repeat, see the
3170 attaches a note to the key (shown with
3174 To view the default bindings and possible commands, see the
3180 .Op Fl P Ar prefix-string Fl T Ar key-table
3183 .D1 Pq alias: Ic lsk
3185 There are two forms: the default lists keys as
3189 lists only keys with attached notes and shows only the key and note for each
3192 With the default form, all key tables are listed by default.
3199 form, only keys in the
3203 key tables are listed by default;
3205 also lists only keys in
3208 specifies a prefix to print before each key and
3210 lists only the first matching key.
3212 lists the command for keys that do not have a note rather than skipping them.
3216 .Op Fl c Ar target-client
3217 .Op Fl N Ar repeat-count
3218 .Op Fl t Ar target-pane
3221 .D1 Pq alias: Ic send
3222 Send a key or keys to a window or client.
3225 is the name of the key (such as
3229 to send; if the string is not recognised as a key, it is sent as a series of
3233 is given, keys are sent to
3235 so they are looked up in the client's key table, rather than to
3237 All arguments are sent sequentially from first to last.
3238 If no keys are given and the command is bound to a key, then that key is used.
3242 flag disables key name lookup and processes the keys as literal UTF-8
3246 flag expects each key to be a hexadecimal number for an ASCII character.
3250 flag causes the terminal state to be reset.
3253 passes through a mouse event (only valid if bound to a mouse key binding, see
3254 .Sx MOUSE SUPPORT ) .
3257 is used to send a command into copy mode - see
3259 .Sx WINDOWS AND PANES
3262 specifies a repeat count and
3264 expands formats in arguments where appropriate.
3265 .It Xo Ic send-prefix
3267 .Op Fl t Ar target-pane
3269 Send the prefix key, or with
3271 the secondary prefix key, to a window as if it was pressed.
3273 .It Xo Ic unbind-key
3275 .Op Fl T Ar key-table
3278 .D1 Pq alias: Ic unbind
3279 Unbind the command bound to
3288 is present, all key bindings are removed.
3291 option prevents errors being returned.
3294 The appearance and behaviour of
3296 may be modified by changing the value of various options.
3297 There are four types of option:
3298 .Em server options ,
3299 .Em session options ,
3300 .Em window options ,
3306 server has a set of global server options which do not apply to any particular
3307 window or session or pane.
3308 These are altered with the
3311 command, or displayed with the
3316 In addition, each individual session may have a set of session options, and
3317 there is a separate set of global session options.
3318 Sessions which do not have a particular option configured inherit the value
3319 from the global session options.
3320 Session options are set or unset with the
3322 command and may be listed with the
3325 The available server and session options are listed under the
3329 Similarly, a set of window options is attached to each window and a set of pane
3330 options to each pane.
3331 Pane options inherit from window options.
3332 This means any pane option may be set as a window option to apply the option to
3333 all panes in the window without the option set, for example these commands will
3334 set the background colour to red for all panes except pane 0:
3335 .Bd -literal -offset indent
3336 set -w window-style bg=red
3337 set -pt:.0 window-style bg=blue
3340 There is also a set of global window options from which any unset window or
3341 pane options are inherited.
3342 Window and pane options are altered with
3347 commands and displayed with
3354 also supports user options which are prefixed with a
3356 User options may have any name, so long as they are prefixed with
3358 and be set to any string.
3360 .Bd -literal -offset indent
3361 $ tmux set -wq @foo "abc123"
3362 $ tmux show -wv @foo
3366 Commands which set options are as follows:
3369 .It Xo Ic set-option
3371 .Op Fl t Ar target-pane
3374 .D1 Pq alias: Ic set
3375 Set a pane option with
3377 a window option with
3379 a server option with
3381 otherwise a session option.
3382 If the option is not a user option,
3386 may be unnecessary -
3388 will infer the type from the option name, assuming
3393 is given, the global session or window option is set.
3396 expands formats in the option value.
3399 flag unsets an option, so a session inherits the option from the global
3402 restores a global option to the default).
3404 unsets an option (like
3406 but if the option is a pane option also unsets the option on any panes in the
3409 depends on the option and may be a number, a string, or a flag (on, off, or
3414 flag prevents setting an option that is already set and the
3416 flag suppresses errors about unknown or ambiguous options.
3420 and if the option expects a string or a style,
3422 is appended to the existing setting.
3424 .Bd -literal -offset indent
3425 set -g status-left "foo"
3426 set -ag status-left "bar"
3432 .Bd -literal -offset indent
3433 set -g status-style "bg=red"
3434 set -ag status-style "fg=blue"
3437 Will result in a red background
3442 the result would be the default background and a blue foreground.
3444 .It Xo Ic show-options
3446 .Op Fl t Ar target-pane
3449 .D1 Pq alias: Ic show
3450 Show the pane options (or a single option if
3454 the window options with
3456 the server options with
3458 otherwise the session options.
3459 If the option is not a user option,
3463 may be unnecessary -
3465 will infer the type from the option name, assuming
3468 Global session or window options are listed if
3472 shows only the option value, not the name.
3475 is set, no error will be returned if
3479 includes hooks (omitted by default).
3481 includes options inherited from a parent set of options, such options are
3482 marked with an asterisk.
3485 Available server options are:
3487 .It Ic backspace Ar key
3491 .It Ic buffer-limit Ar number
3492 Set the number of buffers; as new buffers are added to the top of the stack,
3493 old ones are removed from the bottom if necessary to maintain this maximum
3495 .It Xo Ic command-alias[]
3498 This is an array of custom aliases for commands.
3499 If an unknown command matches
3505 .Dl set -s command-alias[100] zoom='resize-pane -Z'
3513 .Dl resize-pane -Z -t:.1
3515 Note that aliases are expanded when a command is parsed rather than when it is
3516 executed, so binding an alias with
3518 will bind the expanded form.
3519 .It Ic default-terminal Ar terminal
3520 Set the default terminal for new windows created in this session - the
3521 default value of the
3523 environment variable.
3526 to work correctly, this
3531 or a derivative of them.
3532 .It Ic copy-command Ar shell-command
3533 Give the command to pipe to if the
3535 copy mode command is used without arguments.
3536 .It Ic escape-time Ar time
3537 Set the time in milliseconds for which
3539 waits after an escape is input to determine if it is part of a function or meta
3541 The default is 500 milliseconds.
3542 .It Ic editor Ar shell-command
3543 Set the command used when
3546 .It Xo Ic exit-empty
3549 If enabled (the default), the server will exit when there are no active
3551 .It Xo Ic exit-unattached
3554 If enabled, the server will exit when there are no attached clients.
3555 .It Xo Ic extended-keys
3556 .Op Ic on | off | always
3562 the escape sequence to enable extended keys is sent to the terminal, if
3564 knows that it is supported.
3566 always recognises extended keys itself.
3570 will only forward extended keys to applications when they request them; if
3573 will always forward the keys.
3574 .It Xo Ic focus-events
3577 When enabled, focus events are requested from the terminal if supported and
3578 passed through to applications running in
3580 Attached clients should be detached and attached again after changing this
3582 .It Ic history-file Ar path
3583 If not empty, a file to which
3585 will write command prompt history on exit and load it from on start.
3586 .It Ic message-limit Ar number
3587 Set the number of error or information messages to save in the message log for
3589 .It Ic prompt-history-limit Ar number
3590 Set the number of history items to save in the history file for each type of
3592 .It Xo Ic set-clipboard
3593 .Op Ic on | external | off
3595 Attempt to set the terminal clipboard content using the
3597 escape sequence, if there is an
3601 description (see the
3602 .Sx TERMINFO EXTENSIONS
3608 will both accept the escape sequence to create a buffer and attempt to set
3609 the terminal clipboard.
3613 will attempt to set the terminal clipboard but ignore attempts
3614 by applications to set
3620 will neither accept the clipboard escape sequence nor attempt to set the
3623 Note that this feature needs to be enabled in
3625 by setting the resource:
3626 .Bd -literal -offset indent
3627 disallowedWindowOps: 20,21,SetXprop
3630 Or changing this property from the
3632 interactive menu when required.
3633 .It Ic terminal-features[] Ar string
3634 Set terminal features for terminal types read from
3637 has a set of named terminal features.
3638 Each will apply appropriate changes to the
3643 can detect features for a few common terminals; this option can be used to
3644 easily tell tmux about features supported by terminals it cannot detect.
3646 .Ic terminal-overrides
3647 option allows individual
3649 capabilities to be set instead,
3650 .Ic terminal-features
3651 is intended for classes of functionality supported in a standard way but not
3654 Care must be taken to configure this only with features the terminal actually
3657 This is an array option where each entry is a colon-separated string made up
3658 of a terminal type pattern (matched using
3660 followed by a list of terminal features.
3661 The available features are:
3664 Supports 256 colours with the SGR escape sequences.
3666 Allows setting the system clipboard.
3668 Allows setting the cursor colour.
3670 Allows setting the cursor style.
3672 Supports extended keys.
3674 Supports focus reporting.
3676 Supports OSC 8 hyperlinks.
3678 Ignore function keys from
3684 Supports DECSLRM margins.
3690 Supports the OSC 7 working directory extension.
3692 Supports the overline SGR attribute.
3694 Supports the DECFRA rectangle fill escape sequence.
3696 Supports RGB colour with the SGR escape sequences.
3698 Supports SIXEL graphics.
3700 Supports the strikethrough SGR escape sequence.
3702 Supports synchronized updates.
3708 Allows underscore style and colour to be set.
3710 .It Ic terminal-overrides[] Ar string
3711 Allow terminal descriptions read using
3714 Each entry is a colon-separated string made up of a terminal type pattern
3721 For example, to set the
3726 for all terminal types matching
3729 .Dl "rxvt*:clear=\ee[H\ee[2J"
3731 The terminal entry value is passed through
3733 before interpretation.
3734 .It Ic user-keys[] Ar key
3735 Set list of user-defined key escape sequences.
3736 Each item is associated with a key named
3742 .Bd -literal -offset indent
3743 set -s user-keys[0] "\ee[5;30012~"
3744 bind User0 resize-pane -L 3
3748 Available session options are:
3750 .It Xo Ic activity-action
3751 .Op Ic any | none | current | other
3753 Set action on window activity when
3754 .Ic monitor-activity
3757 means activity in any window linked to a session causes a bell or message
3759 .Ic visual-activity )
3760 in the current window of that session,
3762 means all activity is ignored (equivalent to
3763 .Ic monitor-activity
3766 means only activity in windows other than the current window are ignored and
3768 means activity in the current window is ignored but not those in other windows.
3769 .It Ic assume-paste-time Ar milliseconds
3770 If keys are entered faster than one in
3772 they are assumed to have been pasted rather than typed and
3774 key bindings are not processed.
3775 The default is one millisecond and zero disables.
3776 .It Ic base-index Ar index
3777 Set the base index from which an unused index should be searched when a new
3779 The default is zero.
3780 .It Xo Ic bell-action
3781 .Op Ic any | none | current | other
3783 Set action on a bell in a window when
3786 The values are the same as those for
3787 .Ic activity-action .
3788 .It Ic default-command Ar shell-command
3789 Set the command used for new windows (if not specified when the window is
3795 The default is an empty string, which instructs
3797 to create a login shell using the value of the
3800 .It Ic default-shell Ar path
3801 Specify the default shell.
3802 This is used as the login shell for new windows when the
3804 option is set to empty, and must be the full path of the executable.
3807 tries to set a default value from the first suitable of the
3809 environment variable, the shell returned by
3813 This option should be configured when
3815 is used as a login shell.
3816 .It Ic default-size Ar XxY
3817 Set the default size of new windows when the
3819 option is set to manual or when a session is created with
3822 The value is the width and height separated by an
3825 The default is 80x24.
3826 .It Xo Ic destroy-unattached
3829 If enabled and the session is no longer attached to any clients, it is
3831 .It Xo Ic detach-on-destroy
3832 .Op Ic off | on | no-detached
3834 If on (the default), the client is detached when the session it is attached to
3836 If off, the client is switched to the most recently active of the remaining
3840 the client is detached only if there are no detached sessions; if detached
3841 sessions exist, the client is switched to the most recently active.
3842 .It Ic display-panes-active-colour Ar colour
3843 Set the colour used by the
3845 command to show the indicator for the active pane.
3846 .It Ic display-panes-colour Ar colour
3847 Set the colour used by the
3849 command to show the indicators for inactive panes.
3850 .It Ic display-panes-time Ar time
3851 Set the time in milliseconds for which the indicators shown by the
3854 .It Ic display-time Ar time
3855 Set the amount of time for which status line messages and other on-screen
3856 indicators are displayed.
3857 If set to 0, messages and indicators are displayed until a key is pressed.
3860 .It Ic history-limit Ar lines
3861 Set the maximum number of lines held in window history.
3862 This setting applies only to new windows - existing window histories are not
3863 resized and retain the limit at the point they were created.
3864 .It Ic key-table Ar key-table
3865 Set the default key table to
3869 .It Ic lock-after-time Ar number
3870 Lock the session (like the
3874 seconds of inactivity.
3875 The default is not to lock (set to 0).
3876 .It Ic lock-command Ar shell-command
3877 Command to run when locking each client.
3878 The default is to run
3882 .It Ic message-command-style Ar style
3883 Set status line message command style.
3884 This is used for the command prompt with
3886 keys when in command mode.
3892 .It Xo Ic message-line
3893 .Op Ic 0 | 1 | 2 | 3 | 4
3895 Set line on which status line messages and the command prompt are shown.
3896 .It Ic message-style Ar style
3897 Set status line message style.
3898 This is used for messages and for the command prompt.
3909 captures the mouse and allows mouse events to be bound as key bindings.
3912 section for details.
3913 .It Ic prefix Ar key
3914 Set the key accepted as a prefix key.
3915 In addition to the standard keys described under
3918 can be set to the special key
3921 .It Ic prefix2 Ar key
3922 Set a secondary key accepted as a prefix key.
3928 .It Xo Ic renumber-windows
3931 If on, when a window is closed in a session, automatically renumber the other
3932 windows in numerical order.
3935 option if it has been set.
3936 If off, do not renumber the windows.
3937 .It Ic repeat-time Ar time
3938 Allow multiple commands to be entered without pressing the prefix-key again
3941 milliseconds (the default is 500).
3942 Whether a key repeats may be set when it is bound using the
3946 Repeat is enabled for the default keys bound to the
3949 .It Xo Ic set-titles
3952 Attempt to set the client terminal title using the
3957 entries if they exist.
3959 automatically sets these to the \ee]0;...\e007 sequence if
3960 the terminal appears to be
3962 This option is off by default.
3963 .It Ic set-titles-string Ar string
3964 String used to set the client terminal title if
3967 Formats are expanded, see the
3970 .It Xo Ic silence-action
3971 .Op Ic any | none | current | other
3973 Set action on window silence when
3976 The values are the same as those for
3977 .Ic activity-action .
3979 .Op Ic off | on | 2 | 3 | 4 | 5
3981 Show or hide the status line or specify its size.
3984 gives a status line one row in height;
3991 .It Ic status-format[] Ar format
3992 Specify the format to be used for each line of the status line.
3993 The default builds the top status line from the various individual status
3995 .It Ic status-interval Ar interval
3996 Update the status line every
3999 By default, updates will occur every 15 seconds.
4000 A setting of zero disables redrawing at interval.
4001 .It Xo Ic status-justify
4002 .Op Ic left | centre | right | absolute-centre
4004 Set the position of the window list in the status line: left, centre or right.
4005 centre puts the window list in the relative centre of the available free space;
4006 absolute-centre uses the centre of the entire horizontal space.
4007 .It Xo Ic status-keys
4010 Use vi or emacs-style
4011 key bindings in the status line, for example at the command prompt.
4012 The default is emacs, unless the
4016 environment variables are set and contain the string
4018 .It Ic status-left Ar string
4021 (by default the session name) to the left of the status line.
4023 will be passed through
4031 For details on how the names and titles can be set see the
4032 .Sx "NAMES AND TITLES"
4036 .Bd -literal -offset indent
4037 #(sysctl vm.loadavg)
4038 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
4043 .It Ic status-left-length Ar length
4046 of the left component of the status line.
4048 .It Ic status-left-style Ar style
4049 Set the style of the left part of the status line.
4055 .It Xo Ic status-position
4058 Set the position of the status line.
4059 .It Ic status-right Ar string
4062 to the right of the status line.
4063 By default, the current pane title in double quotes, the date and the time
4070 and character pairs are replaced.
4071 .It Ic status-right-length Ar length
4074 of the right component of the status line.
4076 .It Ic status-right-style Ar style
4077 Set the style of the right part of the status line.
4083 .It Ic status-style Ar style
4084 Set status line style.
4090 .It Ic update-environment[] Ar variable
4091 Set list of environment variables to be copied into the session environment
4092 when a new session is created or an existing session is attached.
4093 Any variables that do not exist in the source environment are set to be
4094 removed from the session environment (as if
4099 .It Xo Ic visual-activity
4100 .Op Ic on | off | both
4102 If on, display a message instead of sending a bell when activity occurs in a
4103 window for which the
4104 .Ic monitor-activity
4105 window option is enabled.
4106 If set to both, a bell and a message are produced.
4107 .It Xo Ic visual-bell
4108 .Op Ic on | off | both
4110 If on, a message is shown on a bell in a window for which the
4112 window option is enabled instead of it being passed through to the
4113 terminal (which normally makes a sound).
4114 If set to both, a bell and a message are produced.
4118 .It Xo Ic visual-silence
4119 .Op Ic on | off | both
4123 is enabled, prints a message after the interval has expired on a given window
4124 instead of sending a bell.
4125 If set to both, a bell and a message are produced.
4126 .It Ic word-separators Ar string
4127 Sets the session's conception of what characters are considered word
4128 separators, for the purposes of the next and previous word commands in
4132 Available window options are:
4134 .Bl -tag -width Ds -compact
4135 .It Xo Ic aggressive-resize
4138 Aggressively resize the chosen window.
4141 will resize the window to the size of the smallest or largest session
4144 option) for which it is the current window, rather than the session to
4145 which it is attached.
4146 The window may resize when the current window is changed on another
4147 session; this option is good for full-screen programs which support
4149 and poor for interactive programs such as shells.
4151 .It Xo Ic automatic-rename
4154 Control automatic window renaming.
4155 When this setting is enabled,
4157 will rename the window automatically using the format specified by
4158 .Ic automatic-rename-format .
4159 This flag is automatically disabled for an individual window when a name
4160 is specified at creation with
4166 or with a terminal escape sequence.
4167 It may be switched off globally with:
4168 .Bd -literal -offset indent
4169 set-option -wg automatic-rename off
4172 .It Ic automatic-rename-format Ar format
4176 .Ic automatic-rename
4179 .It Ic clock-mode-colour Ar colour
4182 .It Xo Ic clock-mode-style
4185 Set clock hour format.
4187 .It Ic fill-character Ar character
4188 Set the character used to fill areas of the terminal unused by a window.
4190 .It Ic main-pane-height Ar height
4191 .It Ic main-pane-width Ar width
4192 Set the width or height of the main (left or top) pane in the
4199 this is a percentage of the window size.
4201 .It Ic copy-mode-match-style Ar style
4202 Set the style of search matches in copy mode.
4209 .It Ic copy-mode-mark-style Ar style
4210 Set the style of the line containing the mark in copy mode.
4217 .It Ic copy-mode-current-match-style Ar style
4218 Set the style of the current search match in copy mode.
4228 Use vi or emacs-style key bindings in copy mode.
4229 The default is emacs, unless
4236 .It Ic mode-style Ar style
4237 Set window modes style.
4244 .It Xo Ic monitor-activity
4247 Monitor for activity in the window.
4248 Windows with activity are highlighted in the status line.
4250 .It Xo Ic monitor-bell
4253 Monitor for a bell in the window.
4254 Windows with a bell are highlighted in the status line.
4256 .It Xo Ic monitor-silence
4259 Monitor for silence (no activity) in the window within
4262 Windows that have been silent for the interval are highlighted in the
4264 An interval of zero disables the monitoring.
4266 .It Ic other-pane-height Ar height
4267 Set the height of the other panes (not the main pane) in the
4270 If this option is set to 0 (the default), it will have no effect.
4272 .Ic main-pane-height
4274 .Ic other-pane-height
4275 options are set, the main pane will grow taller to make the other panes the
4276 specified height, but will never shrink to do so.
4279 this is a percentage of the window size.
4281 .It Ic other-pane-width Ar width
4283 .Ic other-pane-height ,
4284 but set the width of other panes in the
4288 .It Ic pane-active-border-style Ar style
4289 Set the pane border style for the currently active pane.
4295 Attributes are ignored.
4297 .It Ic pane-base-index Ar index
4300 but set the starting index for pane numbers.
4302 .It Ic pane-border-format Ar format
4303 Set the text shown in pane border status lines.
4305 .It Xo Ic pane-border-indicators
4306 .Op Ic off | colour | arrows | both
4308 Indicate active pane by colouring only half of the border in windows with
4309 exactly two panes, by displaying arrow markers, by drawing both or neither.
4311 .It Ic pane-border-lines Ar type
4312 Set the type of characters used for drawing pane borders.
4317 single lines using ACS or UTF-8 characters
4319 double lines using UTF-8 characters
4321 heavy lines using UTF-8 characters
4323 simple ASCII characters
4331 will fall back to standard ACS line drawing when UTF-8 is not supported.
4333 .It Xo Ic pane-border-status
4334 .Op Ic off | top | bottom
4336 Turn pane border status lines off or set their position.
4338 .It Ic pane-border-style Ar style
4339 Set the pane border style for panes aside from the active pane.
4345 Attributes are ignored.
4347 .It Ic popup-style Ar style
4348 Set the popup style.
4354 Attributes are ignored.
4356 .It Ic popup-border-style Ar style
4357 Set the popup border style.
4363 Attributes are ignored.
4365 .It Ic popup-border-lines Ar type
4366 Set the type of characters used for drawing popup borders.
4371 single lines using ACS or UTF-8 characters (default)
4373 variation of single with rounded corners using UTF-8 characters
4375 double lines using UTF-8 characters
4377 heavy lines using UTF-8 characters
4379 simple ASCII characters
4381 simple ASCII space character
4389 will fall back to standard ACS line drawing when UTF-8 is not supported.
4391 .It Ic window-status-activity-style Ar style
4392 Set status line style for windows with an activity alert.
4399 .It Ic window-status-bell-style Ar style
4400 Set status line style for windows with a bell alert.
4407 .It Ic window-status-current-format Ar string
4409 .Ar window-status-format ,
4410 but is the format used when the window is the current window.
4412 .It Ic window-status-current-style Ar style
4413 Set status line style for the currently active window.
4420 .It Ic window-status-format Ar string
4421 Set the format in which the window is displayed in the status line window list.
4428 .It Ic window-status-last-style Ar style
4429 Set status line style for the last active window.
4436 .It Ic window-status-separator Ar string
4437 Sets the separator drawn between windows in the status line.
4438 The default is a single space character.
4440 .It Ic window-status-style Ar style
4441 Set status line style for a single window.
4448 .It Xo Ic window-size
4449 .Ar largest | Ar smallest | Ar manual | Ar latest
4453 determines the window size.
4456 the size of the largest attached session is used; if
4458 the size of the smallest.
4461 the size of a new window is set from the
4463 option and windows are resized automatically.
4467 uses the size of the client that had the most recent activity.
4471 .Ic aggressive-resize
4474 .It Xo Ic wrap-search
4477 If this option is set, searches will wrap around the end of the pane contents.
4481 Available pane options are:
4483 .Bl -tag -width Ds -compact
4484 .It Xo Ic allow-passthrough
4485 .Op Ic on | off | all
4487 Allow programs in the pane to bypass
4489 using a terminal escape sequence (\eePtmux;...\ee\e\e).
4492 passthrough sequences will be allowed only if the pane is visible.
4495 they will be allowed even if the pane is invisible.
4497 .It Xo Ic allow-rename
4500 Allow programs in the pane to change the window name using a terminal escape
4501 sequence (\eek...\ee\e\e).
4503 .It Xo Ic alternate-screen
4506 This option configures whether programs running inside the pane may use the
4507 terminal alternate screen feature, which allows the
4513 The alternate screen feature preserves the contents of the window when an
4514 interactive application starts and restores it on exit, so that any output
4515 visible before the application starts reappears unchanged after it exits.
4517 .It Ic cursor-colour Ar colour
4518 Set the colour of the cursor.
4520 .It Ic pane-colours[] Ar colour
4521 The default colour palette.
4522 Each entry in the array defines the colour
4524 uses when the colour with that index is requested.
4525 The index may be from zero to 255.
4527 .It Ic cursor-style Ar style
4528 Set the style of the cursor.
4529 Available styles are:
4531 .Ic blinking-block ,
4533 .Ic blinking-underline ,
4538 .It Xo Ic remain-on-exit
4539 .Op Ic on | off | failed
4541 A pane with this flag set is not destroyed when the program running in it
4545 then only when the program exit status is not zero.
4546 The pane may be reactivated with the
4550 .It Ic remain-on-exit-format Ar string
4551 Set the text shown at the bottom of exited panes when
4555 .It Xo Ic scroll-on-clear
4558 When the entire screen is cleared and this option is on, scroll the contents of
4559 the screen into history before clearing it.
4561 .It Xo Ic synchronize-panes
4564 Duplicate input to all other panes in the same window where this option is also
4565 on (only for panes that are not in any mode).
4567 .It Ic window-active-style Ar style
4568 Set the pane style when it is the active pane.
4575 .It Ic window-style Ar style
4585 allows commands to run on various triggers, called
4591 hook and there are a number of hooks not associated with commands.
4593 Hooks are stored as array options, members of the array are executed in
4594 order when the hook is triggered.
4595 Like options different hooks may be global or belong to a session, window or pane.
4596 Hooks may be configured with the
4600 commands and displayed with
4605 The following two commands are equivalent:
4606 .Bd -literal -offset indent.
4607 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
4608 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
4611 Setting a hook without specifying an array index clears the hook and sets the
4612 first member of the array.
4615 hook is run after it completes, except when the command is run as part of a hook
4617 They are named with an
4620 For example, the following command adds a hook to select the even-vertical
4623 .Bd -literal -offset indent
4624 set-hook -g after-split-window "selectl even-vertical"
4627 All the notifications listed in the
4629 section are hooks (without any arguments), except
4631 The following additional hooks are available:
4632 .Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX"
4634 Run when a window has activity.
4636 .Ic monitor-activity .
4638 Run when a window has received a bell.
4642 Run when a window has been silent.
4644 .Ic monitor-silence .
4646 Run when a client becomes the latest active client of its session.
4648 Run when a client is attached.
4650 Run when a client is detached
4652 Run when focus enters a client
4653 .It client-focus-out
4654 Run when focus exits a client
4656 Run when a client is resized.
4657 .It client-session-changed
4658 Run when a client's attached session is changed.
4660 Run when the program running in a pane exits, but
4662 is on so the pane has not closed.
4664 Run when the program running in a pane exits.
4666 Run when the focus enters a pane, if the
4670 Run when the focus exits a pane, if the
4673 .It pane-set-clipboard
4674 Run when the terminal clipboard is set using the
4678 Run when a new session created.
4680 Run when a session closed.
4682 Run when a session is renamed.
4684 Run when a window is linked into a session.
4686 Run when a window is renamed.
4688 Run when a window is resized.
4689 This may be after the
4693 Run when a window is unlinked from a session.
4696 Hooks are managed with these commands:
4700 .Op Fl t Ar target-pane
4712 The flags are the same as for
4720 .It Xo Ic show-hooks
4722 .Op Fl t Ar target-pane
4725 The flags are the same as for
4731 option is on (the default is off),
4733 allows mouse events to be bound as keys.
4734 The name of each key is made up of a mouse event (such as
4736 and a location suffix, one of the following:
4737 .Bl -column "XXXXXXXXXXXXX" -offset indent
4738 .It Li "Pane" Ta "the contents of a pane"
4739 .It Li "Border" Ta "a pane border"
4740 .It Li "Status" Ta "the status line window list"
4741 .It Li "StatusLeft" Ta "the left part of the status line"
4742 .It Li "StatusRight" Ta "the right part of the status line"
4743 .It Li "StatusDefault" Ta "any other part of the status line"
4746 The following mouse events are available:
4747 .Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
4748 .It Li "WheelUp" Ta "WheelDown" Ta ""
4749 .It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
4750 .It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
4751 .It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
4752 .It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3"
4753 .It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3"
4754 .It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3"
4759 events are fired for the second click of a double click, even if there may be a
4760 third click which will fire
4765 Each should be suffixed with a location, for example
4766 .Ql MouseDown1Status .
4776 in commands bound to mouse key bindings.
4777 It resolves to the window or pane over which the mouse event took place
4778 (for example, the window in the status line over which button 1 was released for a
4780 binding, or the pane over which the wheel was scrolled for a
4787 flag may be used to forward a mouse event to a pane.
4789 The default key bindings allow the mouse to be used to select and resize panes,
4790 to copy text and to change window using the status line.
4791 These take effect if the
4793 option is turned on.
4795 Certain commands accept the
4800 This is a string which controls the output format of the command.
4801 Format variables are enclosed in
4806 .Ql #{session_name} .
4807 The possible variables are listed in the table below, or the name of a
4809 option may be used for an option's value.
4810 Some variables have a shorter alias such as
4813 is replaced by a single
4823 Conditionals are available by prefixing with
4825 and separating two alternatives with a comma;
4826 if the specified variable exists and is not zero, the first alternative
4827 is chosen, otherwise the second is used.
4829 .Ql #{?session_attached,attached,not attached}
4830 will include the string
4832 if the session is attached and the string
4834 if it is unattached, or
4835 .Ql #{?automatic-rename,yes,no}
4839 .Ic automatic-rename
4843 Conditionals can be nested arbitrarily.
4844 Inside a conditional,
4852 unless they are part of a
4856 .Bd -literal -offset indent
4857 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
4860 String comparisons may be expressed by prefixing two comma-separated
4871 .Ql #{==:#{host},myhost}
4881 evaluate to true if either or both of two comma-separated alternatives are
4883 .Ql #{||:#{pane_in_mode},#{alternate_on}} .
4889 or regular expression comparison.
4890 The first argument is the pattern and the second the string to compare.
4891 An optional argument specifies flags:
4893 means the pattern is a regular expression instead of the default
4897 means to ignore case.
4899 .Ql #{m:*foo*,#{host}}
4901 .Ql #{m/ri:^A,MYVAR} .
4904 performs a search for an
4906 pattern or regular expression in the pane content and evaluates to zero if not
4907 found, or a line number if found.
4912 flag means search for a regular expression and
4918 Numeric operators may be performed by prefixing two comma-separated alternatives with an
4923 flag may be given after the operator to use floating point numbers, otherwise integers are used.
4924 This may be followed by a number giving the number of decimal places to use for the result.
4925 The available operators are:
4942 in formats which are also expanded by
4944 and numeric comparison operators
4953 .Ql #{e|*|f|4:5.5,3}
4954 multiplies 5.5 by 3 for a result with four decimal places and
4956 returns the modulus of 7 and 3.
4958 replaces a numeric argument by its ASCII equivalent, so
4965 colour by its six-digit hexadecimal RGB value.
4967 A limit may be placed on the length of the resultant string by prefixing it
4970 a number and a colon.
4971 Positive numbers count from the start of the string and negative from the end,
4973 .Ql #{=5:pane_title}
4974 will include at most the first five characters of the pane title, or
4975 .Ql #{=-5:pane_title}
4976 the last five characters.
4977 A suffix or prefix may be given as a second argument - if provided then it is
4978 appended or prepended to the string if the length has been trimmed, for example
4979 .Ql #{=/5/...:pane_title}
4982 if the pane title is more than five characters.
4985 pads the string to a given width, for example
4986 .Ql #{p10:pane_title}
4987 will result in a width of at least 10 characters.
4988 A positive width pads on the left, a negative on the right.
4990 expands to the length of the variable and
4992 to its width when displayed, for example
4993 .Ql #{n:window_name} .
4995 Prefixing a time variable with
4997 will convert it to a string, so if
4998 .Ql #{window_activity}
5001 .Ql #{t:window_activity}
5003 .Ql Sun Oct 25 09:25:02 2015 .
5007 will use shorter but less accurate time format for times in the past.
5008 A custom format may be given using an
5014 if the format is separately being passed through
5019 .Ql #{t/f/%%H#:%%M:window_activity} ,
5031 of the variable respectively.
5035 special characters or with a
5037 suffix, escape hash characters (so
5042 will expand the format twice, for example
5043 .Ql #{E:status-left}
5044 is the result of expanding the content of the
5046 option rather than the option itself.
5057 will loop over each session, window or pane and insert the format once
5059 For windows and panes, two comma-separated formats may be given:
5060 the second is used for the current window or active pane.
5061 For example, to get a list of windows formatted like the status line:
5062 .Bd -literal -offset indent
5063 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
5067 checks if a window (without any suffix or with the
5069 suffix) or a session (with the
5071 suffix) name exists, for example
5073 is replaced with 1 if a window named
5077 A prefix of the form
5084 The first argument may be an extended regular expression and a final argument may be
5086 to ignore case, for example
5087 .Ql s/a(.)/\e1x/i:\&
5092 A different delimiter character may also be used, to avoid collisions with
5093 literal slashes in the pattern.
5102 In addition, the last line of a shell command's output may be inserted using
5106 will insert the system's uptime.
5107 When constructing formats,
5111 commands to finish; instead, the previous result from running the same command is used,
5112 or a placeholder if the command has not been run before.
5113 If the command hasn't exited, the most recent line of output will be used, but the status
5114 line will not be updated more than once a second.
5115 Commands are executed using
5119 global environment set (see the
5120 .Sx GLOBAL AND SESSION ENVIRONMENT
5125 specifies that a string should be interpreted literally and not expanded.
5127 .Ql #{l:#{?pane_in_mode,yes,no}}
5129 .Ql #{?pane_in_mode,yes,no} .
5131 The following variables are available, where appropriate:
5132 .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
5133 .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
5134 .It Li "active_window_index" Ta "" Ta "Index of active window in session"
5135 .It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen"
5136 .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
5137 .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
5138 .It Li "buffer_created" Ta "" Ta "Time buffer created"
5139 .It Li "buffer_name" Ta "" Ta "Name of buffer"
5140 .It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
5141 .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
5142 .It Li "client_activity" Ta "" Ta "Time client last had activity"
5143 .It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels"
5144 .It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels"
5145 .It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
5146 .It Li "client_created" Ta "" Ta "Time client created"
5147 .It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind"
5148 .It Li "client_flags" Ta "" Ta "List of client flags"
5149 .It Li "client_height" Ta "" Ta "Height of client"
5150 .It Li "client_key_table" Ta "" Ta "Current key table"
5151 .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
5152 .It Li "client_name" Ta "" Ta "Name of client"
5153 .It Li "client_pid" Ta "" Ta "PID of client process"
5154 .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
5155 .It Li "client_readonly" Ta "" Ta "1 if client is read-only"
5156 .It Li "client_session" Ta "" Ta "Name of the client's session"
5157 .It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any"
5158 .It Li "client_termname" Ta "" Ta "Terminal name of client"
5159 .It Li "client_termtype" Ta "" Ta "Terminal type of client, if available"
5160 .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
5161 .It Li "client_uid" Ta "" Ta "UID of client process"
5162 .It Li "client_user" Ta "" Ta "User of client process"
5163 .It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8"
5164 .It Li "client_width" Ta "" Ta "Width of client"
5165 .It Li "client_written" Ta "" Ta "Bytes written to client"
5166 .It Li "command" Ta "" Ta "Name of command in use, if any"
5167 .It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
5168 .It Li "command_list_name" Ta "" Ta "Command name if listing commands"
5169 .It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
5170 .It Li "config_files" Ta "" Ta "List of configuration files loaded"
5171 .It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode"
5172 .It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode"
5173 .It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode"
5174 .It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode"
5175 .It Li "current_file" Ta "" Ta "Current configuration file"
5176 .It Li "cursor_character" Ta "" Ta "Character at cursor in pane"
5177 .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
5178 .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
5179 .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
5180 .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
5181 .It Li "history_limit" Ta "" Ta "Maximum window history lines"
5182 .It Li "history_size" Ta "" Ta "Size of history in lines"
5183 .It Li "hook" Ta "" Ta "Name of running hook, if any"
5184 .It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any"
5185 .It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
5186 .It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
5187 .It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
5188 .It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
5189 .It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
5190 .It Li "host" Ta "#H" Ta "Hostname of local host"
5191 .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
5192 .It Li "insert_flag" Ta "" Ta "Pane insert flag"
5193 .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
5194 .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
5195 .It Li "last_window_index" Ta "" Ta "Index of last window in session"
5196 .It Li "line" Ta "" Ta "Line number in the list"
5197 .It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
5198 .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
5199 .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
5200 .It Li "mouse_hyperlink" Ta "" Ta "Hyperlink under mouse, if any"
5201 .It Li "mouse_line" Ta "" Ta "Line under mouse, if any"
5202 .It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag"
5203 .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
5204 .It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag"
5205 .It Li "mouse_word" Ta "" Ta "Word under mouse, if any"
5206 .It Li "mouse_x" Ta "" Ta "Mouse X position, if any"
5207 .It Li "mouse_y" Ta "" Ta "Mouse Y position, if any"
5208 .It Li "next_session_id" Ta "" Ta "Unique session ID for next new session"
5209 .It Li "origin_flag" Ta "" Ta "Pane origin flag"
5210 .It Li "pane_active" Ta "" Ta "1 if active pane"
5211 .It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window"
5212 .It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window"
5213 .It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window"
5214 .It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window"
5215 .It Li "pane_bg" Ta "" Ta "Pane background colour"
5216 .It Li "pane_bottom" Ta "" Ta "Bottom of pane"
5217 .It Li "pane_current_command" Ta "" Ta "Current command if available"
5218 .It Li "pane_current_path" Ta "" Ta "Current path if available"
5219 .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
5220 .It Li "pane_dead_signal" Ta "" Ta "Exit signal of process in dead pane"
5221 .It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
5222 .It Li "pane_dead_time" Ta "" Ta "Exit time of process in dead pane"
5223 .It Li "pane_fg" Ta "" Ta "Pane foreground colour"
5224 .It Li "pane_format" Ta "" Ta "1 if format is for a pane"
5225 .It Li "pane_height" Ta "" Ta "Height of pane"
5226 .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
5227 .It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode"
5228 .It Li "pane_index" Ta "#P" Ta "Index of pane"
5229 .It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled"
5230 .It Li "pane_last" Ta "" Ta "1 if last pane"
5231 .It Li "pane_left" Ta "" Ta "Left of pane"
5232 .It Li "pane_marked" Ta "" Ta "1 if this is the marked pane"
5233 .It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set"
5234 .It Li "pane_mode" Ta "" Ta "Name of pane mode, if any"
5235 .It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)"
5236 .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
5237 .It Li "pane_pipe" Ta "" Ta "1 if pane is being piped"
5238 .It Li "pane_right" Ta "" Ta "Right of pane"
5239 .It Li "pane_search_string" Ta "" Ta "Last search string in copy mode"
5240 .It Li "pane_start_command" Ta "" Ta "Command pane started with"
5241 .It Li "pane_start_path" Ta "" Ta "Path pane started with"
5242 .It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized"
5243 .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
5244 .It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)"
5245 .It Li "pane_top" Ta "" Ta "Top of pane"
5246 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
5247 .It Li "pane_width" Ta "" Ta "Width of pane"
5248 .It Li "pid" Ta "" Ta "Server PID"
5249 .It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated"
5250 .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
5251 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
5252 .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
5253 .It Li "search_match" Ta "" Ta "Search match if any"
5254 .It Li "search_present" Ta "" Ta "1 if search started in copy mode"
5255 .It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode"
5256 .It Li "selection_end_x" Ta "" Ta "X position of the end of the selection"
5257 .It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection"
5258 .It Li "selection_present" Ta "" Ta "1 if selection started in copy mode"
5259 .It Li "selection_start_x" Ta "" Ta "X position of the start of the selection"
5260 .It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection"
5261 .It Li "session_activity" Ta "" Ta "Time of session last activity"
5262 .It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
5263 .It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
5264 .It Li "session_attached_list" Ta "" Ta "List of clients session is attached to"
5265 .It Li "session_created" Ta "" Ta "Time session created"
5266 .It Li "session_format" Ta "" Ta "1 if format is for a session"
5267 .It Li "session_group" Ta "" Ta "Name of session group"
5268 .It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to"
5269 .It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to"
5270 .It Li "session_group_list" Ta "" Ta "List of sessions in group"
5271 .It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group"
5272 .It Li "session_group_size" Ta "" Ta "Size of session group"
5273 .It Li "session_grouped" Ta "" Ta "1 if session in a group"
5274 .It Li "session_id" Ta "" Ta "Unique session ID"
5275 .It Li "session_last_attached" Ta "" Ta "Time session last attached"
5276 .It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
5277 .It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane"
5278 .It Li "session_name" Ta "#S" Ta "Name of session"
5279 .It Li "session_path" Ta "" Ta "Working directory of session"
5280 .It Li "session_stack" Ta "" Ta "Window indexes in most recent order"
5281 .It Li "session_windows" Ta "" Ta "Number of windows in session"
5282 .It Li "socket_path" Ta "" Ta "Server socket path"
5283 .It Li "start_time" Ta "" Ta "Server start time"
5284 .It Li "uid" Ta "" Ta "Server UID"
5285 .It Li "user" Ta "" Ta "Server user"
5286 .It Li "version" Ta "" Ta "Server version"
5287 .It Li "window_active" Ta "" Ta "1 if window active"
5288 .It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window"
5289 .It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window"
5290 .It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active"
5291 .It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active"
5292 .It Li "window_activity" Ta "" Ta "Time of window last activity"
5293 .It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
5294 .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
5295 .It Li "window_bigger" Ta "" Ta "1 if window is larger than client"
5296 .It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels"
5297 .It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels"
5298 .It Li "window_end_flag" Ta "" Ta "1 if window has the highest index"
5299 .It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##"
5300 .It Li "window_format" Ta "" Ta "1 if format is for a window"
5301 .It Li "window_height" Ta "" Ta "Height of window"
5302 .It Li "window_id" Ta "" Ta "Unique window ID"
5303 .It Li "window_index" Ta "#I" Ta "Index of window"
5304 .It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
5305 .It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
5306 .It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
5307 .It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to"
5308 .It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to"
5309 .It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane"
5310 .It Li "window_name" Ta "#W" Ta "Name of window"
5311 .It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client"
5312 .It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client"
5313 .It Li "window_panes" Ta "" Ta "Number of panes in window"
5314 .It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped"
5315 .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
5316 .It Li "window_stack_index" Ta "" Ta "Index in session most recent stack"
5317 .It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index"
5318 .It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
5319 .It Li "window_width" Ta "" Ta "Width of window"
5320 .It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
5321 .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
5325 offers various options to specify the colour and attributes of aspects of the
5326 interface, for example
5328 for the status line.
5329 In addition, embedded styles may be specified in format options, such as
5331 by enclosing them in
5336 A style may be the single term
5338 to specify the default style (which may come from an option, for example
5340 in the status line) or a space
5341 or comma separated list of the following:
5344 Set the foreground colour.
5345 The colour is one of:
5354 if supported the bright variants
5361 from the 256-colour set;
5363 for the default colour;
5365 for the terminal default colour; or a hexadecimal RGB string such as
5368 Set the background colour.
5370 Set no attributes (turn off any active attributes).
5383 .Ic double-underscore ,
5384 .Ic curly-underscore ,
5385 .Ic dotted-underscore ,
5386 .Ic dashed-underscore
5389 Any of the attributes may be prefixed with
5393 is the terminal alternate character set.
5394 .It Xo Ic align=left
5400 Align text to the left, centre or right of the available space if appropriate.
5402 Fill the available space with a background colour if appropriate.
5405 .Ic list=left-marker ,
5406 .Ic list=right-marker ,
5409 Mark the position of the various window list components in the
5413 marks the start of the list;
5415 is the part of the list that should be kept in focus if the entire list won't fit
5416 in the available space (typically the current window);
5417 .Ic list=left-marker
5419 .Ic list=right-marker
5420 mark the text to be used to mark that text has been trimmed from the left or
5421 right of the list if there is not enough space.
5422 .It Xo Ic push-default ,
5425 Store the current colours and attributes as the default or reset to the previous
5429 affects any subsequent use of the
5433 Only one default may be pushed (each
5435 replaces the previous saved default).
5436 .It Xo Ic range=left ,
5438 .Ic range=window|X ,
5447 are the text used for the
5453 is the range for a window passed to the
5461 .Bd -literal -offset indent
5462 fg=yellow bold underscore blink
5463 bg=black,fg=default,noreverse
5465 .Sh NAMES AND TITLES
5467 distinguishes between names and titles.
5468 Windows and sessions have names, which may be used to specify them in targets
5469 and are displayed in the status line and various lists: the name is the
5471 identifier for a window or session.
5472 Only panes have titles.
5473 A pane's title is typically set by the program running inside the pane using
5474 an escape sequence (like it would set the
5478 Windows themselves do not have titles - a window's title is the title of its
5481 itself may set the title of the terminal in which the client is running, see
5486 A session's name is set with the
5491 A window's name is set with one of:
5494 A command argument (such as
5501 An escape sequence (if the
5503 option is turned on):
5504 .Bd -literal -offset indent
5505 $ printf '\e033kWINDOW_NAME\e033\e\e'
5508 Automatic renaming, which sets the name to the active command in the window's
5511 .Ic automatic-rename
5515 When a pane is first created, its title is the hostname.
5516 A pane's title can be set via the title setting escape sequence, for example:
5517 .Bd -literal -offset indent
5518 $ printf '\e033]2;My Title\e033\e\e'
5521 It can also be modified with the
5525 .Sh GLOBAL AND SESSION ENVIRONMENT
5526 When the server is started,
5528 copies the environment into the
5529 .Em global environment ;
5530 in addition, each session has a
5531 .Em session environment .
5532 When a window is created, the session and global environments are merged.
5533 If a variable exists in both, the value from the session environment is used.
5534 The result is the initial environment passed to the new process.
5537 .Ic update-environment
5538 session option may be used to update the session environment from the client
5539 when a new session is created or an old reattached.
5541 also initialises the
5543 variable with some internal information to allow commands to be executed
5544 from inside, and the
5546 variable with the correct terminal setting of
5549 Variables in both session and global environments may be marked as hidden.
5550 Hidden variables are not passed into the environment of new processes and
5551 instead can only be used by tmux itself (for example in formats, see the
5555 Commands to alter and view the environment are:
5558 .It Xo Ic set-environment
5560 .Op Fl t Ar target-session
5561 .Ar name Op Ar value
5563 .D1 Pq alias: Ic setenv
5564 Set or unset an environment variable.
5567 is used, the change is made in the global environment; otherwise, it is applied
5568 to the session environment for
5569 .Ar target-session .
5574 is expanded as a format.
5577 flag unsets a variable.
5579 indicates the variable is to be removed from the environment before starting a
5582 marks the variable as hidden.
5584 .It Xo Ic show-environment
5586 .Op Fl t Ar target-session
5589 .D1 Pq alias: Ic showenv
5590 Display the environment for
5592 or the global environment with
5596 is omitted, all variables are shown.
5597 Variables removed from the environment are prefixed with
5601 is used, the output is formatted as a set of Bourne shell commands.
5603 shows hidden variables (omitted by default).
5607 includes an optional status line which is displayed in the bottom line of each
5610 By default, the status line is enabled and one line in height (it may be
5611 disabled or made multiple lines with the
5613 session option) and contains, from left-to-right: the name of the current
5614 session in square brackets; the window list; the title of the active pane
5615 in double quotes; and the time and date.
5617 Each line of the status line is configured with the
5620 The default is made of three parts: configurable left and right sections (which
5621 may contain dynamic content such as the time or output from a shell command,
5624 .Ic status-left-length ,
5627 .Ic status-right-length
5628 options below), and a central window list.
5629 By default, the window list shows the index, name and (if any) flag of the
5630 windows present in the current session in ascending numerical order.
5631 It may be customised with the
5632 .Ar window-status-format
5634 .Ar window-status-current-format
5636 The flag is one of the following symbols appended to the window name:
5637 .Bl -column "Symbol" "Meaning" -offset indent
5638 .It Sy "Symbol" Ta Sy "Meaning"
5639 .It Li "*" Ta "Denotes the current window."
5640 .It Li "-" Ta "Marks the last window (previously selected)."
5641 .It Li "#" Ta "Window activity is monitored and activity has been detected."
5642 .It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window."
5643 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
5644 .It Li "M" Ta "The window contains the marked pane."
5645 .It Li "Z" Ta "The window's active pane is zoomed."
5648 The # symbol relates to the
5649 .Ic monitor-activity
5651 The window name is printed in inverted colours if an alert (bell, activity or
5652 silence) is present.
5654 The colour and attributes of the status line may be configured, the entire
5655 status line using the
5657 session option and individual windows using the
5658 .Ic window-status-style
5661 The status line is automatically refreshed at interval if it has changed, the
5662 interval may be controlled with the
5666 Commands related to the status line are as follows:
5669 .It Xo Ic clear-prompt-history
5670 .Op Fl T Ar prompt-type
5672 .D1 Pq alias: Ic clearphist
5673 Clear status prompt history for prompt type
5677 is omitted, then clear history for all types.
5680 for possible values for
5682 .It Xo Ic command-prompt
5686 .Op Fl t Ar target-client
5687 .Op Fl T Ar prompt-type
5690 Open the command prompt in a client.
5691 This may be used from inside
5693 to execute commands interactively.
5697 is specified, it is used as the command.
5701 is expanded as a format.
5705 is a comma-separated list of the initial text for each prompt.
5710 is a comma-separated list of prompts which are displayed in order; otherwise
5711 a single prompt is displayed, constructed from
5713 if it is present, or
5717 Before the command is executed, the first occurrence of the string
5719 and all occurrences of
5721 are replaced by the response to the first prompt, all
5723 are replaced with the response to the second prompt, and so on for further
5725 Up to nine prompt responses may be replaced
5734 but any quotation marks are escaped.
5737 makes the prompt only accept one key press, in this case the resulting input
5738 is a single character.
5742 but the key press is translated to a key name.
5744 makes the prompt only accept numeric key presses.
5746 executes the command every time the prompt input changes instead of when the
5747 user exits the command prompt.
5753 This affects what completions are offered when
5756 Available types are:
5763 The following keys have a special meaning in the command prompt, depending
5767 .Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
5768 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
5769 .It Li "Cancel command prompt" Ta "q" Ta "Escape"
5770 .It Li "Delete from cursor to start of word" Ta "" Ta "C-w"
5771 .It Li "Delete entire command" Ta "d" Ta "C-u"
5772 .It Li "Delete from cursor to end" Ta "D" Ta "C-k"
5773 .It Li "Execute command" Ta "Enter" Ta "Enter"
5774 .It Li "Get next command from history" Ta "" Ta "Down"
5775 .It Li "Get previous command from history" Ta "" Ta "Up"
5776 .It Li "Insert top paste buffer" Ta "p" Ta "C-y"
5777 .It Li "Look for completions" Ta "Tab" Ta "Tab"
5778 .It Li "Move cursor left" Ta "h" Ta "Left"
5779 .It Li "Move cursor right" Ta "l" Ta "Right"
5780 .It Li "Move cursor to end" Ta "$" Ta "C-e"
5781 .It Li "Move cursor to next word" Ta "w" Ta "M-f"
5782 .It Li "Move cursor to previous word" Ta "b" Ta "M-b"
5783 .It Li "Move cursor to start" Ta "0" Ta "C-a"
5784 .It Li "Transpose characters" Ta "" Ta "C-t"
5789 the prompt is shown in the background and the invoking client does not exit
5790 until it is dismissed.
5792 .It Xo Ic confirm-before
5795 .Op Fl t Ar target-client
5798 .D1 Pq alias: Ic confirm
5799 Ask for confirmation before executing
5805 is the prompt to display; otherwise a prompt is constructed from
5807 It may contain the special character sequences supported by the
5812 the prompt is shown in the background and the invoking client does not exit
5813 until it is dismissed.
5815 .It Xo Ic display-menu
5817 .Op Fl c Ar target-client
5818 .Op Fl t Ar target-pane
5820 .Op Fl x Ar position
5821 .Op Fl y Ar position
5827 .D1 Pq alias: Ic menu
5831 gives the target for any commands run from the menu.
5833 A menu is passed as a series of arguments: first the menu item name,
5834 second the key shortcut (or empty for none) and third the command
5835 to run when the menu item is chosen.
5836 The name and command are formats, see the
5841 If the name begins with a hyphen (-), then the item is disabled (shown dim) and
5843 The name may be empty for a separator line, in which case both the key and
5844 command should be omitted.
5847 is a format for the menu title (see
5853 give the position of the menu.
5854 Both may be a row or column number, or one of the following special values:
5855 .Bl -column "XXXXX" "XXXX" -offset indent
5856 .It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning"
5857 .It Li "C" Ta "Both" Ta "The centre of the terminal"
5858 .It Li "R" Ta Fl x Ta "The right side of the terminal"
5859 .It Li "P" Ta "Both" Ta "The bottom left of the pane"
5860 .It Li "M" Ta "Both" Ta "The mouse position"
5861 .It Li "W" Ta "Both" Ta "The window position on the status line"
5862 .It Li "S" Ta Fl y Ta "The line above or below the status line"
5865 Or a format, which is expanded including the following additional variables:
5866 .Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
5867 .It Sy "Variable name" Ta Sy "Replaced with"
5868 .It Li "popup_centre_x" Ta "Centered in the client"
5869 .It Li "popup_centre_y" Ta "Centered in the client"
5870 .It Li "popup_height" Ta "Height of menu or popup"
5871 .It Li "popup_mouse_bottom" Ta "Bottom of at the mouse"
5872 .It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse"
5873 .It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse"
5874 .It Li "popup_mouse_top" Ta "Top at the mouse"
5875 .It Li "popup_mouse_x" Ta "Mouse X position"
5876 .It Li "popup_mouse_y" Ta "Mouse Y position"
5877 .It Li "popup_pane_bottom" Ta "Bottom of the pane"
5878 .It Li "popup_pane_left" Ta "Left of the pane"
5879 .It Li "popup_pane_right" Ta "Right of the pane"
5880 .It Li "popup_pane_top" Ta "Top of the pane"
5881 .It Li "popup_status_line_y" Ta "Above or below the status line"
5882 .It Li "popup_width" Ta "Width of menu or popup"
5883 .It Li "popup_window_status_line_x" Ta "At the window position in status line"
5884 .It Li "popup_window_status_line_y" Ta "At the status line showing the window"
5887 Each menu consists of items followed by a key shortcut shown in brackets.
5888 If the menu is too large to fit on the terminal, it is not displayed.
5889 Pressing the key shortcut chooses the corresponding item.
5890 If the mouse is enabled and the menu is opened from a mouse key binding,
5891 releasing the mouse button with an item selected chooses that item and
5892 releasing the mouse button without an item selected closes the menu.
5894 changes this behaviour so that the menu does not close when the mouse button is
5895 released without an item selected the menu is not closed and a mouse button
5896 must be clicked to choose an item.
5898 The following keys are also available:
5899 .Bl -column "Key" "Function" -offset indent
5900 .It Sy "Key" Ta Sy "Function"
5901 .It Li "Enter" Ta "Choose selected item"
5902 .It Li "Up" Ta "Select previous item"
5903 .It Li "Down" Ta "Select next item"
5904 .It Li "q" Ta "Exit menu"
5907 .It Xo Ic display-message
5909 .Op Fl c Ar target-client
5911 .Op Fl t Ar target-pane
5914 .D1 Pq alias: Ic display
5918 is given, the output is printed to stdout, otherwise it is displayed in the
5920 status line for up to
5927 option is used; a delay of zero waits for a key press.
5929 ignores key presses and closes only after the delay expires.
5934 is printed unchanged.
5935 Otherwise, the format of
5939 section; information is taken from
5943 is given, otherwise the active pane.
5946 prints verbose logging as the format is parsed and
5948 lists the format variables and their values.
5951 forwards any input read from stdin to the empty pane given by
5954 .It Xo Ic display-popup
5956 .Op Fl b Ar border-lines
5957 .Op Fl c Ar target-client
5958 .Op Fl d Ar start-directory
5959 .Op Fl e Ar environment
5962 .Op Fl S Ar border-style
5963 .Op Fl t Ar target-pane
5966 .Op Fl x Ar position
5967 .Op Fl y Ar position
5968 .Op Ar shell-command
5970 .D1 Pq alias: Ic popup
5971 Display a popup running
5975 A popup is a rectangular box drawn over the top of any panes.
5976 Panes are not updated while a popup is present.
5979 closes the popup automatically when
5984 closes the popup only if
5986 exited with success.
5991 give the position of the popup, they have the same meaning as for the
5997 give the width and height - both may be a percentage (followed by
5999 If omitted, half of the terminal size is used.
6002 does not surround the popup by a border.
6005 sets the type of border line for the popup.
6012 .Ic popup-border-lines
6013 for possible values for
6017 sets the style for the popup and
6019 sets the style for the popup border.
6029 and sets an environment variable for the popup; it may be specified multiple
6033 is a format for the popup title (see
6038 flag closes any popup on the client.
6040 .It Xo Ic show-prompt-history
6041 .Op Fl T Ar prompt-type
6043 .D1 Pq alias: Ic showphist
6044 Display status prompt history for prompt type
6048 is omitted, then show history for all types.
6051 for possible values for
6056 maintains a set of named
6058 Each buffer may be either explicitly or automatically named.
6059 Explicitly named buffers are named when created with the
6063 commands, or by renaming an automatically named buffer with
6066 Automatically named buffers are given a name such as
6072 option is reached, the oldest automatically named buffer is deleted.
6073 Explicitly named buffers are not subject to
6075 and may be deleted with the
6079 Buffers may be added using
6085 commands, and pasted into a window using the
6088 If a buffer command is used and no buffer is specified, the most
6089 recently added automatically named buffer is assumed.
6091 A configurable history buffer is also maintained for each window.
6092 By default, up to 2000 lines are kept; this can be altered with the
6098 The buffer commands are as follows:
6105 .Op Fl K Ar key-format
6106 .Op Fl O Ar sort-order
6107 .Op Fl t Ar target-pane
6110 Put a pane into buffer mode, where a buffer may be chosen interactively from
6112 Each buffer is shown on one line.
6113 A shortcut key is shown on the left in brackets allowing for immediate choice,
6114 or the list may be navigated and an item chosen or otherwise manipulated using
6118 The following keys may be used in buffer mode:
6119 .Bl -column "Key" "Function" -offset indent
6120 .It Sy "Key" Ta Sy "Function"
6121 .It Li "Enter" Ta "Paste selected buffer"
6122 .It Li "Up" Ta "Select previous buffer"
6123 .It Li "Down" Ta "Select next buffer"
6124 .It Li "C-s" Ta "Search by name or content"
6125 .It Li "n" Ta "Repeat last search"
6126 .It Li "t" Ta "Toggle if buffer is tagged"
6127 .It Li "T" Ta "Tag no buffers"
6128 .It Li "C-t" Ta "Tag all buffers"
6129 .It Li "p" Ta "Paste selected buffer"
6130 .It Li "P" Ta "Paste tagged buffers"
6131 .It Li "d" Ta "Delete selected buffer"
6132 .It Li "D" Ta "Delete tagged buffers"
6133 .It Li "e" Ta "Open the buffer in an editor"
6134 .It Li "f" Ta "Enter a format to filter items"
6135 .It Li "O" Ta "Change sort field"
6136 .It Li "r" Ta "Reverse sort order"
6137 .It Li "v" Ta "Toggle preview"
6138 .It Li "q" Ta "Exit mode"
6141 After a buffer is chosen,
6143 is replaced by the buffer name in
6145 and the result executed as a command.
6148 is not given, "paste-buffer -b '%%'" is used.
6151 specifies the initial sort field: one of
6158 reverses the sort order.
6160 specifies an initial filter: the filter is a format - if it evaluates to zero,
6161 the item in the list is not shown, otherwise it is shown.
6162 If a filter would lead to an empty list, it is ignored.
6164 specifies the format for each item in the list and
6166 a format for each shortcut key; both are evaluated once for each line.
6168 starts without the preview.
6169 This command works only if at least one client is attached.
6171 .It Xo Ic clear-history
6173 .Op Fl t Ar target-pane
6175 .D1 Pq alias: Ic clearhist
6176 Remove and free the history for the specified pane.
6178 also removes all hyperlinks.
6180 .It Ic delete-buffer Op Fl b Ar buffer-name
6181 .D1 Pq alias: Ic deleteb
6182 Delete the buffer named
6184 or the most recently added automatically named buffer if not specified.
6186 .It Xo Ic list-buffers
6190 .D1 Pq alias: Ic lsb
6191 List the global buffers.
6193 specifies the format of each line and
6196 Only buffers for which the filter is true are shown.
6200 .It Xo Ic load-buffer
6202 .Op Fl b Ar buffer-name
6203 .Op Fl t Ar target-client
6207 .D1 Pq alias: Ic loadb
6208 Load the contents of the specified paste buffer from
6212 is given, the buffer is also sent to the clipboard for
6216 escape sequence, if possible.
6218 .It Xo Ic paste-buffer
6220 .Op Fl b Ar buffer-name
6221 .Op Fl s Ar separator
6222 .Op Fl t Ar target-pane
6224 .D1 Pq alias: Ic pasteb
6225 Insert the contents of a paste buffer into the specified pane.
6226 If not specified, paste into the current one.
6229 also delete the paste buffer.
6230 When output, any linefeed (LF) characters in the paste buffer are replaced with
6231 a separator, by default carriage return (CR).
6232 A custom separator may be specified using the
6237 flag means to do no replacement (equivalent to a separator of LF).
6240 is specified, paste bracket control codes are inserted around the
6241 buffer if the application has requested bracketed paste mode.
6243 .It Xo Ic save-buffer
6245 .Op Fl b Ar buffer-name
6248 .D1 Pq alias: Ic saveb
6249 Save the contents of the specified paste buffer to
6253 option appends to rather than overwriting the file.
6254 .It Xo Ic set-buffer
6256 .Op Fl b Ar buffer-name
6257 .Op Fl t Ar target-client
6259 .Op Fl n Ar new-buffer-name
6262 .D1 Pq alias: Ic setb
6263 Set the contents of the specified buffer to
6267 is given, the buffer is also sent to the clipboard for
6271 escape sequence, if possible.
6274 option appends to rather than overwriting the buffer.
6277 option renames the buffer to
6278 .Ar new-buffer-name .
6280 .It Xo Ic show-buffer
6281 .Op Fl b Ar buffer-name
6283 .D1 Pq alias: Ic showb
6284 Display the contents of the specified buffer.
6287 Miscellaneous commands are as follows:
6289 .It Ic clock-mode Op Fl t Ar target-pane
6290 Display a large clock.
6294 .Op Fl t Ar target-pane
6295 .Ar shell-command command
6305 returns success or the second
6308 Before being executed,
6310 is expanded using the rules specified in the
6312 section, including those relevant to
6317 is run in the background.
6323 is not executed but considered success if neither empty nor zero (after formats
6327 .D1 Pq alias: Ic lock
6328 Lock each client individually by running the command specified by the
6335 .Op Fl t Ar target-pane
6336 .Op Ar shell-command
6338 .D1 Pq alias: Ic run
6347 command in the background without creating a window.
6348 Before being executed,
6350 is expanded using the rules specified in the
6355 the command is run in the background.
6359 seconds before starting the command.
6362 is not given, any output to stdout is displayed in view mode (in the pane
6365 or the current pane if omitted) after the command finishes.
6366 If the command fails, the exit status is also displayed.
6372 .D1 Pq alias: Ic wait
6373 When used without options, prevents the client from exiting until woken using
6376 with the same channel.
6379 is used, the channel is locked and any clients that try to lock the same
6380 channel are made to wait until the channel is unlocked with
6387 client detaches, it prints a message.
6390 .It detached (from session ...)
6391 The client was detached normally.
6392 .It detached and SIGHUP
6393 The client was detached and its parent sent the
6395 signal (for example with
6403 was unexpectedly destroyed.
6405 The client was killed with
6408 The client is in control mode and became unable to keep up with the data from
6411 The server exited when it had no sessions.
6413 The server exited when it received
6415 .It server exited unexpectedly
6416 The server crashed or otherwise exited without telling the client the reason.
6418 .Sh TERMINFO EXTENSIONS
6420 understands some unofficial extensions to
6422 It is not normally necessary to set these manually, instead the
6423 .Ic terminal-features
6424 option should be used.
6427 An existing extension that tells
6429 the terminal supports default colours.
6433 that the terminal supports the VTE bidirectional text extensions.
6435 Set the cursor colour.
6436 The first takes a single string argument and is used to set the colour;
6437 the second takes no arguments and restores the default cursor colour.
6438 If set, a sequence such as this may be used
6439 to change the cursor colour from inside
6441 .Bd -literal -offset indent
6442 $ printf '\e033]12;red\e033\e\e'
6449 .It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg
6450 Set, clear, disable or enable DECSLRM margins.
6451 These are set automatically if the terminal reports it is
6454 .It Em \&Dsbp , \&Enbp
6455 Disable and enable bracketed paste.
6456 These are set automatically if the
6458 capability is present.
6459 .It Em \&Dseks , \&Eneks
6460 Disable and enable extended keys.
6461 .It Em \&Dsfcs , \&Enfcs
6462 Disable and enable focus reporting.
6463 These are set automatically if the
6465 capability is present.
6467 Set or clear a hyperlink annotation.
6471 that the terminal does not use bright colors for bold display.
6475 that the terminal supports rectangle operations.
6477 Enable the overline attribute.
6479 Set a styled underscore.
6480 The single parameter is one of: 0 for no underscore, 1 for normal
6481 underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted
6482 underscore and 5 for dashed underscore.
6483 .It Em \&Setulc , \&ol
6484 Set the underscore colour or reset to the default.
6485 The argument is (red * 65536) + (green * 256) + blue where each is between 0
6488 Set or reset the cursor style.
6489 If set, a sequence such as this may be used
6490 to change the cursor to an underline:
6491 .Bd -literal -offset indent
6492 $ printf '\e033[4 q'
6497 is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
6499 Set the opening sequence for the working directory notification.
6500 The sequence is terminated using the standard
6504 Indicates that the terminal supports SIXEL.
6506 Start (parameter is 1) or end (parameter is 2) a synchronized update.
6508 Indicate that the terminal supports the
6510 RGB escape sequence (for example, \ee[38;2;255;255;255m).
6512 If supported, this is used for the initialize colour escape sequence (which
6513 may be enabled by adding the
6522 This is equivalent to the
6527 Store the current buffer in the host terminal's selection (clipboard).
6530 option above and the
6534 This is an existing extension capability that tmux uses to mean that the
6535 terminal supports the
6537 title set sequences and to automatically set some of the capabilities above.
6541 offers a textual interface called
6543 This allows applications to communicate with
6545 using a simple text-only protocol.
6547 In control mode, a client sends
6549 commands or command sequences terminated by newlines on standard input.
6550 Each command will produce one block of output on standard output.
6551 An output block consists of a
6553 line followed by the output (which may be empty).
6554 The output block ends with a
6563 have three arguments: an integer time (as seconds from epoch), command number and
6564 flags (currently not used).
6566 .Bd -literal -offset indent
6567 %begin 1363006971 2 1
6568 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
6575 command may be used to set the size of a client in control mode.
6579 outputs notifications.
6580 A notification will never occur inside an output block.
6582 The following notifications are defined:
6584 .It Ic %client-detached Ar client
6585 The client has detached.
6586 .It Ic %client-session-changed Ar client session-id name
6587 The client is now attached to the session with ID
6591 .It Ic %config-error Ar error
6592 An error has happened in a configuration file.
6593 .It Ic %continue Ar pane-id
6594 The pane has been continued after being paused (if the
6599 .It Ic %exit Op Ar reason
6602 client is exiting immediately, either because it is not attached to any session
6603 or an error occurred.
6606 describes why the client exited.
6607 .It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value
6614 is the time in milliseconds for which tmux had buffered the output before it was sent.
6615 Any subsequent arguments up until a single
6617 are for future use and should be ignored.
6618 .It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags
6619 The layout of a window with ID
6624 The window's visible layout is
6625 .Ar window-visible-layout
6626 and the window flags are
6628 .It Ic %output Ar pane-id Ar value
6629 A window pane produced output.
6631 escapes non-printable characters and backslash as octal \\xxx.
6632 .It Ic %pane-mode-changed Ar pane-id
6636 .It Ic %paste-buffer-changed Ar name
6640 .It Ic %paste-buffer-deleted Ar name
6644 .It Ic %pause Ar pane-id
6645 The pane has been paused (if the
6648 .It Ic %session-changed Ar session-id Ar name
6649 The client is now attached to the session with ID
6653 .It Ic %session-renamed Ar name
6654 The current session was renamed to
6656 .It Ic %session-window-changed Ar session-id Ar window-id
6659 changed its active window to the window with ID
6661 .It Ic %sessions-changed
6662 A session was created or destroyed.
6663 .It Xo Ic %subscription-changed
6668 .Ar pane-id ... \& :
6671 The value of the format associated with subscription
6682 are for future use and should be ignored.
6683 .It Ic %unlinked-window-add Ar window-id
6686 was created but is not linked to the current session.
6687 .It Ic %unlinked-window-close Ar window-id
6690 which is not linked to the current session, was closed.
6691 .It Ic %unlinked-window-renamed Ar window-id
6694 which is not linked to the current session, was renamed.
6695 .It Ic %window-add Ar window-id
6698 was linked to the current session.
6699 .It Ic %window-close Ar window-id
6703 .It Ic %window-pane-changed Ar window-id Ar pane-id
6704 The active pane in the window with ID
6706 changed to the pane with ID
6708 .It Ic %window-renamed Ar window-id Ar name
6717 is started, it inspects the following environment variables:
6718 .Bl -tag -width LC_CTYPE
6720 If the command specified in this variable contains the string
6724 is unset, use vi-style key bindings.
6731 The user's login directory.
6734 database is consulted.
6736 The character encoding
6738 It is used for two separate purposes.
6739 For output to the terminal, UTF-8 is used if the
6741 option is given or if
6747 Otherwise, only ASCII characters are written and non-ASCII characters
6748 are replaced with underscores
6752 always runs with a UTF-8 locale.
6753 If en_US.UTF-8 is provided by the operating system, it is used and
6755 is ignored for input.
6760 what the UTF-8 locale is called on the current system.
6761 If the locale specified by
6763 is not available or is not a UTF-8 locale,
6765 exits with an error message.
6767 The date and time format
6769 It is used for locale-dependent
6773 The current working directory to be set in the global environment.
6774 This may be useful if it contains symbolic links.
6775 If the value of the variable does not match the current working
6776 directory, the variable is ignored and the result of
6780 The absolute path to the default shell for new windows.
6785 The parent directory of the directory containing the server sockets.
6790 If the command specified in this variable contains the string
6792 use vi-style key bindings.
6800 .Bl -tag -width "/etc/tmux.confXXX" -compact
6805 .It Pa /etc/tmux.conf
6806 System-wide configuration file.
6814 .Dl $ tmux new-session vi
6816 Most commands have a shorter form, known as an alias.
6817 For new-session, this is
6822 Alternatively, the shortest unambiguous form of a command is accepted.
6823 If there are several options, they are listed:
6824 .Bd -literal -offset indent
6826 ambiguous command: n, could be: new-session, new-window, next-window
6829 Within an active session, a new window may be created by typing
6839 Windows may be navigated with:
6841 (to select window 0),
6843 (to select window 1), and so on;
6845 to select the next window; and
6847 to select the previous window.
6849 A session may be detached using
6851 (or by an external event such as
6853 disconnection) and reattached with:
6855 .Dl $ tmux attach-session
6859 lists the current key bindings in the current window; up and down may be used
6860 to navigate the list or
6864 Commands to be run when the
6866 server is started may be placed in the
6869 Common examples include:
6871 Changing the default prefix key:
6872 .Bd -literal -offset indent
6873 set-option -g prefix C-a
6875 bind-key C-a send-prefix
6878 Turning the status line off, or changing its colour:
6879 .Bd -literal -offset indent
6880 set-option -g status off
6881 set-option -g status-style bg=blue
6884 Setting other options, such as the default command,
6885 or locking after 30 minutes of inactivity:
6886 .Bd -literal -offset indent
6887 set-option -g default-command "exec /bin/ksh"
6888 set-option -g lock-after-time 1800
6891 Creating new key bindings:
6892 .Bd -literal -offset indent
6893 bind-key b set-option status
6894 bind-key / command-prompt "split-window 'exec man %%'"
6895 bind-key S command-prompt "new-window -n %1 'ssh %1'"
6900 .An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com