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
127 The configuration file is a set of
129 commands which are executed in sequence when the server is first started.
131 If a command in the configuration file fails,
133 will report an error and exit without executing further commands.
134 .It Fl L Ar socket-name
136 stores the server socket in a directory under
141 the default socket is named
143 This option allows a different socket name to be specified, allowing several
149 a full path is not necessary: the sockets are all created in the same
152 If the socket is accidentally removed, the
154 signal may be sent to the
156 server process to recreate it.
158 Behave as a login shell.
159 This flag currently has no effect and is for compatibility with other shells
160 when using tmux as a login shell.
164 server option to prevent the server sending various informational messages.
165 .It Fl S Ar socket-path
166 Specify a full alternative path to the server socket.
169 is specified, the default socket directory is not used and any
174 attempts to guess if the terminal is likely to support UTF-8 by checking the
180 environment variables to be set for the string "UTF-8".
181 This is not always correct: the
183 flag explicitly informs
185 that UTF-8 is supported.
187 If the server is started from a client passed
189 or where UTF-8 is detected, the
193 options are enabled in the global window and session options respectively.
195 Request verbose logging.
196 This option may be specified multiple times for increasing verbosity.
197 Log messages will be saved into
198 .Pa tmux-client-PID.log
200 .Pa tmux-server-PID.log
201 files in the current directory, where
203 is the PID of the server or client process.
204 .It Ar command Op Ar flags
205 This specifies one of a set of commands used to control
207 as described in the following sections.
208 If no commands are specified, the
214 may be controlled from an attached client by using a key combination of a
217 (Ctrl-b) by default, followed by a command key.
219 The default command key bindings are:
221 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
223 Send the prefix key (C-b) through to the application.
225 Rotate the panes in the current window forwards.
231 Break the current pane out of the window.
233 Split the current pane into two, top and bottom.
235 List all paste buffers.
237 Rename the current session.
239 Split the current pane into two, left and right.
241 Kill the current window.
243 Prompt for a window index to select.
245 Rename the current window.
247 Delete the most recently copied buffer of text.
249 Prompt for an index to move the current window.
251 Select windows 0 to 9.
257 Move to the previously active pane.
259 Choose which buffer to paste interactively from a list.
261 List all key bindings.
263 Choose a client to detach.
265 Enter copy mode to copy text or view the history.
267 Paste the most recently copied buffer of text.
271 Detach the current client.
273 Prompt to search for text in open windows.
275 Display some information about the current window.
277 Move to the previously selected window.
279 Change to the next window.
281 Select the next pane in the current window.
283 Change to the previous window.
285 Briefly display pane indexes.
287 Force redraw of the attached client.
289 Select a new session for the attached client interactively.
291 Switch the attached client back to the last session.
295 Choose the current window interactively.
297 Kill the current pane.
299 Swap the current pane with the previous pane.
301 Swap the current pane with the next pane.
303 Show previous messages from
307 Enter copy mode and scroll one page up.
310 Change to the pane above, below, to the left, or to the right of the current
313 Arrange panes in one of the five preset layouts: even-horizontal,
314 even-vertical, main-horizontal, main-vertical, or tiled.
316 Move to the next window with a bell or activity marker.
318 Rotate the panes in the current window backwards.
320 Move to the previous window with a bell or activity marker.
323 Resize the current pane in steps of one cell.
326 Resize the current pane in steps of five cells.
329 Key bindings may be changed with the
335 This section contains a list of the commands supported by
337 Most commands accept the optional
345 These specify the client, session, window or pane which a command should affect.
349 file to which the client is connected, for example either of
353 for the client attached to
355 If no client is specified, the current client is chosen, if possible, or an
357 Clients may be listed with the
362 is either the name of a session (as listed by the
364 command) or the name of a client with the same syntax as
366 in which case the session attached to the client is used.
367 When looking for the session name,
369 initially searches for an exact match; if none is found, the session names
370 are checked for any for which
372 is a prefix or for which it matches as an
375 If a single match is found, it is used as the target session; multiple matches
377 If a session is omitted, the current session is used if available; if no
378 current session is available, the most recently used is chosen.
381 specifies a window in the form
382 .Em session Ns \&: Ns Em window .
384 follows the same rules as for
388 is looked for in order: as a window index, for example mysession:1;
389 as a window ID, such as @1;
390 as an exact window name, such as mysession:mywindow; then as an
392 pattern or the start of a window name, such as mysession:mywin* or
394 An empty window name specifies the next unused index if appropriate (for
400 otherwise the current window in
403 The special character
405 uses the last (previously current) window, or
409 are the next window or the previous window by number.
410 When the argument does not contain a colon,
412 first attempts to parse it as window; if that fails, an attempt is made to
416 takes a similar form to
418 but with the optional addition of a period followed by a pane index, for
419 example: mysession:mywindow.1.
420 If the pane index is omitted, the currently active pane in the specified
422 If neither a colon nor period appears,
424 first attempts to use the argument as a pane index; if that fails, it is looked
431 indicate the next or previous pane index, respectively.
442 may be used instead of a pane index.
444 The special characters
448 may be followed by an offset, for example:
449 .Bd -literal -offset indent
453 When dealing with a session that doesn't contain sequential window indexes,
454 they will be correctly skipped.
457 also gives each pane created in a server an identifier consisting of a
459 and a number, starting from zero.
460 A pane's identifier is unique for the life of the
462 server and is passed to the child process of the pane in the
464 environment variable.
465 It may be used alone to target a pane or the window containing it.
471 These must be passed as a single item, which typically means quoting them, for
473 .Bd -literal -offset indent
474 new-window 'vi /etc/passwd'
481 command, passed with the command and arguments separately, for example:
482 .Bd -literal -offset indent
483 bind-key F1 set-window-option force-width 81
488 .Bd -literal -offset indent
489 $ tmux bind-key F1 set-window-option force-width 81
492 Multiple commands may be specified together as part of a
493 .Em command sequence .
494 Each command should be separated by spaces and a semicolon;
495 commands are executed sequentially from left to right and
496 lines ending with a backslash continue on to the next line.
497 A literal semicolon may be included by escaping it with a backslash (for
498 example, when specifying a command sequence to
504 .Bd -literal -offset indent
505 refresh-client -t/dev/ttyp2
507 rename-session -tfirst newname
509 set-window-option -t:0 monitor-activity on
511 new-window ; split-window -d
513 bind-key R source-file ~/.tmux.conf \e; \e
514 display-message "source-file done"
519 .Bd -literal -offset indent
520 $ tmux kill-window -t :1
522 $ tmux new-window \e; split-window -d
524 $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
526 .Sh CLIENTS AND SESSIONS
529 server manages clients, sessions, windows and panes.
530 Clients are attached to sessions to interact with them, either
531 when they are created with the
533 command, or later with the
536 Each session has one or more windows
539 Windows may be linked to multiple sessions and are made up of one or
541 each of which contains a pseudo terminal.
542 Commands for creating, linking and otherwise manipulating windows
545 .Sx WINDOWS AND PANES
548 The following commands are available to manage clients and sessions:
550 .It Xo Ic attach-session
552 .Op Fl t Ar target-session
554 .D1 (alias: Ic attach )
557 create a new client in the current terminal and attach it to
559 If used from inside, switch the current client.
562 is specified, any other clients attached to the session are detached.
564 signifies the client is read-only (only keys bound to the
568 commands have any effect)
570 If no server is started,
572 will attempt to start it; this will fail unless sessions are created in the
579 are slightly adjusted: if
581 needs to select the most recently used session, it will prefer the most
585 .It Xo Ic detach-client
587 .Op Fl s Ar target-session
588 .Op Fl t Ar target-client
590 .D1 (alias: Ic detach )
591 Detach the current client if bound to a key, the client specified with
593 or all clients currently attached to the session specified by
597 is given, send SIGHUP to the parent process of the client, typically causing it
599 .It Ic has-session Op Fl t Ar target-session
601 Report an error and exit with 1 if the specified session does not exist.
602 If it does exist, exit with 0.
606 server and clients and destroy all sessions.
607 .It Ic kill-session Op Fl t Ar target-session
608 Destroy the given session, closing any windows linked to it and no other
609 sessions, and detaching all clients attached to it.
610 .It Xo Ic list-clients
612 .Op Fl t Ar target-session
615 List all clients attached to the server.
616 For the meaning of the
623 is specified, list only clients connected to that session.
625 .D1 (alias: Ic lscm )
626 List the syntax of all commands supported by
628 .It Ic list-sessions Op Fl F Ar format
630 List all sessions managed by the server.
631 For the meaning of the
636 .It Ic lock-client Op Fl t Ar target-client
637 .D1 (alias: Ic lockc )
643 .It Ic lock-session Op Fl t Ar target-session
644 .D1 (alias: Ic locks )
645 Lock all clients attached to
647 .It Xo Ic new-session
649 .Op Fl n Ar window-name
650 .Op Fl s Ar session-name
651 .Op Fl t Ar target-session
657 Create a new session with name
660 The new session is attached to the current terminal unless
666 are the name of and shell command to execute in the initial window.
673 specify the size of the initial window (80 by 24 if not given).
675 If run from a terminal, any
677 special characters are saved and used for new windows in the new session.
681 is given, the new session is
685 This means they share the same set of windows - all windows from
687 are linked to the new session and any subsequent new windows or windows being
688 closed are applied to both sessions.
689 The current and previous window and any session options remain independent and
690 either session may be killed without affecting the other.
698 .It Xo Ic refresh-client
700 .Op Fl t Ar target-client
702 .D1 (alias: Ic refresh )
703 Refresh the current client if bound to a key, or a single client if one is given
708 is specified, only update the client's status bar.
709 .It Xo Ic rename-session
710 .Op Fl t Ar target-session
713 .D1 (alias: Ic rename )
714 Rename the session to
716 .It Xo Ic show-messages
717 .Op Fl t Ar target-client
719 .D1 (alias: Ic showmsgs )
720 Any messages displayed on the status line are saved in a per-client message
721 log, up to a maximum of the limit set by the
723 session option for the session attached to that client.
724 This command displays the log for
726 .It Ic source-file Ar path
727 .D1 (alias: Ic source )
728 Execute commands from
731 .D1 (alias: Ic start )
734 server, if not already running, without creating any sessions.
735 .It Xo Ic suspend-client
736 .Op Fl t Ar target-client
738 .D1 (alias: Ic suspendc )
739 Suspend a client by sending
742 .It Xo Ic switch-client
744 .Op Fl c Ar target-client
745 .Op Fl t Ar target-session
747 .D1 (alias: Ic switchc )
748 Switch the current session for client
757 is used, the client is moved to the last, next or previous session
760 toggles whether a client is read-only (see the
764 .Sh WINDOWS AND PANES
767 window may be in one of several modes.
768 The default permits direct access to the terminal attached to the window.
769 The other is copy mode, which permits a section of a window or its
770 history to be copied to a
772 for later insertion into another window.
773 This mode is entered with the
778 It is also entered when a command that produces output, such as
780 is executed from a key binding.
782 The keys available depend on whether emacs or vi mode is selected
786 The following keys are supported as appropriate for the mode:
787 .Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
788 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
789 .It Li "Back to indentation" Ta "^" Ta "M-m"
790 .It Li "Bottom of history" Ta "G" Ta "M-<"
791 .It Li "Clear selection" Ta "Escape" Ta "C-g"
792 .It Li "Copy selection" Ta "Enter" Ta "M-w"
793 .It Li "Cursor down" Ta "j" Ta "Down"
794 .It Li "Cursor left" Ta "h" Ta "Left"
795 .It Li "Cursor right" Ta "l" Ta "Right"
796 .It Li "Cursor to bottom line" Ta "L" Ta ""
797 .It Li "Cursor to middle line" Ta "M" Ta "M-r"
798 .It Li "Cursor to top line" Ta "H" Ta "M-R"
799 .It Li "Cursor up" Ta "k" Ta "Up"
800 .It Li "Delete entire line" Ta "d" Ta "C-u"
801 .It Li "Delete/Copy to end of line" Ta "D" Ta "C-k"
802 .It Li "End of line" Ta "$" Ta "C-e"
803 .It Li "Go to line" Ta ":" Ta "g"
804 .It Li "Half page down" Ta "C-d" Ta "M-Down"
805 .It Li "Half page up" Ta "C-u" Ta "M-Up"
806 .It Li "Jump forward" Ta "f" Ta "f"
807 .It Li "Jump to forward" Ta "t" Ta ""
808 .It Li "Jump backward" Ta "F" Ta "F"
809 .It Li "Jump to backward" Ta "T" Ta ""
810 .It Li "Jump again" Ta ";" Ta ";"
811 .It Li "Jump again in reverse" Ta "," Ta ","
812 .It Li "Next page" Ta "C-f" Ta "Page down"
813 .It Li "Next space" Ta "W" Ta ""
814 .It Li "Next space, end of word" Ta "E" Ta ""
815 .It Li "Next word" Ta "w" Ta ""
816 .It Li "Next word end" Ta "e" Ta "M-f"
817 .It Li "Paste buffer" Ta "p" Ta "C-y"
818 .It Li "Previous page" Ta "C-b" Ta "Page up"
819 .It Li "Previous word" Ta "b" Ta "M-b"
820 .It Li "Previous space" Ta "B" Ta ""
821 .It Li "Quit mode" Ta "q" Ta "Escape"
822 .It Li "Rectangle toggle" Ta "v" Ta "R"
823 .It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down"
824 .It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up"
825 .It Li "Search again" Ta "n" Ta "n"
826 .It Li "Search again in reverse" Ta "N" Ta "N"
827 .It Li "Search backward" Ta "?" Ta "C-r"
828 .It Li "Search forward" Ta "/" Ta "C-s"
829 .It Li "Start of line" Ta "0" Ta "C-a"
830 .It Li "Start selection" Ta "Space" Ta "C-Space"
831 .It Li "Top of history" Ta "g" Ta "M->"
832 .It Li "Transpose chars" Ta "" Ta "C-t"
835 The next and previous word keys use space and the
840 characters as word delimiters by default, but this can be adjusted by
844 Next word moves to the start of the next word, next word end to the end of the
845 next word and previous word to the start of the previous word.
846 The three next and previous space keys work similarly but use a space alone as
849 The jump commands enable quick movement within a line.
854 will move the cursor to the next
856 character on the current line.
859 will then jump to the next occurrence.
861 Commands in copy mode may be prefaced by an optional repeat count.
862 With vi key bindings, a prefix is entered using the number keys; with
863 emacs, the Alt (meta) key and a number begins prefix entry.
864 For example, to move the cursor forward by ten words, use
870 When copying the selection, the repeat count indicates the buffer index to
873 Mode key bindings are defined in a set of named tables:
877 for keys used when line editing at the command prompt;
881 for keys used when choosing from lists (such as produced by the
888 The tables may be viewed with the
890 command and keys modified or removed with
895 The paste buffer key pastes the first line from the top paste buffer on the
904 .Op Fl t Ar target-pane
909 option scrolls one page up.
912 Each window displayed by
914 may be split into one or more
916 each pane takes up a certain area of the display and is a separate terminal.
917 A window may be split into panes using the
920 Windows may be split horizontally (with the
923 Panes may be resized with the
931 by default), the current pane may be changed with the
937 commands may be used to swap panes without changing their position.
938 Panes are numbered beginning from zero in the order they are created.
943 These may be selected with the
945 command or cycled with
949 by default); once a layout is chosen, panes within it may be moved and resized
952 The following layouts are supported:
954 .It Ic even-horizontal
955 Panes are spread out evenly from left to right across the window.
957 Panes are spread evenly from top to bottom.
958 .It Ic main-horizontal
959 A large (main) pane is shown at the top of the window and the remaining panes
960 are spread from left to right in the leftover space at the bottom.
963 window option to specify the height of the top pane.
967 but the large pane is placed on the left and the others spread from top to
968 bottom along the right.
973 Panes are spread out as evenly as possible over the window in both rows and
979 may be used to apply a previously used layout - the
981 command displays the layout of each window in a form suitable for use with
984 .Bd -literal -offset indent
987 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
988 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
992 automatically adjusts the size of the layout for the current window size.
993 Note that a layout cannot be applied to a window with more panes than that
994 from which the layout was originally defined.
996 Commands related to windows and panes are as follows:
1000 .Op Fl t Ar target-pane
1002 .D1 (alias: Ic breakp )
1005 off from its containing window to make it the only pane in a new window.
1008 is given, the new window does not become the current window.
1009 .It Xo Ic capture-pane
1010 .Op Fl b Ar buffer-index
1011 .Op Fl E Ar end-line
1012 .Op Fl S Ar start-line
1013 .Op Fl t Ar target-pane
1015 .D1 (alias: Ic capturep )
1016 Capture the contents of a pane to the specified buffer, or a new buffer if none
1022 specify the starting and ending line numbers, zero is the first line of the
1023 visible pane and negative numbers are lines in the history.
1024 The default is to capture only the visible contents of the pane.
1027 .Op Fl t Ar target-window
1030 Put a window into client choice mode, allowing a client to be selected
1031 interactively from a list.
1032 After a client is chosen,
1034 is replaced by the client
1038 and the result executed as a command.
1041 is not given, "detach-client -t '%%'" is used.
1042 This command works only from inside
1046 .Op Fl t Ar target-window
1049 Put a window into session choice mode, where a session may be selected
1050 interactively from a list.
1053 is replaced by the session name in
1055 and the result executed as a command.
1058 is not given, "switch-client -t '%%'" is used.
1059 This command works only from inside
1063 .Op Fl t Ar target-window
1066 Put a window into window choice mode, where a window may be chosen
1067 interactively from a list.
1068 After a window is selected,
1070 is replaced by the session name and window index in
1072 and the result executed as a command.
1075 is not given, "select-window -t '%%'" is used.
1076 This command works only from inside
1078 .It Ic display-panes Op Fl t Ar target-client
1079 .D1 (alias: Ic displayp)
1080 Display a visible indicator of each pane shown by
1083 .Ic display-panes-time ,
1084 .Ic display-panes-colour ,
1086 .Ic display-panes-active-colour
1088 While the indicator is on screen, a pane may be selected with the
1093 .It Xo Ic find-window
1094 .Op Fl t Ar target-window
1097 .D1 (alias: Ic findw )
1102 in window names, titles, and visible content (but not history).
1103 If only one window is matched, it'll be automatically selected, otherwise a
1104 choice list is shown.
1105 This command only works from inside
1111 .Fl p Ar percentage Oc
1112 .Op Fl s Ar src-pane
1113 .Op Fl t Ar dst-pane
1115 .D1 (alias: Ic joinp )
1118 but instead of splitting
1120 and creating a new pane, split it and move
1123 This can be used to reverse
1127 .Op Fl t Ar target-pane
1129 .D1 (alias: Ic killp )
1130 Destroy the given pane.
1131 If no panes remain in the containing window, it is also destroyed.
1134 option kills all but the pane given with
1136 .It Ic kill-window Op Fl t Ar target-window
1137 .D1 (alias: Ic killw )
1138 Kill the current window or the window at
1140 removing it from any sessions to which it is linked.
1141 .It Ic last-pane Op Fl t Ar target-window
1142 .D1 (alias: Ic lastp )
1143 Select the last (previously selected) pane.
1144 .It Ic last-window Op Fl t Ar target-session
1145 .D1 (alias: Ic last )
1146 Select the last (previously selected) window.
1149 is specified, select the last window of the current session.
1150 .It Xo Ic link-window
1152 .Op Fl s Ar src-window
1153 .Op Fl t Ar dst-window
1155 .D1 (alias: Ic linkw )
1162 is specified and no such window exists, the
1169 exists, it is killed, otherwise an error is generated.
1172 is given, the newly linked window is not selected.
1173 .It Xo Ic list-panes
1178 .D1 (alias: Ic lsp )
1183 is ignored and all panes on the server are listed.
1188 is a session (or the current session).
1189 If neither is given,
1191 is a window (or the current window).
1192 For the meaning of the
1197 .It Xo Ic list-windows
1200 .Op Fl t Ar target-session
1202 .D1 (alias: Ic lsw )
1205 is given, list all windows on the server.
1206 Otherwise, list windows in the current session or in
1207 .Ar target-session .
1208 For the meaning of the
1213 .It Xo Ic move-window
1215 .Op Fl s Ar src-window
1216 .Op Fl t Ar dst-window
1218 .D1 (alias: Ic movew )
1221 except the window at
1225 .It Xo Ic new-window
1227 .Op Fl c Ar start-directory
1228 .Op Fl n Ar window-name
1229 .Op Fl t Ar target-window
1230 .Op Ar shell-command
1232 .D1 (alias: Ic neww )
1233 Create a new window.
1236 the new window is inserted at the next index up from the specified
1238 moving windows up if necessary,
1241 is the new window location.
1245 is given, the session does not make the new window the current window.
1247 represents the window to be created; if the target already exists an error is
1250 flag is used, in which case it is destroyed.
1252 is the command to execute.
1255 is not specified, the value of the
1259 specifies the working directory in which the new window is created.
1260 It may have an absolute path or one of the following values (or a subdirectory):
1261 .Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
1262 .It Li "Empty string" Ta "Current pane's directory"
1263 .It Li "~" Ta "User's home directory"
1264 .It Li "-" Ta "Where session was started"
1265 .It Li "." Ta "Where server was started"
1268 When the shell command completes, the window closes.
1271 option to change this behaviour.
1275 environment variable must be set to
1277 for all programs running
1280 New windows will automatically have
1282 added to their environment, but care must be taken not to reset this in shell
1287 option prints the location of the new window after it has been created.
1288 .It Ic next-layout Op Fl t Ar target-window
1289 .D1 (alias: Ic nextl )
1290 Move a window to the next layout and rearrange the panes to fit.
1291 .It Xo Ic next-window
1293 .Op Fl t Ar target-session
1295 .D1 (alias: Ic next )
1296 Move to the next window in the session.
1299 is used, move to the next window with a bell, activity or content alert.
1302 .Op Fl t Ar target-pane
1303 .Op Ar shell-command
1305 .D1 (alias: Ic pipep )
1306 Pipe any output sent by the program in
1309 A pane may only be piped to one command at a time, any existing pipe is
1315 string may contain the special character sequences supported by the
1320 is given, the current pipe (if any) is closed.
1324 option only opens a new pipe if no previous pipe exists, allowing a pipe to
1325 be toggled with a single key, for example:
1326 .Bd -literal -offset indent
1327 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1329 .It Xo Ic previous-layout
1330 .Op Fl t Ar target-window
1332 .D1 (alias: Ic prevl )
1333 Move to the previous layout in the session.
1334 .It Xo Ic previous-window
1336 .Op Fl t Ar target-session
1338 .D1 (alias: Ic prev )
1339 Move to the previous window in the session.
1342 move to the previous window with a bell, activity or content alert.
1343 .It Xo Ic rename-window
1344 .Op Fl t Ar target-window
1347 .D1 (alias: Ic renamew )
1348 Rename the current window, or the window at
1352 .It Xo Ic resize-pane
1354 .Op Fl t Ar target-pane
1357 .D1 (alias: Ic resizep )
1358 Resize a pane, upward with
1360 (the default), downward with
1364 and to the right with
1368 is given in lines or cells (the default is 1).
1369 .It Xo Ic respawn-pane
1371 .Op Fl t Ar target-pane
1372 .Op Ar shell-command
1374 .D1 (alias: Ic respawnp )
1375 Reactivate a pane in which the command has exited (see the
1380 is not given, the command used when the pane was created is executed.
1381 The pane must be already inactive, unless
1383 is given, in which case any existing command is killed.
1384 .It Xo Ic respawn-window
1386 .Op Fl t Ar target-window
1387 .Op Ar shell-command
1389 .D1 (alias: Ic respawnw )
1390 Reactivate a window in which the command has exited (see the
1395 is not given, the command used when the window was created is executed.
1396 The window must be already inactive, unless
1398 is given, in which case any existing command is killed.
1399 .It Xo Ic rotate-window
1401 .Op Fl t Ar target-window
1403 .D1 (alias: Ic rotatew )
1404 Rotate the positions of the panes within a window, either upward (numerically
1407 or downward (numerically higher).
1408 .It Xo Ic select-layout
1410 .Op Fl t Ar target-window
1413 .D1 (alias: Ic selectl )
1414 Choose a specific layout for a window.
1417 is not given, the last preset layout used (if any) is reapplied.
1421 are equivalent to the
1426 .It Xo Ic select-pane
1428 .Op Fl t Ar target-pane
1430 .D1 (alias: Ic selectp )
1433 the active pane in window
1441 is used, respectively the pane below, to the left, to the right, or above the
1442 target pane is used.
1444 is the same as using the
1447 .It Xo Ic select-window
1449 .Op Fl t Ar target-window
1451 .D1 (alias: Ic selectw )
1452 Select the window at
1458 are equivalent to the
1464 .It Xo Ic split-window
1466 .Op Fl c Ar start-directory
1469 .Fl p Ar percentage Oc
1470 .Op Fl t Ar target-pane
1471 .Op Ar shell-command
1473 .D1 (alias: Ic splitw )
1474 Create a new pane by splitting
1477 does a horizontal split and
1479 a vertical split; if neither is specified,
1486 options specify the size of the new pane in lines (for vertical split) or in
1487 cells (for horizontal split), or as a percentage, respectively.
1488 All other options have the same meaning as for the
1493 .Op Fl s Ar src-pane
1494 .Op Fl t Ar dst-pane
1496 .D1 (alias: Ic swapp )
1500 is used and no source pane is specified with
1503 is swapped with the previous pane (before it numerically);
1505 swaps with the next pane (after it numerically).
1509 not to change the active pane.
1510 .It Xo Ic swap-window
1512 .Op Fl s Ar src-window
1513 .Op Fl t Ar dst-window
1515 .D1 (alias: Ic swapw )
1518 except the source and destination windows are swapped.
1519 It is an error if no window exists at
1521 .It Xo Ic unlink-window
1523 .Op Fl t Ar target-window
1525 .D1 (alias: Ic unlinkw )
1530 is given, a window may be unlinked only if it is linked to multiple sessions -
1531 windows may not be linked to no sessions;
1534 is specified and the window is linked to only one session, it is unlinked and
1539 allows a command to be bound to most keys, with or without a prefix key.
1540 When specifying keys, most represent themselves (for example
1544 Ctrl keys may be prefixed with
1550 In addition, the following special key names are accepted:
1568 .Em NPage/PageDown/PgDn ,
1569 .Em PPage/PageUp/PgUp ,
1573 Note that to bind the
1577 keys, quotation marks are necessary, for example:
1578 .Bd -literal -offset indent
1579 bind-key '"' split-window
1580 bind-key "'" new-window
1583 Commands related to key bindings are as follows:
1587 .Op Fl t Ar key-table
1588 .Ar key Ar command Op Ar arguments
1590 .D1 (alias: Ic bind )
1597 the primary key bindings are modified (those normally activated with the prefix
1598 key); in this case, if
1600 is specified, it is not necessary to use the prefix key,
1607 flag indicates this key may repeat, see the
1617 the binding for command mode with
1619 or for normal mode without.
1620 To view the default bindings and possible commands, see the
1623 .It Ic list-keys Op Fl t Ar key-table
1624 .D1 (alias: Ic lsk )
1625 List all key bindings.
1628 the primary key bindings - those executed when preceded by the prefix key -
1630 Keys bound without the prefix key (see
1640 are listed; this may be one of:
1650 .Op Fl t Ar target-pane
1653 .D1 (alias: Ic send )
1654 Send a key or keys to a window.
1657 is the name of the key (such as
1661 ) to send; if the string is not recognised as a key, it is sent as a series of
1665 flag disables key name lookup and sends the keys literally.
1666 All arguments are sent sequentially from first to last.
1669 flag causes the terminal state to be reset.
1670 .It Xo Ic send-prefix
1672 .Op Fl t Ar target-pane
1674 Send the prefix key, or with
1676 the secondary prefix key, to a window as if it was pressed.
1677 .It Xo Ic unbind-key
1679 .Op Fl t Ar key-table
1682 .D1 (alias: Ic unbind )
1683 Unbind the command bound to
1687 the primary key bindings are modified; in this case, if
1689 is specified, the command bound to
1691 without a prefix (if any) is removed.
1694 is present, all key bindings are removed.
1702 is unbound: the binding for command mode with
1704 or for normal mode without.
1707 The appearance and behaviour of
1709 may be modified by changing the value of various options.
1710 There are three types of option:
1711 .Em server options ,
1714 .Em window options .
1718 server has a set of global options which do not apply to any particular
1720 These are altered with the
1723 command, or displayed with the
1728 In addition, each individual session may have a set of session options, and
1729 there is a separate set of global session options.
1730 Sessions which do not have a particular option configured inherit the value
1731 from the global session options.
1732 Session options are set or unset with the
1734 command and may be listed with the
1737 The available server and session options are listed under the
1741 Similarly, a set of window options is attached to each window, and there is
1742 a set of global window options from which any unset options are inherited.
1743 Window options are altered with the
1744 .Ic set-window-option
1745 command and can be listed with the
1746 .Ic show-window-options
1748 All window options are documented with the
1749 .Ic set-window-option
1752 Commands which set options are as follows:
1754 .It Xo Ic set-option
1756 .Op Fl t Ar target-session | Ar target-window
1759 .D1 (alias: Ic set )
1760 Set a window option with
1763 .Ic set-window-option
1765 a server option with
1767 otherwise a session option.
1771 is specified, the global session or window option is set.
1774 and if the option expects a string,
1776 is appended to the existing setting.
1779 flag unsets an option, so a session inherits the option from the global
1781 It is not possible to unset a global option.
1783 Available window options are listed under
1784 .Ic set-window-option .
1787 depends on the option and may be a number, a string, or a flag (on, off, or
1790 Available server options are:
1792 .It Ic buffer-limit Ar number
1793 Set the number of buffers; as new buffers are added to the top of the stack,
1794 old ones are removed from the bottom if necessary to maintain this maximum
1796 .It Ic escape-time Ar time
1797 Set the time in milliseconds for which
1799 waits after an escape is input to determine if it is part of a function or meta
1801 The default is 500 milliseconds.
1802 .It Xo Ic exit-unattached
1805 If enabled, the server will exit when there are no attached clients.
1809 Enable or disable the display of various informational messages (see also the
1812 .It Xo Ic set-clipboard
1815 Attempt to set the terminal clipboard content using the
1819 This option is on by default if there is an
1823 description for the client terminal.
1824 Note that this feature needs to be enabled in
1826 by setting the resource:
1827 .Bd -literal -offset indent
1828 disallowedWindowOps: 20,21,SetXprop
1831 Or changing this property from the
1833 interactive menu when required.
1836 Available session options are:
1838 .It Ic base-index Ar index
1839 Set the base index from which an unused index should be searched when a new
1841 The default is zero.
1842 .It Xo Ic bell-action
1843 .Op Ic any | none | current
1845 Set action on window bell.
1847 means a bell in any window linked to a session causes a bell in the current
1848 window of that session,
1850 means all bells are ignored and
1852 means only bell in windows other than the current window are ignored.
1853 .It Xo Ic bell-on-alert
1856 If on, ring the terminal bell when an activity, content or silence alert
1858 .It Ic default-command Ar shell-command
1859 Set the command used for new windows (if not specified when the window is
1865 The default is an empty string, which instructs
1867 to create a login shell using the value of the
1870 .It Ic default-path Ar path
1871 Set the default working directory for new panes.
1872 If empty (the default), the working directory is determined from the process
1873 running in the active pane, from the command line environment or from the
1874 working directory where the session was created.
1877 is "$HOME" or "~", the value of the
1879 environment variable is used.
1882 is ".", the working directory when
1884 was started is used.
1885 .It Ic default-shell Ar path
1886 Specify the default shell.
1887 This is used as the login shell for new windows when the
1889 option is set to empty, and must be the full path of the executable.
1892 tries to set a default value from the first suitable of the
1894 environment variable, the shell returned by
1898 This option should be configured when
1900 is used as a login shell.
1901 .It Ic default-terminal Ar terminal
1902 Set the default terminal for new windows created in this session - the
1903 default value of the
1905 environment variable.
1908 to work correctly, this
1912 or a derivative of it.
1913 .It Xo Ic destroy-unattached
1916 If enabled and the session is no longer attached to any clients, it is
1918 .It Xo Ic detach-on-destroy
1921 If on (the default), the client is detached when the session it is attached to
1923 If off, the client is switched to the most recently active of the remaining
1925 .It Ic display-panes-active-colour Ar colour
1926 Set the colour used by the
1928 command to show the indicator for the active pane.
1929 .It Ic display-panes-colour Ar colour
1930 Set the colour used by the
1932 command to show the indicators for inactive panes.
1933 .It Ic display-panes-time Ar time
1934 Set the time in milliseconds for which the indicators shown by the
1937 .It Ic display-time Ar time
1938 Set the amount of time for which status line messages and other on-screen
1939 indicators are displayed.
1942 .It Ic history-limit Ar lines
1943 Set the maximum number of lines held in window history.
1944 This setting applies only to new windows - existing window histories are not
1945 resized and retain the limit at the point they were created.
1946 .It Ic lock-after-time Ar number
1947 Lock the session (like the
1951 seconds of inactivity, or the entire server (all sessions) if the
1954 The default is not to lock (set to 0).
1955 .It Ic lock-command Ar shell-command
1956 Command to run when locking each client.
1957 The default is to run
1961 .It Xo Ic lock-server
1967 instead of each session locking individually as each has been
1969 .Ic lock-after-time ,
1970 the entire server will lock after
1972 sessions would have locked.
1973 This has no effect as a session option; it must be set as a global option.
1974 .It Ic message-attr Ar attributes
1975 Set status line message attributes, where
1979 or a comma-delimited list of one or more of:
1990 .It Ic message-bg Ar colour
1991 Set status line message background colour, where
2002 aixterm bright variants (if supported:
2009 from the 256-colour set,
2011 or a hexadecimal RGB string such as
2013 which chooses the closest match from the default 256-colour set.
2014 .It Ic message-command-attr Ar attributes
2015 Set status line message attributes when in command mode.
2016 .It Ic message-command-bg Ar colour
2017 Set status line message background colour when in command mode.
2018 .It Ic message-command-fg Ar colour
2019 Set status line message foreground colour when in command mode.
2020 .It Ic message-fg Ar colour
2021 Set status line message foreground colour.
2022 .It Ic message-limit Ar number
2023 Set the number of error or information messages to save in the message log for
2026 .It Xo Ic mouse-resize-pane
2031 captures the mouse and allows panes to be resized by dragging on their borders.
2032 .It Xo Ic mouse-select-pane
2037 captures the mouse and when a window is split into multiple panes the mouse may
2038 be used to select the current pane.
2039 The mouse click is also passed through to the application as normal.
2040 .It Xo Ic mouse-select-window
2043 If on, clicking the mouse on a window name in the status line will select that
2045 .It Xo Ic mouse-utf8
2048 If enabled, request mouse input as UTF-8 on UTF-8 terminals.
2049 .It Ic pane-active-border-bg Ar colour
2050 .It Ic pane-active-border-fg Ar colour
2051 Set the pane border colour for the currently active pane.
2052 .It Ic pane-border-bg Ar colour
2053 .It Ic pane-border-fg Ar colour
2054 Set the pane border colour for panes aside from the active pane.
2055 .It Ic prefix Ar key
2056 Set the key accepted as a prefix key.
2057 .It Ic prefix2 Ar key
2058 Set a secondary key accepted as a prefix key.
2059 .It Ic repeat-time Ar time
2060 Allow multiple commands to be entered without pressing the prefix-key again
2063 milliseconds (the default is 500).
2064 Whether a key repeats may be set when it is bound using the
2068 Repeat is enabled for the default keys bound to the
2071 .It Xo Ic set-remain-on-exit
2076 window option for any windows first created in this session.
2077 When this option is true, windows in which the running program has
2078 exited do not close, instead remaining open but inactivate.
2081 command to reactivate such a window, or the
2083 command to destroy it.
2084 .It Xo Ic set-titles
2087 Attempt to set the client terminal title using the
2092 entries if they exist.
2094 automatically sets these to the \ee]2;...\e007 sequence if
2095 the terminal appears to be an xterm.
2096 This option is off by default.
2098 will only attempt to set the window title if the STY environment
2100 .It Ic set-titles-string Ar string
2101 String used to set the window title if
2104 Character sequences are replaced as for the
2110 Show or hide the status line.
2111 .It Ic status-attr Ar attributes
2112 Set status line attributes.
2113 .It Ic status-bg Ar colour
2114 Set status line background colour.
2115 .It Ic status-fg Ar colour
2116 Set status line foreground colour.
2117 .It Ic status-interval Ar interval
2118 Update the status bar every
2121 By default, updates will occur every 15 seconds.
2122 A setting of zero disables redrawing at interval.
2123 .It Xo Ic status-justify
2124 .Op Ic left | centre | right
2126 Set the position of the window list component of the status line: left, centre
2128 .It Xo Ic status-keys
2131 Use vi or emacs-style
2132 key bindings in the status line, for example at the command prompt.
2133 The default is emacs, unless the
2137 environment variables are set and contain the string
2139 .It Ic status-left Ar string
2142 to the left of the status bar.
2144 will be passed through
2147 By default, the session name is shown.
2149 may contain any of the following special character sequences:
2150 .Bl -column "Character pair" "Replaced with" -offset indent
2151 .It Sy "Character pair" Ta Sy "Replaced with"
2152 .It Li "#(shell-command)" Ta "First line of the command's output"
2153 .It Li "#[attributes]" Ta "Colour or attribute change"
2154 .It Li "#H" Ta "Hostname of local host"
2155 .It Li "#h" Ta "Hostname of local host without the domain name"
2156 .It Li "#F" Ta "Current window flag"
2157 .It Li "#I" Ta "Current window index"
2158 .It Li "#P" Ta "Current pane index"
2159 .It Li "#S" Ta "Session name"
2160 .It Li "#T" Ta "Current pane title"
2161 .It Li "#W" Ta "Current window name"
2162 .It Li "##" Ta "A literal" Ql #
2165 The #(shell-command) form executes
2167 and inserts the first line of its output.
2168 Note that shell commands are only executed once at the interval specified by
2171 option: if the status line is redrawn in the meantime, the previous result is
2173 Shell commands are executed with the
2175 global environment set (see the
2179 For details on how the names and titles can be set see the
2180 .Sx "NAMES AND TITLES"
2183 #[attributes] allows a comma-separated list of attributes to be specified,
2186 to set the foreground colour,
2188 to set the background colour, the name of one of the attributes (listed under
2191 option) to turn an attribute on, or an attribute prefixed with
2193 to turn one off, for example
2196 .Bd -literal -offset indent
2197 #(sysctl vm.loadavg)
2198 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2201 Where appropriate, special character sequences may be prefixed with a number to
2202 specify the maximum length, for example
2205 By default, UTF-8 in
2207 is not interpreted, to enable UTF-8, use the
2210 .It Ic status-left-attr Ar attributes
2211 Set the attribute of the left part of the status line.
2212 .It Ic status-left-bg Ar colour
2213 Set the background colour of the left part of the status line.
2214 .It Ic status-left-fg Ar colour
2215 Set the foreground colour of the left part of the status line.
2216 .It Ic status-left-length Ar length
2219 of the left component of the status bar.
2221 .It Xo Ic status-position
2224 Set the position of the status line.
2225 .It Ic status-right Ar string
2228 to the right of the status bar.
2229 By default, the current window title in double quotes, the date and the time
2236 character pairs are replaced, and UTF-8 is dependent on the
2239 .It Ic status-right-attr Ar attributes
2240 Set the attribute of the right part of the status line.
2241 .It Ic status-right-bg Ar colour
2242 Set the background colour of the right part of the status line.
2243 .It Ic status-right-fg Ar colour
2244 Set the foreground colour of the right part of the status line.
2245 .It Ic status-right-length Ar length
2248 of the right component of the status bar.
2250 .It Xo Ic status-utf8
2255 to treat top-bit-set characters in the
2259 strings as UTF-8; notably, this is important for wide characters.
2260 This option defaults to off.
2261 .It Ic terminal-overrides Ar string
2262 Contains a list of entries which override terminal descriptions read using
2265 is a comma-separated list of items each a colon-separated string made up of a
2266 terminal type pattern (matched using
2272 For example, to set the
2277 for all terminal types and the
2283 terminal type, the option could be set to the string:
2284 .Bd -literal -offset indent
2285 "*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
2288 The terminal entry value is passed through
2290 before interpretation.
2291 The default value forcibly corrects the
2293 entry for terminals which support 88 or 256 colours:
2294 .Bd -literal -offset indent
2295 "*88col*:colors=88,*256col*:colors=256,xterm*:XT"
2297 .It Ic update-environment Ar variables
2298 Set a space-separated string containing a list of environment variables to be
2299 copied into the session environment when a new session is created or an
2300 existing session is attached.
2301 Any variables that do not exist in the source environment are set to be
2302 removed from the session environment (as if
2308 "DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID
2310 .It Xo Ic visual-activity
2313 If on, display a status line message when activity occurs in a window
2315 .Ic monitor-activity
2316 window option is enabled.
2317 .It Xo Ic visual-bell
2320 If this option is on, a message is shown on a bell instead of it being passed
2321 through to the terminal (which normally makes a sound).
2325 .It Xo Ic visual-content
2329 .Ic visual-activity ,
2330 display a message when content is present in a window
2333 window option is enabled.
2334 .It Xo Ic visual-silence
2339 is enabled, prints a message after the interval has expired on a given window.
2340 .It Ic word-separators Ar string
2341 Sets the session's conception of what characters are considered word
2342 separators, for the purposes of the next and previous word commands in
2347 .It Xo Ic set-window-option
2349 .Op Fl t Ar target-window
2352 .D1 (alias: Ic setw )
2353 Set a window option.
2359 flags work similarly to the
2363 Supported window options are:
2365 .Bl -tag -width Ds -compact
2366 .It Xo Ic aggressive-resize
2369 Aggressively resize the chosen window.
2372 will resize the window to the size of the smallest session for which it is the
2373 current window, rather than the smallest session to which it is attached.
2374 The window may resize when the current window is changed on another sessions;
2375 this option is good for full-screen programs which support
2377 and poor for interactive programs such as shells.
2379 .It Xo Ic allow-rename
2382 Allow programs to change the window name using a terminal escape
2383 sequence (\\033k...\\033\\\\).
2386 .It Xo Ic alternate-screen
2389 This option configures whether programs running inside
2391 may use the terminal alternate screen feature, which allows the
2397 The alternate screen feature preserves the contents of the window when an
2398 interactive application starts and restores it on exit, so that any output
2399 visible before the application starts reappears unchanged after it exits.
2402 .It Xo Ic automatic-rename
2405 Control automatic window renaming.
2406 When this setting is enabled,
2408 will attempt - on supported platforms - to rename the window to reflect the
2409 command currently running in it.
2410 This flag is automatically disabled for an individual window when a name
2411 is specified at creation with
2417 or with a terminal escape sequence.
2418 It may be switched off globally with:
2419 .Bd -literal -offset indent
2420 set-window-option -g automatic-rename off
2423 .It Ic clock-mode-colour Ar colour
2426 .It Xo Ic clock-mode-style
2429 Set clock hour format.
2431 .It Ic force-height Ar height
2432 .It Ic force-width Ar width
2435 from resizing a window to greater than
2439 A value of zero restores the default unlimited setting.
2441 .It Ic main-pane-height Ar height
2442 .It Ic main-pane-width Ar width
2443 Set the width or height of the main (left or top) pane in the
2449 .It Ic mode-attr Ar attributes
2450 Set window modes attributes.
2452 .It Ic mode-bg Ar colour
2453 Set window modes background colour.
2455 .It Ic mode-fg Ar colour
2456 Set window modes foreground colour.
2461 Use vi or emacs-style key bindings in copy and choice modes.
2464 option, the default is emacs, unless
2471 .It Xo Ic mode-mouse
2472 .Op Ic on | off | copy-mode
2474 Mouse state in modes.
2475 If on, the mouse may be used to enter copy mode and copy a selection by
2476 dragging, to enter copy mode and scroll with the mouse wheel, or to select an
2477 option in choice mode.
2480 the mouse behaves as set to on, but cannot be used to enter copy
2483 .It Xo Ic monitor-activity
2486 Monitor for activity in the window.
2487 Windows with activity are highlighted in the status line.
2489 .It Ic monitor-content Ar match-string
2490 Monitor content in the window.
2495 appears in the window, it is highlighted in the status line.
2497 .It Xo Ic monitor-silence
2500 Monitor for silence (no activity) in the window within
2503 Windows that have been silent for the interval are highlighted in the
2505 An interval of zero disables the monitoring.
2507 .It Ic other-pane-height Ar height
2508 Set the height of the other panes (not the main pane) in the
2511 If this option is set to 0 (the default), it will have no effect.
2513 .Ic main-pane-height
2515 .Ic other-pane-height
2516 options are set, the main pane will grow taller to make the other panes the
2517 specified height, but will never shrink to do so.
2519 .It Ic other-pane-width Ar width
2521 .Ic other-pane-height ,
2522 but set the width of other panes in the
2526 .It Ic pane-base-index Ar index
2529 but set the starting index for pane numbers.
2531 .It Xo Ic remain-on-exit
2534 A window with this flag set is not destroyed when the program running in it
2536 The window may be reactivated with the
2540 .It Xo Ic synchronize-panes
2543 Duplicate input to any pane to all other panes in the same window (only
2544 for panes that are not in any special mode).
2551 to expect UTF-8 sequences to appear in this window.
2553 .It Ic window-status-bell-attr Ar attributes
2554 Set status line attributes for windows which have a bell alert.
2556 .It Ic window-status-bell-bg Ar colour
2557 Set status line background colour for windows with a bell alert.
2559 .It Ic window-status-bell-fg Ar colour
2560 Set status line foreground colour for windows with a bell alert.
2562 .It Ic window-status-content-attr Ar attributes
2563 Set status line attributes for windows which have a content alert.
2565 .It Ic window-status-content-bg Ar colour
2566 Set status line background colour for windows with a content alert.
2568 .It Ic window-status-content-fg Ar colour
2569 Set status line foreground colour for windows with a content alert.
2571 .It Ic window-status-activity-attr Ar attributes
2572 Set status line attributes for windows which have an activity (or silence) alert.
2574 .It Ic window-status-activity-bg Ar colour
2575 Set status line background colour for windows with an activity alert.
2577 .It Ic window-status-activity-fg Ar colour
2578 Set status line foreground colour for windows with an activity alert.
2580 .It Ic window-status-attr Ar attributes
2581 Set status line attributes for a single window.
2583 .It Ic window-status-bg Ar colour
2584 Set status line background colour for a single window.
2586 .It Ic window-status-current-attr Ar attributes
2587 Set status line attributes for the currently active window.
2589 .It Ic window-status-current-bg Ar colour
2590 Set status line background colour for the currently active window.
2592 .It Ic window-status-current-fg Ar colour
2593 Set status line foreground colour for the currently active window.
2595 .It Ic window-status-current-format Ar string
2597 .Ar window-status-format ,
2598 but is the format used when the window is the current window.
2600 .It Ic window-status-fg Ar colour
2601 Set status line foreground colour for a single window.
2603 .It Ic window-status-format Ar string
2604 Set the format in which the window is displayed in the status line window list.
2607 option for details of special character sequences available.
2611 .It Xo Ic xterm-keys
2614 If this option is set,
2618 function key sequences; these have a number included to indicate modifiers such
2619 as Shift, Alt or Ctrl.
2622 .It Xo Ic show-options
2624 .Op Fl t Ar target-session | Ar target-window
2626 .D1 (alias: Ic show )
2627 Show the window options with
2630 .Ic show-window-options ) ,
2631 the server options with
2633 otherwise the session options for
2634 .Ar target session .
2635 Global session or window options are listed if
2638 .It Xo Ic show-window-options
2640 .Op Fl t Ar target-window
2642 .D1 (alias: Ic showw )
2643 List the window options for
2645 or the global window options if
2661 This is a string which controls the output format of the command.
2662 Special character sequences are replaced as documented under the
2664 option and an additional long form is accepted.
2665 Replacement variables are enclosed in
2673 Conditionals are also accepted by prefixing with
2675 and separating two alternatives with a comma;
2676 if the specified variable exists and is not zero, the first alternative
2677 is chosen, otherwise the second is used.
2679 .Ql #{?session_attached,attached,not attached}
2680 will include the string
2682 if the session is attached and the string
2684 if it is unattached.
2686 The following variables are available, where appropriate:
2687 .Bl -column "session_created_string" "Replaced with" -offset indent
2688 .It Sy "Variable name" Ta Sy "Replaced with"
2689 .It Li "client_activity" Ta "Integer time client last had activity"
2690 .It Li "client_activity_string" Ta "String time client last had activity"
2691 .It Li "client_created" Ta "Integer time client created"
2692 .It Li "client_created_string" Ta "String time client created"
2693 .It Li "client_cwd" Ta "Working directory of client"
2694 .It Li "client_height" Ta "Height of client"
2695 .It Li "client_readonly" Ta "1 if client is readonly"
2696 .It Li "client_termname" Ta "Terminal name of client"
2697 .It Li "client_tty" Ta "Pseudo terminal of client"
2698 .It Li "client_utf8" Ta "1 if client supports utf8"
2699 .It Li "client_width" Ta "Width of client"
2700 .It Li "host" Ta "Hostname of local host"
2701 .It Li "line" Ta "Line number in the list"
2702 .It Li "pane_active" Ta "1 if active pane"
2703 .It Li "pane_dead" Ta "1 if pane is dead"
2704 .It Li "pane_height" Ta "Height of pane"
2705 .It Li "pane_id" Ta "Unique pane ID"
2706 .It Li "pane_pid" Ta "PID of first process in pane"
2707 .It Li "pane_start_command" Ta "Command pane started with"
2708 .It Li "pane_start_path" Ta "Path pane started with"
2709 .It Li "pane_title" Ta "Title of pane"
2710 .It Li "pane_tty" Ta "Pseudo terminal of pane"
2711 .It Li "pane_width" Ta "Width of pane"
2712 .It Li "session_attached" Ta "1 if session attached"
2713 .It Li "session_created" Ta "Integer time session created"
2714 .It Li "session_created_string" Ta "String time session created"
2715 .It Li "session_group" Ta "Number of session group"
2716 .It Li "session_grouped" Ta "1 if session in a group"
2717 .It Li "session_height" Ta "Height of session"
2718 .It Li "session_name" Ta "Name of session"
2719 .It Li "session_width" Ta "Width of session"
2720 .It Li "session_windows" Ta "Number of windows in session"
2721 .It Li "window_active" Ta "1 if window active"
2722 .It Li "window_flags" Ta "Window flags"
2723 .It Li "window_height" Ta "Height of window"
2724 .It Li "window_index" Ta "Index of window"
2725 .It Li "window_layout" Ta "Window layout description"
2726 .It Li "window_name" Ta "Name of window"
2727 .It Li "window_width" Ta "Width of window"
2729 .Sh NAMES AND TITLES
2731 distinguishes between names and titles.
2732 Windows and sessions have names, which may be used to specify them in targets
2733 and are displayed in the status line and various lists: the name is the
2735 identifier for a window or session.
2736 Only panes have titles.
2737 A pane's title is typically set by the program running inside the pane and
2740 It is the same mechanism used to set for example the
2745 Windows themselves do not have titles - a window's title is the title of its
2748 itself may set the title of the terminal in which the client is running, see
2753 A session's name is set with the
2758 A window's name is set with one of:
2761 A command argument (such as
2769 .Bd -literal -offset indent
2770 $ printf '\e033kWINDOW_NAME\e033\e\e'
2773 Automatic renaming, which sets the name to the active command in the window's
2776 .Ic automatic-rename
2780 When a pane is first created, its title is the hostname.
2781 A pane's title can be set via the OSC title setting sequence, for example:
2782 .Bd -literal -offset indent
2783 $ printf '\e033]2;My Title\e033\e\e'
2786 When the server is started,
2788 copies the environment into the
2789 .Em global environment ;
2790 in addition, each session has a
2791 .Em session environment .
2792 When a window is created, the session and global environments are merged.
2793 If a variable exists in both, the value from the session environment is used.
2794 The result is the initial environment passed to the new process.
2797 .Ic update-environment
2798 session option may be used to update the session environment from the client
2799 when a new session is created or an old reattached.
2801 also initialises the
2803 variable with some internal information to allow commands to be executed
2804 from inside, and the
2806 variable with the correct terminal setting of
2809 Commands to alter and view the environment are:
2811 .It Xo Ic set-environment
2813 .Op Fl t Ar target-session
2814 .Ar name Op Ar value
2816 .D1 (alias: Ic setenv )
2817 Set or unset an environment variable.
2820 is used, the change is made in the global environment; otherwise, it is applied
2821 to the session environment for
2822 .Ar target-session .
2825 flag unsets a variable.
2827 indicates the variable is to be removed from the environment before starting a
2829 .It Xo Ic show-environment
2831 .Op Fl t Ar target-session
2833 .D1 (alias: Ic showenv )
2834 Display the environment for
2836 or the global environment with
2838 Variables removed from the environment are prefixed with
2843 includes an optional status line which is displayed in the bottom line of each
2845 By default, the status line is enabled (it may be disabled with the
2847 session option) and contains, from left-to-right: the name of the current
2848 session in square brackets; the window list; the title of the active pane
2849 in double quotes; and the time and date.
2851 The status line is made of three parts: configurable left and right sections
2852 (which may contain dynamic content such as the time or output from a shell
2855 .Ic status-left-length ,
2858 .Ic status-right-length
2859 options below), and a central window list.
2860 By default, the window list shows the index, name and (if any) flag of the
2861 windows present in the current session in ascending numerical order.
2862 It may be customised with the
2863 .Ar window-status-format
2865 .Ar window-status-current-format
2867 The flag is one of the following symbols appended to the window name:
2868 .Bl -column "Symbol" "Meaning" -offset indent
2869 .It Sy "Symbol" Ta Sy "Meaning"
2870 .It Li "*" Ta "Denotes the current window."
2871 .It Li "-" Ta "Marks the last window (previously selected)."
2872 .It Li "#" Ta "Window is monitored and activity has been detected."
2873 .It Li "!" Ta "A bell has occurred in the window."
2874 .It Li "+" Ta "Window is monitored for content and it has appeared."
2875 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
2878 The # symbol relates to the
2879 .Ic monitor-activity
2883 The window name is printed in inverted colours if an alert (bell, activity or
2884 content) is present.
2886 The colour and attributes of the status line may be configured, the entire
2887 status line using the
2892 session options and individual windows using the
2893 .Ic window-status-attr ,
2894 .Ic window-status-fg
2896 .Ic window-status-bg
2899 The status line is automatically refreshed at interval if it has changed, the
2900 interval may be controlled with the
2904 Commands related to the status line are as follows:
2906 .It Xo Ic command-prompt
2909 .Op Fl t Ar target-client
2912 Open the command prompt in a client.
2913 This may be used from inside
2915 to execute commands interactively.
2919 is specified, it is used as the command.
2922 is a comma-separated list of the initial text for each prompt.
2927 is a comma-separated list of prompts which are displayed in order; otherwise
2928 a single prompt is displayed, constructed from
2930 if it is present, or
2938 may contain the special character sequences supported by the
2942 Before the command is executed, the first occurrence of the string
2944 and all occurrences of
2946 are replaced by the response to the first prompt, the second
2950 are replaced with the response to the second prompt, and so on for further
2952 Up to nine prompt responses may be replaced
2958 .It Xo Ic confirm-before
2960 .Op Fl t Ar target-client
2963 .D1 (alias: Ic confirm )
2964 Ask for confirmation before executing
2970 is the prompt to display; otherwise a prompt is constructed from
2972 It may contain the special character sequences supported by the
2976 This command works only from inside
2978 .It Xo Ic display-message
2980 .Op Fl c Ar target-client
2981 .Op Fl t Ar target-pane
2984 .D1 (alias: Ic display )
2988 is given, the output is printed to stdout, otherwise it is displayed in the
2995 with the exception that #() are not handled; information is taken from
2999 is given, otherwise the active pane for the session attached to
3004 maintains a stack of
3006 Up to the value of the
3008 option are kept; when a new buffer is added, the buffer at the bottom of the
3010 Buffers may be added using
3014 command, and pasted into a window using the
3018 A configurable history buffer is also maintained for each window.
3019 By default, up to 2000 lines are kept; this can be altered with the
3025 The buffer commands are as follows:
3029 .Op Fl t Ar target-window
3032 Put a window into buffer choice mode, where a buffer may be chosen
3033 interactively from a list.
3034 After a buffer is selected,
3036 is replaced by the buffer index in
3038 and the result executed as a command.
3041 is not given, "paste-buffer -b '%%'" is used.
3042 This command works only from inside
3044 .It Ic clear-history Op Fl t Ar target-pane
3045 .D1 (alias: Ic clearhist )
3046 Remove and free the history for the specified pane.
3047 .It Ic delete-buffer Op Fl b Ar buffer-index
3048 .D1 (alias: Ic deleteb )
3049 Delete the buffer at
3051 or the top buffer if not specified.
3053 .D1 (alias: Ic lsb )
3054 List the global buffers.
3055 .It Xo Ic load-buffer
3056 .Op Fl b Ar buffer-index
3059 .D1 (alias: Ic loadb )
3060 Load the contents of the specified paste buffer from
3062 .It Xo Ic paste-buffer
3064 .Op Fl b Ar buffer-index
3065 .Op Fl s Ar separator
3066 .Op Fl t Ar target-pane
3068 .D1 (alias: Ic pasteb )
3069 Insert the contents of a paste buffer into the specified pane.
3070 If not specified, paste into the current one.
3073 also delete the paste buffer from the stack.
3074 When output, any linefeed (LF) characters in the paste buffer are replaced with
3075 a separator, by default carriage return (CR).
3076 A custom separator may be specified using the
3081 flag means to do no replacement (equivalent to a separator of LF).
3082 .It Xo Ic save-buffer
3084 .Op Fl b Ar buffer-index
3087 .D1 (alias: Ic saveb )
3088 Save the contents of the specified paste buffer to
3092 option appends to rather than overwriting the file.
3093 .It Xo Ic set-buffer
3094 .Op Fl b Ar buffer-index
3097 .D1 (alias: Ic setb )
3098 Set the contents of the specified buffer to
3100 .It Xo Ic show-buffer
3101 .Op Fl b Ar buffer-index
3103 .D1 (alias: Ic showb )
3104 Display the contents of the specified buffer.
3107 Miscellaneous commands are as follows:
3109 .It Ic clock-mode Op Fl t Ar target-pane
3110 Display a large clock.
3111 .It Ic if-shell Ar shell-command command Op Ar command
3117 returns success or the second
3121 .D1 (alias: Ic lock )
3122 Lock each client individually by running the command specified by the
3125 .It Ic run-shell Ar shell-command
3126 .D1 (alias: Ic run )
3129 in the background without creating a window.
3130 After it finishes, any output to stdout is displayed in copy mode.
3131 If the command doesn't return success, the exit status is also displayed.
3133 .D1 (alias: Ic info )
3134 Show server information and terminal details.
3136 .Sh TERMINFO EXTENSIONS
3138 understands some extensions to
3142 Set the cursor colour.
3143 The first takes a single string argument and is used to set the colour;
3144 the second takes no arguments and restores the default cursor colour.
3145 If set, a sequence such as this may be used
3146 to change the cursor colour from inside
3148 .Bd -literal -offset indent
3149 $ printf '\e033]12;red\e033\e\e'
3152 Change the cursor style.
3153 If set, a sequence such as this may be used
3154 to change the cursor to an underline:
3155 .Bd -literal -offset indent
3156 $ printf '\e033[4 q'
3161 is set, it will be used to reset the cursor style instead
3165 This sequence can be used by
3167 to store the current buffer in the host terminal's selection (clipboard).
3170 option above and the
3175 .Bl -tag -width "/etc/tmux.confXXX" -compact
3180 .It Pa /etc/tmux.conf
3181 System-wide configuration file.
3189 .Dl $ tmux new-session vi
3191 Most commands have a shorter form, known as an alias.
3192 For new-session, this is
3197 Alternatively, the shortest unambiguous form of a command is accepted.
3198 If there are several options, they are listed:
3199 .Bd -literal -offset indent
3201 ambiguous command: n, could be: new-session, new-window, next-window
3204 Within an active session, a new window may be created by typing
3214 Windows may be navigated with:
3216 (to select window 0),
3218 (to select window 1), and so on;
3220 to select the next window; and
3222 to select the previous window.
3224 A session may be detached using
3226 (or by an external event such as
3228 disconnection) and reattached with:
3230 .Dl $ tmux attach-session
3234 lists the current key bindings in the current window; up and down may be used
3235 to navigate the list or
3239 Commands to be run when the
3241 server is started may be placed in the
3244 Common examples include:
3246 Changing the default prefix key:
3247 .Bd -literal -offset indent
3248 set-option -g prefix C-a
3250 bind-key C-a send-prefix
3253 Turning the status line off, or changing its colour:
3254 .Bd -literal -offset indent
3255 set-option -g status off
3256 set-option -g status-bg blue
3259 Setting other options, such as the default command,
3260 or locking after 30 minutes of inactivity:
3261 .Bd -literal -offset indent
3262 set-option -g default-command "exec /bin/ksh"
3263 set-option -g lock-after-time 1800
3266 Creating new key bindings:
3267 .Bd -literal -offset indent
3268 bind-key b set-option status
3269 bind-key / command-prompt "split-window 'exec man %%'"
3270 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3275 .An Nicholas Marriott Aq nicm@users.sourceforge.net