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 Split the current pane into two, left and right.
239 Kill the current window.
241 Prompt for a window index to select.
243 Rename the current window.
245 Delete the most recently copied buffer of text.
247 Prompt for an index to move the current window.
249 Select windows 0 to 9.
255 Move to the previously active pane.
257 Choose which buffer to paste interactively from a list.
259 List all key bindings.
261 Choose a client to detach.
263 Enter copy mode to copy text or view the history.
265 Paste the most recently copied buffer of text.
269 Detach the current client.
271 Prompt to search for text in open windows.
273 Display some information about the current window.
275 Move to the previously selected window.
277 Change to the next window.
279 Select the next pane in the current window.
281 Change to the previous window.
283 Briefly display pane indexes.
285 Force redraw of the attached client.
287 Select a new session for the attached client interactively.
289 Switch the attached client back to the last session.
293 Choose the current window interactively.
295 Kill the current pane.
297 Swap the current pane with the previous pane.
299 Swap the current pane with the next pane.
301 Show previous messages from
305 Enter copy mode and scroll one page up.
308 Change to the pane above, below, to the left, or to the right of the current
311 Arrange panes in one of the five preset layouts: even-horizontal,
312 even-vertical, main-horizontal, main-vertical, or tiled.
314 Move to the next window with a bell or activity marker.
316 Rotate the panes in the current window backwards.
318 Move to the previous window with a bell or activity marker.
321 Resize the current pane in steps of one cell.
324 Resize the current pane in steps of five cells.
327 Key bindings may be changed with the
333 This section contains a list of the commands supported by
335 Most commands accept the optional
343 These specify the client, session, window or pane which a command should affect.
347 file to which the client is connected, for example either of
351 for the client attached to
353 If no client is specified, the current client is chosen, if possible, or an
355 Clients may be listed with the
360 is either the name of a session (as listed by the
362 command) or the name of a client with the same syntax as
364 in which case the session attached to the client is used.
365 When looking for the session name,
367 initially searches for an exact match; if none is found, the session names
368 are checked for any for which
370 is a prefix or for which it matches as an
373 If a single match is found, it is used as the target session; multiple matches
375 If a session is omitted, the current session is used if available; if no
376 current session is available, the most recently used is chosen.
379 specifies a window in the form
380 .Em session Ns \&: Ns Em window .
382 follows the same rules as for
386 is looked for in order: as a window index, for example mysession:1; as an exact
387 window name, such as mysession:mywindow; then as an
389 pattern or the start of a window name, such as mysession:mywin* or
391 An empty window name specifies the next unused index if appropriate (for
397 otherwise the current window in
400 The special character
402 uses the last (previously current) window, or
406 are the next window or the previous window by number.
407 When the argument does not contain a colon,
409 first attempts to parse it as window; if that fails, an attempt is made to
413 takes a similar form to
415 but with the optional addition of a period followed by a pane index, for
416 example: mysession:mywindow.1.
417 If the pane index is omitted, the currently active pane in the specified
419 If neither a colon nor period appears,
421 first attempts to use the argument as a pane index; if that fails, it is looked
428 indicate the next or previous pane index, respectively.
439 may be used instead of a pane index.
441 The special characters
445 may be followed by an offset, for example:
446 .Bd -literal -offset indent
450 When dealing with a session that doesn't contain sequential window indexes,
451 they will be correctly skipped.
454 also gives each pane created in a server an identifier consisting of a
456 and a number, starting from zero.
457 A pane's identifier is unique for the life of the
459 server and is passed to the child process of the pane in the
461 environment variable.
462 It may be used alone to target a pane or the window containing it.
468 These must be passed as a single item, which typically means quoting them, for
470 .Bd -literal -offset indent
471 new-window 'vi /etc/passwd'
478 command, passed with the command and arguments separately, for example:
479 .Bd -literal -offset indent
480 bind-key F1 set-window-option force-width 81
485 .Bd -literal -offset indent
486 $ tmux bind-key F1 set-window-option force-width 81
489 Multiple commands may be specified together as part of a
490 .Em command sequence .
491 Each command should be separated by spaces and a semicolon;
492 commands are executed sequentially from left to right.
493 A literal semicolon may be included by escaping it with a backslash (for
494 example, when specifying a command sequence to
500 .Bd -literal -offset indent
501 refresh-client -t/dev/ttyp2
503 rename-session -tfirst newname
505 set-window-option -t:0 monitor-activity on
507 new-window ; split-window -d
512 .Bd -literal -offset indent
513 $ tmux kill-window -t :1
515 $ tmux new-window \e; split-window -d
517 $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
519 .Sh CLIENTS AND SESSIONS
522 server manages clients, sessions, windows and panes.
523 Clients are attached to sessions to interact with them, either
524 when they are created with the
526 command, or later with the
529 Each session has one or more windows
532 Windows may be linked to multiple sessions and are made up of one or
534 each of which contains a pseudo terminal.
535 Commands for creating, linking and otherwise manipulating windows
538 .Sx WINDOWS AND PANES
541 The following commands are available to manage clients and sessions:
543 .It Xo Ic attach-session
545 .Op Fl t Ar target-session
547 .D1 (alias: Ic attach )
550 create a new client in the current terminal and attach it to
552 If used from inside, switch the current client.
555 is specified, any other clients attached to the session are detached.
557 signifies the client is read-only (only keys bound to the
559 command have any effect)
561 If no server is started,
563 will attempt to start it; this will fail unless sessions are created in the
570 are slightly adjusted: if
572 needs to select the most recently used session, it will prefer the most
576 .It Xo Ic detach-client
578 .Op Fl s Ar target-session
579 .Op Fl t Ar target-client
581 .D1 (alias: Ic detach )
582 Detach the current client if bound to a key, the client specified with
584 or all clients currently attached to to the session specified by
588 is given, send SIGHUP to the parent process of the client, typically causing it
590 .It Ic has-session Op Fl t Ar target-session
592 Report an error and exit with 1 if the specified session does not exist.
593 If it does exist, exit with 0.
597 server and clients and destroy all sessions.
598 .It Ic kill-session Op Fl t Ar target-session
599 Destroy the given session, closing any windows linked to it and no other
600 sessions, and detaching all clients attached to it.
601 .It Ic list-clients Op Fl t Ar target-session
603 List all clients attached to the server.
606 is specified, list only clients connected to that session.
608 .D1 (alias: Ic lscm )
609 List the syntax of all commands supported by
613 List all sessions managed by the server.
614 .It Ic lock-client Op Fl t Ar target-client
615 .D1 (alias: Ic lockc )
621 .It Ic lock-session Op Fl t Ar target-session
622 .D1 (alias: Ic locks )
623 Lock all clients attached to
625 .It Xo Ic new-session
627 .Op Fl n Ar window-name
628 .Op Fl s Ar session-name
629 .Op Fl t Ar target-session
635 Create a new session with name
638 The new session is attached to the current terminal unless
644 are the name of and shell command to execute in the initial window.
651 specify the size of the initial window (80 by 24 if not given).
653 If run from a terminal, any
655 special characters are saved and used for new windows in the new session.
659 is given, the new session is
663 This means they share the same set of windows - all windows from
665 are linked to the new session and any subsequent new windows or windows being
666 closed are applied to both sessions.
667 The current and previous window and any session options remain independent and
668 either session may be killed without affecting the other.
676 .It Ic refresh-client Op Fl t Ar target-client
677 .D1 (alias: Ic refresh )
678 Refresh the current client if bound to a key, or a single client if one is given
681 .It Xo Ic rename-session
682 .Op Fl t Ar target-session
685 .D1 (alias: Ic rename )
686 Rename the session to
688 .It Xo Ic show-messages
689 .Op Fl t Ar target-client
691 .D1 (alias: Ic showmsgs )
692 Any messages displayed on the status line are saved in a per-client message
693 log, up to a maximum of the limit set by the
695 session option for the session attached to that client.
696 This command displays the log for
698 .It Ic source-file Ar path
699 .D1 (alias: Ic source )
700 Execute commands from
703 .D1 (alias: Ic start )
706 server, if not already running, without creating any sessions.
707 .It Xo Ic suspend-client
708 .Op Fl t Ar target-client
710 .D1 (alias: Ic suspendc )
711 Suspend a client by sending
714 .It Xo Ic switch-client
716 .Op Fl c Ar target-client
717 .Op Fl t Ar target-session
719 .D1 (alias: Ic switchc )
720 Switch the current session for client
729 is used, the client is moved to the last, next or previous session
732 .Sh WINDOWS AND PANES
735 window may be in one of several modes.
736 The default permits direct access to the terminal attached to the window.
737 The other is copy mode, which permits a section of a window or its
738 history to be copied to a
740 for later insertion into another window.
741 This mode is entered with the
746 It is also entered when a command that produces output, such as
748 is executed from a key binding.
750 The keys available depend on whether emacs or vi mode is selected
754 The following keys are supported as appropriate for the mode:
755 .Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
756 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
757 .It Li "Back to indentation" Ta "^" Ta "M-m"
758 .It Li "Bottom of history" Ta "G" Ta "M-<"
759 .It Li "Clear selection" Ta "Escape" Ta "C-g"
760 .It Li "Copy selection" Ta "Enter" Ta "M-w"
761 .It Li "Cursor down" Ta "j" Ta "Down"
762 .It Li "Cursor left" Ta "h" Ta "Left"
763 .It Li "Cursor right" Ta "l" Ta "Right"
764 .It Li "Cursor to bottom line" Ta "L" Ta ""
765 .It Li "Cursor to middle line" Ta "M" Ta "M-r"
766 .It Li "Cursor to top line" Ta "H" Ta "M-R"
767 .It Li "Cursor up" Ta "k" Ta "Up"
768 .It Li "Delete entire line" Ta "d" Ta "C-u"
769 .It Li "Delete/Copy to end of line" Ta "D" Ta "C-k"
770 .It Li "End of line" Ta "$" Ta "C-e"
771 .It Li "Go to line" Ta ":" Ta "g"
772 .It Li "Half page down" Ta "C-d" Ta "M-Down"
773 .It Li "Half page up" Ta "C-u" Ta "M-Up"
774 .It Li "Jump forward" Ta "f" Ta "f"
775 .It Li "Jump backward" Ta "F" Ta "F"
776 .It Li "Jump again" Ta ";" Ta ";"
777 .It Li "Jump again in reverse" Ta "," Ta ","
778 .It Li "Next page" Ta "C-f" Ta "Page down"
779 .It Li "Next space" Ta "W" Ta ""
780 .It Li "Next space, end of word" Ta "E" Ta ""
781 .It Li "Next word" Ta "w" Ta ""
782 .It Li "Next word end" Ta "e" Ta "M-f"
783 .It Li "Paste buffer" Ta "p" Ta "C-y"
784 .It Li "Previous page" Ta "C-b" Ta "Page up"
785 .It Li "Previous word" Ta "b" Ta "M-b"
786 .It Li "Previous space" Ta "B" Ta ""
787 .It Li "Quit mode" Ta "q" Ta "Escape"
788 .It Li "Rectangle toggle" Ta "v" Ta "R"
789 .It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down"
790 .It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up"
791 .It Li "Search again" Ta "n" Ta "n"
792 .It Li "Search again in reverse" Ta "N" Ta "N"
793 .It Li "Search backward" Ta "?" Ta "C-r"
794 .It Li "Search forward" Ta "/" Ta "C-s"
795 .It Li "Start of line" Ta "0" Ta "C-a"
796 .It Li "Start selection" Ta "Space" Ta "C-Space"
797 .It Li "Top of history" Ta "g" Ta "M->"
798 .It Li "Transpose chars" Ta "" Ta "C-t"
801 The next and previous word keys use space and the
806 characters as word delimiters by default, but this can be adjusted by
810 Next word moves to the start of the next word, next word end to the end of the
811 next word and previous word to the start of the previous word.
812 The three next and previous space keys work similarly but use a space alone as
815 The jump commands enable quick movement within a line.
820 will move the cursor to the next
822 character on the current line.
825 will then jump to the next occurrence.
827 Commands in copy mode may be prefaced by an optional repeat count.
828 With vi key bindings, a prefix is entered using the number keys; with
829 emacs, the Alt (meta) key and a number begins prefix entry.
830 For example, to move the cursor forward by ten words, use
836 Mode key bindings are defined in a set of named tables:
840 for keys used when line editing at the command prompt;
844 for keys used when choosing from lists (such as produced by the
851 The tables may be viewed with the
853 command and keys modified or removed with
858 The paste buffer key pastes the first line from the top paste buffer on the
867 .Op Fl t Ar target-pane
872 option scrolls one page up.
875 Each window displayed by
877 may be split into one or more
879 each pane takes up a certain area of the display and is a separate terminal.
880 A window may be split into panes using the
883 Windows may be split horizontally (with the
886 Panes may be resized with the
894 by default), the current pane may be changed with the
900 commands may be used to swap panes without changing their position.
901 Panes are numbered beginning from zero in the order they are created.
906 These may be selected with the
908 command or cycled with
912 by default); once a layout is chosen, panes within it may be moved and resized
915 The following layouts are supported:
917 .It Ic even-horizontal
918 Panes are spread out evenly from left to right across the window.
920 Panes are spread evenly from top to bottom.
921 .It Ic main-horizontal
922 A large (main) pane is shown at the top of the window and the remaining panes
923 are spread from left to right in the leftover space at the bottom.
926 window option to specify the height of the top pane.
930 but the large pane is placed on the left and the others spread from top to
931 bottom along the right.
936 Panes are spread out as evenly as possible over the window in both rows and
942 may be used to apply a previously used layout - the
944 command displays the layout of each window in a form suitable for use with
947 .Bd -literal -offset indent
950 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
951 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
955 automatically adjusts the size of the layout for the current window size.
956 Note that a layout cannot be applied to a window with more panes than that
957 from which the layout was originally defined.
959 Commands related to windows and panes are as follows:
963 .Op Fl t Ar target-pane
965 .D1 (alias: Ic breakp )
968 off from its containing window to make it the only pane in a new window.
971 is given, the new window does not become the current window.
972 .It Xo Ic capture-pane
973 .Op Fl b Ar buffer-index
975 .Op Fl S Ar start-line
976 .Op Fl t Ar target-pane
978 .D1 (alias: Ic capturep )
979 Capture the contents of a pane to the specified buffer, or a new buffer if none
985 specify the starting and ending line numbers, zero is the first line of the
986 visible pane and negative numbers are lines in the history.
987 The default is to capture only the visible contents of the pane.
990 .Op Fl t Ar target-window
993 Put a window into client choice mode, allowing a client to be selected
994 interactively from a list.
995 After a client is chosen,
997 is replaced by the client
1001 and the result executed as a command.
1004 is not given, "detach-client -t '%%'" is used.
1005 This command works only from inside
1009 .Op Fl t Ar target-window
1012 Put a window into session choice mode, where a session may be selected
1013 interactively from a list.
1016 is replaced by the session name in
1018 and the result executed as a command.
1021 is not given, "switch-client -t '%%'" is used.
1022 This command works only from inside
1026 .Op Fl t Ar target-window
1029 Put a window into window choice mode, where a window may be chosen
1030 interactively from a list.
1031 After a window is selected,
1033 is replaced by the session name and window index in
1035 and the result executed as a command.
1038 is not given, "select-window -t '%%'" is used.
1039 This command works only from inside
1041 .It Ic display-panes Op Fl t Ar target-client
1042 .D1 (alias: Ic displayp)
1043 Display a visible indicator of each pane shown by
1046 .Ic display-panes-time ,
1047 .Ic display-panes-colour ,
1049 .Ic display-panes-active-colour
1051 While the indicator is on screen, a pane may be selected with the
1056 .It Xo Ic find-window
1057 .Op Fl t Ar target-window
1060 .D1 (alias: Ic findw )
1065 in window names, titles, and visible content (but not history).
1066 If only one window is matched, it'll be automatically selected, otherwise a
1067 choice list is shown.
1068 This command only works from inside
1074 .Fl p Ar percentage Oc
1075 .Op Fl s Ar src-pane
1076 .Op Fl t Ar dst-pane
1078 .D1 (alias: Ic joinp )
1081 but instead of splitting
1083 and creating a new pane, split it and move
1086 This can be used to reverse
1090 .Op Fl t Ar target-pane
1092 .D1 (alias: Ic killp )
1093 Destroy the given pane.
1094 If no panes remain in the containing window, it is also destroyed.
1097 option kills all but the pane given with
1099 .It Ic kill-window Op Fl t Ar target-window
1100 .D1 (alias: Ic killw )
1101 Kill the current window or the window at
1103 removing it from any sessions to which it is linked.
1104 .It Ic last-pane Op Fl t Ar target-window
1105 .D1 (alias: Ic lastp )
1106 Select the last (previously selected) pane.
1107 .It Ic last-window Op Fl t Ar target-session
1108 .D1 (alias: Ic last )
1109 Select the last (previously selected) window.
1112 is specified, select the last window of the current session.
1113 .It Xo Ic link-window
1115 .Op Fl s Ar src-window
1116 .Op Fl t Ar dst-window
1118 .D1 (alias: Ic linkw )
1125 is specified and no such window exists, the
1132 exists, it is killed, otherwise an error is generated.
1135 is given, the newly linked window is not selected.
1136 .It Xo Ic list-panes
1140 .D1 (alias: Ic lsp )
1145 is ignored and all panes on the server are listed.
1150 is a session (or the current session).
1151 If neither is given,
1153 is a window (or the current window).
1154 .It Xo Ic list-windows
1156 .Op Fl t Ar target-session
1158 .D1 (alias: Ic lsw )
1161 is given, list all windows on the server.
1162 Otherwise, list windows in the current session or in
1163 .Ar target-session .
1164 .It Xo Ic move-window
1166 .Op Fl s Ar src-window
1167 .Op Fl t Ar dst-window
1169 .D1 (alias: Ic movew )
1172 except the window at
1176 .It Xo Ic new-window
1178 .Op Fl n Ar window-name
1179 .Op Fl t Ar target-window
1180 .Op Ar shell-command
1182 .D1 (alias: Ic neww )
1183 Create a new window.
1186 the new window is inserted at the next index up from the specified
1188 moving windows up if necessary,
1191 is the new window location.
1195 is given, the session does not make the new window the current window.
1197 represents the window to be created; if the target already exists an error is
1200 flag is used, in which case it is destroyed.
1202 is the command to execute.
1205 is not specified, the value of the
1209 When the shell command completes, the window closes.
1212 option to change this behaviour.
1216 environment variable must be set to
1218 for all programs running
1221 New windows will automatically have
1223 added to their environment, but care must be taken not to reset this in shell
1228 option prints the location of the new window after it has been created.
1229 .It Ic next-layout Op Fl t Ar target-window
1230 .D1 (alias: Ic nextl )
1231 Move a window to the next layout and rearrange the panes to fit.
1232 .It Xo Ic next-window
1234 .Op Fl t Ar target-session
1236 .D1 (alias: Ic next )
1237 Move to the next window in the session.
1240 is used, move to the next window with a bell, activity or content alert.
1243 .Op Fl t Ar target-pane
1244 .Op Ar shell-command
1246 .D1 (alias: Ic pipep )
1247 Pipe any output sent by the program in
1250 A pane may only be piped to one command at a time, any existing pipe is
1256 string may contain the special character sequences supported by the
1261 is given, the current pipe (if any) is closed.
1265 option only opens a new pipe if no previous pipe exists, allowing a pipe to
1266 be toggled with a single key, for example:
1267 .Bd -literal -offset indent
1268 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1270 .It Xo Ic previous-layout
1271 .Op Fl t Ar target-window
1273 .D1 (alias: Ic prevl )
1274 Move to the previous layout in the session.
1275 .It Xo Ic previous-window
1277 .Op Fl t Ar target-session
1279 .D1 (alias: Ic prev )
1280 Move to the previous window in the session.
1283 move to the previous window with a bell, activity or content alert.
1284 .It Xo Ic rename-window
1285 .Op Fl t Ar target-window
1288 .D1 (alias: Ic renamew )
1289 Rename the current window, or the window at
1293 .It Xo Ic resize-pane
1295 .Op Fl t Ar target-pane
1298 .D1 (alias: Ic resizep )
1299 Resize a pane, upward with
1301 (the default), downward with
1305 and to the right with
1309 is given in lines or cells (the default is 1).
1310 .It Xo Ic respawn-window
1312 .Op Fl t Ar target-window
1313 .Op Ar shell-command
1315 .D1 (alias: Ic respawnw )
1316 Reactivate a window in which the command has exited (see the
1321 is not given, the command used when the window was created is executed.
1322 The window must be already inactive, unless
1324 is given, in which case any existing command is killed.
1325 .It Xo Ic rotate-window
1327 .Op Fl t Ar target-window
1329 .D1 (alias: Ic rotatew )
1330 Rotate the positions of the panes within a window, either upward (numerically
1333 or downward (numerically higher).
1334 .It Xo Ic select-layout
1336 .Op Fl t Ar target-window
1339 .D1 (alias: Ic selectl )
1340 Choose a specific layout for a window.
1343 is not given, the last preset layout used (if any) is reapplied.
1347 are equivalent to the
1352 .It Xo Ic select-pane
1354 .Op Fl t Ar target-pane
1356 .D1 (alias: Ic selectp )
1359 the active pane in window
1367 is used, respectively the pane below, to the left, to the right, or above the
1368 target pane is used.
1370 is the same as using the
1373 .It Xo Ic select-window
1375 .Op Fl t Ar target-window
1377 .D1 (alias: Ic selectw )
1378 Select the window at
1384 are equivalent to the
1390 .It Xo Ic split-window
1394 .Fl p Ar percentage Oc
1395 .Op Fl t Ar target-pane
1396 .Op Ar shell-command
1398 .D1 (alias: Ic splitw )
1399 Create a new pane by splitting
1402 does a horizontal split and
1404 a vertical split; if neither is specified,
1411 options specify the size of the new pane in lines (for vertical split) or in
1412 cells (for horizontal split), or as a percentage, respectively.
1413 All other options have the same meaning as for the
1418 .Op Fl s Ar src-pane
1419 .Op Fl t Ar dst-pane
1421 .D1 (alias: Ic swapp )
1425 is used and no source pane is specified with
1428 is swapped with the previous pane (before it numerically);
1430 swaps with the next pane (after it numerically).
1434 not to change the active pane.
1435 .It Xo Ic swap-window
1437 .Op Fl s Ar src-window
1438 .Op Fl t Ar dst-window
1440 .D1 (alias: Ic swapw )
1443 except the source and destination windows are swapped.
1444 It is an error if no window exists at
1446 .It Xo Ic unlink-window
1448 .Op Fl t Ar target-window
1450 .D1 (alias: Ic unlinkw )
1455 is given, a window may be unlinked only if it is linked to multiple sessions -
1456 windows may not be linked to no sessions;
1459 is specified and the window is linked to only one session, it is unlinked and
1464 allows a command to be bound to most keys, with or without a prefix key.
1465 When specifying keys, most represent themselves (for example
1469 Ctrl keys may be prefixed with
1475 In addition, the following special key names are accepted:
1500 Note that to bind the
1504 keys, quotation marks are necessary, for example:
1505 .Bd -literal -offset indent
1506 bind-key '"' split-window
1507 bind-key "'" new-window
1510 Commands related to key bindings are as follows:
1514 .Op Fl t Ar key-table
1515 .Ar key Ar command Op Ar arguments
1517 .D1 (alias: Ic bind )
1524 the primary key bindings are modified (those normally activated with the prefix
1525 key); in this case, if
1527 is specified, it is not necessary to use the prefix key,
1534 flag indicates this key may repeat, see the
1544 the binding for command mode with
1546 or for normal mode without.
1547 To view the default bindings and possible commands, see the
1550 .It Ic list-keys Op Fl t Ar key-table
1551 .D1 (alias: Ic lsk )
1552 List all key bindings.
1555 the primary key bindings - those executed when preceded by the prefix key -
1557 Keys bound without the prefix key (see
1567 are listed; this may be one of:
1576 .Op Fl t Ar target-pane
1579 .D1 (alias: Ic send )
1580 Send a key or keys to a window.
1583 is the name of the key (such as
1587 ) to send; if the string is not recognised as a key, it is sent as a series of
1589 All arguments are sent sequentially from first to last.
1590 .It Ic send-prefix Op Fl t Ar target-pane
1591 Send the prefix key to a window as if it was pressed.
1592 If multiple prefix keys are configured, only the first is sent.
1593 .It Xo Ic unbind-key
1595 .Op Fl t Ar key-table
1598 .D1 (alias: Ic unbind )
1599 Unbind the command bound to
1603 the primary key bindings are modified; in this case, if
1605 is specified, the command bound to
1607 without a prefix (if any) is removed.
1610 is present, all key bindings are removed.
1618 is unbound: the binding for command mode with
1620 or for normal mode without.
1623 The appearance and behaviour of
1625 may be modified by changing the value of various options.
1626 There are three types of option:
1627 .Em server options ,
1630 .Em window options .
1634 server has a set of global options which do not apply to any particular
1636 These are altered with the
1639 command, or displayed with the
1644 In addition, each individual session may have a set of session options, and
1645 there is a separate set of global session options.
1646 Sessions which do not have a particular option configured inherit the value
1647 from the global session options.
1648 Session options are set or unset with the
1650 command and may be listed with the
1653 The available server and session options are listed under the
1657 Similarly, a set of window options is attached to each window, and there is
1658 a set of global window options from which any unset options are inherited.
1659 Window options are altered with the
1660 .Ic set-window-option
1661 command and can be listed with the
1662 .Ic show-window-options
1664 All window options are documented with the
1665 .Ic set-window-option
1668 Commands which set options are as follows:
1670 .It Xo Ic set-option
1672 .Op Fl t Ar target-session | Ar target-window
1675 .D1 (alias: Ic set )
1676 Set a window option with
1679 .Ic set-window-option
1681 a server option with
1683 otherwise a session option.
1687 is specified, the global session or window option is set.
1690 and if the option expects a string,
1692 is appended to the existing setting.
1695 flag unsets an option, so a session inherits the option from the global
1697 It is not possible to unset a global option.
1699 Available window options are listed under
1700 .Ic set-window-option .
1702 Available server options are:
1704 .It Ic buffer-limit Ar number
1705 Set the number of buffers; as new buffers are added to the top of the stack,
1706 old ones are removed from the bottom if necessary to maintain this maximum
1708 .It Xo Ic set-clipboard
1711 Attempt to set the terminal clipboard content using the
1715 This option is on by default if there is an
1719 description for the client terminal.
1720 Note that this feature needs to be enabled in
1722 by setting the resource:
1723 .Bd -literal -offset indent
1724 disallowedWindowOps: 20,21,SetXprop
1727 Or changing this property from the
1729 interactive menu when required.
1730 .It Ic escape-time Ar time
1731 Set the time in milliseconds for which
1733 waits after an escape is input to determine if it is part of a function or meta
1735 The default is 500 milliseconds.
1736 .It Xo Ic exit-unattached
1739 If enabled, the server will exit when there are no attached clients.
1743 Enable or disable the display of various informational messages (see also the
1748 Available session options are:
1750 .It Ic base-index Ar index
1751 Set the base index from which an unused index should be searched when a new
1753 The default is zero.
1754 .It Xo Ic bell-action
1755 .Op Ic any | none | current
1757 Set action on window bell.
1759 means a bell in any window linked to a session causes a bell in the current
1760 window of that session,
1762 means all bells are ignored and
1764 means only bell in windows other than the current window are ignored.
1765 .It Ic default-command Ar shell-command
1766 Set the command used for new windows (if not specified when the window is
1772 The default is an empty string, which instructs
1774 to create a login shell using the value of the
1777 .It Ic default-path Ar path
1778 Set the default working directory for processes created from keys, or
1779 interactively from the prompt.
1780 The default is empty, which means to use the working directory of the shell
1781 from which the server was started if it is available or the user's home if not.
1782 .It Ic default-shell Ar path
1783 Specify the default shell.
1784 This is used as the login shell for new windows when the
1786 option is set to empty, and must be the full path of the executable.
1789 tries to set a default value from the first suitable of the
1791 environment variable, the shell returned by
1795 This option should be configured when
1797 is used as a login shell.
1798 .It Ic default-terminal Ar terminal
1799 Set the default terminal for new windows created in this session - the
1800 default value of the
1802 environment variable.
1805 to work correctly, this
1809 or a derivative of it.
1810 .It Xo Ic destroy-unattached
1813 If enabled and the session is no longer attached to any clients, it is
1815 .It Xo Ic detach-on-destroy
1818 If on (the default), the client is detached when the session it is attached to
1820 If off, the client is switched to the most recently active of the remaining
1822 .It Ic display-panes-active-colour Ar colour
1823 Set the colour used by the
1825 command to show the indicator for the active pane.
1826 .It Ic display-panes-colour Ar colour
1827 Set the colour used by the
1829 command to show the indicators for inactive panes.
1830 .It Ic display-panes-time Ar time
1831 Set the time in milliseconds for which the indicators shown by the
1834 .It Ic display-time Ar time
1835 Set the amount of time for which status line messages and other on-screen
1836 indicators are displayed.
1839 .It Ic history-limit Ar lines
1840 Set the maximum number of lines held in window history.
1841 This setting applies only to new windows - existing window histories are not
1842 resized and retain the limit at the point they were created.
1843 .It Ic lock-after-time Ar number
1844 Lock the session (like the
1848 seconds of inactivity, or the entire server (all sessions) if the
1851 The default is not to lock (set to 0).
1852 .It Ic lock-command Ar shell-command
1853 Command to run when locking each client.
1854 The default is to run
1858 .It Xo Ic lock-server
1864 instead of each session locking individually as each has been
1866 .Ic lock-after-time ,
1867 the entire server will lock after
1869 sessions would have locked.
1870 This has no effect as a session option; it must be set as a global option.
1871 .It Ic message-attr Ar attributes
1872 Set status line message attributes, where
1876 or a comma-delimited list of one or more of:
1887 .It Ic message-bg Ar colour
1888 Set status line message background colour, where
1902 from the 256-colour set,
1904 or a hexadecimal RGB string such as
1906 which chooses the closest match from the default 256-colour set.
1907 .It Ic message-fg Ar colour
1908 Set status line message foreground colour.
1909 .It Ic message-limit Ar number
1910 Set the number of error or information messages to save in the message log for
1913 .It Xo Ic mouse-resize-pane
1918 captures the mouse and allows panes to be resized by dragging on their borders.
1919 .It Xo Ic mouse-select-pane
1924 captures the mouse and when a window is split into multiple panes the mouse may
1925 be used to select the current pane.
1926 The mouse click is also passed through to the application as normal.
1927 .It Xo Ic mouse-select-window
1930 If on, clicking the mouse on a window name in the status line will select that
1932 .It Ic pane-active-border-bg Ar colour
1933 .It Ic pane-active-border-fg Ar colour
1934 Set the pane border colour for the currently active pane.
1935 .It Ic pane-border-bg Ar colour
1936 .It Ic pane-border-fg Ar colour
1937 Set the pane border colour for panes aside from the active pane.
1938 .It Ic prefix Ar keys
1939 Set the keys accepted as a prefix key.
1941 is a comma-separated list of key names, each of which individually behave as
1943 .It Ic repeat-time Ar time
1944 Allow multiple commands to be entered without pressing the prefix-key again
1947 milliseconds (the default is 500).
1948 Whether a key repeats may be set when it is bound using the
1952 Repeat is enabled for the default keys bound to the
1955 .It Xo Ic mouse-utf8
1958 If enabled, request mouse input as UTF-8 on UTF-8 terminals.
1959 .It Xo Ic set-remain-on-exit
1964 window option for any windows first created in this session.
1965 When this option is true, windows in which the running program has
1966 exited do not close, instead remaining open but inactivate.
1969 command to reactivate such a window, or the
1971 command to destroy it.
1972 .It Xo Ic set-titles
1975 Attempt to set the window title using the \ee]2;...\e007 xterm code if
1976 the terminal appears to be an xterm.
1977 This option is off by default.
1979 will only attempt to set the window title if the STY environment
1981 .It Ic set-titles-string Ar string
1982 String used to set the window title if
1985 Character sequences are replaced as for the
1991 Show or hide the status line.
1992 .It Ic status-attr Ar attributes
1993 Set status line attributes.
1994 .It Ic status-bg Ar colour
1995 Set status line background colour.
1996 .It Ic status-fg Ar colour
1997 Set status line foreground colour.
1998 .It Ic status-interval Ar interval
1999 Update the status bar every
2002 By default, updates will occur every 15 seconds.
2003 A setting of zero disables redrawing at interval.
2004 .It Xo Ic status-justify
2005 .Op Ic left | centre | right
2007 Set the position of the window list component of the status line: left, centre
2009 .It Xo Ic status-keys
2012 Use vi or emacs-style
2013 key bindings in the status line, for example at the command prompt.
2014 The default is emacs, unless the
2018 environment variables are set and contain the string
2020 .It Ic status-left Ar string
2023 to the left of the status bar.
2025 will be passed through
2028 By default, the session name is shown.
2030 may contain any of the following special character sequences:
2031 .Bl -column "Character pair" "Replaced with" -offset indent
2032 .It Sy "Character pair" Ta Sy "Replaced with"
2033 .It Li "#(shell-command)" Ta "First line of the command's output"
2034 .It Li "#[attributes]" Ta "Colour or attribute change"
2035 .It Li "#H" Ta "Hostname of local host"
2036 .It Li "#h" Ta "Hostname of local host without the domain name"
2037 .It Li "#F" Ta "Current window flag"
2038 .It Li "#I" Ta "Current window index"
2039 .It Li "#P" Ta "Current pane index"
2040 .It Li "#S" Ta "Session name"
2041 .It Li "#T" Ta "Current window title"
2042 .It Li "#W" Ta "Current window name"
2043 .It Li "##" Ta "A literal" Ql #
2046 The #(shell-command) form executes
2048 and inserts the first line of its output.
2049 Note that shell commands are only executed once at the interval specified by
2052 option: if the status line is redrawn in the meantime, the previous result is
2054 Shell commands are executed with the
2056 global environment set (see the
2060 The window title (#T) is the title set by the program running within the window
2061 using the OSC title setting sequence, for example:
2062 .Bd -literal -offset indent
2063 $ printf '\e033]2;My Title\e033\e\e'
2066 When a window is first created, its title is the hostname.
2068 #[attributes] allows a comma-separated list of attributes to be specified,
2071 to set the foreground colour,
2073 to set the background colour, the name of one of the attributes (listed under
2076 option) to turn an attribute on, or an attribute prefixed with
2078 to turn one off, for example
2081 .Bd -literal -offset indent
2082 #(sysctl vm.loadavg)
2083 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2086 Where appropriate, special character sequences may be prefixed with a number to
2087 specify the maximum length, for example
2090 By default, UTF-8 in
2092 is not interpreted, to enable UTF-8, use the
2095 .It Ic status-left-attr Ar attributes
2096 Set the attribute of the left part of the status line.
2097 .It Ic status-left-bg Ar colour
2098 Set the background colour of the left part of the status line.
2099 .It Ic status-left-fg Ar colour
2100 Set the foreground colour of the left part of the status line.
2101 .It Ic status-left-length Ar length
2104 of the left component of the status bar.
2106 .It Ic status-right Ar string
2109 to the right of the status bar.
2110 By default, the current window title in double quotes, the date and the time
2117 character pairs are replaced, and UTF-8 is dependent on the
2120 .It Ic status-right-attr Ar attributes
2121 Set the attribute of the right part of the status line.
2122 .It Ic status-right-bg Ar colour
2123 Set the background colour of the right part of the status line.
2124 .It Ic status-right-fg Ar colour
2125 Set the foreground colour of the right part of the status line.
2126 .It Ic status-right-length Ar length
2129 of the right component of the status bar.
2131 .It Xo Ic status-utf8
2136 to treat top-bit-set characters in the
2140 strings as UTF-8; notably, this is important for wide characters.
2141 This option defaults to off.
2142 .It Ic terminal-overrides Ar string
2143 Contains a list of entries which override terminal descriptions read using
2146 is a comma-separated list of items each a colon-separated string made up of a
2147 terminal type pattern (matched using
2153 For example, to set the
2158 for all terminal types and the
2164 terminal type, the option could be set to the string:
2165 .Bd -literal -offset indent
2166 "*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
2169 The terminal entry value is passed through
2171 before interpretation.
2172 The default value forcibly corrects the
2174 entry for terminals which support 88 or 256 colours:
2175 .Bd -literal -offset indent
2176 "*88col*:colors=88,*256col*:colors=256,xterm*:XT"
2178 .It Ic update-environment Ar variables
2179 Set a space-separated string containing a list of environment variables to be
2180 copied into the session environment when a new session is created or an
2181 existing session is attached.
2182 Any variables that do not exist in the source environment are set to be
2183 removed from the session environment (as if
2189 "DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID
2191 .It Xo Ic visual-activity
2194 If on, display a status line message when activity occurs in a window
2196 .Ic monitor-activity
2197 window option is enabled.
2198 .It Xo Ic visual-bell
2201 If this option is on, a message is shown on a bell instead of it being passed
2202 through to the terminal (which normally makes a sound).
2206 .It Xo Ic visual-content
2210 .Ic visual-activity ,
2211 display a message when content is present in a window
2214 window option is enabled.
2215 .It Xo Ic visual-silence
2220 is enabled, prints a message after the interval has expired on a given window.
2222 .It Xo Ic set-window-option
2224 .Op Fl t Ar target-window
2227 .D1 (alias: Ic setw )
2228 Set a window option.
2234 flags work similarly to the
2238 Supported window options are:
2240 .Bl -tag -width Ds -compact
2241 .It Xo Ic aggressive-resize
2244 Aggressively resize the chosen window.
2247 will resize the window to the size of the smallest session for which it is the
2248 current window, rather than the smallest session to which it is attached.
2249 The window may resize when the current window is changed on another sessions;
2250 this option is good for full-screen programs which support
2252 and poor for interactive programs such as shells.
2254 .It Xo Ic alternate-screen
2257 This option configures whether programs running inside
2259 may use the terminal alternate screen feature, which allows the
2265 The alternate screen feature preserves the contents of the window when an
2266 interactive application starts and restores it on exit, so that any output
2267 visible before the application starts reappears unchanged after it exits.
2270 .It Xo Ic automatic-rename
2273 Control automatic window renaming.
2274 When this setting is enabled,
2276 will attempt - on supported platforms - to rename the window to reflect the
2277 command currently running in it.
2278 This flag is automatically disabled for an individual window when a name
2279 is specified at creation with
2285 It may be switched off globally with:
2286 .Bd -literal -offset indent
2287 set-window-option -g automatic-rename off
2290 .It Ic clock-mode-colour Ar colour
2293 .It Xo Ic clock-mode-style
2296 Set clock hour format.
2298 .It Ic force-height Ar height
2299 .It Ic force-width Ar width
2302 from resizing a window to greater than
2306 A value of zero restores the default unlimited setting.
2308 .It Ic main-pane-height Ar height
2309 .It Ic main-pane-width Ar width
2310 Set the width or height of the main (left or top) pane in the
2316 .It Ic mode-attr Ar attributes
2317 Set window modes attributes.
2319 .It Ic mode-bg Ar colour
2320 Set window modes background colour.
2322 .It Ic mode-fg Ar colour
2323 Set window modes foreground colour.
2328 Use vi or emacs-style key bindings in copy and choice modes.
2331 option, the default is emacs, unless
2338 .It Xo Ic mode-mouse
2341 Mouse state in modes.
2342 If on, the mouse may be used to enter copy mode and copy a selection by
2343 dragging, to enter copy mode and scroll with the mouse wheel, or to select an
2344 option in choice mode.
2346 .It Xo Ic monitor-activity
2349 Monitor for activity in the window.
2350 Windows with activity are highlighted in the status line.
2352 .It Ic monitor-content Ar match-string
2353 Monitor content in the window.
2358 appears in the window, it is highlighted in the status line.
2360 .It Xo Ic monitor-silence
2363 Monitor for silence (no activity) in the window within
2366 Windows that have been silent for the interval are highlighted in the
2368 An interval of zero disables the monitoring.
2370 .It Ic other-pane-height Ar height
2371 Set the height of the other panes (not the main pane) in the
2374 If this option is set to 0 (the default), it will have no effect.
2376 .Ic main-pane-height
2378 .Ic other-pane-height
2379 options are set, the main pane will grow taller to make the other panes the
2380 specified height, but will never shrink to do so.
2382 .It Ic other-pane-width Ar width
2384 .Ic other-pane-height ,
2385 but set the width of other panes in the
2389 .It Xo Ic remain-on-exit
2392 A window with this flag set is not destroyed when the program running in it
2394 The window may be reactivated with the
2398 .It Xo Ic synchronize-panes
2401 Duplicate input to any pane to all other panes in the same window (only
2402 for panes that are not in any special mode).
2409 to expect UTF-8 sequences to appear in this window.
2411 .It Ic window-status-attr Ar attributes
2412 Set status line attributes for a single window.
2414 .It Ic window-status-bg Ar colour
2415 Set status line background colour for a single window.
2417 .It Ic window-status-fg Ar colour
2418 Set status line foreground colour for a single window.
2420 .It Ic window-status-format Ar string
2421 Set the format in which the window is displayed in the status line window list.
2424 option for details of special character sequences available.
2428 .It Ic window-status-alert-attr Ar attributes
2429 Set status line attributes for windows which have an alert (bell, activity
2432 .It Ic window-status-alert-bg Ar colour
2433 Set status line background colour for windows with an alert.
2435 .It Ic window-status-alert-fg Ar colour
2436 Set status line foreground colour for windows with an alert.
2438 .It Ic window-status-current-attr Ar attributes
2439 Set status line attributes for the currently active window.
2441 .It Ic window-status-current-bg Ar colour
2442 Set status line background colour for the currently active window.
2444 .It Ic window-status-current-fg Ar colour
2445 Set status line foreground colour for the currently active window.
2447 .It Ic window-status-current-format Ar string
2449 .Ar window-status-format ,
2450 but is the format used when the window is the current window.
2452 .It Ic word-separators Ar string
2453 Sets the window's conception of what characters are considered word
2454 separators, for the purposes of the next and previous word commands in
2459 .It Xo Ic xterm-keys
2462 If this option is set,
2466 function key sequences; these have a number included to indicate modifiers such
2467 as Shift, Alt or Ctrl.
2470 .It Xo Ic show-options
2472 .Op Fl t Ar target-session | Ar target-window
2474 .D1 (alias: Ic show )
2475 Show the window options with
2478 .Ic show-window-options ) ,
2479 the server options with
2481 otherwise the session options for
2482 .Ar target session .
2483 Global session or window options are listed if
2486 .It Xo Ic show-window-options
2488 .Op Fl t Ar target-window
2490 .D1 (alias: Ic showw )
2491 List the window options for
2493 or the global window options if
2498 When the server is started,
2500 copies the environment into the
2501 .Em global environment ;
2502 in addition, each session has a
2503 .Em session environment .
2504 When a window is created, the session and global environments are merged.
2505 If a variable exists in both, the value from the session environment is used.
2506 The result is the initial environment passed to the new process.
2509 .Ic update-environment
2510 session option may be used to update the session environment from the client
2511 when a new session is created or an old reattached.
2513 also initialises the
2515 variable with some internal information to allow commands to be executed
2516 from inside, and the
2518 variable with the correct terminal setting of
2521 Commands to alter and view the environment are:
2523 .It Xo Ic set-environment
2525 .Op Fl t Ar target-session
2526 .Ar name Op Ar value
2528 .D1 (alias: Ic setenv )
2529 Set or unset an environment variable.
2532 is used, the change is made in the global environment; otherwise, it is applied
2533 to the session environment for
2534 .Ar target-session .
2537 flag unsets a variable.
2539 indicates the variable is to be removed from the environment before starting a
2541 .It Xo Ic show-environment
2543 .Op Fl t Ar target-session
2545 .D1 (alias: Ic showenv )
2546 Display the environment for
2548 or the global environment with
2550 Variables removed from the environment are prefixed with
2555 includes an optional status line which is displayed in the bottom line of each
2557 By default, the status line is enabled (it may be disabled with the
2559 session option) and contains, from left-to-right: the name of the current
2560 session in square brackets; the window list; the current window title in double
2561 quotes; and the time and date.
2563 The status line is made of three parts: configurable left and right sections
2564 (which may contain dynamic content such as the time or output from a shell
2567 .Ic status-left-length ,
2570 .Ic status-right-length
2571 options below), and a central window list.
2572 By default, the window list shows the index, name and (if any) flag of the
2573 windows present in the current session in ascending numerical order.
2574 It may be customised with the
2575 .Ar window-status-format
2577 .Ar window-status-current-format
2579 The flag is one of the following symbols appended to the window name:
2580 .Bl -column "Symbol" "Meaning" -offset indent
2581 .It Sy "Symbol" Ta Sy "Meaning"
2582 .It Li "*" Ta "Denotes the current window."
2583 .It Li "-" Ta "Marks the last window (previously selected)."
2584 .It Li "#" Ta "Window is monitored and activity has been detected."
2585 .It Li "!" Ta "A bell has occurred in the window."
2586 .It Li "+" Ta "Window is monitored for content and it has appeared."
2587 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
2590 The # symbol relates to the
2591 .Ic monitor-activity
2595 The window name is printed in inverted colours if an alert (bell, activity or
2596 content) is present.
2598 The colour and attributes of the status line may be configured, the entire
2599 status line using the
2604 session options and individual windows using the
2605 .Ic window-status-attr ,
2606 .Ic window-status-fg
2608 .Ic window-status-bg
2611 The status line is automatically refreshed at interval if it has changed, the
2612 interval may be controlled with the
2616 Commands related to the status line are as follows:
2618 .It Xo Ic command-prompt
2620 .Op Fl t Ar target-client
2623 Open the command prompt in a client.
2624 This may be used from inside
2626 to execute commands interactively.
2629 is specified, it is used as the command.
2634 is a comma-separated list of prompts which are displayed in order; otherwise
2635 a single prompt is displayed, constructed from
2637 if it is present, or
2640 Before the command is executed, the first occurrence of the string
2642 and all occurrences of
2644 are replaced by the response to the first prompt, the second
2648 are replaced with the response to the second prompt, and so on for further
2650 Up to nine prompt responses may be replaced
2656 .It Xo Ic confirm-before
2657 .Op Fl t Ar target-client
2660 .D1 (alias: Ic confirm )
2661 Ask for confirmation before executing
2663 This command works only from inside
2665 .It Xo Ic display-message
2667 .Op Fl c Ar target-client
2668 .Op Fl t Ar target-pane
2671 .D1 (alias: Ic display )
2675 is given, the output is printed to stdout, otherwise it is displayed in the
2682 with the exception that #() are not handled; information is taken from
2686 is given, otherwise the active pane for the session attached to
2691 maintains a stack of
2693 Up to the value of the
2695 option are kept; when a new buffer is added, the buffer at the bottom of the
2697 Buffers may be added using
2701 command, and pasted into a window using the
2705 A configurable history buffer is also maintained for each window.
2706 By default, up to 2000 lines are kept; this can be altered with the
2712 The buffer commands are as follows:
2716 .Op Fl t Ar target-window
2719 Put a window into buffer choice mode, where a buffer may be chosen
2720 interactively from a list.
2721 After a buffer is selected,
2723 is replaced by the buffer index in
2725 and the result executed as a command.
2728 is not given, "paste-buffer -b '%%'" is used.
2729 This command works only from inside
2731 .It Ic clear-history Op Fl t Ar target-pane
2732 .D1 (alias: Ic clearhist )
2733 Remove and free the history for the specified pane.
2734 .It Ic delete-buffer Op Fl b Ar buffer-index
2735 .D1 (alias: Ic deleteb )
2736 Delete the buffer at
2738 or the top buffer if not specified.
2740 .D1 (alias: Ic lsb )
2741 List the global buffers.
2742 .It Xo Ic load-buffer
2743 .Op Fl b Ar buffer-index
2746 .D1 (alias: Ic loadb )
2747 Load the contents of the specified paste buffer from
2749 .It Xo Ic paste-buffer
2751 .Op Fl b Ar buffer-index
2752 .Op Fl s Ar separator
2753 .Op Fl t Ar target-pane
2755 .D1 (alias: Ic pasteb )
2756 Insert the contents of a paste buffer into the specified pane.
2757 If not specified, paste into the current one.
2760 also delete the paste buffer from the stack.
2761 When output, any linefeed (LF) characters in the paste buffer are replaced with
2762 a separator, by default carriage return (CR).
2763 A custom separator may be specified using the
2768 flag means to do no replacement (equivalent to a separator of LF).
2769 .It Xo Ic save-buffer
2771 .Op Fl b Ar buffer-index
2774 .D1 (alias: Ic saveb )
2775 Save the contents of the specified paste buffer to
2779 option appends to rather than overwriting the file.
2780 .It Xo Ic set-buffer
2781 .Op Fl b Ar buffer-index
2784 .D1 (alias: Ic setb )
2785 Set the contents of the specified buffer to
2787 .It Xo Ic show-buffer
2788 .Op Fl b Ar buffer-index
2790 .D1 (alias: Ic showb )
2791 Display the contents of the specified buffer.
2794 Miscellaneous commands are as follows:
2796 .It Ic clock-mode Op Fl t Ar target-pane
2797 Display a large clock.
2798 .It Ic if-shell Ar shell-command command
2806 .D1 (alias: Ic lock )
2807 Lock each client individually by running the command specified by the
2810 .It Ic run-shell Ar shell-command
2811 .D1 (alias: Ic run )
2814 in the background without creating a window.
2815 After it finishes, any output to stdout is displayed in copy mode.
2816 If the command doesn't return success, the exit status is also displayed.
2818 .D1 (alias: Ic info )
2819 Show server information and terminal details.
2821 .Sh TERMINFO EXTENSIONS
2823 understands some extensions to
2827 This sequence can be used by
2829 to store the current buffer in the host terminal's selection (clipboard).
2832 option above and the
2836 The first takes one string argument and is used to set the cursor colour;
2837 the second takes no arguments and restores the default cursor colour.
2838 If they present, a sequence such as this may be used to change the
2839 cursor colour from inside
2841 .Bd -literal -offset indent
2842 $ printf '\e033]12;red\e033\e\e'
2846 .Bl -tag -width "/etc/tmux.confXXX" -compact
2851 .It Pa /etc/tmux.conf
2852 System-wide configuration file.
2860 .Dl $ tmux new-session vi
2862 Most commands have a shorter form, known as an alias.
2863 For new-session, this is
2868 Alternatively, the shortest unambiguous form of a command is accepted.
2869 If there are several options, they are listed:
2870 .Bd -literal -offset indent
2872 ambiguous command: n, could be: new-session, new-window, next-window
2875 Within an active session, a new window may be created by typing
2885 Windows may be navigated with:
2887 (to select window 0),
2889 (to select window 1), and so on;
2891 to select the next window; and
2893 to select the previous window.
2895 A session may be detached using
2897 (or by an external event such as
2899 disconnection) and reattached with:
2901 .Dl $ tmux attach-session
2905 lists the current key bindings in the current window; up and down may be used
2906 to navigate the list or
2910 Commands to be run when the
2912 server is started may be placed in the
2915 Common examples include:
2917 Changing the default prefix key:
2918 .Bd -literal -offset indent
2919 set-option -g prefix C-a
2921 bind-key C-a send-prefix
2924 Turning the status line off, or changing its colour:
2925 .Bd -literal -offset indent
2926 set-option -g status off
2927 set-option -g status-bg blue
2930 Setting other options, such as the default command,
2931 or locking after 30 minutes of inactivity:
2932 .Bd -literal -offset indent
2933 set-option -g default-command "exec /bin/ksh"
2934 set-option -g lock-after-time 1800
2937 Creating new key bindings:
2938 .Bd -literal -offset indent
2939 bind-key b set-option status
2940 bind-key / command-prompt "split-window 'exec man %%'"
2941 bind-key S command-prompt "new-window -n %1 'ssh %1'"
2946 .An Nicholas Marriott Aq nicm@users.sourceforge.net