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.
102 Start in control mode (see the
108 .It Fl c Ar shell-command
111 using the default shell.
114 server will be started to retrieve the
117 This option is for compatibility with
121 is used as a login shell.
123 Specify an alternative configuration file.
126 loads the system configuration file from
128 if present, then looks for a user configuration file at
131 The configuration file is a set of
133 commands which are executed in sequence when the server is first started.
135 loads configuration files once when the server process has started.
138 command may be used to load a file later.
141 shows any error messages from commands in configuration files in the first
142 session created, and continues to process the rest of the configuration file.
143 .It Fl L Ar socket-name
145 stores the server socket in a directory under
151 The default socket is named
153 This option allows a different socket name to be specified, allowing several
159 a full path is not necessary: the sockets are all created in the same
162 If the socket is accidentally removed, the
164 signal may be sent to the
166 server process to recreate it.
168 Behave as a login shell.
169 This flag currently has no effect and is for compatibility with other shells
170 when using tmux as a login shell.
174 server option to prevent the server sending various informational messages.
175 .It Fl S Ar socket-path
176 Specify a full alternative path to the server socket.
179 is specified, the default socket directory is not used and any
184 attempts to guess if the terminal is likely to support UTF-8 by checking the
190 environment variables to be set for the string "UTF-8".
191 This is not always correct: the
193 flag explicitly informs
195 that UTF-8 is supported.
197 If the server is started from a client passed
199 or where UTF-8 is detected, the
203 options are enabled in the global window and session options respectively.
205 Request verbose logging.
206 This option may be specified multiple times for increasing verbosity.
207 Log messages will be saved into
208 .Pa tmux-client-PID.log
210 .Pa tmux-server-PID.log
211 files in the current directory, where
213 is the PID of the server or client process.
214 .It Ar command Op Ar flags
215 This specifies one of a set of commands used to control
217 as described in the following sections.
218 If no commands are specified, the
224 may be controlled from an attached client by using a key combination of a
227 (Ctrl-b) by default, followed by a command key.
229 The default command key bindings are:
231 .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
233 Send the prefix key (C-b) through to the application.
235 Rotate the panes in the current window forwards.
241 Break the current pane out of the window.
243 Split the current pane into two, top and bottom.
245 List all paste buffers.
247 Rename the current session.
249 Split the current pane into two, left and right.
251 Kill the current window.
253 Prompt for a window index to select.
255 Rename the current window.
257 Delete the most recently copied buffer of text.
259 Prompt for an index to move the current window.
261 Select windows 0 to 9.
267 Move to the previously active pane.
269 Choose which buffer to paste interactively from a list.
271 List all key bindings.
273 Choose a client to detach.
275 Enter copy mode to copy text or view the history.
277 Paste the most recently copied buffer of text.
281 Detach the current client.
283 Prompt to search for text in open windows.
285 Display some information about the current window.
287 Move to the previously selected window.
289 Change to the next window.
291 Select the next pane in the current window.
293 Change to the previous window.
295 Briefly display pane indexes.
297 Force redraw of the attached client.
299 Select a new session for the attached client interactively.
301 Switch the attached client back to the last session.
305 Choose the current window interactively.
307 Kill the current pane.
309 Swap the current pane with the previous pane.
311 Swap the current pane with the next pane.
313 Show previous messages from
317 Enter copy mode and scroll one page up.
320 Change to the pane above, below, to the left, or to the right of the current
323 Arrange panes in one of the five preset layouts: even-horizontal,
324 even-vertical, main-horizontal, main-vertical, or tiled.
326 Move to the next window with a bell or activity marker.
328 Rotate the panes in the current window backwards.
330 Move to the previous window with a bell or activity marker.
333 Resize the current pane in steps of one cell.
336 Resize the current pane in steps of five cells.
339 Key bindings may be changed with the
345 This section contains a list of the commands supported by
347 Most commands accept the optional
355 These specify the client, session, window or pane which a command should affect.
359 file to which the client is connected, for example either of
363 for the client attached to
365 If no client is specified, the current client is chosen, if possible, or an
367 Clients may be listed with the
372 is the session id prefixed with a $, the name of a session (as listed by the
374 command), or the name of a client with the same syntax as
376 in which case the session attached to the client is used.
377 When looking for the session name,
379 initially searches for an exact match; if none is found, the session names
380 are checked for any for which
382 is a prefix or for which it matches as an
385 If a single match is found, it is used as the target session; multiple matches
387 If a session is omitted, the current session is used if available; if no
388 current session is available, the most recently used is chosen.
391 specifies a window in the form
392 .Em session Ns \&: Ns Em window .
394 follows the same rules as for
398 is looked for in order: as a window index, for example mysession:1;
399 as a window ID, such as @1;
400 as an exact window name, such as mysession:mywindow; then as an
402 pattern or the start of a window name, such as mysession:mywin* or
404 An empty window name specifies the next unused index if appropriate (for
410 otherwise the current window in
413 The special character
415 uses the last (previously current) window,
417 selects the highest numbered window,
419 selects the lowest numbered window, and
423 select the next window or the previous window by number.
424 When the argument does not contain a colon,
426 first attempts to parse it as window; if that fails, an attempt is made to
430 takes a similar form to
432 but with the optional addition of a period followed by a pane index, for
433 example: mysession:mywindow.1.
434 If the pane index is omitted, the currently active pane in the specified
436 If neither a colon nor period appears,
438 first attempts to use the argument as a pane index; if that fails, it is looked
445 indicate the next or previous pane index, respectively.
456 may be used instead of a pane index.
458 The special characters
462 may be followed by an offset, for example:
463 .Bd -literal -offset indent
467 When dealing with a session that doesn't contain sequential window indexes,
468 they will be correctly skipped.
471 also gives each pane created in a server an identifier consisting of a
473 and a number, starting from zero.
474 A pane's identifier is unique for the life of the
476 server and is passed to the child process of the pane in the
478 environment variable.
479 It may be used alone to target a pane or the window containing it.
485 These must be passed as a single item, which typically means quoting them, for
487 .Bd -literal -offset indent
488 new-window 'vi /etc/passwd'
495 command, passed with the command and arguments separately, for example:
496 .Bd -literal -offset indent
497 bind-key F1 set-window-option force-width 81
502 .Bd -literal -offset indent
503 $ tmux bind-key F1 set-window-option force-width 81
506 Multiple commands may be specified together as part of a
507 .Em command sequence .
508 Each command should be separated by spaces and a semicolon;
509 commands are executed sequentially from left to right and
510 lines ending with a backslash continue on to the next line,
511 except when escaped by another backslash.
512 A literal semicolon may be included by escaping it with a backslash (for
513 example, when specifying a command sequence to
519 .Bd -literal -offset indent
520 refresh-client -t/dev/ttyp2
522 rename-session -tfirst newname
524 set-window-option -t:0 monitor-activity on
526 new-window ; split-window -d
528 bind-key R source-file ~/.tmux.conf \e; \e
529 display-message "source-file done"
534 .Bd -literal -offset indent
535 $ tmux kill-window -t :1
537 $ tmux new-window \e; split-window -d
539 $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
541 .Sh CLIENTS AND SESSIONS
544 server manages clients, sessions, windows and panes.
545 Clients are attached to sessions to interact with them, either
546 when they are created with the
548 command, or later with the
551 Each session has one or more windows
554 Windows may be linked to multiple sessions and are made up of one or
556 each of which contains a pseudo terminal.
557 Commands for creating, linking and otherwise manipulating windows
560 .Sx WINDOWS AND PANES
563 The following commands are available to manage clients and sessions:
565 .It Xo Ic attach-session
567 .Op Fl c Ar working-directory
568 .Op Fl t Ar target-session
570 .D1 (alias: Ic attach )
573 create a new client in the current terminal and attach it to
575 If used from inside, switch the current client.
578 is specified, any other clients attached to the session are detached.
580 signifies the client is read-only (only keys bound to the
584 commands have any effect)
586 If no server is started,
588 will attempt to start it; this will fail unless sessions are created in the
595 are slightly adjusted: if
597 needs to select the most recently used session, it will prefer the most
603 will set the session working directory (used for new windows) to
604 .Ar working-directory .
605 .It Xo Ic detach-client
608 .Op Fl s Ar target-session
609 .Op Fl t Ar target-client
611 .D1 (alias: Ic detach )
612 Detach the current client if bound to a key, the client specified with
614 or all clients currently attached to the session specified by
618 option kills all but the client given with
622 is given, send SIGHUP to the parent process of the client, typically causing it
624 .It Ic has-session Op Fl t Ar target-session
626 Report an error and exit with 1 if the specified session does not exist.
627 If it does exist, exit with 0.
631 server and clients and destroy all sessions.
632 .It Xo Ic kill-session
634 .Op Fl t Ar target-session
636 Destroy the given session, closing any windows linked to it and no other
637 sessions, and detaching all clients attached to it.
640 is given, all sessions but the specified one is killed.
641 .It Xo Ic list-clients
643 .Op Fl t Ar target-session
646 List all clients attached to the server.
647 For the meaning of the
654 is specified, list only clients connected to that session.
656 .D1 (alias: Ic lscm )
657 List the syntax of all commands supported by
659 .It Ic list-sessions Op Fl F Ar format
661 List all sessions managed by the server.
662 For the meaning of the
667 .It Ic lock-client Op Fl t Ar target-client
668 .D1 (alias: Ic lockc )
674 .It Ic lock-session Op Fl t Ar target-session
675 .D1 (alias: Ic locks )
676 Lock all clients attached to
678 .It Xo Ic new-session
680 .Op Fl c Ar start-directory
682 .Op Fl n Ar window-name
683 .Op Fl s Ar session-name
684 .Op Fl t Ar target-session
690 Create a new session with name
693 The new session is attached to the current terminal unless
699 are the name of and shell command to execute in the initial window.
706 specify the size of the initial window (80 by 24 if not given).
708 If run from a terminal, any
710 special characters are saved and used for new windows in the new session.
720 already exists; in the case,
729 is given, the new session is
733 This means they share the same set of windows - all windows from
735 are linked to the new session and any subsequent new windows or windows being
736 closed are applied to both sessions.
737 The current and previous window and any session options remain independent and
738 either session may be killed without affecting the other.
749 option prints information about the new session after it has been created.
750 By default, it uses the format
752 but a different format may be specified with
754 .It Xo Ic refresh-client
756 .Op Fl t Ar target-client
758 .D1 (alias: Ic refresh )
759 Refresh the current client if bound to a key, or a single client if one is given
764 is specified, only update the client's status bar.
765 .It Xo Ic rename-session
766 .Op Fl t Ar target-session
769 .D1 (alias: Ic rename )
770 Rename the session to
772 .It Xo Ic show-messages
773 .Op Fl t Ar target-client
775 .D1 (alias: Ic showmsgs )
776 Any messages displayed on the status line are saved in a per-client message
777 log, up to a maximum of the limit set by the
779 session option for the session attached to that client.
780 This command displays the log for
782 .It Ic source-file Ar path
783 .D1 (alias: Ic source )
784 Execute commands from
787 .D1 (alias: Ic start )
790 server, if not already running, without creating any sessions.
791 .It Xo Ic suspend-client
792 .Op Fl t Ar target-client
794 .D1 (alias: Ic suspendc )
795 Suspend a client by sending
798 .It Xo Ic switch-client
800 .Op Fl c Ar target-client
801 .Op Fl t Ar target-session
803 .D1 (alias: Ic switchc )
804 Switch the current session for client
813 is used, the client is moved to the last, next or previous session
816 toggles whether a client is read-only (see the
820 .Sh WINDOWS AND PANES
823 window may be in one of several modes.
824 The default permits direct access to the terminal attached to the window.
825 The other is copy mode, which permits a section of a window or its
826 history to be copied to a
828 for later insertion into another window.
829 This mode is entered with the
834 It is also entered when a command that produces output, such as
836 is executed from a key binding.
838 The keys available depend on whether emacs or vi mode is selected
842 The following keys are supported as appropriate for the mode:
843 .Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
844 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
845 .It Li "Back to indentation" Ta "^" Ta "M-m"
846 .It Li "Bottom of history" Ta "G" Ta "M-<"
847 .It Li "Clear selection" Ta "Escape" Ta "C-g"
848 .It Li "Copy selection" Ta "Enter" Ta "M-w"
849 .It Li "Cursor down" Ta "j" Ta "Down"
850 .It Li "Cursor left" Ta "h" Ta "Left"
851 .It Li "Cursor right" Ta "l" Ta "Right"
852 .It Li "Cursor to bottom line" Ta "L" Ta ""
853 .It Li "Cursor to middle line" Ta "M" Ta "M-r"
854 .It Li "Cursor to top line" Ta "H" Ta "M-R"
855 .It Li "Cursor up" Ta "k" Ta "Up"
856 .It Li "Delete entire line" Ta "d" Ta "C-u"
857 .It Li "Delete/Copy to end of line" Ta "D" Ta "C-k"
858 .It Li "End of line" Ta "$" Ta "C-e"
859 .It Li "Go to line" Ta ":" Ta "g"
860 .It Li "Half page down" Ta "C-d" Ta "M-Down"
861 .It Li "Half page up" Ta "C-u" Ta "M-Up"
862 .It Li "Jump forward" Ta "f" Ta "f"
863 .It Li "Jump to forward" Ta "t" Ta ""
864 .It Li "Jump backward" Ta "F" Ta "F"
865 .It Li "Jump to backward" Ta "T" Ta ""
866 .It Li "Jump again" Ta ";" Ta ";"
867 .It Li "Jump again in reverse" Ta "," Ta ","
868 .It Li "Next page" Ta "C-f" Ta "Page down"
869 .It Li "Next space" Ta "W" Ta ""
870 .It Li "Next space, end of word" Ta "E" Ta ""
871 .It Li "Next word" Ta "w" Ta ""
872 .It Li "Next word end" Ta "e" Ta "M-f"
873 .It Li "Paste buffer" Ta "p" Ta "C-y"
874 .It Li "Previous page" Ta "C-b" Ta "Page up"
875 .It Li "Previous word" Ta "b" Ta "M-b"
876 .It Li "Previous space" Ta "B" Ta ""
877 .It Li "Quit mode" Ta "q" Ta "Escape"
878 .It Li "Rectangle toggle" Ta "v" Ta "R"
879 .It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down"
880 .It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up"
881 .It Li "Search again" Ta "n" Ta "n"
882 .It Li "Search again in reverse" Ta "N" Ta "N"
883 .It Li "Search backward" Ta "?" Ta "C-r"
884 .It Li "Search forward" Ta "/" Ta "C-s"
885 .It Li "Start of line" Ta "0" Ta "C-a"
886 .It Li "Start selection" Ta "Space" Ta "C-Space"
887 .It Li "Top of history" Ta "g" Ta "M->"
888 .It Li "Transpose characters" Ta "" Ta "C-t"
891 The next and previous word keys use space and the
896 characters as word delimiters by default, but this can be adjusted by
900 Next word moves to the start of the next word, next word end to the end of the
901 next word and previous word to the start of the previous word.
902 The three next and previous space keys work similarly but use a space alone as
905 The jump commands enable quick movement within a line.
910 will move the cursor to the next
912 character on the current line.
915 will then jump to the next occurrence.
917 Commands in copy mode may be prefaced by an optional repeat count.
918 With vi key bindings, a prefix is entered using the number keys; with
919 emacs, the Alt (meta) key and a number begins prefix entry.
920 For example, to move the cursor forward by ten words, use
926 When copying the selection, the repeat count indicates the buffer index to
929 Mode key bindings are defined in a set of named tables:
933 for keys used when line editing at the command prompt;
937 for keys used when choosing from lists (such as produced by the
944 The tables may be viewed with the
946 command and keys modified or removed with
950 One command accepts an argument,
952 which copies the selection and pipes it to a command.
953 For example the following will bind
955 to copy the selection into
957 as well as the paste buffer:
958 .Bd -literal -offset indent
959 bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out"
962 The paste buffer key pastes the first line from the top paste buffer on the
971 .Op Fl t Ar target-pane
976 option scrolls one page up.
979 Each window displayed by
981 may be split into one or more
983 each pane takes up a certain area of the display and is a separate terminal.
984 A window may be split into panes using the
987 Windows may be split horizontally (with the
990 Panes may be resized with the
998 by default), the current pane may be changed with the
1004 commands may be used to swap panes without changing their position.
1005 Panes are numbered beginning from zero in the order they are created.
1010 These may be selected with the
1012 command or cycled with
1016 by default); once a layout is chosen, panes within it may be moved and resized
1019 The following layouts are supported:
1021 .It Ic even-horizontal
1022 Panes are spread out evenly from left to right across the window.
1023 .It Ic even-vertical
1024 Panes are spread evenly from top to bottom.
1025 .It Ic main-horizontal
1026 A large (main) pane is shown at the top of the window and the remaining panes
1027 are spread from left to right in the leftover space at the bottom.
1029 .Em main-pane-height
1030 window option to specify the height of the top pane.
1031 .It Ic main-vertical
1034 but the large pane is placed on the left and the others spread from top to
1035 bottom along the right.
1040 Panes are spread out as evenly as possible over the window in both rows and
1046 may be used to apply a previously used layout - the
1048 command displays the layout of each window in a form suitable for use with
1051 .Bd -literal -offset indent
1054 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1055 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1059 automatically adjusts the size of the layout for the current window size.
1060 Note that a layout cannot be applied to a window with more panes than that
1061 from which the layout was originally defined.
1063 Commands related to windows and panes are as follows:
1065 .It Xo Ic break-pane
1068 .Op Fl t Ar target-pane
1070 .D1 (alias: Ic breakp )
1073 off from its containing window to make it the only pane in a new window.
1076 is given, the new window does not become the current window.
1079 option prints information about the new window after it has been created.
1080 By default, it uses the format
1081 .Ql #{session_name}:#{window_index}
1082 but a different format may be specified with
1084 .It Xo Ic capture-pane
1086 .Op Fl b Ar buffer-index
1087 .Op Fl E Ar end-line
1088 .Op Fl S Ar start-line
1089 .Op Fl t Ar target-pane
1091 .D1 (alias: Ic capturep )
1092 Capture the contents of a pane.
1095 is given, the output goes to stdout, otherwise to the buffer specified with
1097 or a new buffer if omitted.
1100 is given, the alternate screen is used, and the history is not accessible.
1101 If no alternate screen exists, an error will be returned unless
1106 is given, the output includes escape sequences for text and background
1109 also escapes non-printable characters as octal \exxx.
1111 joins wrapped lines and preserves trailing spaces at each line's end.
1113 captures only any output that the pane has received that is the beginning of an
1114 as-yet incomplete escape sequence.
1119 specify the starting and ending line numbers, zero is the first line of the
1120 visible pane and negative numbers are lines in the history.
1121 The default is to capture only the visible contents of the pane.
1125 .Op Fl t Ar target-window
1128 Put a window into client choice mode, allowing a client to be selected
1129 interactively from a list.
1130 After a client is chosen,
1132 is replaced by the client
1136 and the result executed as a command.
1139 is not given, "detach-client -t '%%'" is used.
1140 For the meaning of the
1145 This command works only if at least one client is attached.
1149 .Op Fl t Ar target-window
1152 Put a window into list choice mode, allowing
1156 can be a comma-separated list to display more than one item.
1157 If an item has spaces, that entry must be quoted.
1158 After an item is chosen,
1160 is replaced by the chosen item in the
1162 and the result is executed as a command.
1165 is not given, "run-shell '%%'" is used.
1167 also accepts format specifiers.
1168 For the meaning of this see the
1171 This command works only if at least one client is attached.
1175 .Op Fl t Ar target-window
1178 Put a window into session choice mode, where a session may be selected
1179 interactively from a list.
1182 is replaced by the session name in
1184 and the result executed as a command.
1187 is not given, "switch-client -t '%%'" is used.
1188 For the meaning of the
1193 This command works only if at least one client is attached.
1197 .Op Fl b Ar session-template
1198 .Op Fl c Ar window-template
1201 .Op Fl t Ar target-window
1203 Put a window into tree choice mode, where either sessions or windows may be
1204 selected interactively from a list.
1205 By default, windows belonging to a session are indented to show their
1206 relationship to a session.
1212 commands are wrappers around
1217 is given, will show sessions.
1220 is given, will show windows.
1222 By default, the tree is collapsed and sessions must be expanded to windows
1223 with the right arrow key.
1226 option will start with all sessions expanded instead.
1230 is given, will override the default session command.
1233 can be used and will be replaced with the session name.
1234 The default option if not specified is "switch-client -t '%%'".
1237 is given, will override the default window command.
1241 can be used and will be replaced with the session name and window index.
1242 When a window is chosen from the list, the session command is run before the
1247 is given will display the specified format instead of the default session
1251 is given will display the specified format instead of the default window
1253 For the meaning of the
1261 This command works only if at least one client is attached.
1265 .Op Fl t Ar target-window
1268 Put a window into window choice mode, where a window may be chosen
1269 interactively from a list.
1270 After a window is selected,
1272 is replaced by the session name and window index in
1274 and the result executed as a command.
1277 is not given, "select-window -t '%%'" is used.
1278 For the meaning of the
1283 This command works only if at least one client is attached.
1284 .It Ic display-panes Op Fl t Ar target-client
1285 .D1 (alias: Ic displayp)
1286 Display a visible indicator of each pane shown by
1289 .Ic display-panes-time ,
1290 .Ic display-panes-colour ,
1292 .Ic display-panes-active-colour
1294 While the indicator is on screen, a pane may be selected with the
1299 .It Xo Ic find-window
1302 .Op Fl t Ar target-window
1305 .D1 (alias: Ic findw )
1310 in window names, titles, and visible content (but not history).
1311 The flags control matching behavior:
1313 matches only visible window contents,
1315 matches only the window name and
1317 matches only the window title.
1320 If only one window is matched, it'll be automatically selected,
1321 otherwise a choice list is shown.
1322 For the meaning of the
1327 This command works only if at least one client is attached.
1332 .Fl p Ar percentage Oc
1333 .Op Fl s Ar src-pane
1334 .Op Fl t Ar dst-pane
1336 .D1 (alias: Ic joinp )
1339 but instead of splitting
1341 and creating a new pane, split it and move
1344 This can be used to reverse
1350 to be joined to left of or above
1354 .Op Fl t Ar target-pane
1356 .D1 (alias: Ic killp )
1357 Destroy the given pane.
1358 If no panes remain in the containing window, it is also destroyed.
1361 option kills all but the pane given with
1363 .It Xo Ic kill-window
1365 .Op Fl t Ar target-window
1367 .D1 (alias: Ic killw )
1368 Kill the current window or the window at
1370 removing it from any sessions to which it is linked.
1373 option kills all but the window given with
1375 .It Ic last-pane Op Fl t Ar target-window
1376 .D1 (alias: Ic lastp )
1377 Select the last (previously selected) pane.
1378 .It Ic last-window Op Fl t Ar target-session
1379 .D1 (alias: Ic last )
1380 Select the last (previously selected) window.
1383 is specified, select the last window of the current session.
1384 .It Xo Ic link-window
1386 .Op Fl s Ar src-window
1387 .Op Fl t Ar dst-window
1389 .D1 (alias: Ic linkw )
1396 is specified and no such window exists, the
1403 exists, it is killed, otherwise an error is generated.
1406 is given, the newly linked window is not selected.
1407 .It Xo Ic list-panes
1412 .D1 (alias: Ic lsp )
1417 is ignored and all panes on the server are listed.
1422 is a session (or the current session).
1423 If neither is given,
1425 is a window (or the current window).
1426 For the meaning of the
1431 .It Xo Ic list-windows
1434 .Op Fl t Ar target-session
1436 .D1 (alias: Ic lsw )
1439 is given, list all windows on the server.
1440 Otherwise, list windows in the current session or in
1441 .Ar target-session .
1442 For the meaning of the
1451 .Fl p Ar percentage Oc
1452 .Op Fl s Ar src-pane
1453 .Op Fl t Ar dst-pane
1455 .D1 (alias: Ic movep )
1462 may belong to the same window.
1463 .It Xo Ic move-window
1465 .Op Fl s Ar src-window
1466 .Op Fl t Ar dst-window
1468 .D1 (alias: Ic movew )
1471 except the window at
1477 all windows in the session are renumbered in sequential order, respecting
1481 .It Xo Ic new-window
1483 .Op Fl c Ar start-directory
1485 .Op Fl n Ar window-name
1486 .Op Fl t Ar target-window
1487 .Op Ar shell-command
1489 .D1 (alias: Ic neww )
1490 Create a new window.
1493 the new window is inserted at the next index up from the specified
1495 moving windows up if necessary,
1498 is the new window location.
1502 is given, the session does not make the new window the current window.
1504 represents the window to be created; if the target already exists an error is
1507 flag is used, in which case it is destroyed.
1509 is the command to execute.
1512 is not specified, the value of the
1516 specifies the working directory in which the new window is created.
1518 When the shell command completes, the window closes.
1521 option to change this behaviour.
1525 environment variable must be set to
1527 for all programs running
1530 New windows will automatically have
1532 added to their environment, but care must be taken not to reset this in shell
1537 option prints information about the new window after it has been created.
1538 By default, it uses the format
1539 .Ql #{session_name}:#{window_index}
1540 but a different format may be specified with
1542 .It Ic next-layout Op Fl t Ar target-window
1543 .D1 (alias: Ic nextl )
1544 Move a window to the next layout and rearrange the panes to fit.
1545 .It Xo Ic next-window
1547 .Op Fl t Ar target-session
1549 .D1 (alias: Ic next )
1550 Move to the next window in the session.
1553 is used, move to the next window with an alert.
1556 .Op Fl t Ar target-pane
1557 .Op Ar shell-command
1559 .D1 (alias: Ic pipep )
1560 Pipe any output sent by the program in
1563 A pane may only be piped to one command at a time, any existing pipe is
1569 string may contain the special character sequences supported by the
1574 is given, the current pipe (if any) is closed.
1578 option only opens a new pipe if no previous pipe exists, allowing a pipe to
1579 be toggled with a single key, for example:
1580 .Bd -literal -offset indent
1581 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1583 .It Xo Ic previous-layout
1584 .Op Fl t Ar target-window
1586 .D1 (alias: Ic prevl )
1587 Move to the previous layout in the session.
1588 .It Xo Ic previous-window
1590 .Op Fl t Ar target-session
1592 .D1 (alias: Ic prev )
1593 Move to the previous window in the session.
1596 move to the previous window with an alert.
1597 .It Xo Ic rename-window
1598 .Op Fl t Ar target-window
1601 .D1 (alias: Ic renamew )
1602 Rename the current window, or the window at
1606 .It Xo Ic resize-pane
1608 .Op Fl t Ar target-pane
1613 .D1 (alias: Ic resizep )
1614 Resize a pane, up, down, left or right by
1630 is given in lines or cells (the default is 1).
1634 the active pane is toggled between zoomed (occupying the whole of the window)
1635 and unzoomed (its normal position in the layout).
1636 .It Xo Ic respawn-pane
1638 .Op Fl t Ar target-pane
1639 .Op Ar shell-command
1641 .D1 (alias: Ic respawnp )
1642 Reactivate a pane in which the command has exited (see the
1647 is not given, the command used when the pane was created is executed.
1648 The pane must be already inactive, unless
1650 is given, in which case any existing command is killed.
1651 .It Xo Ic respawn-window
1653 .Op Fl t Ar target-window
1654 .Op Ar shell-command
1656 .D1 (alias: Ic respawnw )
1657 Reactivate a window in which the command has exited (see the
1662 is not given, the command used when the window was created is executed.
1663 The window must be already inactive, unless
1665 is given, in which case any existing command is killed.
1666 .It Xo Ic rotate-window
1668 .Op Fl t Ar target-window
1670 .D1 (alias: Ic rotatew )
1671 Rotate the positions of the panes within a window, either upward (numerically
1674 or downward (numerically higher).
1675 .It Xo Ic select-layout
1677 .Op Fl t Ar target-window
1680 .D1 (alias: Ic selectl )
1681 Choose a specific layout for a window.
1684 is not given, the last preset layout used (if any) is reapplied.
1688 are equivalent to the
1693 .It Xo Ic select-pane
1695 .Op Fl t Ar target-pane
1697 .D1 (alias: Ic selectp )
1700 the active pane in window
1708 is used, respectively the pane below, to the left, to the right, or above the
1709 target pane is used.
1711 is the same as using the
1714 .It Xo Ic select-window
1716 .Op Fl t Ar target-window
1718 .D1 (alias: Ic selectw )
1719 Select the window at
1725 are equivalent to the
1733 is given and the selected window is already the current window,
1734 the command behaves like
1736 .It Xo Ic split-window
1738 .Op Fl c Ar start-directory
1741 .Fl p Ar percentage Oc
1742 .Op Fl t Ar target-pane
1743 .Op Ar shell-command
1746 .D1 (alias: Ic splitw )
1747 Create a new pane by splitting
1750 does a horizontal split and
1752 a vertical split; if neither is specified,
1759 options specify the size of the new pane in lines (for vertical split) or in
1760 cells (for horizontal split), or as a percentage, respectively.
1761 All other options have the same meaning as for the
1766 .Op Fl s Ar src-pane
1767 .Op Fl t Ar dst-pane
1769 .D1 (alias: Ic swapp )
1773 is used and no source pane is specified with
1776 is swapped with the previous pane (before it numerically);
1778 swaps with the next pane (after it numerically).
1782 not to change the active pane.
1783 .It Xo Ic swap-window
1785 .Op Fl s Ar src-window
1786 .Op Fl t Ar dst-window
1788 .D1 (alias: Ic swapw )
1791 except the source and destination windows are swapped.
1792 It is an error if no window exists at
1794 .It Xo Ic unlink-window
1796 .Op Fl t Ar target-window
1798 .D1 (alias: Ic unlinkw )
1803 is given, a window may be unlinked only if it is linked to multiple sessions -
1804 windows may not be linked to no sessions;
1807 is specified and the window is linked to only one session, it is unlinked and
1812 allows a command to be bound to most keys, with or without a prefix key.
1813 When specifying keys, most represent themselves (for example
1817 Ctrl keys may be prefixed with
1823 In addition, the following special key names are accepted:
1841 .Em NPage/PageDown/PgDn ,
1842 .Em PPage/PageUp/PgUp ,
1846 Note that to bind the
1850 keys, quotation marks are necessary, for example:
1851 .Bd -literal -offset indent
1852 bind-key '"' split-window
1853 bind-key "'" new-window
1856 Commands related to key bindings are as follows:
1860 .Op Fl t Ar key-table
1861 .Ar key Ar command Op Ar arguments
1863 .D1 (alias: Ic bind )
1870 the primary key bindings are modified (those normally activated with the prefix
1871 key); in this case, if
1873 is specified, it is not necessary to use the prefix key,
1880 flag indicates this key may repeat, see the
1890 the binding for command mode with
1892 or for normal mode without.
1893 To view the default bindings and possible commands, see the
1896 .It Ic list-keys Op Fl t Ar key-table
1897 .D1 (alias: Ic lsk )
1898 List all key bindings.
1901 the primary key bindings - those executed when preceded by the prefix key -
1908 are listed; this may be one of:
1918 .Op Fl t Ar target-pane
1921 .D1 (alias: Ic send )
1922 Send a key or keys to a window.
1925 is the name of the key (such as
1929 ) to send; if the string is not recognised as a key, it is sent as a series of
1933 flag disables key name lookup and sends the keys literally.
1934 All arguments are sent sequentially from first to last.
1937 flag causes the terminal state to be reset.
1938 .It Xo Ic send-prefix
1940 .Op Fl t Ar target-pane
1942 Send the prefix key, or with
1944 the secondary prefix key, to a window as if it was pressed.
1945 .It Xo Ic unbind-key
1947 .Op Fl t Ar key-table
1950 .D1 (alias: Ic unbind )
1951 Unbind the command bound to
1955 the primary key bindings are modified; in this case, if
1957 is specified, the command bound to
1959 without a prefix (if any) is removed.
1962 is present, all key bindings are removed.
1970 is unbound: the binding for command mode with
1972 or for normal mode without.
1975 The appearance and behaviour of
1977 may be modified by changing the value of various options.
1978 There are three types of option:
1979 .Em server options ,
1982 .Em window options .
1986 server has a set of global options which do not apply to any particular
1988 These are altered with the
1991 command, or displayed with the
1996 In addition, each individual session may have a set of session options, and
1997 there is a separate set of global session options.
1998 Sessions which do not have a particular option configured inherit the value
1999 from the global session options.
2000 Session options are set or unset with the
2002 command and may be listed with the
2005 The available server and session options are listed under the
2009 Similarly, a set of window options is attached to each window, and there is
2010 a set of global window options from which any unset options are inherited.
2011 Window options are altered with the
2012 .Ic set-window-option
2013 command and can be listed with the
2014 .Ic show-window-options
2016 All window options are documented with the
2017 .Ic set-window-option
2021 also supports user options which are prefixed with a
2023 User options may have any name, so long as they are prefixed with
2025 and be set to any string.
2027 .Bd -literal -offset indent
2028 $ tmux setw -q @foo "abc123"
2029 $ tmux showw -v @foo
2033 Commands which set options are as follows:
2035 .It Xo Ic set-option
2037 .Op Fl t Ar target-session | Ar target-window
2040 .D1 (alias: Ic set )
2041 Set a window option with
2044 .Ic set-window-option
2046 a server option with
2048 otherwise a session option.
2052 is specified, the global session or window option is set.
2055 and if the option expects a string,
2057 is appended to the existing setting.
2060 flag unsets an option, so a session inherits the option from the global
2062 It is not possible to unset a global option.
2066 flag prevents setting an option that is already set.
2070 flag suppresses the informational message (as if the
2072 server option was set).
2074 Available window options are listed under
2075 .Ic set-window-option .
2078 depends on the option and may be a number, a string, or a flag (on, off, or
2081 Available server options are:
2083 .It Ic buffer-limit Ar number
2084 Set the number of buffers; as new buffers are added to the top of the stack,
2085 old ones are removed from the bottom if necessary to maintain this maximum
2087 .It Ic escape-time Ar time
2088 Set the time in milliseconds for which
2090 waits after an escape is input to determine if it is part of a function or meta
2092 The default is 500 milliseconds.
2093 .It Xo Ic exit-unattached
2096 If enabled, the server will exit when there are no attached clients.
2097 .It Xo Ic focus-events
2100 When enabled, focus events are requested from the terminal if supported and
2101 passed through to applications running in
2103 Attached clients should be detached and attached again after changing this
2108 Enable or disable the display of various informational messages (see also the
2111 .It Xo Ic set-clipboard
2114 Attempt to set the terminal clipboard content using the
2118 This option is on by default if there is an
2122 description for the client terminal.
2123 Note that this feature needs to be enabled in
2125 by setting the resource:
2126 .Bd -literal -offset indent
2127 disallowedWindowOps: 20,21,SetXprop
2130 Or changing this property from the
2132 interactive menu when required.
2135 Available session options are:
2137 .It Ic assume-paste-time Ar milliseconds
2138 If keys are entered faster than one in
2140 they are assumed to have been pasted rather than typed and
2142 key bindings are not processed.
2143 The default is one millisecond and zero disables.
2144 .It Ic base-index Ar index
2145 Set the base index from which an unused index should be searched when a new
2147 The default is zero.
2148 .It Xo Ic bell-action
2149 .Op Ic any | none | current
2151 Set action on window bell.
2153 means a bell in any window linked to a session causes a bell in the current
2154 window of that session,
2156 means all bells are ignored and
2158 means only bells in windows other than the current window are ignored.
2159 .It Xo Ic bell-on-alert
2162 If on, ring the terminal bell when an alert
2164 .It Ic default-command Ar shell-command
2165 Set the command used for new windows (if not specified when the window is
2171 The default is an empty string, which instructs
2173 to create a login shell using the value of the
2176 .It Ic default-shell Ar path
2177 Specify the default shell.
2178 This is used as the login shell for new windows when the
2180 option is set to empty, and must be the full path of the executable.
2183 tries to set a default value from the first suitable of the
2185 environment variable, the shell returned by
2189 This option should be configured when
2191 is used as a login shell.
2192 .It Ic default-terminal Ar terminal
2193 Set the default terminal for new windows created in this session - the
2194 default value of the
2196 environment variable.
2199 to work correctly, this
2203 or a derivative of it.
2204 .It Xo Ic destroy-unattached
2207 If enabled and the session is no longer attached to any clients, it is
2209 .It Xo Ic detach-on-destroy
2212 If on (the default), the client is detached when the session it is attached to
2214 If off, the client is switched to the most recently active of the remaining
2216 .It Ic display-panes-active-colour Ar colour
2217 Set the colour used by the
2219 command to show the indicator for the active pane.
2220 .It Ic display-panes-colour Ar colour
2221 Set the colour used by the
2223 command to show the indicators for inactive panes.
2224 .It Ic display-panes-time Ar time
2225 Set the time in milliseconds for which the indicators shown by the
2228 .It Ic display-time Ar time
2229 Set the amount of time for which status line messages and other on-screen
2230 indicators are displayed.
2233 .It Ic history-limit Ar lines
2234 Set the maximum number of lines held in window history.
2235 This setting applies only to new windows - existing window histories are not
2236 resized and retain the limit at the point they were created.
2237 .It Ic lock-after-time Ar number
2238 Lock the session (like the
2242 seconds of inactivity, or the entire server (all sessions) if the
2245 The default is not to lock (set to 0).
2246 .It Ic lock-command Ar shell-command
2247 Command to run when locking each client.
2248 The default is to run
2252 .It Xo Ic lock-server
2258 instead of each session locking individually as each has been
2260 .Ic lock-after-time ,
2261 the entire server will lock after
2263 sessions would have locked.
2264 This has no effect as a session option; it must be set as a global option.
2265 .It Ic message-attr Ar attributes
2266 Set status line message attributes, where
2270 or a comma-delimited list of one or more of:
2281 .It Ic message-bg Ar colour
2282 Set status line message background colour, where
2293 aixterm bright variants (if supported:
2300 from the 256-colour set,
2302 or a hexadecimal RGB string such as
2304 which chooses the closest match from the default 256-colour set.
2305 .It Ic message-command-attr Ar attributes
2306 Set status line message attributes when in command mode.
2307 .It Ic message-command-bg Ar colour
2308 Set status line message background colour when in command mode.
2309 .It Ic message-command-fg Ar colour
2310 Set status line message foreground colour when in command mode.
2311 .It Ic message-fg Ar colour
2312 Set status line message foreground colour.
2313 .It Ic message-limit Ar number
2314 Set the number of error or information messages to save in the message log for
2317 .It Xo Ic mouse-resize-pane
2322 captures the mouse and allows panes to be resized by dragging on their borders.
2323 .It Xo Ic mouse-select-pane
2328 captures the mouse and when a window is split into multiple panes the mouse may
2329 be used to select the current pane.
2330 The mouse click is also passed through to the application as normal.
2331 .It Xo Ic mouse-select-window
2334 If on, clicking the mouse on a window name in the status line will select that
2336 .It Xo Ic mouse-utf8
2339 If enabled, request mouse input as UTF-8 on UTF-8 terminals.
2340 .It Ic pane-active-border-bg Ar colour
2341 .It Ic pane-active-border-fg Ar colour
2342 Set the pane border colour for the currently active pane.
2343 .It Ic pane-border-bg Ar colour
2344 .It Ic pane-border-fg Ar colour
2345 Set the pane border colour for panes aside from the active pane.
2346 .It Ic prefix Ar key
2347 Set the key accepted as a prefix key.
2348 .It Ic prefix2 Ar key
2349 Set a secondary key accepted as a prefix key.
2350 .It Xo Ic renumber-windows
2353 If on, when a window is closed in a session, automatically renumber the other
2354 windows in numerical order.
2357 option if it has been set.
2358 If off, do not renumber the windows.
2359 .It Ic repeat-time Ar time
2360 Allow multiple commands to be entered without pressing the prefix-key again
2363 milliseconds (the default is 500).
2364 Whether a key repeats may be set when it is bound using the
2368 Repeat is enabled for the default keys bound to the
2371 .It Xo Ic set-remain-on-exit
2376 window option for any windows first created in this session.
2377 When this option is true, windows in which the running program has
2378 exited do not close, instead remaining open but inactivate.
2381 command to reactivate such a window, or the
2383 command to destroy it.
2384 .It Xo Ic set-titles
2387 Attempt to set the client terminal title using the
2392 entries if they exist.
2394 automatically sets these to the \ee]2;...\e007 sequence if
2395 the terminal appears to be an xterm.
2396 This option is off by default.
2398 will only attempt to set the window title if the STY environment
2400 .It Ic set-titles-string Ar string
2401 String used to set the window title if
2404 Character sequences are replaced as for the
2410 Show or hide the status line.
2411 .It Ic status-attr Ar attributes
2412 Set status line attributes.
2413 .It Ic status-bg Ar colour
2414 Set status line background colour.
2415 .It Ic status-fg Ar colour
2416 Set status line foreground colour.
2417 .It Ic status-interval Ar interval
2418 Update the status bar every
2421 By default, updates will occur every 15 seconds.
2422 A setting of zero disables redrawing at interval.
2423 .It Xo Ic status-justify
2424 .Op Ic left | centre | right
2426 Set the position of the window list component of the status line: left, centre
2428 .It Xo Ic status-keys
2431 Use vi or emacs-style
2432 key bindings in the status line, for example at the command prompt.
2433 The default is emacs, unless the
2437 environment variables are set and contain the string
2439 .It Ic status-left Ar string
2442 (by default the session name) to the left of the status bar.
2444 will be passed through
2449 It may also contain any of the following special character sequences:
2450 .Bl -column "Character pair" "Replaced with" -offset indent
2451 .It Sy "Character pair" Ta Sy "Replaced with"
2452 .It Li "#(shell-command)" Ta "First line of the command's output"
2453 .It Li "#[attributes]" Ta "Colour or attribute change"
2454 .It Li "##" Ta "A literal" Ql #
2457 The #(shell-command) form executes
2459 and inserts the first line of its output.
2460 Note that shell commands are only executed once at the interval specified by
2463 option: if the status line is redrawn in the meantime, the previous result is
2465 Shell commands are executed with the
2467 global environment set (see the
2471 For details on how the names and titles can be set see the
2472 .Sx "NAMES AND TITLES"
2475 #[attributes] allows a comma-separated list of attributes to be specified,
2478 to set the foreground colour,
2480 to set the background colour, the name of one of the attributes (listed under
2483 option) to turn an attribute on, or an attribute prefixed with
2485 to turn one off, for example
2488 .Bd -literal -offset indent
2489 #(sysctl vm.loadavg)
2490 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2493 Where appropriate, special character sequences may be prefixed with a number to
2494 specify the maximum length, for example
2497 By default, UTF-8 in
2499 is not interpreted, to enable UTF-8, use the
2502 .It Ic status-left-attr Ar attributes
2503 Set the attribute of the left part of the status line.
2504 .It Ic status-left-bg Ar colour
2505 Set the background colour of the left part of the status line.
2506 .It Ic status-left-fg Ar colour
2507 Set the foreground colour of the left part of the status line.
2508 .It Ic status-left-length Ar length
2511 of the left component of the status bar.
2513 .It Xo Ic status-position
2516 Set the position of the status line.
2517 .It Ic status-right Ar string
2520 to the right of the status bar.
2521 By default, the current window title in double quotes, the date and the time
2528 character pairs are replaced, and UTF-8 is dependent on the
2531 .It Ic status-right-attr Ar attributes
2532 Set the attribute of the right part of the status line.
2533 .It Ic status-right-bg Ar colour
2534 Set the background colour of the right part of the status line.
2535 .It Ic status-right-fg Ar colour
2536 Set the foreground colour of the right part of the status line.
2537 .It Ic status-right-length Ar length
2540 of the right component of the status bar.
2542 .It Xo Ic status-utf8
2547 to treat top-bit-set characters in the
2551 strings as UTF-8; notably, this is important for wide characters.
2552 This option defaults to off.
2553 .It Ic terminal-overrides Ar string
2554 Contains a list of entries which override terminal descriptions read using
2557 is a comma-separated list of items each a colon-separated string made up of a
2558 terminal type pattern (matched using
2564 For example, to set the
2569 for all terminal types and the
2575 terminal type, the option could be set to the string:
2576 .Bd -literal -offset indent
2577 "*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
2580 The terminal entry value is passed through
2582 before interpretation.
2583 The default value forcibly corrects the
2585 entry for terminals which support 88 or 256 colours:
2586 .Bd -literal -offset indent
2587 "*88col*:colors=88,*256col*:colors=256,xterm*:XT"
2589 .It Ic update-environment Ar variables
2590 Set a space-separated string containing a list of environment variables to be
2591 copied into the session environment when a new session is created or an
2592 existing session is attached.
2593 Any variables that do not exist in the source environment are set to be
2594 removed from the session environment (as if
2600 "DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID
2602 .It Xo Ic visual-activity
2605 If on, display a status line message when activity occurs in a window
2607 .Ic monitor-activity
2608 window option is enabled.
2609 .It Xo Ic visual-bell
2612 If this option is on, a message is shown on a bell instead of it being passed
2613 through to the terminal (which normally makes a sound).
2617 .It Xo Ic visual-content
2621 .Ic visual-activity ,
2622 display a message when content is present in a window
2625 window option is enabled.
2626 .It Xo Ic visual-silence
2631 is enabled, prints a message after the interval has expired on a given window.
2632 .It Ic word-separators Ar string
2633 Sets the session's conception of what characters are considered word
2634 separators, for the purposes of the next and previous word commands in
2639 .It Xo Ic set-window-option
2641 .Op Fl t Ar target-window
2644 .D1 (alias: Ic setw )
2645 Set a window option.
2653 flags work similarly to the
2657 Supported window options are:
2659 .Bl -tag -width Ds -compact
2660 .It Xo Ic aggressive-resize
2663 Aggressively resize the chosen window.
2666 will resize the window to the size of the smallest session for which it is the
2667 current window, rather than the smallest session to which it is attached.
2668 The window may resize when the current window is changed on another sessions;
2669 this option is good for full-screen programs which support
2671 and poor for interactive programs such as shells.
2673 .It Xo Ic allow-rename
2676 Allow programs to change the window name using a terminal escape
2677 sequence (\\033k...\\033\\\\).
2680 .It Xo Ic alternate-screen
2683 This option configures whether programs running inside
2685 may use the terminal alternate screen feature, which allows the
2691 The alternate screen feature preserves the contents of the window when an
2692 interactive application starts and restores it on exit, so that any output
2693 visible before the application starts reappears unchanged after it exits.
2696 .It Xo Ic automatic-rename
2699 Control automatic window renaming.
2700 When this setting is enabled,
2702 will rename the window automatically using the format specified by
2703 .Ic automatic-rename-format .
2704 This flag is automatically disabled for an individual window when a name
2705 is specified at creation with
2711 or with a terminal escape sequence.
2712 It may be switched off globally with:
2713 .Bd -literal -offset indent
2714 set-window-option -g automatic-rename off
2717 .It Ic automatic-rename-format Ar format
2721 .Ic automatic-rename
2724 .It Ic c0-change-interval Ar interval
2725 .It Ic c0-change-trigger Ar trigger
2726 These two options configure a simple form of rate limiting for a pane.
2731 C0 sequences that modify the screen (for example, carriage returns, linefeeds
2732 or backspaces) in one millisecond, it will stop updating the pane immediately and
2733 instead redraw it entirely every
2736 This helps to prevent fast output (such as
2738 overwhelming the terminal).
2739 The default is a trigger of 250 and an interval of 100.
2740 A trigger of zero disables the rate limiting.
2742 .It Ic clock-mode-colour Ar colour
2745 .It Xo Ic clock-mode-style
2748 Set clock hour format.
2750 .It Ic force-height Ar height
2751 .It Ic force-width Ar width
2754 from resizing a window to greater than
2758 A value of zero restores the default unlimited setting.
2760 .It Ic main-pane-height Ar height
2761 .It Ic main-pane-width Ar width
2762 Set the width or height of the main (left or top) pane in the
2768 .It Ic mode-attr Ar attributes
2769 Set window modes attributes.
2771 .It Ic mode-bg Ar colour
2772 Set window modes background colour.
2774 .It Ic mode-fg Ar colour
2775 Set window modes foreground colour.
2780 Use vi or emacs-style key bindings in copy and choice modes.
2783 option, the default is emacs, unless
2790 .It Xo Ic mode-mouse
2791 .Op Ic on | off | copy-mode
2793 Mouse state in modes.
2794 If on, the mouse may be used to enter copy mode and copy a selection by
2795 dragging, to enter copy mode and scroll with the mouse wheel, or to select an
2796 option in choice mode.
2799 the mouse behaves as set to on, but cannot be used to enter copy
2802 .It Xo Ic monitor-activity
2805 Monitor for activity in the window.
2806 Windows with activity are highlighted in the status line.
2808 .It Ic monitor-content Ar match-string
2809 Monitor content in the window.
2814 appears in the window, it is highlighted in the status line.
2816 .It Xo Ic monitor-silence
2819 Monitor for silence (no activity) in the window within
2822 Windows that have been silent for the interval are highlighted in the
2824 An interval of zero disables the monitoring.
2826 .It Ic other-pane-height Ar height
2827 Set the height of the other panes (not the main pane) in the
2830 If this option is set to 0 (the default), it will have no effect.
2832 .Ic main-pane-height
2834 .Ic other-pane-height
2835 options are set, the main pane will grow taller to make the other panes the
2836 specified height, but will never shrink to do so.
2838 .It Ic other-pane-width Ar width
2840 .Ic other-pane-height ,
2841 but set the width of other panes in the
2845 .It Ic pane-base-index Ar index
2848 but set the starting index for pane numbers.
2850 .It Xo Ic remain-on-exit
2853 A window with this flag set is not destroyed when the program running in it
2855 The window may be reactivated with the
2859 .It Xo Ic synchronize-panes
2862 Duplicate input to any pane to all other panes in the same window (only
2863 for panes that are not in any special mode).
2870 to expect UTF-8 sequences to appear in this window.
2872 .It Ic window-status-bell-attr Ar attributes
2873 Set status line attributes for windows which have a bell alert.
2875 .It Ic window-status-bell-bg Ar colour
2876 Set status line background colour for windows with a bell alert.
2878 .It Ic window-status-bell-fg Ar colour
2879 Set status line foreground colour for windows with a bell alert.
2881 .It Ic window-status-content-attr Ar attributes
2882 Set status line attributes for windows which have a content alert.
2884 .It Ic window-status-content-bg Ar colour
2885 Set status line background colour for windows with a content alert.
2887 .It Ic window-status-content-fg Ar colour
2888 Set status line foreground colour for windows with a content alert.
2890 .It Ic window-status-activity-attr Ar attributes
2891 Set status line attributes for windows which have an activity (or silence) alert.
2893 .It Ic window-status-activity-bg Ar colour
2894 Set status line background colour for windows with an activity alert.
2896 .It Ic window-status-activity-fg Ar colour
2897 Set status line foreground colour for windows with an activity alert.
2899 .It Ic window-status-attr Ar attributes
2900 Set status line attributes for a single window.
2902 .It Ic window-status-bg Ar colour
2903 Set status line background colour for a single window.
2905 .It Ic window-status-current-attr Ar attributes
2906 Set status line attributes for the currently active window.
2908 .It Ic window-status-current-bg Ar colour
2909 Set status line background colour for the currently active window.
2911 .It Ic window-status-current-fg Ar colour
2912 Set status line foreground colour for the currently active window.
2914 .It Ic window-status-current-format Ar string
2916 .Ar window-status-format ,
2917 but is the format used when the window is the current window.
2919 .It Ic window-status-last-attr Ar attributes
2920 Set status line attributes for the last active window.
2922 .It Ic window-status-last-bg Ar colour
2923 Set status line background colour for the last active window.
2925 .It Ic window-status-last-fg Ar colour
2926 Set status line foreground colour for the last active window.
2928 .It Ic window-status-fg Ar colour
2929 Set status line foreground colour for a single window.
2931 .It Ic window-status-format Ar string
2932 Set the format in which the window is displayed in the status line window list.
2935 option for details of special character sequences available.
2939 .It Ic window-status-separator Ar string
2940 Sets the separator drawn between windows in the status line.
2941 The default is a single space character.
2943 .It Xo Ic xterm-keys
2946 If this option is set,
2950 function key sequences; these have a number included to indicate modifiers such
2951 as Shift, Alt or Ctrl.
2954 .It Xo Ic wrap-search
2957 If this option is set, searches will wrap around the end of the pane contents.
2960 .It Xo Ic show-options
2962 .Op Fl t Ar target-session | Ar target-window
2965 .D1 (alias: Ic show )
2966 Show the window options (or a single window option if given) with
2969 .Ic show-window-options ) ,
2970 the server options with
2972 otherwise the session options for
2973 .Ar target session .
2974 Global session or window options are listed if
2978 shows only the option value, not the name.
2981 is set, no error will be returned if
2984 .It Xo Ic show-window-options
2986 .Op Fl t Ar target-window
2989 .D1 (alias: Ic showw )
2990 List the window options or a single option for
2992 or the global window options if
2996 shows only the option value, not the name.
2999 Certain commands accept the
3004 This is a string which controls the output format of the command.
3005 Replacement variables are enclosed in
3010 .Ql #{session_name} .
3011 Some variables also have an shorter alias such as
3013 Conditionals are also accepted by prefixing with
3015 and separating two alternatives with a comma;
3016 if the specified variable exists and is not zero, the first alternative
3017 is chosen, otherwise the second is used.
3019 .Ql #{?session_attached,attached,not attached}
3020 will include the string
3022 if the session is attached and the string
3024 if it is unattached.
3025 A limit may be placed on the length of the resultant string by prefixing it
3028 a number and a colon, so
3029 .Ql #{=10:pane_title}
3030 will include at most the first 10 characters of the pane title.
3032 The following variables are available, where appropriate:
3033 .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
3034 .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
3035 .It Li "alternate_on" Ta "" Ta "If pane is in alternate screen"
3036 .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
3037 .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
3038 .It Li "buffer_sample" Ta "" Ta "First 50 characters from buffer"
3039 .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
3040 .It Li "client_activity" Ta "" Ta "Integer time client last had activity"
3041 .It Li "client_activity_string" Ta "" Ta "String time client last had activity"
3042 .It Li "client_created" Ta "" Ta "Integer time client created"
3043 .It Li "client_created_string" Ta "" Ta "String time client created"
3044 .It Li "client_height" Ta "" Ta "Height of client"
3045 .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
3046 .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
3047 .It Li "client_readonly" Ta "" Ta "1 if client is readonly"
3048 .It Li "client_session" Ta "" Ta "Name of the client's session"
3049 .It Li "client_termname" Ta "" Ta "Terminal name of client"
3050 .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
3051 .It Li "client_utf8" Ta "" Ta "1 if client supports utf8"
3052 .It Li "client_width" Ta "" Ta "Width of client"
3053 .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
3054 .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
3055 .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
3056 .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
3057 .It Li "history_limit" Ta "" Ta "Maximum window history lines"
3058 .It Li "history_size" Ta "" Ta "Size of history in bytes"
3059 .It Li "host" Ta "#H" Ta "Hostname of local host"
3060 .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
3061 .It Li "insert_flag" Ta "" Ta "Pane insert flag"
3062 .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
3063 .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
3064 .It Li "line" Ta "" Ta "Line number in the list"
3065 .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
3066 .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
3067 .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
3068 .It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag"
3069 .It Li "pane_active" Ta "" Ta "1 if active pane"
3070 .It Li "pane_current_command" Ta "" Ta "Current command if available"
3071 .It Li "pane_current_path" Ta "" Ta "Current path if available"
3072 .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
3073 .It Li "pane_height" Ta "" Ta "Height of pane"
3074 .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
3075 .It Li "pane_in_mode" Ta "" Ta "If pane is in a mode"
3076 .It Li "pane_synchronized" Ta "" Ta "If pane is synchronized"
3077 .It Li "pane_index" Ta "#P" Ta "Index of pane"
3078 .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
3079 .It Li "pane_start_command" Ta "" Ta "Command pane started with"
3080 .It Li "pane_start_path" Ta "" Ta "Path pane started with"
3081 .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
3082 .It Li "pane_title" Ta "#T" Ta "Title of pane"
3083 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
3084 .It Li "pane_width" Ta "" Ta "Width of pane"
3085 .It Li "saved_cursor_x" Ta "" Ta "Saved cursor X in pane"
3086 .It Li "saved_cursor_y" Ta "" Ta "Saved cursor Y in pane"
3087 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
3088 .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
3089 .It Li "session_attached" Ta "" Ta "1 if session attached"
3090 .It Li "session_created" Ta "" Ta "Integer time session created"
3091 .It Li "session_created_string" Ta "" Ta "String time session created"
3092 .It Li "session_group" Ta "" Ta "Number of session group"
3093 .It Li "session_grouped" Ta "" Ta "1 if session in a group"
3094 .It Li "session_height" Ta "" Ta "Height of session"
3095 .It Li "session_id" Ta "" Ta "Unique session ID"
3096 .It Li "session_name" Ta "#S" Ta "Name of session"
3097 .It Li "session_width" Ta "" Ta "Width of session"
3098 .It Li "session_windows" Ta "" Ta "Number of windows in session"
3099 .It Li "window_active" Ta "" Ta "1 if window active"
3100 .It Li "window_activity_flag" Ta "" Ta "1 if window has activity alert"
3101 .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
3102 .It Li "window_content_flag" Ta "" Ta "1 if window has content alert"
3103 .It Li "window_find_matches" Ta "" Ta "Matched data from the find-window"
3104 .It Li "window_flags" Ta "#F" Ta "Window flags"
3105 .It Li "window_height" Ta "" Ta "Height of window"
3106 .It Li "window_id" Ta "" Ta "Unique window ID"
3107 .It Li "window_index" Ta "#I" Ta "Index of window"
3108 .It Li "window_layout" Ta "" Ta "Window layout description"
3109 .It Li "window_name" Ta "#W" Ta "Name of window"
3110 .It Li "window_panes" Ta "" Ta "Number of panes in window"
3111 .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
3112 .It Li "window_width" Ta "" Ta "Width of window"
3113 .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
3115 .Sh NAMES AND TITLES
3117 distinguishes between names and titles.
3118 Windows and sessions have names, which may be used to specify them in targets
3119 and are displayed in the status line and various lists: the name is the
3121 identifier for a window or session.
3122 Only panes have titles.
3123 A pane's title is typically set by the program running inside the pane and
3126 It is the same mechanism used to set for example the
3131 Windows themselves do not have titles - a window's title is the title of its
3134 itself may set the title of the terminal in which the client is running, see
3139 A session's name is set with the
3144 A window's name is set with one of:
3147 A command argument (such as
3155 .Bd -literal -offset indent
3156 $ printf '\e033kWINDOW_NAME\e033\e\e'
3159 Automatic renaming, which sets the name to the active command in the window's
3162 .Ic automatic-rename
3166 When a pane is first created, its title is the hostname.
3167 A pane's title can be set via the OSC title setting sequence, for example:
3168 .Bd -literal -offset indent
3169 $ printf '\e033]2;My Title\e033\e\e'
3172 When the server is started,
3174 copies the environment into the
3175 .Em global environment ;
3176 in addition, each session has a
3177 .Em session environment .
3178 When a window is created, the session and global environments are merged.
3179 If a variable exists in both, the value from the session environment is used.
3180 The result is the initial environment passed to the new process.
3183 .Ic update-environment
3184 session option may be used to update the session environment from the client
3185 when a new session is created or an old reattached.
3187 also initialises the
3189 variable with some internal information to allow commands to be executed
3190 from inside, and the
3192 variable with the correct terminal setting of
3195 Commands to alter and view the environment are:
3197 .It Xo Ic set-environment
3199 .Op Fl t Ar target-session
3200 .Ar name Op Ar value
3202 .D1 (alias: Ic setenv )
3203 Set or unset an environment variable.
3206 is used, the change is made in the global environment; otherwise, it is applied
3207 to the session environment for
3208 .Ar target-session .
3211 flag unsets a variable.
3213 indicates the variable is to be removed from the environment before starting a
3215 .It Xo Ic show-environment
3217 .Op Fl t Ar target-session
3220 .D1 (alias: Ic showenv )
3221 Display the environment for
3223 or the global environment with
3227 is omitted, all variables are shown.
3228 Variables removed from the environment are prefixed with
3233 includes an optional status line which is displayed in the bottom line of each
3235 By default, the status line is enabled (it may be disabled with the
3237 session option) and contains, from left-to-right: the name of the current
3238 session in square brackets; the window list; the title of the active pane
3239 in double quotes; and the time and date.
3241 The status line is made of three parts: configurable left and right sections
3242 (which may contain dynamic content such as the time or output from a shell
3245 .Ic status-left-length ,
3248 .Ic status-right-length
3249 options below), and a central window list.
3250 By default, the window list shows the index, name and (if any) flag of the
3251 windows present in the current session in ascending numerical order.
3252 It may be customised with the
3253 .Ar window-status-format
3255 .Ar window-status-current-format
3257 The flag is one of the following symbols appended to the window name:
3258 .Bl -column "Symbol" "Meaning" -offset indent
3259 .It Sy "Symbol" Ta Sy "Meaning"
3260 .It Li "*" Ta "Denotes the current window."
3261 .It Li "-" Ta "Marks the last window (previously selected)."
3262 .It Li "#" Ta "Window is monitored and activity has been detected."
3263 .It Li "!" Ta "A bell has occurred in the window."
3264 .It Li "+" Ta "Window is monitored for content and it has appeared."
3265 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
3266 .It Li "Z" Ta "The window's active pane is zoomed."
3269 The # symbol relates to the
3270 .Ic monitor-activity
3274 The window name is printed in inverted colours if an alert (bell, activity or
3275 content) is present.
3277 The colour and attributes of the status line may be configured, the entire
3278 status line using the
3283 session options and individual windows using the
3284 .Ic window-status-attr ,
3285 .Ic window-status-fg
3287 .Ic window-status-bg
3290 The status line is automatically refreshed at interval if it has changed, the
3291 interval may be controlled with the
3295 Commands related to the status line are as follows:
3297 .It Xo Ic command-prompt
3300 .Op Fl t Ar target-client
3303 Open the command prompt in a client.
3304 This may be used from inside
3306 to execute commands interactively.
3310 is specified, it is used as the command.
3313 is a comma-separated list of the initial text for each prompt.
3318 is a comma-separated list of prompts which are displayed in order; otherwise
3319 a single prompt is displayed, constructed from
3321 if it is present, or
3329 may contain the special character sequences supported by the
3333 Before the command is executed, the first occurrence of the string
3335 and all occurrences of
3337 are replaced by the response to the first prompt, the second
3341 are replaced with the response to the second prompt, and so on for further
3343 Up to nine prompt responses may be replaced
3349 .It Xo Ic confirm-before
3351 .Op Fl t Ar target-client
3354 .D1 (alias: Ic confirm )
3355 Ask for confirmation before executing
3361 is the prompt to display; otherwise a prompt is constructed from
3363 It may contain the special character sequences supported by the
3367 This command works only from inside
3369 .It Xo Ic display-message
3371 .Op Fl c Ar target-client
3372 .Op Fl t Ar target-pane
3375 .D1 (alias: Ic display )
3379 is given, the output is printed to stdout, otherwise it is displayed in the
3386 section; information is taken from
3390 is given, otherwise the active pane for the session attached to
3395 maintains a stack of
3397 Up to the value of the
3399 option are kept; when a new buffer is added, the buffer at the bottom of the
3401 Buffers may be added using
3405 command, and pasted into a window using the
3409 A configurable history buffer is also maintained for each window.
3410 By default, up to 2000 lines are kept; this can be altered with the
3416 The buffer commands are as follows:
3421 .Op Fl t Ar target-window
3424 Put a window into buffer choice mode, where a buffer may be chosen
3425 interactively from a list.
3426 After a buffer is selected,
3428 is replaced by the buffer index in
3430 and the result executed as a command.
3433 is not given, "paste-buffer -b '%%'" is used.
3434 For the meaning of the
3439 This command works only if at least one client is attached.
3440 .It Ic clear-history Op Fl t Ar target-pane
3441 .D1 (alias: Ic clearhist )
3442 Remove and free the history for the specified pane.
3443 .It Ic delete-buffer Op Fl b Ar buffer-index
3444 .D1 (alias: Ic deleteb )
3445 Delete the buffer at
3447 or the top buffer if not specified.
3448 .It Xo Ic list-buffers
3451 .D1 (alias: Ic lsb )
3452 List the global buffers.
3453 For the meaning of the
3458 .It Xo Ic load-buffer
3459 .Op Fl b Ar buffer-index
3462 .D1 (alias: Ic loadb )
3463 Load the contents of the specified paste buffer from
3465 .It Xo Ic paste-buffer
3467 .Op Fl b Ar buffer-index
3468 .Op Fl s Ar separator
3469 .Op Fl t Ar target-pane
3471 .D1 (alias: Ic pasteb )
3472 Insert the contents of a paste buffer into the specified pane.
3473 If not specified, paste into the current one.
3476 also delete the paste buffer from the stack.
3477 When output, any linefeed (LF) characters in the paste buffer are replaced with
3478 a separator, by default carriage return (CR).
3479 A custom separator may be specified using the
3484 flag means to do no replacement (equivalent to a separator of LF).
3487 is specified, paste bracket control codes are inserted around the
3488 buffer if the application has requested bracketed paste mode.
3489 .It Xo Ic save-buffer
3491 .Op Fl b Ar buffer-index
3494 .D1 (alias: Ic saveb )
3495 Save the contents of the specified paste buffer to
3499 option appends to rather than overwriting the file.
3500 .It Xo Ic set-buffer
3501 .Op Fl b Ar buffer-index
3504 .D1 (alias: Ic setb )
3505 Set the contents of the specified buffer to
3507 .It Xo Ic show-buffer
3508 .Op Fl b Ar buffer-index
3510 .D1 (alias: Ic showb )
3511 Display the contents of the specified buffer.
3514 Miscellaneous commands are as follows:
3516 .It Ic clock-mode Op Fl t Ar target-pane
3517 Display a large clock.
3520 .Op Fl t Ar target-pane
3521 .Ar shell-command command
3529 returns success or the second
3532 Before being executed, shell-command is expanded using the rules specified in the
3534 section, including those relevant to
3539 is run in the background.
3541 .D1 (alias: Ic lock )
3542 Lock each client individually by running the command specified by the
3547 .Op Fl t Ar target-pane
3550 .D1 (alias: Ic run )
3553 in the background without creating a window.
3554 Before being executed, shell-command is expanded using the rules specified in
3560 the command is run in the background.
3561 After it finishes, any output to stdout is displayed in copy mode (in the pane
3564 or the current pane if omitted).
3565 If the command doesn't return success, the exit status is also displayed.
3567 .D1 (alias: Ic info )
3568 Show server information and terminal details.
3573 .D1 (alias: Ic wait )
3574 When used without options, prevents the client from exiting until woken using
3577 with the same channel.
3580 is used, the channel is locked and any clients that try to lock the same
3581 channel are made to wait until the channel is unlocked with
3584 This command only works from outside
3587 .Sh TERMINFO EXTENSIONS
3589 understands some extensions to
3593 Set the cursor colour.
3594 The first takes a single string argument and is used to set the colour;
3595 the second takes no arguments and restores the default cursor colour.
3596 If set, a sequence such as this may be used
3597 to change the cursor colour from inside
3599 .Bd -literal -offset indent
3600 $ printf '\e033]12;red\e033\e\e'
3603 Change the cursor style.
3604 If set, a sequence such as this may be used
3605 to change the cursor to an underline:
3606 .Bd -literal -offset indent
3607 $ printf '\e033[4 q'
3612 is set, it will be used to reset the cursor style instead
3616 This sequence can be used by
3618 to store the current buffer in the host terminal's selection (clipboard).
3621 option above and the
3627 offers a textual interface called
3629 This allows applications to communicate with
3631 using a simple text-only protocol.
3633 In control mode, a client sends
3635 commands or command sequences terminated by newlines on standard input.
3636 Each command will produce one block of output on standard output.
3637 An output block consists of a
3639 line followed by the output (which may be empty).
3640 The output block ends with a
3649 have two arguments: an integer time (as seconds from epoch) and command number.
3651 .Bd -literal -offset indent
3653 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
3659 outputs notifications.
3660 A notification will never occur inside an output block.
3662 The following notifications are defined:
3664 .It Ic %exit Op Ar reason
3667 client is exiting immediately, either because it is not attached to any session
3668 or an error occurred.
3671 describes why the client exited.
3672 .It Ic %layout-change Ar window-id Ar window-layout
3673 The layout of a window with ID
3678 .It Ic %output Ar pane-id Ar value
3679 A window pane produced output.
3681 escapes non-printable characters and backslash as octal \\xxx.
3682 .It Ic %session-changed Ar session-id Ar name
3683 The client is now attached to the session with ID
3687 .It Ic %session-renamed Ar name
3688 The current session was renamed to
3690 .It Ic %sessions-changed
3691 A session was created or destroyed.
3692 .It Ic %unlinked-window-add Ar window-id
3695 was created but is not linked to the current session.
3696 .It Ic %window-add Ar window-id
3699 was linked to the current session.
3700 .It Ic %window-close Ar window-id
3704 .It Ic %window-renamed Ar window-id Ar name
3711 .Bl -tag -width "/etc/tmux.confXXX" -compact
3716 .It Pa /etc/tmux.conf
3717 System-wide configuration file.
3725 .Dl $ tmux new-session vi
3727 Most commands have a shorter form, known as an alias.
3728 For new-session, this is
3733 Alternatively, the shortest unambiguous form of a command is accepted.
3734 If there are several options, they are listed:
3735 .Bd -literal -offset indent
3737 ambiguous command: n, could be: new-session, new-window, next-window
3740 Within an active session, a new window may be created by typing
3750 Windows may be navigated with:
3752 (to select window 0),
3754 (to select window 1), and so on;
3756 to select the next window; and
3758 to select the previous window.
3760 A session may be detached using
3762 (or by an external event such as
3764 disconnection) and reattached with:
3766 .Dl $ tmux attach-session
3770 lists the current key bindings in the current window; up and down may be used
3771 to navigate the list or
3775 Commands to be run when the
3777 server is started may be placed in the
3780 Common examples include:
3782 Changing the default prefix key:
3783 .Bd -literal -offset indent
3784 set-option -g prefix C-a
3786 bind-key C-a send-prefix
3789 Turning the status line off, or changing its colour:
3790 .Bd -literal -offset indent
3791 set-option -g status off
3792 set-option -g status-bg blue
3795 Setting other options, such as the default command,
3796 or locking after 30 minutes of inactivity:
3797 .Bd -literal -offset indent
3798 set-option -g default-command "exec /bin/ksh"
3799 set-option -g lock-after-time 1800
3802 Creating new key bindings:
3803 .Bd -literal -offset indent
3804 bind-key b set-option status
3805 bind-key / command-prompt "split-window 'exec man %%'"
3806 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3811 .An Nicholas Marriott Aq Mt nicm@users.sourceforge.net