3 .\" Copyright (c) 2007 Nicholas Marriott <nicm@users.sourceforge.net>
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
31 .Op Ar command Op Ar flags
35 is a terminal multiplexer:
36 it enables a number of terminals to be created, accessed, and
37 controlled from a single screen.
39 may be detached from a screen
40 and continue running in the background,
41 then later reattached.
45 is started it creates a new
49 and displays it on screen.
50 A status line at the bottom of the screen
51 shows information on the current session
52 and is used to enter interactive commands.
54 A session is a single collection of
56 under the management of
58 Each session has one or more
60 A window occupies the entire screen
61 and may be split into rectangular panes,
62 each of which is a separate pseudo terminal
65 manual page documents the technical details of pseudo terminals).
68 instances may connect to the same session,
69 and any number of windows may be present in the same session.
70 Once all sessions are killed,
74 Each session is persistent and will survive accidental disconnection
77 connection timeout) or intentional detaching (with the
81 may be reattached using:
87 a session is displayed on screen by a
89 and all sessions are managed by a single
91 The server and each client are separate processes which communicate through a
95 The options are as follows:
96 .Bl -tag -width "XXXXXXXXXXXX"
100 to assume the terminal supports 256 colours.
104 but indicates that the terminal supports 88 colours.
105 .It Fl c Ar shell-command
108 using the default shell.
111 server will be started to retrieve the
114 This option is for compatibility with
118 is used as a login shell.
120 Specify an alternative configuration file.
123 loads the system configuration file from
125 if present, then looks for a user configuration file at
128 The configuration file is a set of
130 commands which are executed in sequence when the server is first started.
132 loads configuration files once when the server process has started.
135 command may be used to load a file later.
138 shows any error messages from commands in configuration files in the first
139 session created, and continues to process the rest of the configuration file.
140 .It Fl L Ar socket-name
142 stores the server socket in a directory under
147 the default socket is named
149 This option allows a different socket name to be specified, allowing several
155 a full path is not necessary: the sockets are all created in the same
158 If the socket is accidentally removed, the
160 signal may be sent to the
162 server process to recreate it.
164 Behave as a login shell.
165 This flag currently has no effect and is for compatibility with other shells
166 when using tmux as a login shell.
170 server option to prevent the server sending various informational messages.
171 .It Fl S Ar socket-path
172 Specify a full alternative path to the server socket.
175 is specified, the default socket directory is not used and any
180 attempts to guess if the terminal is likely to support UTF-8 by checking the
186 environment variables to be set for the string "UTF-8".
187 This is not always correct: the
189 flag explicitly informs
191 that UTF-8 is supported.
193 If the server is started from a client passed
195 or where UTF-8 is detected, the
199 options are enabled in the global window and session options respectively.
201 Request verbose logging.
202 This option may be specified multiple times for increasing verbosity.
203 Log messages will be saved into
204 .Pa tmux-client-PID.log
206 .Pa tmux-server-PID.log
207 files in the current directory, where
209 is the PID of the server or client process.
210 .It Ar command Op Ar flags
211 This specifies one of a set of commands used to control
213 as described in the following sections.
214 If no commands are specified, the
220 may be controlled from an attached client by using a key combination of a
223 (Ctrl-b) by default, followed by a command key.
225 The default command key bindings are:
227 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
229 Send the prefix key (C-b) through to the application.
231 Rotate the panes in the current window forwards.
237 Break the current pane out of the window.
239 Split the current pane into two, top and bottom.
241 List all paste buffers.
243 Rename the current session.
245 Split the current pane into two, left and right.
247 Kill the current window.
249 Prompt for a window index to select.
251 Rename the current window.
253 Delete the most recently copied buffer of text.
255 Prompt for an index to move the current window.
257 Select windows 0 to 9.
263 Move to the previously active pane.
265 Choose which buffer to paste interactively from a list.
267 List all key bindings.
269 Choose a client to detach.
271 Enter copy mode to copy text or view the history.
273 Paste the most recently copied buffer of text.
277 Detach the current client.
279 Prompt to search for text in open windows.
281 Display some information about the current window.
283 Move to the previously selected window.
285 Change to the next window.
287 Select the next pane in the current window.
289 Change to the previous window.
291 Briefly display pane indexes.
293 Force redraw of the attached client.
295 Select a new session for the attached client interactively.
297 Switch the attached client back to the last session.
301 Choose the current window interactively.
303 Kill the current pane.
305 Swap the current pane with the previous pane.
307 Swap the current pane with the next pane.
309 Show previous messages from
313 Enter copy mode and scroll one page up.
316 Change to the pane above, below, to the left, or to the right of the current
319 Arrange panes in one of the five preset layouts: even-horizontal,
320 even-vertical, main-horizontal, main-vertical, or tiled.
322 Move to the next window with a bell or activity marker.
324 Rotate the panes in the current window backwards.
326 Move to the previous window with a bell or activity marker.
329 Resize the current pane in steps of one cell.
332 Resize the current pane in steps of five cells.
335 Key bindings may be changed with the
341 This section contains a list of the commands supported by
343 Most commands accept the optional
351 These specify the client, session, window or pane which a command should affect.
355 file to which the client is connected, for example either of
359 for the client attached to
361 If no client is specified, the current client is chosen, if possible, or an
363 Clients may be listed with the
368 is either the name of a session (as listed by the
370 command) or the name of a client with the same syntax as
372 in which case the session attached to the client is used.
373 When looking for the session name,
375 initially searches for an exact match; if none is found, the session names
376 are checked for any for which
378 is a prefix or for which it matches as an
381 If a single match is found, it is used as the target session; multiple matches
383 If a session is omitted, the current session is used if available; if no
384 current session is available, the most recently used is chosen.
387 specifies a window in the form
388 .Em session Ns \&: Ns Em window .
390 follows the same rules as for
394 is looked for in order: as a window index, for example mysession:1;
395 as a window ID, such as @1;
396 as an exact window name, such as mysession:mywindow; then as an
398 pattern or the start of a window name, such as mysession:mywin* or
400 An empty window name specifies the next unused index if appropriate (for
406 otherwise the current window in
409 The special character
411 uses the last (previously current) window,
413 selects the highest numbered window,
415 selects the lowest numbered window, and
419 select the next window or the previous window by number.
420 When the argument does not contain a colon,
422 first attempts to parse it as window; if that fails, an attempt is made to
426 takes a similar form to
428 but with the optional addition of a period followed by a pane index, for
429 example: mysession:mywindow.1.
430 If the pane index is omitted, the currently active pane in the specified
432 If neither a colon nor period appears,
434 first attempts to use the argument as a pane index; if that fails, it is looked
441 indicate the next or previous pane index, respectively.
452 may be used instead of a pane index.
454 The special characters
458 may be followed by an offset, for example:
459 .Bd -literal -offset indent
463 When dealing with a session that doesn't contain sequential window indexes,
464 they will be correctly skipped.
467 also gives each pane created in a server an identifier consisting of a
469 and a number, starting from zero.
470 A pane's identifier is unique for the life of the
472 server and is passed to the child process of the pane in the
474 environment variable.
475 It may be used alone to target a pane or the window containing it.
481 These must be passed as a single item, which typically means quoting them, for
483 .Bd -literal -offset indent
484 new-window 'vi /etc/passwd'
491 command, passed with the command and arguments separately, for example:
492 .Bd -literal -offset indent
493 bind-key F1 set-window-option force-width 81
498 .Bd -literal -offset indent
499 $ tmux bind-key F1 set-window-option force-width 81
502 Multiple commands may be specified together as part of a
503 .Em command sequence .
504 Each command should be separated by spaces and a semicolon;
505 commands are executed sequentially from left to right and
506 lines ending with a backslash continue on to the next line,
507 except when escaped by another backslash.
508 A literal semicolon may be included by escaping it with a backslash (for
509 example, when specifying a command sequence to
515 .Bd -literal -offset indent
516 refresh-client -t/dev/ttyp2
518 rename-session -tfirst newname
520 set-window-option -t:0 monitor-activity on
522 new-window ; split-window -d
524 bind-key R source-file ~/.tmux.conf \e; \e
525 display-message "source-file done"
530 .Bd -literal -offset indent
531 $ tmux kill-window -t :1
533 $ tmux new-window \e; split-window -d
535 $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
537 .Sh CLIENTS AND SESSIONS
540 server manages clients, sessions, windows and panes.
541 Clients are attached to sessions to interact with them, either
542 when they are created with the
544 command, or later with the
547 Each session has one or more windows
550 Windows may be linked to multiple sessions and are made up of one or
552 each of which contains a pseudo terminal.
553 Commands for creating, linking and otherwise manipulating windows
556 .Sx WINDOWS AND PANES
559 The following commands are available to manage clients and sessions:
561 .It Xo Ic attach-session
563 .Op Fl t Ar target-session
565 .D1 (alias: Ic attach )
568 create a new client in the current terminal and attach it to
570 If used from inside, switch the current client.
573 is specified, any other clients attached to the session are detached.
575 signifies the client is read-only (only keys bound to the
579 commands have any effect)
581 If no server is started,
583 will attempt to start it; this will fail unless sessions are created in the
590 are slightly adjusted: if
592 needs to select the most recently used session, it will prefer the most
596 .It Xo Ic detach-client
599 .Op Fl s Ar target-session
600 .Op Fl t Ar target-client
602 .D1 (alias: Ic detach )
603 Detach the current client if bound to a key, the client specified with
605 or all clients currently attached to the session specified by
609 option kills all but the client given with
613 is given, send SIGHUP to the parent process of the client, typically causing it
615 .It Ic has-session Op Fl t Ar target-session
617 Report an error and exit with 1 if the specified session does not exist.
618 If it does exist, exit with 0.
622 server and clients and destroy all sessions.
625 .Op Fl t Ar target-session
626 Destroy the given session, closing any windows linked to it and no other
627 sessions, and detaching all clients attached to it.
630 is given, all sessions but the specified one is killed.
631 .It Xo Ic list-clients
633 .Op Fl t Ar target-session
636 List all clients attached to the server.
637 For the meaning of the
644 is specified, list only clients connected to that session.
646 .D1 (alias: Ic lscm )
647 List the syntax of all commands supported by
649 .It Ic list-sessions Op Fl F Ar format
651 List all sessions managed by the server.
652 For the meaning of the
657 .It Ic lock-client Op Fl t Ar target-client
658 .D1 (alias: Ic lockc )
664 .It Ic lock-session Op Fl t Ar target-session
665 .D1 (alias: Ic locks )
666 Lock all clients attached to
668 .It Xo Ic new-session
670 .Op Fl n Ar window-name
671 .Op Fl s Ar session-name
672 .Op Fl t Ar target-session
678 Create a new session with name
681 The new session is attached to the current terminal unless
687 are the name of and shell command to execute in the initial window.
694 specify the size of the initial window (80 by 24 if not given).
696 If run from a terminal, any
698 special characters are saved and used for new windows in the new session.
708 already exists; in the case,
717 is given, the new session is
721 This means they share the same set of windows - all windows from
723 are linked to the new session and any subsequent new windows or windows being
724 closed are applied to both sessions.
725 The current and previous window and any session options remain independent and
726 either session may be killed without affecting the other.
734 .It Xo Ic refresh-client
736 .Op Fl t Ar target-client
738 .D1 (alias: Ic refresh )
739 Refresh the current client if bound to a key, or a single client if one is given
744 is specified, only update the client's status bar.
745 .It Xo Ic rename-session
746 .Op Fl t Ar target-session
749 .D1 (alias: Ic rename )
750 Rename the session to
752 .It Xo Ic show-messages
753 .Op Fl t Ar target-client
755 .D1 (alias: Ic showmsgs )
756 Any messages displayed on the status line are saved in a per-client message
757 log, up to a maximum of the limit set by the
759 session option for the session attached to that client.
760 This command displays the log for
762 .It Ic source-file Ar path
763 .D1 (alias: Ic source )
764 Execute commands from
767 .D1 (alias: Ic start )
770 server, if not already running, without creating any sessions.
771 .It Xo Ic suspend-client
772 .Op Fl t Ar target-client
774 .D1 (alias: Ic suspendc )
775 Suspend a client by sending
778 .It Xo Ic switch-client
780 .Op Fl c Ar target-client
781 .Op Fl t Ar target-session
783 .D1 (alias: Ic switchc )
784 Switch the current session for client
793 is used, the client is moved to the last, next or previous session
796 toggles whether a client is read-only (see the
800 .Sh WINDOWS AND PANES
803 window may be in one of several modes.
804 The default permits direct access to the terminal attached to the window.
805 The other is copy mode, which permits a section of a window or its
806 history to be copied to a
808 for later insertion into another window.
809 This mode is entered with the
814 It is also entered when a command that produces output, such as
816 is executed from a key binding.
818 The keys available depend on whether emacs or vi mode is selected
822 The following keys are supported as appropriate for the mode:
823 .Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
824 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
825 .It Li "Back to indentation" Ta "^" Ta "M-m"
826 .It Li "Bottom of history" Ta "G" Ta "M-<"
827 .It Li "Clear selection" Ta "Escape" Ta "C-g"
828 .It Li "Copy selection" Ta "Enter" Ta "M-w"
829 .It Li "Cursor down" Ta "j" Ta "Down"
830 .It Li "Cursor left" Ta "h" Ta "Left"
831 .It Li "Cursor right" Ta "l" Ta "Right"
832 .It Li "Cursor to bottom line" Ta "L" Ta ""
833 .It Li "Cursor to middle line" Ta "M" Ta "M-r"
834 .It Li "Cursor to top line" Ta "H" Ta "M-R"
835 .It Li "Cursor up" Ta "k" Ta "Up"
836 .It Li "Delete entire line" Ta "d" Ta "C-u"
837 .It Li "Delete/Copy to end of line" Ta "D" Ta "C-k"
838 .It Li "End of line" Ta "$" Ta "C-e"
839 .It Li "Go to line" Ta ":" Ta "g"
840 .It Li "Half page down" Ta "C-d" Ta "M-Down"
841 .It Li "Half page up" Ta "C-u" Ta "M-Up"
842 .It Li "Jump forward" Ta "f" Ta "f"
843 .It Li "Jump to forward" Ta "t" Ta ""
844 .It Li "Jump backward" Ta "F" Ta "F"
845 .It Li "Jump to backward" Ta "T" Ta ""
846 .It Li "Jump again" Ta ";" Ta ";"
847 .It Li "Jump again in reverse" Ta "," Ta ","
848 .It Li "Next page" Ta "C-f" Ta "Page down"
849 .It Li "Next space" Ta "W" Ta ""
850 .It Li "Next space, end of word" Ta "E" Ta ""
851 .It Li "Next word" Ta "w" Ta ""
852 .It Li "Next word end" Ta "e" Ta "M-f"
853 .It Li "Paste buffer" Ta "p" Ta "C-y"
854 .It Li "Previous page" Ta "C-b" Ta "Page up"
855 .It Li "Previous word" Ta "b" Ta "M-b"
856 .It Li "Previous space" Ta "B" Ta ""
857 .It Li "Quit mode" Ta "q" Ta "Escape"
858 .It Li "Rectangle toggle" Ta "v" Ta "R"
859 .It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down"
860 .It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up"
861 .It Li "Search again" Ta "n" Ta "n"
862 .It Li "Search again in reverse" Ta "N" Ta "N"
863 .It Li "Search backward" Ta "?" Ta "C-r"
864 .It Li "Search forward" Ta "/" Ta "C-s"
865 .It Li "Start of line" Ta "0" Ta "C-a"
866 .It Li "Start selection" Ta "Space" Ta "C-Space"
867 .It Li "Top of history" Ta "g" Ta "M->"
868 .It Li "Transpose characters" Ta "" Ta "C-t"
871 The next and previous word keys use space and the
876 characters as word delimiters by default, but this can be adjusted by
880 Next word moves to the start of the next word, next word end to the end of the
881 next word and previous word to the start of the previous word.
882 The three next and previous space keys work similarly but use a space alone as
885 The jump commands enable quick movement within a line.
890 will move the cursor to the next
892 character on the current line.
895 will then jump to the next occurrence.
897 Commands in copy mode may be prefaced by an optional repeat count.
898 With vi key bindings, a prefix is entered using the number keys; with
899 emacs, the Alt (meta) key and a number begins prefix entry.
900 For example, to move the cursor forward by ten words, use
906 When copying the selection, the repeat count indicates the buffer index to
909 Mode key bindings are defined in a set of named tables:
913 for keys used when line editing at the command prompt;
917 for keys used when choosing from lists (such as produced by the
924 The tables may be viewed with the
926 command and keys modified or removed with
930 One command accepts an argument,
932 which copies the selection and pipes it to a command.
933 For example the following will bind
935 to copy the selection into
937 as well as the paste buffer:
938 .Bd -literal -offset indent
939 bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out"
942 The paste buffer key pastes the first line from the top paste buffer on the
951 .Op Fl t Ar target-pane
956 option scrolls one page up.
959 Each window displayed by
961 may be split into one or more
963 each pane takes up a certain area of the display and is a separate terminal.
964 A window may be split into panes using the
967 Windows may be split horizontally (with the
970 Panes may be resized with the
978 by default), the current pane may be changed with the
984 commands may be used to swap panes without changing their position.
985 Panes are numbered beginning from zero in the order they are created.
990 These may be selected with the
992 command or cycled with
996 by default); once a layout is chosen, panes within it may be moved and resized
999 The following layouts are supported:
1001 .It Ic even-horizontal
1002 Panes are spread out evenly from left to right across the window.
1003 .It Ic even-vertical
1004 Panes are spread evenly from top to bottom.
1005 .It Ic main-horizontal
1006 A large (main) pane is shown at the top of the window and the remaining panes
1007 are spread from left to right in the leftover space at the bottom.
1009 .Em main-pane-height
1010 window option to specify the height of the top pane.
1011 .It Ic main-vertical
1014 but the large pane is placed on the left and the others spread from top to
1015 bottom along the right.
1020 Panes are spread out as evenly as possible over the window in both rows and
1026 may be used to apply a previously used layout - the
1028 command displays the layout of each window in a form suitable for use with
1031 .Bd -literal -offset indent
1034 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1035 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1039 automatically adjusts the size of the layout for the current window size.
1040 Note that a layout cannot be applied to a window with more panes than that
1041 from which the layout was originally defined.
1043 Commands related to windows and panes are as follows:
1045 .It Xo Ic break-pane
1048 .Op Fl t Ar target-pane
1050 .D1 (alias: Ic breakp )
1053 off from its containing window to make it the only pane in a new window.
1056 is given, the new window does not become the current window.
1059 option prints information about the new window after it has been created.
1060 By default, it uses the format
1061 .Ql #{session_name}:#{window_index}
1062 but a different format may be specified with
1064 .It Xo Ic capture-pane
1067 .Op Fl b Ar buffer-index
1068 .Op Fl E Ar end-line
1069 .Op Fl S Ar start-line
1070 .Op Fl t Ar target-pane
1072 .D1 (alias: Ic capturep )
1073 Capture the contents of a pane.
1076 is given, the output goes to stdout, otherwise to the buffer specified with
1078 or a new buffer if omitted.
1081 is given, the output includes escape sequences for text and background
1084 also escapes non-printable characters as octal \exxx.
1086 joins wrapped lines.
1091 specify the starting and ending line numbers, zero is the first line of the
1092 visible pane and negative numbers are lines in the history.
1093 The default is to capture only the visible contents of the pane.
1097 .Op Fl t Ar target-window
1100 Put a window into client choice mode, allowing a client to be selected
1101 interactively from a list.
1102 After a client is chosen,
1104 is replaced by the client
1108 and the result executed as a command.
1111 is not given, "detach-client -t '%%'" is used.
1112 For the meaning of the
1117 This command works only if at least one client is attached.
1121 .Op Fl t Ar target-window
1124 Put a window into list choice mode, allowing
1128 can be a comma-separated list to display more than one item.
1129 If an item has spaces, that entry must be quoted.
1130 After an item is chosen,
1132 is replaced by the chosen item in the
1134 and the result is executed as a command.
1137 is not given, "run-shell '%%'" is used.
1139 also accepts format specifiers.
1140 For the meaning of this see the
1143 This command works only if at least one client is attached.
1147 .Op Fl t Ar target-window
1150 Put a window into session choice mode, where a session may be selected
1151 interactively from a list.
1154 is replaced by the session name in
1156 and the result executed as a command.
1159 is not given, "switch-client -t '%%'" is used.
1160 For the meaning of the
1165 This command works only if at least one client is attached.
1169 .Op Fl b Ar session-template
1170 .Op Fl c Ar window-template
1173 .Op Fl t Ar target-window
1175 Put a window into tree choice mode, where either sessions or windows may be
1176 selected interactively from a list.
1177 By default, windows belonging to a session are indented to show their
1178 relationship to a session.
1184 commands are wrappers around
1189 is given, will show sessions.
1192 is given, will show windows.
1194 By default, the tree is collapsed and sessions must be expanded to windows
1195 with the right arrow key.
1198 option will start with all sessions expanded instead.
1202 is given, will override the default session command.
1205 can be used and will be replaced with the session name.
1206 The default option if not specified is "switch-client -t '%%'".
1209 is given, will override the default window command.
1213 can be used and will be replaced with the session name and window index.
1214 When a window is chosen from the list, the session command is run before the
1219 is given will display the specified format instead of the default session
1223 is given will display the specified format instead of the default window
1225 For the meaning of the
1233 This command works only if at least one client is attached.
1237 .Op Fl t Ar target-window
1240 Put a window into window choice mode, where a window may be chosen
1241 interactively from a list.
1242 After a window is selected,
1244 is replaced by the session name and window index in
1246 and the result executed as a command.
1249 is not given, "select-window -t '%%'" is used.
1250 For the meaning of the
1255 This command works only if at least one client is attached.
1256 .It Ic display-panes Op Fl t Ar target-client
1257 .D1 (alias: Ic displayp)
1258 Display a visible indicator of each pane shown by
1261 .Ic display-panes-time ,
1262 .Ic display-panes-colour ,
1264 .Ic display-panes-active-colour
1266 While the indicator is on screen, a pane may be selected with the
1271 .It Xo Ic find-window
1274 .Op Fl t Ar target-window
1277 .D1 (alias: Ic findw )
1282 in window names, titles, and visible content (but not history).
1283 The flags control matching behavior:
1285 matches only visible window contents,
1287 matches only the window name and
1289 matches only the window title.
1292 If only one window is matched, it'll be automatically selected,
1293 otherwise a choice list is shown.
1294 For the meaning of the
1299 This command works only if at least one client is attached.
1304 .Fl p Ar percentage Oc
1305 .Op Fl s Ar src-pane
1306 .Op Fl t Ar dst-pane
1308 .D1 (alias: Ic joinp )
1311 but instead of splitting
1313 and creating a new pane, split it and move
1316 This can be used to reverse
1322 to be joined to left of or above
1326 .Op Fl t Ar target-pane
1328 .D1 (alias: Ic killp )
1329 Destroy the given pane.
1330 If no panes remain in the containing window, it is also destroyed.
1333 option kills all but the pane given with
1335 .It Xo Ic kill-window
1337 .Op Fl t Ar target-window
1339 .D1 (alias: Ic killw )
1340 Kill the current window or the window at
1342 removing it from any sessions to which it is linked.
1345 option kills all but the window given with
1347 .It Ic last-pane Op Fl t Ar target-window
1348 .D1 (alias: Ic lastp )
1349 Select the last (previously selected) pane.
1350 .It Ic last-window Op Fl t Ar target-session
1351 .D1 (alias: Ic last )
1352 Select the last (previously selected) window.
1355 is specified, select the last window of the current session.
1356 .It Xo Ic link-window
1358 .Op Fl s Ar src-window
1359 .Op Fl t Ar dst-window
1361 .D1 (alias: Ic linkw )
1368 is specified and no such window exists, the
1375 exists, it is killed, otherwise an error is generated.
1378 is given, the newly linked window is not selected.
1379 .It Xo Ic list-panes
1384 .D1 (alias: Ic lsp )
1389 is ignored and all panes on the server are listed.
1394 is a session (or the current session).
1395 If neither is given,
1397 is a window (or the current window).
1398 For the meaning of the
1403 .It Xo Ic list-windows
1406 .Op Fl t Ar target-session
1408 .D1 (alias: Ic lsw )
1411 is given, list all windows on the server.
1412 Otherwise, list windows in the current session or in
1413 .Ar target-session .
1414 For the meaning of the
1423 .Fl p Ar percentage Oc
1424 .Op Fl s Ar src-pane
1425 .Op Fl t Ar dst-pane
1427 .D1 (alias: Ic movep )
1434 may belong to the same window.
1435 .It Xo Ic move-window
1437 .Op Fl s Ar src-window
1438 .Op Fl t Ar dst-window
1440 .D1 (alias: Ic movew )
1443 except the window at
1449 all windows in the session are renumbered in sequential order, respecting
1453 .It Xo Ic new-window
1455 .Op Fl c Ar start-directory
1456 .Op Fl n Ar window-name
1457 .Op Fl t Ar target-window
1459 .Op Ar shell-command
1461 .D1 (alias: Ic neww )
1462 Create a new window.
1465 the new window is inserted at the next index up from the specified
1467 moving windows up if necessary,
1470 is the new window location.
1474 is given, the session does not make the new window the current window.
1476 represents the window to be created; if the target already exists an error is
1479 flag is used, in which case it is destroyed.
1481 is the command to execute.
1484 is not specified, the value of the
1488 specifies the working directory in which the new window is created.
1489 It may have an absolute path or one of the following values (or a subdirectory):
1490 .Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
1491 .It Li "Empty string" Ta "Current pane's directory"
1492 .It Li "~" Ta "User's home directory"
1493 .It Li "-" Ta "Where session was started"
1494 .It Li "." Ta "Where server was started"
1497 When the shell command completes, the window closes.
1500 option to change this behaviour.
1504 environment variable must be set to
1506 for all programs running
1509 New windows will automatically have
1511 added to their environment, but care must be taken not to reset this in shell
1516 option prints information about the new window after it has been created.
1517 By default, it uses the format
1518 .Ql #{session_name}:#{window_index}
1519 but a different format may be specified with
1521 .It Ic next-layout Op Fl t Ar target-window
1522 .D1 (alias: Ic nextl )
1523 Move a window to the next layout and rearrange the panes to fit.
1524 .It Xo Ic next-window
1526 .Op Fl t Ar target-session
1528 .D1 (alias: Ic next )
1529 Move to the next window in the session.
1532 is used, move to the next window with an alert.
1535 .Op Fl t Ar target-pane
1536 .Op Ar shell-command
1538 .D1 (alias: Ic pipep )
1539 Pipe any output sent by the program in
1542 A pane may only be piped to one command at a time, any existing pipe is
1548 string may contain the special character sequences supported by the
1553 is given, the current pipe (if any) is closed.
1557 option only opens a new pipe if no previous pipe exists, allowing a pipe to
1558 be toggled with a single key, for example:
1559 .Bd -literal -offset indent
1560 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1562 .It Xo Ic previous-layout
1563 .Op Fl t Ar target-window
1565 .D1 (alias: Ic prevl )
1566 Move to the previous layout in the session.
1567 .It Xo Ic previous-window
1569 .Op Fl t Ar target-session
1571 .D1 (alias: Ic prev )
1572 Move to the previous window in the session.
1575 move to the previous window with an alert.
1576 .It Xo Ic rename-window
1577 .Op Fl t Ar target-window
1580 .D1 (alias: Ic renamew )
1581 Rename the current window, or the window at
1585 .It Xo Ic resize-pane
1587 .Op Fl t Ar target-pane
1592 .D1 (alias: Ic resizep )
1593 Resize a pane, up, down, left or right by
1609 is given in lines or cells (the default is 1).
1613 the active pane is toggled between occupying the whole of the window and its
1614 normal position in the layout.
1615 .It Xo Ic respawn-pane
1617 .Op Fl t Ar target-pane
1618 .Op Ar shell-command
1620 .D1 (alias: Ic respawnp )
1621 Reactivate a pane in which the command has exited (see the
1626 is not given, the command used when the pane was created is executed.
1627 The pane must be already inactive, unless
1629 is given, in which case any existing command is killed.
1630 .It Xo Ic respawn-window
1632 .Op Fl t Ar target-window
1633 .Op Ar shell-command
1635 .D1 (alias: Ic respawnw )
1636 Reactivate a window in which the command has exited (see the
1641 is not given, the command used when the window was created is executed.
1642 The window must be already inactive, unless
1644 is given, in which case any existing command is killed.
1645 .It Xo Ic rotate-window
1647 .Op Fl t Ar target-window
1649 .D1 (alias: Ic rotatew )
1650 Rotate the positions of the panes within a window, either upward (numerically
1653 or downward (numerically higher).
1654 .It Xo Ic select-layout
1656 .Op Fl t Ar target-window
1659 .D1 (alias: Ic selectl )
1660 Choose a specific layout for a window.
1663 is not given, the last preset layout used (if any) is reapplied.
1667 are equivalent to the
1672 .It Xo Ic select-pane
1674 .Op Fl t Ar target-pane
1676 .D1 (alias: Ic selectp )
1679 the active pane in window
1687 is used, respectively the pane below, to the left, to the right, or above the
1688 target pane is used.
1690 is the same as using the
1693 .It Xo Ic select-window
1695 .Op Fl t Ar target-window
1697 .D1 (alias: Ic selectw )
1698 Select the window at
1704 are equivalent to the
1712 is given and the selected window is already the current window,
1713 the command behaves like
1715 .It Xo Ic split-window
1717 .Op Fl c Ar start-directory
1720 .Fl p Ar percentage Oc
1721 .Op Fl t Ar target-pane
1722 .Op Ar shell-command
1725 .D1 (alias: Ic splitw )
1726 Create a new pane by splitting
1729 does a horizontal split and
1731 a vertical split; if neither is specified,
1738 options specify the size of the new pane in lines (for vertical split) or in
1739 cells (for horizontal split), or as a percentage, respectively.
1740 All other options have the same meaning as for the
1745 .Op Fl s Ar src-pane
1746 .Op Fl t Ar dst-pane
1748 .D1 (alias: Ic swapp )
1752 is used and no source pane is specified with
1755 is swapped with the previous pane (before it numerically);
1757 swaps with the next pane (after it numerically).
1761 not to change the active pane.
1762 .It Xo Ic swap-window
1764 .Op Fl s Ar src-window
1765 .Op Fl t Ar dst-window
1767 .D1 (alias: Ic swapw )
1770 except the source and destination windows are swapped.
1771 It is an error if no window exists at
1773 .It Xo Ic unlink-window
1775 .Op Fl t Ar target-window
1777 .D1 (alias: Ic unlinkw )
1782 is given, a window may be unlinked only if it is linked to multiple sessions -
1783 windows may not be linked to no sessions;
1786 is specified and the window is linked to only one session, it is unlinked and
1791 allows a command to be bound to most keys, with or without a prefix key.
1792 When specifying keys, most represent themselves (for example
1796 Ctrl keys may be prefixed with
1802 In addition, the following special key names are accepted:
1820 .Em NPage/PageDown/PgDn ,
1821 .Em PPage/PageUp/PgUp ,
1825 Note that to bind the
1829 keys, quotation marks are necessary, for example:
1830 .Bd -literal -offset indent
1831 bind-key '"' split-window
1832 bind-key "'" new-window
1835 Commands related to key bindings are as follows:
1839 .Op Fl t Ar key-table
1840 .Ar key Ar command Op Ar arguments
1842 .D1 (alias: Ic bind )
1849 the primary key bindings are modified (those normally activated with the prefix
1850 key); in this case, if
1852 is specified, it is not necessary to use the prefix key,
1859 flag indicates this key may repeat, see the
1869 the binding for command mode with
1871 or for normal mode without.
1872 To view the default bindings and possible commands, see the
1875 .It Ic list-keys Op Fl t Ar key-table
1876 .D1 (alias: Ic lsk )
1877 List all key bindings.
1880 the primary key bindings - those executed when preceded by the prefix key -
1887 are listed; this may be one of:
1897 .Op Fl t Ar target-pane
1900 .D1 (alias: Ic send )
1901 Send a key or keys to a window.
1904 is the name of the key (such as
1908 ) to send; if the string is not recognised as a key, it is sent as a series of
1912 flag disables key name lookup and sends the keys literally.
1913 All arguments are sent sequentially from first to last.
1916 flag causes the terminal state to be reset.
1917 .It Xo Ic send-prefix
1919 .Op Fl t Ar target-pane
1921 Send the prefix key, or with
1923 the secondary prefix key, to a window as if it was pressed.
1924 .It Xo Ic unbind-key
1926 .Op Fl t Ar key-table
1929 .D1 (alias: Ic unbind )
1930 Unbind the command bound to
1934 the primary key bindings are modified; in this case, if
1936 is specified, the command bound to
1938 without a prefix (if any) is removed.
1941 is present, all key bindings are removed.
1949 is unbound: the binding for command mode with
1951 or for normal mode without.
1954 The appearance and behaviour of
1956 may be modified by changing the value of various options.
1957 There are three types of option:
1958 .Em server options ,
1961 .Em window options .
1965 server has a set of global options which do not apply to any particular
1967 These are altered with the
1970 command, or displayed with the
1975 In addition, each individual session may have a set of session options, and
1976 there is a separate set of global session options.
1977 Sessions which do not have a particular option configured inherit the value
1978 from the global session options.
1979 Session options are set or unset with the
1981 command and may be listed with the
1984 The available server and session options are listed under the
1988 Similarly, a set of window options is attached to each window, and there is
1989 a set of global window options from which any unset options are inherited.
1990 Window options are altered with the
1991 .Ic set-window-option
1992 command and can be listed with the
1993 .Ic show-window-options
1995 All window options are documented with the
1996 .Ic set-window-option
2000 also supports user options which are prefixed with a
2002 User options may have any name, so long as they are prefixed with
2004 and be set to any string.
2006 .Bd -literal -offset indent
2007 $ tmux setw -q @foo "abc123"
2008 $ tmux showw -v @foo
2012 Commands which set options are as follows:
2014 .It Xo Ic set-option
2016 .Op Fl t Ar target-session | Ar target-window
2019 .D1 (alias: Ic set )
2020 Set a window option with
2023 .Ic set-window-option
2025 a server option with
2027 otherwise a session option.
2031 is specified, the global session or window option is set.
2034 and if the option expects a string,
2036 is appended to the existing setting.
2039 flag unsets an option, so a session inherits the option from the global
2041 It is not possible to unset a global option.
2045 flag prevents setting an option that is already set.
2049 flag suppresses the informational message (as if the
2051 server option was set).
2053 Available window options are listed under
2054 .Ic set-window-option .
2057 depends on the option and may be a number, a string, or a flag (on, off, or
2060 Available server options are:
2062 .It Ic buffer-limit Ar number
2063 Set the number of buffers; as new buffers are added to the top of the stack,
2064 old ones are removed from the bottom if necessary to maintain this maximum
2066 .It Ic escape-time Ar time
2067 Set the time in milliseconds for which
2069 waits after an escape is input to determine if it is part of a function or meta
2071 The default is 500 milliseconds.
2072 .It Xo Ic exit-unattached
2075 If enabled, the server will exit when there are no attached clients.
2079 Enable or disable the display of various informational messages (see also the
2082 .It Xo Ic set-clipboard
2085 Attempt to set the terminal clipboard content using the
2089 This option is on by default if there is an
2093 description for the client terminal.
2094 Note that this feature needs to be enabled in
2096 by setting the resource:
2097 .Bd -literal -offset indent
2098 disallowedWindowOps: 20,21,SetXprop
2101 Or changing this property from the
2103 interactive menu when required.
2106 Available session options are:
2108 .It Ic assume-paste-time Ar milliseconds
2109 If keys are entered faster than one in
2111 they are assumed to have been pasted rather than typed and
2113 key bindings are not processed.
2114 The default is one millisecond and zero disables.
2115 .It Ic base-index Ar index
2116 Set the base index from which an unused index should be searched when a new
2118 The default is zero.
2119 .It Xo Ic bell-action
2120 .Op Ic any | none | current
2122 Set action on window bell.
2124 means a bell in any window linked to a session causes a bell in the current
2125 window of that session,
2127 means all bells are ignored and
2129 means only bells in windows other than the current window are ignored.
2130 .It Xo Ic bell-on-alert
2133 If on, ring the terminal bell when an alert
2135 .It Ic default-command Ar shell-command
2136 Set the command used for new windows (if not specified when the window is
2142 The default is an empty string, which instructs
2144 to create a login shell using the value of the
2147 .It Ic default-path Ar path
2148 Set the default working directory for new panes.
2149 If empty (the default), the working directory is determined from the process
2150 running in the active pane, from the command line environment or from the
2151 working directory where the session was created.
2152 Otherwise the same options are available as for the
2156 .It Ic default-shell Ar path
2157 Specify the default shell.
2158 This is used as the login shell for new windows when the
2160 option is set to empty, and must be the full path of the executable.
2163 tries to set a default value from the first suitable of the
2165 environment variable, the shell returned by
2169 This option should be configured when
2171 is used as a login shell.
2172 .It Ic default-terminal Ar terminal
2173 Set the default terminal for new windows created in this session - the
2174 default value of the
2176 environment variable.
2179 to work correctly, this
2183 or a derivative of it.
2184 .It Xo Ic destroy-unattached
2187 If enabled and the session is no longer attached to any clients, it is
2189 .It Xo Ic detach-on-destroy
2192 If on (the default), the client is detached when the session it is attached to
2194 If off, the client is switched to the most recently active of the remaining
2196 .It Ic display-panes-active-colour Ar colour
2197 Set the colour used by the
2199 command to show the indicator for the active pane.
2200 .It Ic display-panes-colour Ar colour
2201 Set the colour used by the
2203 command to show the indicators for inactive panes.
2204 .It Ic display-panes-time Ar time
2205 Set the time in milliseconds for which the indicators shown by the
2208 .It Ic display-time Ar time
2209 Set the amount of time for which status line messages and other on-screen
2210 indicators are displayed.
2213 .It Ic history-limit Ar lines
2214 Set the maximum number of lines held in window history.
2215 This setting applies only to new windows - existing window histories are not
2216 resized and retain the limit at the point they were created.
2217 .It Ic lock-after-time Ar number
2218 Lock the session (like the
2222 seconds of inactivity, or the entire server (all sessions) if the
2225 The default is not to lock (set to 0).
2226 .It Ic lock-command Ar shell-command
2227 Command to run when locking each client.
2228 The default is to run
2232 .It Xo Ic lock-server
2238 instead of each session locking individually as each has been
2240 .Ic lock-after-time ,
2241 the entire server will lock after
2243 sessions would have locked.
2244 This has no effect as a session option; it must be set as a global option.
2245 .It Ic message-attr Ar attributes
2246 Set status line message attributes, where
2250 or a comma-delimited list of one or more of:
2261 .It Ic message-bg Ar colour
2262 Set status line message background colour, where
2273 aixterm bright variants (if supported:
2280 from the 256-colour set,
2282 or a hexadecimal RGB string such as
2284 which chooses the closest match from the default 256-colour set.
2285 .It Ic message-command-attr Ar attributes
2286 Set status line message attributes when in command mode.
2287 .It Ic message-command-bg Ar colour
2288 Set status line message background colour when in command mode.
2289 .It Ic message-command-fg Ar colour
2290 Set status line message foreground colour when in command mode.
2291 .It Ic message-fg Ar colour
2292 Set status line message foreground colour.
2293 .It Ic message-limit Ar number
2294 Set the number of error or information messages to save in the message log for
2297 .It Xo Ic mouse-resize-pane
2302 captures the mouse and allows panes to be resized by dragging on their borders.
2303 .It Xo Ic mouse-select-pane
2308 captures the mouse and when a window is split into multiple panes the mouse may
2309 be used to select the current pane.
2310 The mouse click is also passed through to the application as normal.
2311 .It Xo Ic mouse-select-window
2314 If on, clicking the mouse on a window name in the status line will select that
2316 .It Xo Ic mouse-utf8
2319 If enabled, request mouse input as UTF-8 on UTF-8 terminals.
2320 .It Ic pane-active-border-bg Ar colour
2321 .It Ic pane-active-border-fg Ar colour
2322 Set the pane border colour for the currently active pane.
2323 .It Ic pane-border-bg Ar colour
2324 .It Ic pane-border-fg Ar colour
2325 Set the pane border colour for panes aside from the active pane.
2326 .It Ic prefix Ar key
2327 Set the key accepted as a prefix key.
2328 .It Ic prefix2 Ar key
2329 Set a secondary key accepted as a prefix key.
2330 .It Xo Ic renumber-windows
2333 If on, when a window is closed in a session, automatically renumber the other
2334 windows in numerical order.
2337 option if it has been set.
2338 If off, do not renumber the windows.
2339 .It Ic repeat-time Ar time
2340 Allow multiple commands to be entered without pressing the prefix-key again
2343 milliseconds (the default is 500).
2344 Whether a key repeats may be set when it is bound using the
2348 Repeat is enabled for the default keys bound to the
2351 .It Xo Ic set-remain-on-exit
2356 window option for any windows first created in this session.
2357 When this option is true, windows in which the running program has
2358 exited do not close, instead remaining open but inactivate.
2361 command to reactivate such a window, or the
2363 command to destroy it.
2364 .It Xo Ic set-titles
2367 Attempt to set the client terminal title using the
2372 entries if they exist.
2374 automatically sets these to the \ee]2;...\e007 sequence if
2375 the terminal appears to be an xterm.
2376 This option is off by default.
2378 will only attempt to set the window title if the STY environment
2380 .It Ic set-titles-string Ar string
2381 String used to set the window title if
2384 Character sequences are replaced as for the
2390 Show or hide the status line.
2391 .It Ic status-attr Ar attributes
2392 Set status line attributes.
2393 .It Ic status-bg Ar colour
2394 Set status line background colour.
2395 .It Ic status-fg Ar colour
2396 Set status line foreground colour.
2397 .It Ic status-interval Ar interval
2398 Update the status bar every
2401 By default, updates will occur every 15 seconds.
2402 A setting of zero disables redrawing at interval.
2403 .It Xo Ic status-justify
2404 .Op Ic left | centre | right
2406 Set the position of the window list component of the status line: left, centre
2408 .It Xo Ic status-keys
2411 Use vi or emacs-style
2412 key bindings in the status line, for example at the command prompt.
2413 The default is emacs, unless the
2417 environment variables are set and contain the string
2419 .It Ic status-left Ar string
2422 to the left of the status bar.
2424 will be passed through
2427 By default, the session name is shown.
2429 may contain any of the following special character sequences:
2430 .Bl -column "Character pair" "Replaced with" -offset indent
2431 .It Sy "Character pair" Ta Sy "Replaced with"
2432 .It Li "#(shell-command)" Ta "First line of the command's output"
2433 .It Li "#[attributes]" Ta "Colour or attribute change"
2434 .It Li "#H" Ta "Hostname of local host"
2435 .It Li "#h" Ta "Hostname of local host without the domain name"
2436 .It Li "#F" Ta "Current window flag"
2437 .It Li "#I" Ta "Current window index"
2438 .It Li "#D" Ta "Current pane unique identifier"
2439 .It Li "#P" Ta "Current pane index"
2440 .It Li "#S" Ta "Session name"
2441 .It Li "#T" Ta "Current pane title"
2442 .It Li "#W" Ta "Current window name"
2443 .It Li "##" Ta "A literal" Ql #
2446 The #(shell-command) form executes
2448 and inserts the first line of its output.
2449 Note that shell commands are only executed once at the interval specified by
2452 option: if the status line is redrawn in the meantime, the previous result is
2454 Shell commands are executed with the
2456 global environment set (see the
2460 For details on how the names and titles can be set see the
2461 .Sx "NAMES AND TITLES"
2464 #[attributes] allows a comma-separated list of attributes to be specified,
2467 to set the foreground colour,
2469 to set the background colour, the name of one of the attributes (listed under
2472 option) to turn an attribute on, or an attribute prefixed with
2474 to turn one off, for example
2477 .Bd -literal -offset indent
2478 #(sysctl vm.loadavg)
2479 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2482 Where appropriate, special character sequences may be prefixed with a number to
2483 specify the maximum length, for example
2486 By default, UTF-8 in
2488 is not interpreted, to enable UTF-8, use the
2491 .It Ic status-left-attr Ar attributes
2492 Set the attribute of the left part of the status line.
2493 .It Ic status-left-bg Ar colour
2494 Set the background colour of the left part of the status line.
2495 .It Ic status-left-fg Ar colour
2496 Set the foreground colour of the left part of the status line.
2497 .It Ic status-left-length Ar length
2500 of the left component of the status bar.
2502 .It Xo Ic status-position
2505 Set the position of the status line.
2506 .It Ic status-right Ar string
2509 to the right of the status bar.
2510 By default, the current window title in double quotes, the date and the time
2517 character pairs are replaced, and UTF-8 is dependent on the
2520 .It Ic status-right-attr Ar attributes
2521 Set the attribute of the right part of the status line.
2522 .It Ic status-right-bg Ar colour
2523 Set the background colour of the right part of the status line.
2524 .It Ic status-right-fg Ar colour
2525 Set the foreground colour of the right part of the status line.
2526 .It Ic status-right-length Ar length
2529 of the right component of the status bar.
2531 .It Xo Ic status-utf8
2536 to treat top-bit-set characters in the
2540 strings as UTF-8; notably, this is important for wide characters.
2541 This option defaults to off.
2542 .It Ic terminal-overrides Ar string
2543 Contains a list of entries which override terminal descriptions read using
2546 is a comma-separated list of items each a colon-separated string made up of a
2547 terminal type pattern (matched using
2553 For example, to set the
2558 for all terminal types and the
2564 terminal type, the option could be set to the string:
2565 .Bd -literal -offset indent
2566 "*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
2569 The terminal entry value is passed through
2571 before interpretation.
2572 The default value forcibly corrects the
2574 entry for terminals which support 88 or 256 colours:
2575 .Bd -literal -offset indent
2576 "*88col*:colors=88,*256col*:colors=256,xterm*:XT"
2578 .It Ic update-environment Ar variables
2579 Set a space-separated string containing a list of environment variables to be
2580 copied into the session environment when a new session is created or an
2581 existing session is attached.
2582 Any variables that do not exist in the source environment are set to be
2583 removed from the session environment (as if
2589 "DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID
2591 .It Xo Ic visual-activity
2594 If on, display a status line message when activity occurs in a window
2596 .Ic monitor-activity
2597 window option is enabled.
2598 .It Xo Ic visual-bell
2601 If this option is on, a message is shown on a bell instead of it being passed
2602 through to the terminal (which normally makes a sound).
2606 .It Xo Ic visual-content
2610 .Ic visual-activity ,
2611 display a message when content is present in a window
2614 window option is enabled.
2615 .It Xo Ic visual-silence
2620 is enabled, prints a message after the interval has expired on a given window.
2621 .It Ic word-separators Ar string
2622 Sets the session's conception of what characters are considered word
2623 separators, for the purposes of the next and previous word commands in
2628 .It Xo Ic set-window-option
2630 .Op Fl t Ar target-window
2633 .D1 (alias: Ic setw )
2634 Set a window option.
2641 flags work similarly to the
2645 Supported window options are:
2647 .Bl -tag -width Ds -compact
2648 .It Xo Ic aggressive-resize
2651 Aggressively resize the chosen window.
2654 will resize the window to the size of the smallest session for which it is the
2655 current window, rather than the smallest session to which it is attached.
2656 The window may resize when the current window is changed on another sessions;
2657 this option is good for full-screen programs which support
2659 and poor for interactive programs such as shells.
2661 .It Xo Ic allow-rename
2664 Allow programs to change the window name using a terminal escape
2665 sequence (\\033k...\\033\\\\).
2668 .It Xo Ic alternate-screen
2671 This option configures whether programs running inside
2673 may use the terminal alternate screen feature, which allows the
2679 The alternate screen feature preserves the contents of the window when an
2680 interactive application starts and restores it on exit, so that any output
2681 visible before the application starts reappears unchanged after it exits.
2684 .It Xo Ic automatic-rename
2687 Control automatic window renaming.
2688 When this setting is enabled,
2690 will attempt - on supported platforms - to rename the window to reflect the
2691 command currently running in it.
2692 This flag is automatically disabled for an individual window when a name
2693 is specified at creation with
2699 or with a terminal escape sequence.
2700 It may be switched off globally with:
2701 .Bd -literal -offset indent
2702 set-window-option -g automatic-rename off
2705 .It Ic c0-change-interval Ar interval
2706 .It Ic c0-change-trigger Ar trigger
2707 These two options configure a simple form of rate limiting for a pane.
2712 C0 sequences that modify the screen (for example, carriage returns, linefeeds
2713 or backspaces) in one millisecond, it will stop updating the pane immediately and
2714 instead redraw it entirely every
2717 This helps to prevent fast output (such as
2719 overwhelming the terminal).
2720 The default is a trigger of 250 and an interval of 100.
2721 A trigger of zero disables the rate limiting.
2723 .It Ic clock-mode-colour Ar colour
2726 .It Xo Ic clock-mode-style
2729 Set clock hour format.
2731 .It Ic command-prefix Ar string
2732 String prefixed to commands (apart from a plain shell as set by the
2738 .It Ic force-height Ar height
2739 .It Ic force-width Ar width
2742 from resizing a window to greater than
2746 A value of zero restores the default unlimited setting.
2748 .It Ic main-pane-height Ar height
2749 .It Ic main-pane-width Ar width
2750 Set the width or height of the main (left or top) pane in the
2756 .It Ic mode-attr Ar attributes
2757 Set window modes attributes.
2759 .It Ic mode-bg Ar colour
2760 Set window modes background colour.
2762 .It Ic mode-fg Ar colour
2763 Set window modes foreground colour.
2768 Use vi or emacs-style key bindings in copy and choice modes.
2771 option, the default is emacs, unless
2778 .It Xo Ic mode-mouse
2779 .Op Ic on | off | copy-mode
2781 Mouse state in modes.
2782 If on, the mouse may be used to enter copy mode and copy a selection by
2783 dragging, to enter copy mode and scroll with the mouse wheel, or to select an
2784 option in choice mode.
2787 the mouse behaves as set to on, but cannot be used to enter copy
2790 .It Xo Ic monitor-activity
2793 Monitor for activity in the window.
2794 Windows with activity are highlighted in the status line.
2796 .It Ic monitor-content Ar match-string
2797 Monitor content in the window.
2802 appears in the window, it is highlighted in the status line.
2804 .It Xo Ic monitor-silence
2807 Monitor for silence (no activity) in the window within
2810 Windows that have been silent for the interval are highlighted in the
2812 An interval of zero disables the monitoring.
2814 .It Ic other-pane-height Ar height
2815 Set the height of the other panes (not the main pane) in the
2818 If this option is set to 0 (the default), it will have no effect.
2820 .Ic main-pane-height
2822 .Ic other-pane-height
2823 options are set, the main pane will grow taller to make the other panes the
2824 specified height, but will never shrink to do so.
2826 .It Ic other-pane-width Ar width
2828 .Ic other-pane-height ,
2829 but set the width of other panes in the
2833 .It Ic pane-base-index Ar index
2836 but set the starting index for pane numbers.
2838 .It Xo Ic remain-on-exit
2841 A window with this flag set is not destroyed when the program running in it
2843 The window may be reactivated with the
2847 .It Xo Ic synchronize-panes
2850 Duplicate input to any pane to all other panes in the same window (only
2851 for panes that are not in any special mode).
2858 to expect UTF-8 sequences to appear in this window.
2860 .It Ic window-status-bell-attr Ar attributes
2861 Set status line attributes for windows which have a bell alert.
2863 .It Ic window-status-bell-bg Ar colour
2864 Set status line background colour for windows with a bell alert.
2866 .It Ic window-status-bell-fg Ar colour
2867 Set status line foreground colour for windows with a bell alert.
2869 .It Ic window-status-content-attr Ar attributes
2870 Set status line attributes for windows which have a content alert.
2872 .It Ic window-status-content-bg Ar colour
2873 Set status line background colour for windows with a content alert.
2875 .It Ic window-status-content-fg Ar colour
2876 Set status line foreground colour for windows with a content alert.
2878 .It Ic window-status-activity-attr Ar attributes
2879 Set status line attributes for windows which have an activity (or silence) alert.
2881 .It Ic window-status-activity-bg Ar colour
2882 Set status line background colour for windows with an activity alert.
2884 .It Ic window-status-activity-fg Ar colour
2885 Set status line foreground colour for windows with an activity alert.
2887 .It Ic window-status-attr Ar attributes
2888 Set status line attributes for a single window.
2890 .It Ic window-status-bg Ar colour
2891 Set status line background colour for a single window.
2893 .It Ic window-status-current-attr Ar attributes
2894 Set status line attributes for the currently active window.
2896 .It Ic window-status-current-bg Ar colour
2897 Set status line background colour for the currently active window.
2899 .It Ic window-status-current-fg Ar colour
2900 Set status line foreground colour for the currently active window.
2902 .It Ic window-status-current-format Ar string
2904 .Ar window-status-format ,
2905 but is the format used when the window is the current window.
2907 .It Ic window-status-last-attr Ar attributes
2908 Set status line attributes for the last active window.
2910 .It Ic window-status-last-bg Ar colour
2911 Set status line background colour for the last active window.
2913 .It Ic window-status-last-fg Ar colour
2914 Set status line foreground colour for the last active window.
2916 .It Ic window-status-fg Ar colour
2917 Set status line foreground colour for a single window.
2919 .It Ic window-status-format Ar string
2920 Set the format in which the window is displayed in the status line window list.
2923 option for details of special character sequences available.
2927 .It Ic window-status-separator Ar string
2928 Sets the separator drawn between windows in the status line.
2929 The default is a single space character.
2931 .It Xo Ic xterm-keys
2934 If this option is set,
2938 function key sequences; these have a number included to indicate modifiers such
2939 as Shift, Alt or Ctrl.
2942 .It Xo Ic wrap-search
2945 If this option is set, searches will wrap around the end of the pane contents.
2948 .It Xo Ic show-options
2950 .Op Fl t Ar target-session | Ar target-window
2953 .D1 (alias: Ic show )
2954 Show the window options (or a single window option if given) with
2957 .Ic show-window-options ) ,
2958 the server options with
2960 otherwise the session options for
2961 .Ar target session .
2962 Global session or window options are listed if
2966 shows only the option value, not the name.
2967 .It Xo Ic show-window-options
2969 .Op Fl t Ar target-window
2972 .D1 (alias: Ic showw )
2973 List the window options or a single option for
2975 or the global window options if
2979 shows only the option value, not the name.
2982 Certain commands accept the
2987 This is a string which controls the output format of the command.
2988 Special character sequences are replaced as documented under the
2990 option and an additional long form is accepted.
2991 Replacement variables are enclosed in
2999 Conditionals are also accepted by prefixing with
3001 and separating two alternatives with a comma;
3002 if the specified variable exists and is not zero, the first alternative
3003 is chosen, otherwise the second is used.
3005 .Ql #{?session_attached,attached,not attached}
3006 will include the string
3008 if the session is attached and the string
3010 if it is unattached.
3012 The following variables are available, where appropriate:
3013 .Bl -column "session_created_string" "Replaced with" -offset indent
3014 .It Sy "Variable name" Ta Sy "Replaced with"
3015 .It Li "alternate_on" Ta "If pane is in alternate screen"
3016 .It Li "alternate_saved_x" Ta "Saved cursor X in alternate screen"
3017 .It Li "alternate_saved_y" Ta "Saved cursor Y in alternate screen"
3018 .It Li "buffer_sample" Ta "First 50 characters from the specified buffer"
3019 .It Li "buffer_size" Ta "Size of the specified buffer in bytes"
3020 .It Li "client_activity" Ta "Integer time client last had activity"
3021 .It Li "client_activity_string" Ta "String time client last had activity"
3022 .It Li "client_created" Ta "Integer time client created"
3023 .It Li "client_created_string" Ta "String time client created"
3024 .It Li "client_cwd" Ta "Working directory of client"
3025 .It Li "client_height" Ta "Height of client"
3026 .It Li "client_last_session" Ta "Name of the client's last session"
3027 .It Li "client_prefix" Ta "1 if prefix key has been pressed"
3028 .It Li "client_readonly" Ta "1 if client is readonly"
3029 .It Li "client_session" Ta "Name of the client's session"
3030 .It Li "client_termname" Ta "Terminal name of client"
3031 .It Li "client_tty" Ta "Pseudo terminal of client"
3032 .It Li "client_utf8" Ta "1 if client supports utf8"
3033 .It Li "client_width" Ta "Width of client"
3034 .It Li "cursor_flag" Ta "Pane cursor flag"
3035 .It Li "cursor_x" Ta "Cursor X position in pane"
3036 .It Li "cursor_y" Ta "Cursor Y position in pane"
3037 .It Li "history_bytes" Ta "Number of bytes in window history"
3038 .It Li "history_limit" Ta "Maximum window history lines"
3039 .It Li "history_size" Ta "Size of history in bytes"
3040 .It Li "host" Ta "Hostname of local host"
3041 .It Li "insert_flag" Ta "Pane insert flag"
3042 .It Li "keypad_cursor_flag" Ta "Pane keypad cursor flag"
3043 .It Li "keypad_flag" Ta "Pane keypad flag"
3044 .It Li "line" Ta "Line number in the list"
3045 .It Li "mouse_any_flag" Ta "Pane mouse any flag"
3046 .It Li "mouse_button_flag" Ta "Pane mouse button flag"
3047 .It Li "mouse_standard_flag" Ta "Pane mouse standard flag"
3048 .It Li "mouse_utf8_flag" Ta "Pane mouse UTF-8 flag"
3049 .It Li "pane_active" Ta "1 if active pane"
3050 .It Li "pane_current_command" Ta "Current command if available"
3051 .It Li "pane_current_path" Ta "Current path if available"
3052 .It Li "pane_dead" Ta "1 if pane is dead"
3053 .It Li "pane_height" Ta "Height of pane"
3054 .It Li "pane_id" Ta "Unique pane ID"
3055 .It Li "pane_in_mode" Ta "If pane is in a mode"
3056 .It Li "pane_index" Ta "Index of pane"
3057 .It Li "pane_pid" Ta "PID of first process in pane"
3058 .It Li "pane_start_command" Ta "Command pane started with"
3059 .It Li "pane_start_path" Ta "Path pane started with"
3060 .It Li "pane_tabs" Ta "Pane tab positions"
3061 .It Li "pane_title" Ta "Title of pane"
3062 .It Li "pane_tty" Ta "Pseudo terminal of pane"
3063 .It Li "pane_width" Ta "Width of pane"
3064 .It Li "saved_cursor_x" Ta "Saved cursor X in pane"
3065 .It Li "saved_cursor_y" Ta "Saved cursor Y in pane"
3066 .It Li "scroll_region_lower" Ta "Bottom of scroll region in pane"
3067 .It Li "scroll_region_upper" Ta "Top of scroll region in pane"
3068 .It Li "session_attached" Ta "1 if session attached"
3069 .It Li "session_created" Ta "Integer time session created"
3070 .It Li "session_created_string" Ta "String time session created"
3071 .It Li "session_group" Ta "Number of session group"
3072 .It Li "session_grouped" Ta "1 if session in a group"
3073 .It Li "session_height" Ta "Height of session"
3074 .It Li "session_name" Ta "Name of session"
3075 .It Li "session_width" Ta "Width of session"
3076 .It Li "session_windows" Ta "Number of windows in session"
3077 .It Li "window_active" Ta "1 if window active"
3078 .It Li "window_find_matches" Ta "Matched data from the find-window command if available"
3079 .It Li "window_flags" Ta "Window flags"
3080 .It Li "window_height" Ta "Height of window"
3081 .It Li "window_id" Ta "Unique window ID"
3082 .It Li "window_index" Ta "Index of window"
3083 .It Li "window_layout" Ta "Window layout description"
3084 .It Li "window_name" Ta "Name of window"
3085 .It Li "window_panes" Ta "Number of panes in window"
3086 .It Li "window_width" Ta "Width of window"
3087 .It Li "wrap_flag" Ta "Pane wrap flag"
3089 .Sh NAMES AND TITLES
3091 distinguishes between names and titles.
3092 Windows and sessions have names, which may be used to specify them in targets
3093 and are displayed in the status line and various lists: the name is the
3095 identifier for a window or session.
3096 Only panes have titles.
3097 A pane's title is typically set by the program running inside the pane and
3100 It is the same mechanism used to set for example the
3105 Windows themselves do not have titles - a window's title is the title of its
3108 itself may set the title of the terminal in which the client is running, see
3113 A session's name is set with the
3118 A window's name is set with one of:
3121 A command argument (such as
3129 .Bd -literal -offset indent
3130 $ printf '\e033kWINDOW_NAME\e033\e\e'
3133 Automatic renaming, which sets the name to the active command in the window's
3136 .Ic automatic-rename
3140 When a pane is first created, its title is the hostname.
3141 A pane's title can be set via the OSC title setting sequence, for example:
3142 .Bd -literal -offset indent
3143 $ printf '\e033]2;My Title\e033\e\e'
3146 When the server is started,
3148 copies the environment into the
3149 .Em global environment ;
3150 in addition, each session has a
3151 .Em session environment .
3152 When a window is created, the session and global environments are merged.
3153 If a variable exists in both, the value from the session environment is used.
3154 The result is the initial environment passed to the new process.
3157 .Ic update-environment
3158 session option may be used to update the session environment from the client
3159 when a new session is created or an old reattached.
3161 also initialises the
3163 variable with some internal information to allow commands to be executed
3164 from inside, and the
3166 variable with the correct terminal setting of
3169 Commands to alter and view the environment are:
3171 .It Xo Ic set-environment
3173 .Op Fl t Ar target-session
3174 .Ar name Op Ar value
3176 .D1 (alias: Ic setenv )
3177 Set or unset an environment variable.
3180 is used, the change is made in the global environment; otherwise, it is applied
3181 to the session environment for
3182 .Ar target-session .
3185 flag unsets a variable.
3187 indicates the variable is to be removed from the environment before starting a
3189 .It Xo Ic show-environment
3191 .Op Fl t Ar target-session
3194 .D1 (alias: Ic showenv )
3195 Display the environment for
3197 or the global environment with
3201 is omitted, all variables are shown.
3202 Variables removed from the environment are prefixed with
3207 includes an optional status line which is displayed in the bottom line of each
3209 By default, the status line is enabled (it may be disabled with the
3211 session option) and contains, from left-to-right: the name of the current
3212 session in square brackets; the window list; the title of the active pane
3213 in double quotes; and the time and date.
3215 The status line is made of three parts: configurable left and right sections
3216 (which may contain dynamic content such as the time or output from a shell
3219 .Ic status-left-length ,
3222 .Ic status-right-length
3223 options below), and a central window list.
3224 By default, the window list shows the index, name and (if any) flag of the
3225 windows present in the current session in ascending numerical order.
3226 It may be customised with the
3227 .Ar window-status-format
3229 .Ar window-status-current-format
3231 The flag is one of the following symbols appended to the window name:
3232 .Bl -column "Symbol" "Meaning" -offset indent
3233 .It Sy "Symbol" Ta Sy "Meaning"
3234 .It Li "*" Ta "Denotes the current window."
3235 .It Li "-" Ta "Marks the last window (previously selected)."
3236 .It Li "#" Ta "Window is monitored and activity has been detected."
3237 .It Li "!" Ta "A bell has occurred in the window."
3238 .It Li "+" Ta "Window is monitored for content and it has appeared."
3239 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
3242 The # symbol relates to the
3243 .Ic monitor-activity
3247 The window name is printed in inverted colours if an alert (bell, activity or
3248 content) is present.
3250 The colour and attributes of the status line may be configured, the entire
3251 status line using the
3256 session options and individual windows using the
3257 .Ic window-status-attr ,
3258 .Ic window-status-fg
3260 .Ic window-status-bg
3263 The status line is automatically refreshed at interval if it has changed, the
3264 interval may be controlled with the
3268 Commands related to the status line are as follows:
3270 .It Xo Ic command-prompt
3273 .Op Fl t Ar target-client
3276 Open the command prompt in a client.
3277 This may be used from inside
3279 to execute commands interactively.
3283 is specified, it is used as the command.
3286 is a comma-separated list of the initial text for each prompt.
3291 is a comma-separated list of prompts which are displayed in order; otherwise
3292 a single prompt is displayed, constructed from
3294 if it is present, or
3302 may contain the special character sequences supported by the
3306 Before the command is executed, the first occurrence of the string
3308 and all occurrences of
3310 are replaced by the response to the first prompt, the second
3314 are replaced with the response to the second prompt, and so on for further
3316 Up to nine prompt responses may be replaced
3322 .It Xo Ic confirm-before
3324 .Op Fl t Ar target-client
3327 .D1 (alias: Ic confirm )
3328 Ask for confirmation before executing
3334 is the prompt to display; otherwise a prompt is constructed from
3336 It may contain the special character sequences supported by the
3340 This command works only from inside
3342 .It Xo Ic display-message
3344 .Op Fl c Ar target-client
3345 .Op Fl t Ar target-pane
3348 .D1 (alias: Ic display )
3352 is given, the output is printed to stdout, otherwise it is displayed in the
3359 section; information is taken from
3363 is given, otherwise the active pane for the session attached to
3368 maintains a stack of
3370 Up to the value of the
3372 option are kept; when a new buffer is added, the buffer at the bottom of the
3374 Buffers may be added using
3378 command, and pasted into a window using the
3382 A configurable history buffer is also maintained for each window.
3383 By default, up to 2000 lines are kept; this can be altered with the
3389 The buffer commands are as follows:
3394 .Op Fl t Ar target-window
3397 Put a window into buffer choice mode, where a buffer may be chosen
3398 interactively from a list.
3399 After a buffer is selected,
3401 is replaced by the buffer index in
3403 and the result executed as a command.
3406 is not given, "paste-buffer -b '%%'" is used.
3407 For the meaning of the
3412 This command works only if at least one client is attached.
3413 .It Ic clear-history Op Fl t Ar target-pane
3414 .D1 (alias: Ic clearhist )
3415 Remove and free the history for the specified pane.
3416 .It Ic delete-buffer Op Fl b Ar buffer-index
3417 .D1 (alias: Ic deleteb )
3418 Delete the buffer at
3420 or the top buffer if not specified.
3421 .It Xo Ic list-buffers
3424 .D1 (alias: Ic lsb )
3425 List the global buffers.
3426 For the meaning of the
3431 .It Xo Ic load-buffer
3432 .Op Fl b Ar buffer-index
3435 .D1 (alias: Ic loadb )
3436 Load the contents of the specified paste buffer from
3438 .It Xo Ic paste-buffer
3440 .Op Fl b Ar buffer-index
3441 .Op Fl s Ar separator
3442 .Op Fl t Ar target-pane
3444 .D1 (alias: Ic pasteb )
3445 Insert the contents of a paste buffer into the specified pane.
3446 If not specified, paste into the current one.
3449 also delete the paste buffer from the stack.
3450 When output, any linefeed (LF) characters in the paste buffer are replaced with
3451 a separator, by default carriage return (CR).
3452 A custom separator may be specified using the
3457 flag means to do no replacement (equivalent to a separator of LF).
3460 is specified, paste bracket control codes are inserted around the
3461 buffer if the application has requested bracketed paste mode.
3462 .It Xo Ic save-buffer
3464 .Op Fl b Ar buffer-index
3467 .D1 (alias: Ic saveb )
3468 Save the contents of the specified paste buffer to
3472 option appends to rather than overwriting the file.
3473 .It Xo Ic set-buffer
3474 .Op Fl b Ar buffer-index
3477 .D1 (alias: Ic setb )
3478 Set the contents of the specified buffer to
3480 .It Xo Ic show-buffer
3481 .Op Fl b Ar buffer-index
3483 .D1 (alias: Ic showb )
3484 Display the contents of the specified buffer.
3487 Miscellaneous commands are as follows:
3489 .It Ic clock-mode Op Fl t Ar target-pane
3490 Display a large clock.
3492 .Op Fl t Ar target-pane
3494 .Ar shell-command command
3502 returns success or the second
3505 Before being executed, shell-command is expanded using the rules specified in the
3507 section, including those relevant to
3512 is run in the background.
3514 .D1 (alias: Ic lock )
3515 Lock each client individually by running the command specified by the
3520 .Op Fl t Ar target-pane
3523 .D1 (alias: Ic run )
3526 in the background without creating a window.
3527 Before being executed, shell-command is expanded using the rules specified in
3533 the command is run in the background.
3534 After it finishes, any output to stdout is displayed in copy mode (in the pane
3537 or the current pane if omitted).
3538 If the command doesn't return success, the exit status is also displayed.
3540 .D1 (alias: Ic info )
3541 Show server information and terminal details.
3543 .Sh TERMINFO EXTENSIONS
3545 understands some extensions to
3549 Set the cursor colour.
3550 The first takes a single string argument and is used to set the colour;
3551 the second takes no arguments and restores the default cursor colour.
3552 If set, a sequence such as this may be used
3553 to change the cursor colour from inside
3555 .Bd -literal -offset indent
3556 $ printf '\e033]12;red\e033\e\e'
3559 Change the cursor style.
3560 If set, a sequence such as this may be used
3561 to change the cursor to an underline:
3562 .Bd -literal -offset indent
3563 $ printf '\e033[4 q'
3568 is set, it will be used to reset the cursor style instead
3572 This sequence can be used by
3574 to store the current buffer in the host terminal's selection (clipboard).
3577 option above and the
3582 .Bl -tag -width "/etc/tmux.confXXX" -compact
3587 .It Pa /etc/tmux.conf
3588 System-wide configuration file.
3596 .Dl $ tmux new-session vi
3598 Most commands have a shorter form, known as an alias.
3599 For new-session, this is
3604 Alternatively, the shortest unambiguous form of a command is accepted.
3605 If there are several options, they are listed:
3606 .Bd -literal -offset indent
3608 ambiguous command: n, could be: new-session, new-window, next-window
3611 Within an active session, a new window may be created by typing
3621 Windows may be navigated with:
3623 (to select window 0),
3625 (to select window 1), and so on;
3627 to select the next window; and
3629 to select the previous window.
3631 A session may be detached using
3633 (or by an external event such as
3635 disconnection) and reattached with:
3637 .Dl $ tmux attach-session
3641 lists the current key bindings in the current window; up and down may be used
3642 to navigate the list or
3646 Commands to be run when the
3648 server is started may be placed in the
3651 Common examples include:
3653 Changing the default prefix key:
3654 .Bd -literal -offset indent
3655 set-option -g prefix C-a
3657 bind-key C-a send-prefix
3660 Turning the status line off, or changing its colour:
3661 .Bd -literal -offset indent
3662 set-option -g status off
3663 set-option -g status-bg blue
3666 Setting other options, such as the default command,
3667 or locking after 30 minutes of inactivity:
3668 .Bd -literal -offset indent
3669 set-option -g default-command "exec /bin/ksh"
3670 set-option -g lock-after-time 1800
3673 Creating new key bindings:
3674 .Bd -literal -offset indent
3675 bind-key b set-option status
3676 bind-key / command-prompt "split-window 'exec man %%'"
3677 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3682 .An Nicholas Marriott Aq nicm@users.sourceforge.net