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; as an exact
389 window name, such as mysession:mywindow; then as an
391 pattern or the start of a window name, such as mysession:mywin* or
393 An empty window name specifies the next unused index if appropriate (for
399 otherwise the current window in
402 The special character
404 uses the last (previously current) window, or
408 are the next window or the previous window by number.
409 When the argument does not contain a colon,
411 first attempts to parse it as window; if that fails, an attempt is made to
415 takes a similar form to
417 but with the optional addition of a period followed by a pane index, for
418 example: mysession:mywindow.1.
419 If the pane index is omitted, the currently active pane in the specified
421 If neither a colon nor period appears,
423 first attempts to use the argument as a pane index; if that fails, it is looked
430 indicate the next or previous pane index, respectively.
441 may be used instead of a pane index.
443 The special characters
447 may be followed by an offset, for example:
448 .Bd -literal -offset indent
452 When dealing with a session that doesn't contain sequential window indexes,
453 they will be correctly skipped.
456 also gives each pane created in a server an identifier consisting of a
458 and a number, starting from zero.
459 A pane's identifier is unique for the life of the
461 server and is passed to the child process of the pane in the
463 environment variable.
464 It may be used alone to target a pane or the window containing it.
470 These must be passed as a single item, which typically means quoting them, for
472 .Bd -literal -offset indent
473 new-window 'vi /etc/passwd'
480 command, passed with the command and arguments separately, for example:
481 .Bd -literal -offset indent
482 bind-key F1 set-window-option force-width 81
487 .Bd -literal -offset indent
488 $ tmux bind-key F1 set-window-option force-width 81
491 Multiple commands may be specified together as part of a
492 .Em command sequence .
493 Each command should be separated by spaces and a semicolon;
494 commands are executed sequentially from left to right.
495 A literal semicolon may be included by escaping it with a backslash (for
496 example, when specifying a command sequence to
502 .Bd -literal -offset indent
503 refresh-client -t/dev/ttyp2
505 rename-session -tfirst newname
507 set-window-option -t:0 monitor-activity on
509 new-window ; split-window -d
514 .Bd -literal -offset indent
515 $ tmux kill-window -t :1
517 $ tmux new-window \e; split-window -d
519 $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
521 .Sh CLIENTS AND SESSIONS
524 server manages clients, sessions, windows and panes.
525 Clients are attached to sessions to interact with them, either
526 when they are created with the
528 command, or later with the
531 Each session has one or more windows
534 Windows may be linked to multiple sessions and are made up of one or
536 each of which contains a pseudo terminal.
537 Commands for creating, linking and otherwise manipulating windows
540 .Sx WINDOWS AND PANES
543 The following commands are available to manage clients and sessions:
545 .It Xo Ic attach-session
547 .Op Fl t Ar target-session
549 .D1 (alias: Ic attach )
552 create a new client in the current terminal and attach it to
554 If used from inside, switch the current client.
557 is specified, any other clients attached to the session are detached.
559 signifies the client is read-only (only keys bound to the
561 command have any effect)
563 If no server is started,
565 will attempt to start it; this will fail unless sessions are created in the
572 are slightly adjusted: if
574 needs to select the most recently used session, it will prefer the most
578 .It Xo Ic detach-client
580 .Op Fl s Ar target-session
581 .Op Fl t Ar target-client
583 .D1 (alias: Ic detach )
584 Detach the current client if bound to a key, the client specified with
586 or all clients currently attached to to the session specified by
590 is given, send SIGHUP to the parent process of the client, typically causing it
592 .It Ic has-session Op Fl t Ar target-session
594 Report an error and exit with 1 if the specified session does not exist.
595 If it does exist, exit with 0.
599 server and clients and destroy all sessions.
600 .It Ic kill-session Op Fl t Ar target-session
601 Destroy the given session, closing any windows linked to it and no other
602 sessions, and detaching all clients attached to it.
603 .It Ic list-clients Op Fl t Ar target-session
605 List all clients attached to the server.
608 is specified, list only clients connected to that session.
610 .D1 (alias: Ic lscm )
611 List the syntax of all commands supported by
615 List all sessions managed by the server.
616 .It Ic lock-client Op Fl t Ar target-client
617 .D1 (alias: Ic lockc )
623 .It Ic lock-session Op Fl t Ar target-session
624 .D1 (alias: Ic locks )
625 Lock all clients attached to
627 .It Xo Ic new-session
629 .Op Fl n Ar window-name
630 .Op Fl s Ar session-name
631 .Op Fl t Ar target-session
637 Create a new session with name
640 The new session is attached to the current terminal unless
646 are the name of and shell command to execute in the initial window.
653 specify the size of the initial window (80 by 24 if not given).
655 If run from a terminal, any
657 special characters are saved and used for new windows in the new session.
661 is given, the new session is
665 This means they share the same set of windows - all windows from
667 are linked to the new session and any subsequent new windows or windows being
668 closed are applied to both sessions.
669 The current and previous window and any session options remain independent and
670 either session may be killed without affecting the other.
678 .It Ic refresh-client Op Fl t Ar target-client
679 .D1 (alias: Ic refresh )
680 Refresh the current client if bound to a key, or a single client if one is given
683 .It Xo Ic rename-session
684 .Op Fl t Ar target-session
687 .D1 (alias: Ic rename )
688 Rename the session to
690 .It Xo Ic show-messages
691 .Op Fl t Ar target-client
693 .D1 (alias: Ic showmsgs )
694 Any messages displayed on the status line are saved in a per-client message
695 log, up to a maximum of the limit set by the
697 session option for the session attached to that client.
698 This command displays the log for
700 .It Ic source-file Ar path
701 .D1 (alias: Ic source )
702 Execute commands from
705 .D1 (alias: Ic start )
708 server, if not already running, without creating any sessions.
709 .It Xo Ic suspend-client
710 .Op Fl t Ar target-client
712 .D1 (alias: Ic suspendc )
713 Suspend a client by sending
716 .It Xo Ic switch-client
718 .Op Fl c Ar target-client
719 .Op Fl t Ar target-session
721 .D1 (alias: Ic switchc )
722 Switch the current session for client
731 is used, the client is moved to the last, next or previous session
734 .Sh WINDOWS AND PANES
737 window may be in one of several modes.
738 The default permits direct access to the terminal attached to the window.
739 The other is copy mode, which permits a section of a window or its
740 history to be copied to a
742 for later insertion into another window.
743 This mode is entered with the
748 It is also entered when a command that produces output, such as
750 is executed from a key binding.
752 The keys available depend on whether emacs or vi mode is selected
756 The following keys are supported as appropriate for the mode:
757 .Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
758 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
759 .It Li "Back to indentation" Ta "^" Ta "M-m"
760 .It Li "Bottom of history" Ta "G" Ta "M-<"
761 .It Li "Clear selection" Ta "Escape" Ta "C-g"
762 .It Li "Copy selection" Ta "Enter" Ta "M-w"
763 .It Li "Cursor down" Ta "j" Ta "Down"
764 .It Li "Cursor left" Ta "h" Ta "Left"
765 .It Li "Cursor right" Ta "l" Ta "Right"
766 .It Li "Cursor to bottom line" Ta "L" Ta ""
767 .It Li "Cursor to middle line" Ta "M" Ta "M-r"
768 .It Li "Cursor to top line" Ta "H" Ta "M-R"
769 .It Li "Cursor up" Ta "k" Ta "Up"
770 .It Li "Delete entire line" Ta "d" Ta "C-u"
771 .It Li "Delete/Copy to end of line" Ta "D" Ta "C-k"
772 .It Li "End of line" Ta "$" Ta "C-e"
773 .It Li "Go to line" Ta ":" Ta "g"
774 .It Li "Half page down" Ta "C-d" Ta "M-Down"
775 .It Li "Half page up" Ta "C-u" Ta "M-Up"
776 .It Li "Jump forward" Ta "f" Ta "f"
777 .It Li "Jump backward" Ta "F" Ta "F"
778 .It Li "Jump again" Ta ";" Ta ";"
779 .It Li "Jump again in reverse" Ta "," Ta ","
780 .It Li "Next page" Ta "C-f" Ta "Page down"
781 .It Li "Next space" Ta "W" Ta ""
782 .It Li "Next space, end of word" Ta "E" Ta ""
783 .It Li "Next word" Ta "w" Ta ""
784 .It Li "Next word end" Ta "e" Ta "M-f"
785 .It Li "Paste buffer" Ta "p" Ta "C-y"
786 .It Li "Previous page" Ta "C-b" Ta "Page up"
787 .It Li "Previous word" Ta "b" Ta "M-b"
788 .It Li "Previous space" Ta "B" Ta ""
789 .It Li "Quit mode" Ta "q" Ta "Escape"
790 .It Li "Rectangle toggle" Ta "v" Ta "R"
791 .It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down"
792 .It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up"
793 .It Li "Search again" Ta "n" Ta "n"
794 .It Li "Search again in reverse" Ta "N" Ta "N"
795 .It Li "Search backward" Ta "?" Ta "C-r"
796 .It Li "Search forward" Ta "/" Ta "C-s"
797 .It Li "Start of line" Ta "0" Ta "C-a"
798 .It Li "Start selection" Ta "Space" Ta "C-Space"
799 .It Li "Top of history" Ta "g" Ta "M->"
800 .It Li "Transpose chars" Ta "" Ta "C-t"
803 The next and previous word keys use space and the
808 characters as word delimiters by default, but this can be adjusted by
812 Next word moves to the start of the next word, next word end to the end of the
813 next word and previous word to the start of the previous word.
814 The three next and previous space keys work similarly but use a space alone as
817 The jump commands enable quick movement within a line.
822 will move the cursor to the next
824 character on the current line.
827 will then jump to the next occurrence.
829 Commands in copy mode may be prefaced by an optional repeat count.
830 With vi key bindings, a prefix is entered using the number keys; with
831 emacs, the Alt (meta) key and a number begins prefix entry.
832 For example, to move the cursor forward by ten words, use
838 Mode key bindings are defined in a set of named tables:
842 for keys used when line editing at the command prompt;
846 for keys used when choosing from lists (such as produced by the
853 The tables may be viewed with the
855 command and keys modified or removed with
860 The paste buffer key pastes the first line from the top paste buffer on the
869 .Op Fl t Ar target-pane
874 option scrolls one page up.
877 Each window displayed by
879 may be split into one or more
881 each pane takes up a certain area of the display and is a separate terminal.
882 A window may be split into panes using the
885 Windows may be split horizontally (with the
888 Panes may be resized with the
896 by default), the current pane may be changed with the
902 commands may be used to swap panes without changing their position.
903 Panes are numbered beginning from zero in the order they are created.
908 These may be selected with the
910 command or cycled with
914 by default); once a layout is chosen, panes within it may be moved and resized
917 The following layouts are supported:
919 .It Ic even-horizontal
920 Panes are spread out evenly from left to right across the window.
922 Panes are spread evenly from top to bottom.
923 .It Ic main-horizontal
924 A large (main) pane is shown at the top of the window and the remaining panes
925 are spread from left to right in the leftover space at the bottom.
928 window option to specify the height of the top pane.
932 but the large pane is placed on the left and the others spread from top to
933 bottom along the right.
938 Panes are spread out as evenly as possible over the window in both rows and
944 may be used to apply a previously used layout - the
946 command displays the layout of each window in a form suitable for use with
949 .Bd -literal -offset indent
952 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
953 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
957 automatically adjusts the size of the layout for the current window size.
958 Note that a layout cannot be applied to a window with more panes than that
959 from which the layout was originally defined.
961 Commands related to windows and panes are as follows:
965 .Op Fl t Ar target-pane
967 .D1 (alias: Ic breakp )
970 off from its containing window to make it the only pane in a new window.
973 is given, the new window does not become the current window.
974 .It Xo Ic capture-pane
975 .Op Fl b Ar buffer-index
977 .Op Fl S Ar start-line
978 .Op Fl t Ar target-pane
980 .D1 (alias: Ic capturep )
981 Capture the contents of a pane to the specified buffer, or a new buffer if none
987 specify the starting and ending line numbers, zero is the first line of the
988 visible pane and negative numbers are lines in the history.
989 The default is to capture only the visible contents of the pane.
992 .Op Fl t Ar target-window
995 Put a window into client choice mode, allowing a client to be selected
996 interactively from a list.
997 After a client is chosen,
999 is replaced by the client
1003 and the result executed as a command.
1006 is not given, "detach-client -t '%%'" is used.
1007 This command works only from inside
1011 .Op Fl t Ar target-window
1014 Put a window into session choice mode, where a session may be selected
1015 interactively from a list.
1018 is replaced by the session name in
1020 and the result executed as a command.
1023 is not given, "switch-client -t '%%'" is used.
1024 This command works only from inside
1028 .Op Fl t Ar target-window
1031 Put a window into window choice mode, where a window may be chosen
1032 interactively from a list.
1033 After a window is selected,
1035 is replaced by the session name and window index in
1037 and the result executed as a command.
1040 is not given, "select-window -t '%%'" is used.
1041 This command works only from inside
1043 .It Ic display-panes Op Fl t Ar target-client
1044 .D1 (alias: Ic displayp)
1045 Display a visible indicator of each pane shown by
1048 .Ic display-panes-time ,
1049 .Ic display-panes-colour ,
1051 .Ic display-panes-active-colour
1053 While the indicator is on screen, a pane may be selected with the
1058 .It Xo Ic find-window
1059 .Op Fl t Ar target-window
1062 .D1 (alias: Ic findw )
1067 in window names, titles, and visible content (but not history).
1068 If only one window is matched, it'll be automatically selected, otherwise a
1069 choice list is shown.
1070 This command only works from inside
1076 .Fl p Ar percentage Oc
1077 .Op Fl s Ar src-pane
1078 .Op Fl t Ar dst-pane
1080 .D1 (alias: Ic joinp )
1083 but instead of splitting
1085 and creating a new pane, split it and move
1088 This can be used to reverse
1092 .Op Fl t Ar target-pane
1094 .D1 (alias: Ic killp )
1095 Destroy the given pane.
1096 If no panes remain in the containing window, it is also destroyed.
1099 option kills all but the pane given with
1101 .It Ic kill-window Op Fl t Ar target-window
1102 .D1 (alias: Ic killw )
1103 Kill the current window or the window at
1105 removing it from any sessions to which it is linked.
1106 .It Ic last-pane Op Fl t Ar target-window
1107 .D1 (alias: Ic lastp )
1108 Select the last (previously selected) pane.
1109 .It Ic last-window Op Fl t Ar target-session
1110 .D1 (alias: Ic last )
1111 Select the last (previously selected) window.
1114 is specified, select the last window of the current session.
1115 .It Xo Ic link-window
1117 .Op Fl s Ar src-window
1118 .Op Fl t Ar dst-window
1120 .D1 (alias: Ic linkw )
1127 is specified and no such window exists, the
1134 exists, it is killed, otherwise an error is generated.
1137 is given, the newly linked window is not selected.
1138 .It Xo Ic list-panes
1142 .D1 (alias: Ic lsp )
1147 is ignored and all panes on the server are listed.
1152 is a session (or the current session).
1153 If neither is given,
1155 is a window (or the current window).
1156 .It Xo Ic list-windows
1158 .Op Fl t Ar target-session
1160 .D1 (alias: Ic lsw )
1163 is given, list all windows on the server.
1164 Otherwise, list windows in the current session or in
1165 .Ar target-session .
1166 .It Xo Ic move-window
1168 .Op Fl s Ar src-window
1169 .Op Fl t Ar dst-window
1171 .D1 (alias: Ic movew )
1174 except the window at
1178 .It Xo Ic new-window
1180 .Op Fl n Ar window-name
1181 .Op Fl t Ar target-window
1182 .Op Ar shell-command
1184 .D1 (alias: Ic neww )
1185 Create a new window.
1188 the new window is inserted at the next index up from the specified
1190 moving windows up if necessary,
1193 is the new window location.
1197 is given, the session does not make the new window the current window.
1199 represents the window to be created; if the target already exists an error is
1202 flag is used, in which case it is destroyed.
1204 is the command to execute.
1207 is not specified, the value of the
1211 When the shell command completes, the window closes.
1214 option to change this behaviour.
1218 environment variable must be set to
1220 for all programs running
1223 New windows will automatically have
1225 added to their environment, but care must be taken not to reset this in shell
1230 option prints the location of the new window after it has been created.
1231 .It Ic next-layout Op Fl t Ar target-window
1232 .D1 (alias: Ic nextl )
1233 Move a window to the next layout and rearrange the panes to fit.
1234 .It Xo Ic next-window
1236 .Op Fl t Ar target-session
1238 .D1 (alias: Ic next )
1239 Move to the next window in the session.
1242 is used, move to the next window with a bell, activity or content alert.
1245 .Op Fl t Ar target-pane
1246 .Op Ar shell-command
1248 .D1 (alias: Ic pipep )
1249 Pipe any output sent by the program in
1252 A pane may only be piped to one command at a time, any existing pipe is
1258 string may contain the special character sequences supported by the
1263 is given, the current pipe (if any) is closed.
1267 option only opens a new pipe if no previous pipe exists, allowing a pipe to
1268 be toggled with a single key, for example:
1269 .Bd -literal -offset indent
1270 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1272 .It Xo Ic previous-layout
1273 .Op Fl t Ar target-window
1275 .D1 (alias: Ic prevl )
1276 Move to the previous layout in the session.
1277 .It Xo Ic previous-window
1279 .Op Fl t Ar target-session
1281 .D1 (alias: Ic prev )
1282 Move to the previous window in the session.
1285 move to the previous window with a bell, activity or content alert.
1286 .It Xo Ic rename-window
1287 .Op Fl t Ar target-window
1290 .D1 (alias: Ic renamew )
1291 Rename the current window, or the window at
1295 .It Xo Ic resize-pane
1297 .Op Fl t Ar target-pane
1300 .D1 (alias: Ic resizep )
1301 Resize a pane, upward with
1303 (the default), downward with
1307 and to the right with
1311 is given in lines or cells (the default is 1).
1312 .It Xo Ic respawn-pane
1314 .Op Fl t Ar target-pane
1315 .Op Ar shell-command
1317 .D1 (alias: Ic respawnp )
1318 Reactivate a pane in which the command has exited (see the
1323 is not given, the command used when the pane was created is executed.
1324 The pane must be already inactive, unless
1326 is given, in which case any existing command is killed.
1327 .It Xo Ic respawn-window
1329 .Op Fl t Ar target-window
1330 .Op Ar shell-command
1332 .D1 (alias: Ic respawnw )
1333 Reactivate a window in which the command has exited (see the
1338 is not given, the command used when the window was created is executed.
1339 The window must be already inactive, unless
1341 is given, in which case any existing command is killed.
1342 .It Xo Ic rotate-window
1344 .Op Fl t Ar target-window
1346 .D1 (alias: Ic rotatew )
1347 Rotate the positions of the panes within a window, either upward (numerically
1350 or downward (numerically higher).
1351 .It Xo Ic select-layout
1353 .Op Fl t Ar target-window
1356 .D1 (alias: Ic selectl )
1357 Choose a specific layout for a window.
1360 is not given, the last preset layout used (if any) is reapplied.
1364 are equivalent to the
1369 .It Xo Ic select-pane
1371 .Op Fl t Ar target-pane
1373 .D1 (alias: Ic selectp )
1376 the active pane in window
1384 is used, respectively the pane below, to the left, to the right, or above the
1385 target pane is used.
1387 is the same as using the
1390 .It Xo Ic select-window
1392 .Op Fl t Ar target-window
1394 .D1 (alias: Ic selectw )
1395 Select the window at
1401 are equivalent to the
1407 .It Xo Ic split-window
1411 .Fl p Ar percentage Oc
1412 .Op Fl t Ar target-pane
1413 .Op Ar shell-command
1415 .D1 (alias: Ic splitw )
1416 Create a new pane by splitting
1419 does a horizontal split and
1421 a vertical split; if neither is specified,
1428 options specify the size of the new pane in lines (for vertical split) or in
1429 cells (for horizontal split), or as a percentage, respectively.
1430 All other options have the same meaning as for the
1435 .Op Fl s Ar src-pane
1436 .Op Fl t Ar dst-pane
1438 .D1 (alias: Ic swapp )
1442 is used and no source pane is specified with
1445 is swapped with the previous pane (before it numerically);
1447 swaps with the next pane (after it numerically).
1451 not to change the active pane.
1452 .It Xo Ic swap-window
1454 .Op Fl s Ar src-window
1455 .Op Fl t Ar dst-window
1457 .D1 (alias: Ic swapw )
1460 except the source and destination windows are swapped.
1461 It is an error if no window exists at
1463 .It Xo Ic unlink-window
1465 .Op Fl t Ar target-window
1467 .D1 (alias: Ic unlinkw )
1472 is given, a window may be unlinked only if it is linked to multiple sessions -
1473 windows may not be linked to no sessions;
1476 is specified and the window is linked to only one session, it is unlinked and
1481 allows a command to be bound to most keys, with or without a prefix key.
1482 When specifying keys, most represent themselves (for example
1486 Ctrl keys may be prefixed with
1492 In addition, the following special key names are accepted:
1517 Note that to bind the
1521 keys, quotation marks are necessary, for example:
1522 .Bd -literal -offset indent
1523 bind-key '"' split-window
1524 bind-key "'" new-window
1527 Commands related to key bindings are as follows:
1531 .Op Fl t Ar key-table
1532 .Ar key Ar command Op Ar arguments
1534 .D1 (alias: Ic bind )
1541 the primary key bindings are modified (those normally activated with the prefix
1542 key); in this case, if
1544 is specified, it is not necessary to use the prefix key,
1551 flag indicates this key may repeat, see the
1561 the binding for command mode with
1563 or for normal mode without.
1564 To view the default bindings and possible commands, see the
1567 .It Ic list-keys Op Fl t Ar key-table
1568 .D1 (alias: Ic lsk )
1569 List all key bindings.
1572 the primary key bindings - those executed when preceded by the prefix key -
1574 Keys bound without the prefix key (see
1584 are listed; this may be one of:
1593 .Op Fl t Ar target-pane
1596 .D1 (alias: Ic send )
1597 Send a key or keys to a window.
1600 is the name of the key (such as
1604 ) to send; if the string is not recognised as a key, it is sent as a series of
1606 All arguments are sent sequentially from first to last.
1607 .It Ic send-prefix Op Fl t Ar target-pane
1608 Send the prefix key to a window as if it was pressed.
1609 If multiple prefix keys are configured, only the first is sent.
1610 .It Xo Ic unbind-key
1612 .Op Fl t Ar key-table
1615 .D1 (alias: Ic unbind )
1616 Unbind the command bound to
1620 the primary key bindings are modified; in this case, if
1622 is specified, the command bound to
1624 without a prefix (if any) is removed.
1627 is present, all key bindings are removed.
1635 is unbound: the binding for command mode with
1637 or for normal mode without.
1640 The appearance and behaviour of
1642 may be modified by changing the value of various options.
1643 There are three types of option:
1644 .Em server options ,
1647 .Em window options .
1651 server has a set of global options which do not apply to any particular
1653 These are altered with the
1656 command, or displayed with the
1661 In addition, each individual session may have a set of session options, and
1662 there is a separate set of global session options.
1663 Sessions which do not have a particular option configured inherit the value
1664 from the global session options.
1665 Session options are set or unset with the
1667 command and may be listed with the
1670 The available server and session options are listed under the
1674 Similarly, a set of window options is attached to each window, and there is
1675 a set of global window options from which any unset options are inherited.
1676 Window options are altered with the
1677 .Ic set-window-option
1678 command and can be listed with the
1679 .Ic show-window-options
1681 All window options are documented with the
1682 .Ic set-window-option
1685 Commands which set options are as follows:
1687 .It Xo Ic set-option
1689 .Op Fl t Ar target-session | Ar target-window
1692 .D1 (alias: Ic set )
1693 Set a window option with
1696 .Ic set-window-option
1698 a server option with
1700 otherwise a session option.
1704 is specified, the global session or window option is set.
1707 and if the option expects a string,
1709 is appended to the existing setting.
1712 flag unsets an option, so a session inherits the option from the global
1714 It is not possible to unset a global option.
1716 Available window options are listed under
1717 .Ic set-window-option .
1719 Available server options are:
1721 .It Ic buffer-limit Ar number
1722 Set the number of buffers; as new buffers are added to the top of the stack,
1723 old ones are removed from the bottom if necessary to maintain this maximum
1725 .It Xo Ic set-clipboard
1728 Attempt to set the terminal clipboard content using the
1732 This option is on by default if there is an
1736 description for the client terminal.
1737 Note that this feature needs to be enabled in
1739 by setting the resource:
1740 .Bd -literal -offset indent
1741 disallowedWindowOps: 20,21,SetXprop
1744 Or changing this property from the
1746 interactive menu when required.
1747 .It Ic escape-time Ar time
1748 Set the time in milliseconds for which
1750 waits after an escape is input to determine if it is part of a function or meta
1752 The default is 500 milliseconds.
1753 .It Xo Ic exit-unattached
1756 If enabled, the server will exit when there are no attached clients.
1760 Enable or disable the display of various informational messages (see also the
1765 Available session options are:
1767 .It Ic base-index Ar index
1768 Set the base index from which an unused index should be searched when a new
1770 The default is zero.
1771 .It Xo Ic bell-action
1772 .Op Ic any | none | current
1774 Set action on window bell.
1776 means a bell in any window linked to a session causes a bell in the current
1777 window of that session,
1779 means all bells are ignored and
1781 means only bell in windows other than the current window are ignored.
1782 .It Xo Ic bell-on-alert
1785 If on, ring the terminal bell when an activity, content or silence alert
1787 .It Ic default-command Ar shell-command
1788 Set the command used for new windows (if not specified when the window is
1794 The default is an empty string, which instructs
1796 to create a login shell using the value of the
1799 .It Ic default-path Ar path
1800 Set the default working directory for processes created from keys, or
1801 interactively from the prompt.
1802 The default is empty, which means to use the working directory of the shell
1803 from which the server was started if it is available or the user's home if not.
1804 .It Ic default-shell Ar path
1805 Specify the default shell.
1806 This is used as the login shell for new windows when the
1808 option is set to empty, and must be the full path of the executable.
1811 tries to set a default value from the first suitable of the
1813 environment variable, the shell returned by
1817 This option should be configured when
1819 is used as a login shell.
1820 .It Ic default-terminal Ar terminal
1821 Set the default terminal for new windows created in this session - the
1822 default value of the
1824 environment variable.
1827 to work correctly, this
1831 or a derivative of it.
1832 .It Xo Ic destroy-unattached
1835 If enabled and the session is no longer attached to any clients, it is
1837 .It Xo Ic detach-on-destroy
1840 If on (the default), the client is detached when the session it is attached to
1842 If off, the client is switched to the most recently active of the remaining
1844 .It Ic display-panes-active-colour Ar colour
1845 Set the colour used by the
1847 command to show the indicator for the active pane.
1848 .It Ic display-panes-colour Ar colour
1849 Set the colour used by the
1851 command to show the indicators for inactive panes.
1852 .It Ic display-panes-time Ar time
1853 Set the time in milliseconds for which the indicators shown by the
1856 .It Ic display-time Ar time
1857 Set the amount of time for which status line messages and other on-screen
1858 indicators are displayed.
1861 .It Ic history-limit Ar lines
1862 Set the maximum number of lines held in window history.
1863 This setting applies only to new windows - existing window histories are not
1864 resized and retain the limit at the point they were created.
1865 .It Ic lock-after-time Ar number
1866 Lock the session (like the
1870 seconds of inactivity, or the entire server (all sessions) if the
1873 The default is not to lock (set to 0).
1874 .It Ic lock-command Ar shell-command
1875 Command to run when locking each client.
1876 The default is to run
1880 .It Xo Ic lock-server
1886 instead of each session locking individually as each has been
1888 .Ic lock-after-time ,
1889 the entire server will lock after
1891 sessions would have locked.
1892 This has no effect as a session option; it must be set as a global option.
1893 .It Ic message-attr Ar attributes
1894 Set status line message attributes, where
1898 or a comma-delimited list of one or more of:
1909 .It Ic message-bg Ar colour
1910 Set status line message background colour, where
1924 from the 256-colour set,
1926 or a hexadecimal RGB string such as
1928 which chooses the closest match from the default 256-colour set.
1929 .It Ic message-fg Ar colour
1930 Set status line message foreground colour.
1931 .It Ic message-limit Ar number
1932 Set the number of error or information messages to save in the message log for
1935 .It Xo Ic mouse-resize-pane
1940 captures the mouse and allows panes to be resized by dragging on their borders.
1941 .It Xo Ic mouse-select-pane
1946 captures the mouse and when a window is split into multiple panes the mouse may
1947 be used to select the current pane.
1948 The mouse click is also passed through to the application as normal.
1949 .It Xo Ic mouse-select-window
1952 If on, clicking the mouse on a window name in the status line will select that
1954 .It Ic pane-active-border-bg Ar colour
1955 .It Ic pane-active-border-fg Ar colour
1956 Set the pane border colour for the currently active pane.
1957 .It Ic pane-border-bg Ar colour
1958 .It Ic pane-border-fg Ar colour
1959 Set the pane border colour for panes aside from the active pane.
1960 .It Ic prefix Ar keys
1961 Set the keys accepted as a prefix key.
1963 is a comma-separated list of key names, each of which individually behave as
1965 .It Ic repeat-time Ar time
1966 Allow multiple commands to be entered without pressing the prefix-key again
1969 milliseconds (the default is 500).
1970 Whether a key repeats may be set when it is bound using the
1974 Repeat is enabled for the default keys bound to the
1977 .It Xo Ic mouse-utf8
1980 If enabled, request mouse input as UTF-8 on UTF-8 terminals.
1981 .It Xo Ic set-remain-on-exit
1986 window option for any windows first created in this session.
1987 When this option is true, windows in which the running program has
1988 exited do not close, instead remaining open but inactivate.
1991 command to reactivate such a window, or the
1993 command to destroy it.
1994 .It Xo Ic set-titles
1997 Attempt to set the window title using the \ee]2;...\e007 xterm code if
1998 the terminal appears to be an xterm.
1999 This option is off by default.
2001 will only attempt to set the window title if the STY environment
2003 .It Ic set-titles-string Ar string
2004 String used to set the window title if
2007 Character sequences are replaced as for the
2013 Show or hide the status line.
2014 .It Ic status-attr Ar attributes
2015 Set status line attributes.
2016 .It Ic status-bg Ar colour
2017 Set status line background colour.
2018 .It Ic status-fg Ar colour
2019 Set status line foreground colour.
2020 .It Ic status-interval Ar interval
2021 Update the status bar every
2024 By default, updates will occur every 15 seconds.
2025 A setting of zero disables redrawing at interval.
2026 .It Xo Ic status-justify
2027 .Op Ic left | centre | right
2029 Set the position of the window list component of the status line: left, centre
2031 .It Xo Ic status-keys
2034 Use vi or emacs-style
2035 key bindings in the status line, for example at the command prompt.
2036 The default is emacs, unless the
2040 environment variables are set and contain the string
2042 .It Ic status-left Ar string
2045 to the left of the status bar.
2047 will be passed through
2050 By default, the session name is shown.
2052 may contain any of the following special character sequences:
2053 .Bl -column "Character pair" "Replaced with" -offset indent
2054 .It Sy "Character pair" Ta Sy "Replaced with"
2055 .It Li "#(shell-command)" Ta "First line of the command's output"
2056 .It Li "#[attributes]" Ta "Colour or attribute change"
2057 .It Li "#H" Ta "Hostname of local host"
2058 .It Li "#h" Ta "Hostname of local host without the domain name"
2059 .It Li "#F" Ta "Current window flag"
2060 .It Li "#I" Ta "Current window index"
2061 .It Li "#P" Ta "Current pane index"
2062 .It Li "#S" Ta "Session name"
2063 .It Li "#T" Ta "Current window title"
2064 .It Li "#W" Ta "Current window name"
2065 .It Li "##" Ta "A literal" Ql #
2068 The #(shell-command) form executes
2070 and inserts the first line of its output.
2071 Note that shell commands are only executed once at the interval specified by
2074 option: if the status line is redrawn in the meantime, the previous result is
2076 Shell commands are executed with the
2078 global environment set (see the
2082 The window title (#T) is the title set by the program running within the window
2083 using the OSC title setting sequence, for example:
2084 .Bd -literal -offset indent
2085 $ printf '\e033]2;My Title\e033\e\e'
2088 When a window is first created, its title is the hostname.
2090 #[attributes] allows a comma-separated list of attributes to be specified,
2093 to set the foreground colour,
2095 to set the background colour, the name of one of the attributes (listed under
2098 option) to turn an attribute on, or an attribute prefixed with
2100 to turn one off, for example
2103 .Bd -literal -offset indent
2104 #(sysctl vm.loadavg)
2105 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2108 Where appropriate, special character sequences may be prefixed with a number to
2109 specify the maximum length, for example
2112 By default, UTF-8 in
2114 is not interpreted, to enable UTF-8, use the
2117 .It Ic status-left-attr Ar attributes
2118 Set the attribute of the left part of the status line.
2119 .It Ic status-left-bg Ar colour
2120 Set the background colour of the left part of the status line.
2121 .It Ic status-left-fg Ar colour
2122 Set the foreground colour of the left part of the status line.
2123 .It Ic status-left-length Ar length
2126 of the left component of the status bar.
2128 .It Ic status-right Ar string
2131 to the right of the status bar.
2132 By default, the current window title in double quotes, the date and the time
2139 character pairs are replaced, and UTF-8 is dependent on the
2142 .It Ic status-right-attr Ar attributes
2143 Set the attribute of the right part of the status line.
2144 .It Ic status-right-bg Ar colour
2145 Set the background colour of the right part of the status line.
2146 .It Ic status-right-fg Ar colour
2147 Set the foreground colour of the right part of the status line.
2148 .It Ic status-right-length Ar length
2151 of the right component of the status bar.
2153 .It Xo Ic status-utf8
2158 to treat top-bit-set characters in the
2162 strings as UTF-8; notably, this is important for wide characters.
2163 This option defaults to off.
2164 .It Ic terminal-overrides Ar string
2165 Contains a list of entries which override terminal descriptions read using
2168 is a comma-separated list of items each a colon-separated string made up of a
2169 terminal type pattern (matched using
2175 For example, to set the
2180 for all terminal types and the
2186 terminal type, the option could be set to the string:
2187 .Bd -literal -offset indent
2188 "*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
2191 The terminal entry value is passed through
2193 before interpretation.
2194 The default value forcibly corrects the
2196 entry for terminals which support 88 or 256 colours:
2197 .Bd -literal -offset indent
2198 "*88col*:colors=88,*256col*:colors=256,xterm*:XT"
2200 .It Ic update-environment Ar variables
2201 Set a space-separated string containing a list of environment variables to be
2202 copied into the session environment when a new session is created or an
2203 existing session is attached.
2204 Any variables that do not exist in the source environment are set to be
2205 removed from the session environment (as if
2211 "DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID
2213 .It Xo Ic visual-activity
2216 If on, display a status line message when activity occurs in a window
2218 .Ic monitor-activity
2219 window option is enabled.
2220 .It Xo Ic visual-bell
2223 If this option is on, a message is shown on a bell instead of it being passed
2224 through to the terminal (which normally makes a sound).
2228 .It Xo Ic visual-content
2232 .Ic visual-activity ,
2233 display a message when content is present in a window
2236 window option is enabled.
2237 .It Xo Ic visual-silence
2242 is enabled, prints a message after the interval has expired on a given window.
2244 .It Xo Ic set-window-option
2246 .Op Fl t Ar target-window
2249 .D1 (alias: Ic setw )
2250 Set a window option.
2256 flags work similarly to the
2260 Supported window options are:
2262 .Bl -tag -width Ds -compact
2263 .It Xo Ic aggressive-resize
2266 Aggressively resize the chosen window.
2269 will resize the window to the size of the smallest session for which it is the
2270 current window, rather than the smallest session to which it is attached.
2271 The window may resize when the current window is changed on another sessions;
2272 this option is good for full-screen programs which support
2274 and poor for interactive programs such as shells.
2276 .It Xo Ic alternate-screen
2279 This option configures whether programs running inside
2281 may use the terminal alternate screen feature, which allows the
2287 The alternate screen feature preserves the contents of the window when an
2288 interactive application starts and restores it on exit, so that any output
2289 visible before the application starts reappears unchanged after it exits.
2292 .It Xo Ic automatic-rename
2295 Control automatic window renaming.
2296 When this setting is enabled,
2298 will attempt - on supported platforms - to rename the window to reflect the
2299 command currently running in it.
2300 This flag is automatically disabled for an individual window when a name
2301 is specified at creation with
2307 It may be switched off globally with:
2308 .Bd -literal -offset indent
2309 set-window-option -g automatic-rename off
2312 .It Ic clock-mode-colour Ar colour
2315 .It Xo Ic clock-mode-style
2318 Set clock hour format.
2320 .It Ic force-height Ar height
2321 .It Ic force-width Ar width
2324 from resizing a window to greater than
2328 A value of zero restores the default unlimited setting.
2330 .It Ic main-pane-height Ar height
2331 .It Ic main-pane-width Ar width
2332 Set the width or height of the main (left or top) pane in the
2338 .It Ic mode-attr Ar attributes
2339 Set window modes attributes.
2341 .It Ic mode-bg Ar colour
2342 Set window modes background colour.
2344 .It Ic mode-fg Ar colour
2345 Set window modes foreground colour.
2350 Use vi or emacs-style key bindings in copy and choice modes.
2353 option, the default is emacs, unless
2360 .It Xo Ic mode-mouse
2363 Mouse state in modes.
2364 If on, the mouse may be used to enter copy mode and copy a selection by
2365 dragging, to enter copy mode and scroll with the mouse wheel, or to select an
2366 option in choice mode.
2368 .It Xo Ic monitor-activity
2371 Monitor for activity in the window.
2372 Windows with activity are highlighted in the status line.
2374 .It Ic monitor-content Ar match-string
2375 Monitor content in the window.
2380 appears in the window, it is highlighted in the status line.
2382 .It Xo Ic monitor-silence
2385 Monitor for silence (no activity) in the window within
2388 Windows that have been silent for the interval are highlighted in the
2390 An interval of zero disables the monitoring.
2392 .It Ic other-pane-height Ar height
2393 Set the height of the other panes (not the main pane) in the
2396 If this option is set to 0 (the default), it will have no effect.
2398 .Ic main-pane-height
2400 .Ic other-pane-height
2401 options are set, the main pane will grow taller to make the other panes the
2402 specified height, but will never shrink to do so.
2404 .It Ic other-pane-width Ar width
2406 .Ic other-pane-height ,
2407 but set the width of other panes in the
2411 .It Xo Ic remain-on-exit
2414 A window with this flag set is not destroyed when the program running in it
2416 The window may be reactivated with the
2420 .It Xo Ic synchronize-panes
2423 Duplicate input to any pane to all other panes in the same window (only
2424 for panes that are not in any special mode).
2431 to expect UTF-8 sequences to appear in this window.
2433 .It Ic window-status-attr Ar attributes
2434 Set status line attributes for a single window.
2436 .It Ic window-status-bg Ar colour
2437 Set status line background colour for a single window.
2439 .It Ic window-status-fg Ar colour
2440 Set status line foreground colour for a single window.
2442 .It Ic window-status-format Ar string
2443 Set the format in which the window is displayed in the status line window list.
2446 option for details of special character sequences available.
2450 .It Ic window-status-alert-attr Ar attributes
2451 Set status line attributes for windows which have an alert (bell, activity
2454 .It Ic window-status-alert-bg Ar colour
2455 Set status line background colour for windows with an alert.
2457 .It Ic window-status-alert-fg Ar colour
2458 Set status line foreground colour for windows with an alert.
2460 .It Ic window-status-current-attr Ar attributes
2461 Set status line attributes for the currently active window.
2463 .It Ic window-status-current-bg Ar colour
2464 Set status line background colour for the currently active window.
2466 .It Ic window-status-current-fg Ar colour
2467 Set status line foreground colour for the currently active window.
2469 .It Ic window-status-current-format Ar string
2471 .Ar window-status-format ,
2472 but is the format used when the window is the current window.
2474 .It Ic word-separators Ar string
2475 Sets the window's conception of what characters are considered word
2476 separators, for the purposes of the next and previous word commands in
2481 .It Xo Ic xterm-keys
2484 If this option is set,
2488 function key sequences; these have a number included to indicate modifiers such
2489 as Shift, Alt or Ctrl.
2492 .It Xo Ic show-options
2494 .Op Fl t Ar target-session | Ar target-window
2496 .D1 (alias: Ic show )
2497 Show the window options with
2500 .Ic show-window-options ) ,
2501 the server options with
2503 otherwise the session options for
2504 .Ar target session .
2505 Global session or window options are listed if
2508 .It Xo Ic show-window-options
2510 .Op Fl t Ar target-window
2512 .D1 (alias: Ic showw )
2513 List the window options for
2515 or the global window options if
2520 When the server is started,
2522 copies the environment into the
2523 .Em global environment ;
2524 in addition, each session has a
2525 .Em session environment .
2526 When a window is created, the session and global environments are merged.
2527 If a variable exists in both, the value from the session environment is used.
2528 The result is the initial environment passed to the new process.
2531 .Ic update-environment
2532 session option may be used to update the session environment from the client
2533 when a new session is created or an old reattached.
2535 also initialises the
2537 variable with some internal information to allow commands to be executed
2538 from inside, and the
2540 variable with the correct terminal setting of
2543 Commands to alter and view the environment are:
2545 .It Xo Ic set-environment
2547 .Op Fl t Ar target-session
2548 .Ar name Op Ar value
2550 .D1 (alias: Ic setenv )
2551 Set or unset an environment variable.
2554 is used, the change is made in the global environment; otherwise, it is applied
2555 to the session environment for
2556 .Ar target-session .
2559 flag unsets a variable.
2561 indicates the variable is to be removed from the environment before starting a
2563 .It Xo Ic show-environment
2565 .Op Fl t Ar target-session
2567 .D1 (alias: Ic showenv )
2568 Display the environment for
2570 or the global environment with
2572 Variables removed from the environment are prefixed with
2577 includes an optional status line which is displayed in the bottom line of each
2579 By default, the status line is enabled (it may be disabled with the
2581 session option) and contains, from left-to-right: the name of the current
2582 session in square brackets; the window list; the current window title in double
2583 quotes; and the time and date.
2585 The status line is made of three parts: configurable left and right sections
2586 (which may contain dynamic content such as the time or output from a shell
2589 .Ic status-left-length ,
2592 .Ic status-right-length
2593 options below), and a central window list.
2594 By default, the window list shows the index, name and (if any) flag of the
2595 windows present in the current session in ascending numerical order.
2596 It may be customised with the
2597 .Ar window-status-format
2599 .Ar window-status-current-format
2601 The flag is one of the following symbols appended to the window name:
2602 .Bl -column "Symbol" "Meaning" -offset indent
2603 .It Sy "Symbol" Ta Sy "Meaning"
2604 .It Li "*" Ta "Denotes the current window."
2605 .It Li "-" Ta "Marks the last window (previously selected)."
2606 .It Li "#" Ta "Window is monitored and activity has been detected."
2607 .It Li "!" Ta "A bell has occurred in the window."
2608 .It Li "+" Ta "Window is monitored for content and it has appeared."
2609 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
2612 The # symbol relates to the
2613 .Ic monitor-activity
2617 The window name is printed in inverted colours if an alert (bell, activity or
2618 content) is present.
2620 The colour and attributes of the status line may be configured, the entire
2621 status line using the
2626 session options and individual windows using the
2627 .Ic window-status-attr ,
2628 .Ic window-status-fg
2630 .Ic window-status-bg
2633 The status line is automatically refreshed at interval if it has changed, the
2634 interval may be controlled with the
2638 Commands related to the status line are as follows:
2640 .It Xo Ic command-prompt
2643 .Op Fl t Ar target-client
2646 Open the command prompt in a client.
2647 This may be used from inside
2649 to execute commands interactively.
2653 is specified, it is used as the command.
2656 is a comma-separated list of the initial text for each prompt.
2661 is a comma-separated list of prompts which are displayed in order; otherwise
2662 a single prompt is displayed, constructed from
2664 if it is present, or
2672 may contain the special character sequences supported by the
2676 Before the command is executed, the first occurrence of the string
2678 and all occurrences of
2680 are replaced by the response to the first prompt, the second
2684 are replaced with the response to the second prompt, and so on for further
2686 Up to nine prompt responses may be replaced
2692 .It Xo Ic confirm-before
2694 .Op Fl t Ar target-client
2697 .D1 (alias: Ic confirm )
2698 Ask for confirmation before executing
2704 is the prompt to display; otherwise a prompt is constructed from
2706 It may contain the special character sequences supported by the
2710 This command works only from inside
2712 .It Xo Ic display-message
2714 .Op Fl c Ar target-client
2715 .Op Fl t Ar target-pane
2718 .D1 (alias: Ic display )
2722 is given, the output is printed to stdout, otherwise it is displayed in the
2729 with the exception that #() are not handled; information is taken from
2733 is given, otherwise the active pane for the session attached to
2738 maintains a stack of
2740 Up to the value of the
2742 option are kept; when a new buffer is added, the buffer at the bottom of the
2744 Buffers may be added using
2748 command, and pasted into a window using the
2752 A configurable history buffer is also maintained for each window.
2753 By default, up to 2000 lines are kept; this can be altered with the
2759 The buffer commands are as follows:
2763 .Op Fl t Ar target-window
2766 Put a window into buffer choice mode, where a buffer may be chosen
2767 interactively from a list.
2768 After a buffer is selected,
2770 is replaced by the buffer index in
2772 and the result executed as a command.
2775 is not given, "paste-buffer -b '%%'" is used.
2776 This command works only from inside
2778 .It Ic clear-history Op Fl t Ar target-pane
2779 .D1 (alias: Ic clearhist )
2780 Remove and free the history for the specified pane.
2781 .It Ic delete-buffer Op Fl b Ar buffer-index
2782 .D1 (alias: Ic deleteb )
2783 Delete the buffer at
2785 or the top buffer if not specified.
2787 .D1 (alias: Ic lsb )
2788 List the global buffers.
2789 .It Xo Ic load-buffer
2790 .Op Fl b Ar buffer-index
2793 .D1 (alias: Ic loadb )
2794 Load the contents of the specified paste buffer from
2796 .It Xo Ic paste-buffer
2798 .Op Fl b Ar buffer-index
2799 .Op Fl s Ar separator
2800 .Op Fl t Ar target-pane
2802 .D1 (alias: Ic pasteb )
2803 Insert the contents of a paste buffer into the specified pane.
2804 If not specified, paste into the current one.
2807 also delete the paste buffer from the stack.
2808 When output, any linefeed (LF) characters in the paste buffer are replaced with
2809 a separator, by default carriage return (CR).
2810 A custom separator may be specified using the
2815 flag means to do no replacement (equivalent to a separator of LF).
2816 .It Xo Ic save-buffer
2818 .Op Fl b Ar buffer-index
2821 .D1 (alias: Ic saveb )
2822 Save the contents of the specified paste buffer to
2826 option appends to rather than overwriting the file.
2827 .It Xo Ic set-buffer
2828 .Op Fl b Ar buffer-index
2831 .D1 (alias: Ic setb )
2832 Set the contents of the specified buffer to
2834 .It Xo Ic show-buffer
2835 .Op Fl b Ar buffer-index
2837 .D1 (alias: Ic showb )
2838 Display the contents of the specified buffer.
2841 Miscellaneous commands are as follows:
2843 .It Ic clock-mode Op Fl t Ar target-pane
2844 Display a large clock.
2845 .It Ic if-shell Ar shell-command command
2853 .D1 (alias: Ic lock )
2854 Lock each client individually by running the command specified by the
2857 .It Ic run-shell Ar shell-command
2858 .D1 (alias: Ic run )
2861 in the background without creating a window.
2862 After it finishes, any output to stdout is displayed in copy mode.
2863 If the command doesn't return success, the exit status is also displayed.
2865 .D1 (alias: Ic info )
2866 Show server information and terminal details.
2868 .Sh TERMINFO EXTENSIONS
2870 understands some extensions to
2874 Set the cursor colour.
2875 The first takes a single string argument and is used to set the colour;
2876 the second takes no arguments and restores the default cursor colour.
2877 If set, a sequence such as this may be used
2878 to change the cursor colour from inside
2880 .Bd -literal -offset indent
2881 $ printf '\e033]12;red\e033\e\e'
2884 Change the cursor style.
2885 If set, a sequence such as this may be used
2886 to change the cursor to an underline:
2887 .Bd -literal -offset indent
2888 $ printf '\e033[4 q'
2893 is set, it will be used to reset the cursor style instead
2897 This sequence can be used by
2899 to store the current buffer in the host terminal's selection (clipboard).
2902 option above and the
2907 .Bl -tag -width "/etc/tmux.confXXX" -compact
2912 .It Pa /etc/tmux.conf
2913 System-wide configuration file.
2921 .Dl $ tmux new-session vi
2923 Most commands have a shorter form, known as an alias.
2924 For new-session, this is
2929 Alternatively, the shortest unambiguous form of a command is accepted.
2930 If there are several options, they are listed:
2931 .Bd -literal -offset indent
2933 ambiguous command: n, could be: new-session, new-window, next-window
2936 Within an active session, a new window may be created by typing
2946 Windows may be navigated with:
2948 (to select window 0),
2950 (to select window 1), and so on;
2952 to select the next window; and
2954 to select the previous window.
2956 A session may be detached using
2958 (or by an external event such as
2960 disconnection) and reattached with:
2962 .Dl $ tmux attach-session
2966 lists the current key bindings in the current window; up and down may be used
2967 to navigate the list or
2971 Commands to be run when the
2973 server is started may be placed in the
2976 Common examples include:
2978 Changing the default prefix key:
2979 .Bd -literal -offset indent
2980 set-option -g prefix C-a
2982 bind-key C-a send-prefix
2985 Turning the status line off, or changing its colour:
2986 .Bd -literal -offset indent
2987 set-option -g status off
2988 set-option -g status-bg blue
2991 Setting other options, such as the default command,
2992 or locking after 30 minutes of inactivity:
2993 .Bd -literal -offset indent
2994 set-option -g default-command "exec /bin/ksh"
2995 set-option -g lock-after-time 1800
2998 Creating new key bindings:
2999 .Bd -literal -offset indent
3000 bind-key b set-option status
3001 bind-key / command-prompt "split-window 'exec man %%'"
3002 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3007 .An Nicholas Marriott Aq nicm@users.sourceforge.net