Plug memory leak, from Tiago Cunha.
[tmux-openbsd.git] / tmux.1
blobfa6303213f9d13d798731ffa3f1549fcf684bd5f
1 .\" $OpenBSD$
2 .\"
3 .\" Copyright (c) 2007 Nicholas Marriott <nicm@users.sourceforge.net>
4 .\"
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.
8 .\"
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.
16 .\"
17 .Dd $Mdocdate$
18 .Dt TMUX 1
19 .Os
20 .Sh NAME
21 .Nm tmux
22 .Nd terminal multiplexer
23 .Sh SYNOPSIS
24 .Nm tmux
25 .Bk -words
26 .Op Fl 28lquv
27 .Op Fl c Ar shell-command
28 .Op Fl f Ar file
29 .Op Fl L Ar socket-name
30 .Op Fl S Ar socket-path
31 .Op Ar command Op Ar flags
32 .Ek
33 .Sh DESCRIPTION
34 .Nm
35 is a terminal multiplexer:
36 it enables a number of terminals to be created, accessed, and
37 controlled from a single screen.
38 .Nm
39 may be detached from a screen
40 and continue running in the background,
41 then later reattached.
42 .Pp
43 When
44 .Nm
45 is started it creates a new
46 .Em session
47 with a single
48 .Em window
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.
53 .Pp
54 A session is a single collection of
55 .Em pseudo terminals
56 under the management of
57 .Nm .
58 Each session has one or more
59 windows linked to it.
60 A window occupies the entire screen
61 and may be split into rectangular panes,
62 each of which is a separate pseudo terminal
63 (the
64 .Xr pty 4
65 manual page documents the technical details of pseudo terminals).
66 Any number of
67 .Nm
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,
71 .Nm
72 exits.
73 .Pp
74 Each session is persistent and will survive accidental disconnection
75 (such as
76 .Xr ssh 1
77 connection timeout) or intentional detaching (with the
78 .Ql C-b d
79 key strokes).
80 .Nm
81 may be reattached using:
82 .Pp
83 .Dl $ tmux attach
84 .Pp
86 .Nm ,
87 a session is displayed on screen by a
88 .Em client
89 and all sessions are managed by a single
90 .Em server .
91 The server and each client are separate processes which communicate through a
92 socket in
93 .Pa /tmp .
94 .Pp
95 The options are as follows:
96 .Bl -tag -width "XXXXXXXXXXXX"
97 .It Fl 2
98 Force
99 .Nm
100 to assume the terminal supports 256 colours.
101 .It Fl 8
102 Like
103 .Fl 2 ,
104 but indicates that the terminal supports 88 colours.
105 .It Fl c Ar shell-command
106 Execute
107 .Ar shell-command
108 using the default shell.
109 If necessary, the
111 server will be started to retrieve the
112 .Ic default-shell
113 option.
114 This option is for compatibility with
115 .Xr sh 1
116 when
118 is used as a login shell.
119 .It Fl f Ar file
120 Specify an alternative configuration file.
121 By default,
123 loads the system configuration file from
124 .Pa /etc/tmux.conf ,
125 if present, then looks for a user configuration file at
126 .Pa ~/.tmux.conf .
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
137 .Pa /tmp
139 .Ev TMPDIR
140 if set);
141 the default socket is named
142 .Em default .
143 This option allows a different socket name to be specified, allowing several
144 independent
146 servers to be run.
147 Unlike
148 .Fl S
149 a full path is not necessary: the sockets are all created in the same
150 directory.
152 If the socket is accidentally removed, the
153 .Dv SIGUSR1
154 signal may be sent to the
156 server process to recreate it.
157 .It Fl l
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.
161 .It Fl q
162 Set the
163 .Ic quiet
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.
168 .Fl S
169 is specified, the default socket directory is not used and any
170 .Fl L
171 flag is ignored.
172 .It Fl u
174 attempts to guess if the terminal is likely to support UTF-8 by checking the
175 first of the
176 .Ev LC_ALL ,
177 .Ev LC_CTYPE
179 .Ev LANG
180 environment variables to be set for the string "UTF-8".
181 This is not always correct: the
182 .Fl u
183 flag explicitly informs
185 that UTF-8 is supported.
187 If the server is started from a client passed
188 .Fl u
189 or where UTF-8 is detected, the
190 .Ic utf8
192 .Ic status-utf8
193 options are enabled in the global window and session options respectively.
194 .It Fl v
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
202 .Em PID
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
206 .Nm ,
207 as described in the following sections.
208 If no commands are specified, the
209 .Ic new-session
210 command is assumed.
212 .Sh KEY BINDINGS
214 may be controlled from an attached client by using a key combination of a
215 prefix key,
216 .Ql C-b
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
222 .It C-b
223 Send the prefix key (C-b) through to the application.
224 .It C-o
225 Rotate the panes in the current window forwards.
226 .It C-z
227 Suspend the
229 client.
230 .It !
231 Break the current pane out of the window.
232 .It \&"
233 Split the current pane into two, top and bottom.
234 .It #
235 List all paste buffers.
236 .It $
237 Rename the current session.
238 .It %
239 Split the current pane into two, left and right.
240 .It &
241 Kill the current window.
242 .It '
243 Prompt for a window index to select.
244 .It ,
245 Rename the current window.
246 .It -
247 Delete the most recently copied buffer of text.
248 .It .
249 Prompt for an index to move the current window.
250 .It 0 to 9
251 Select windows 0 to 9.
252 .It :
253 Enter the
255 command prompt.
256 .It ;
257 Move to the previously active pane.
258 .It =
259 Choose which buffer to paste interactively from a list.
260 .It \&?
261 List all key bindings.
262 .It D
263 Choose a client to detach.
264 .It \&[
265 Enter copy mode to copy text or view the history.
266 .It \&]
267 Paste the most recently copied buffer of text.
268 .It c
269 Create a new window.
270 .It d
271 Detach the current client.
272 .It f
273 Prompt to search for text in open windows.
274 .It i
275 Display some information about the current window.
276 .It l
277 Move to the previously selected window.
278 .It n
279 Change to the next window.
280 .It o
281 Select the next pane in the current window.
282 .It p
283 Change to the previous window.
284 .It q
285 Briefly display pane indexes.
286 .It r
287 Force redraw of the attached client.
288 .It s
289 Select a new session for the attached client interactively.
290 .It L
291 Switch the attached client back to the last session.
292 .It t
293 Show the time.
294 .It w
295 Choose the current window interactively.
296 .It x
297 Kill the current pane.
298 .It {
299 Swap the current pane with the previous pane.
300 .It }
301 Swap the current pane with the next pane.
302 .It ~
303 Show previous messages from
304 .Nm ,
305 if any.
306 .It Page Up
307 Enter copy mode and scroll one page up.
308 .It Up, Down
309 .It Left, Right
310 Change to the pane above, below, to the left, or to the right of the current
311 pane.
312 .It M-1 to M-5
313 Arrange panes in one of the five preset layouts: even-horizontal,
314 even-vertical, main-horizontal, main-vertical, or tiled.
315 .It M-n
316 Move to the next window with a bell or activity marker.
317 .It M-o
318 Rotate the panes in the current window backwards.
319 .It M-p
320 Move to the previous window with a bell or activity marker.
321 .It C-Up, C-Down
322 .It C-Left, C-Right
323 Resize the current pane in steps of one cell.
324 .It M-Up, M-Down
325 .It M-Left, M-Right
326 Resize the current pane in steps of five cells.
329 Key bindings may be changed with the
330 .Ic bind-key
332 .Ic unbind-key
333 commands.
334 .Sh COMMANDS
335 This section contains a list of the commands supported by
336 .Nm .
337 Most commands accept the optional
338 .Fl t
339 argument with one of
340 .Ar target-client ,
341 .Ar target-session
342 .Ar target-window ,
344 .Ar target-pane .
345 These specify the client, session, window or pane which a command should affect.
346 .Ar target-client
347 is the name of the
348 .Xr pty 4
349 file to which the client is connected, for example either of
350 .Pa /dev/ttyp1
352 .Pa ttyp1
353 for the client attached to
354 .Pa /dev/ttyp1 .
355 If no client is specified, the current client is chosen, if possible, or an
356 error is reported.
357 Clients may be listed with the
358 .Ic list-clients
359 command.
361 .Ar target-session
362 is either the name of a session (as listed by the
363 .Ic list-sessions
364 command) or the name of a client with the same syntax as
365 .Ar target-client ,
366 in which case the session attached to the client is used.
367 When looking for the session name,
369 initially searches for an exact match; if none is found, the session names
370 are checked for any for which
371 .Ar target-session
372 is a prefix or for which it matches as an
373 .Xr fnmatch 3
374 pattern.
375 If a single match is found, it is used as the target session; multiple matches
376 produce an error.
377 If a session is omitted, the current session is used if available; if no
378 current session is available, the most recently used is chosen.
380 .Ar target-window
381 specifies a window in the form
382 .Em session Ns \&: Ns Em window .
383 .Em session
384 follows the same rules as for
385 .Ar target-session ,
387 .Em window
388 is looked for in order: as a window index, for example mysession:1; as an exact
389 window name, such as mysession:mywindow; then as an
390 .Xr fnmatch 3
391 pattern or the start of a window name, such as mysession:mywin* or
392 mysession:mywin.
393 An empty window name specifies the next unused index if appropriate (for
394 example the
395 .Ic new-window
397 .Ic link-window
398 commands)
399 otherwise the current window in
400 .Em session
401 is chosen.
402 The special character
403 .Ql \&!
404 uses the last (previously current) window, or
405 .Ql +
407 .Ql -
408 are the next window or the previous window by number.
409 When the argument does not contain a colon,
411 first attempts to parse it as window; if that fails, an attempt is made to
412 match a session.
414 .Ar target-pane
415 takes a similar form to
416 .Ar target-window
417 but with the optional addition of a period followed by a pane index, for
418 example: mysession:mywindow.1.
419 If the pane index is omitted, the currently active pane in the specified
420 window is used.
421 If neither a colon nor period appears,
423 first attempts to use the argument as a pane index; if that fails, it is looked
424 up as for
425 .Ar target-window .
427 .Ql +
429 .Ql -
430 indicate the next or previous pane index, respectively.
431 One of the strings
432 .Em top ,
433 .Em bottom ,
434 .Em left ,
435 .Em right ,
436 .Em top-left ,
437 .Em top-right ,
438 .Em bottom-left
440 .Em bottom-right
441 may be used instead of a pane index.
443 The special characters
444 .Ql +
446 .Ql -
447 may be followed by an offset, for example:
448 .Bd -literal -offset indent
449 select-window -t:+2
452 When dealing with a session that doesn't contain sequential window indexes,
453 they will be correctly skipped.
456 also gives each pane created in a server an identifier consisting of a
457 .Ql %
458 and a number, starting from zero.
459 A pane's identifier is unique for the life of the
461 server and is passed to the child process of the pane in the
462 .Ev TMUX_PANE
463 environment variable.
464 It may be used alone to target a pane or the window containing it.
466 .Ar shell-command
467 arguments are
468 .Xr sh 1
469 commands.
470 These must be passed as a single item, which typically means quoting them, for
471 example:
472 .Bd -literal -offset indent
473 new-window 'vi /etc/passwd'
476 .Ar command
477 .Op Ar arguments
478 refers to a
480 command, passed with the command and arguments separately, for example:
481 .Bd -literal -offset indent
482 bind-key F1 set-window-option force-width 81
485 Or if using
486 .Xr sh 1 :
487 .Bd -literal -offset indent
488 $ tmux bind-key F1 set-window-option force-width 81
491 Multiple commands may be specified together as part of a
492 .Em command sequence .
493 Each command should be separated by spaces and a semicolon;
494 commands are executed sequentially from left to right and
495 lines ending with a backslash continue on to the next line.
496 A literal semicolon may be included by escaping it with a backslash (for
497 example, when specifying a command sequence to
498 .Ic bind-key ) .
500 Example
502 commands include:
503 .Bd -literal -offset indent
504 refresh-client -t/dev/ttyp2
506 rename-session -tfirst newname
508 set-window-option -t:0 monitor-activity on
510 new-window ; split-window -d
512 bind-key R source-file ~/.tmux.conf \e; \e
513         display-message "source-file done"
516 Or from
517 .Xr sh 1 :
518 .Bd -literal -offset indent
519 $ tmux kill-window -t :1
521 $ tmux new-window \e; split-window -d
523 $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
525 .Sh CLIENTS AND SESSIONS
528 server manages clients, sessions, windows and panes.
529 Clients are attached to sessions to interact with them, either
530 when they are created with the
531 .Ic new-session
532 command, or later with the
533 .Ic attach-session
534 command.
535 Each session has one or more windows
536 .Em linked
537 into it.
538 Windows may be linked to multiple sessions and are made up of one or
539 more panes,
540 each of which contains a pseudo terminal.
541 Commands for creating, linking and otherwise manipulating windows
542 are covered
543 in the
544 .Sx WINDOWS AND PANES
545 section.
547 The following commands are available to manage clients and sessions:
548 .Bl -tag -width Ds
549 .It Xo Ic attach-session
550 .Op Fl dr
551 .Op Fl t Ar target-session
553 .D1 (alias: Ic attach )
554 If run from outside
555 .Nm ,
556 create a new client in the current terminal and attach it to
557 .Ar target-session .
558 If used from inside, switch the current client.
560 .Fl d
561 is specified, any other clients attached to the session are detached.
562 .Fl r
563 signifies the client is read-only (only keys bound to the
564 .Ic detach-client
566 .Ic switch-client
567 commands have any effect)
569 If no server is started,
570 .Ic attach-session
571 will attempt to start it; this will fail unless sessions are created in the
572 configuration file.
575 .Ar target-session
576 rules for
577 .Ic attach-session
578 are slightly adjusted: if
580 needs to select the most recently used session, it will prefer the most
581 recently used
582 .Em unattached
583 session.
584 .It Xo Ic detach-client
585 .Op Fl P
586 .Op Fl s Ar target-session
587 .Op Fl t Ar target-client
589 .D1 (alias: Ic detach )
590 Detach the current client if bound to a key, the client specified with
591 .Fl t ,
592 or all clients currently attached to to the session specified by
593 .Fl s .
595 .Fl P
596 is given, send SIGHUP to the parent process of the client, typically causing it
597 to exit.
598 .It Ic has-session Op Fl t Ar target-session
599 .D1 (alias: Ic has )
600 Report an error and exit with 1 if the specified session does not exist.
601 If it does exist, exit with 0.
602 .It Ic kill-server
603 Kill the
605 server and clients and destroy all sessions.
606 .It Ic kill-session Op Fl t Ar target-session
607 Destroy the given session, closing any windows linked to it and no other
608 sessions, and detaching all clients attached to it.
609 .It Ic list-clients Op Fl t Ar target-session
610 .D1 (alias: Ic lsc )
611 List all clients attached to the server.
613 .Ar target-session
614 is specified, list only clients connected to that session.
615 .It Ic list-commands
616 .D1 (alias: Ic lscm )
617 List the syntax of all commands supported by
618 .Nm .
619 .It Ic list-sessions
620 .Op Fl F Ar format
621 .D1 (alias: Ic ls )
622 List all sessions managed by the server.
623 .It Ic lock-client Op Fl t Ar target-client
624 .D1 (alias: Ic lockc )
625 Lock
626 .Ar target-client ,
627 see the
628 .Ic lock-server
629 command.
630 For the meaning of the
631 .Fl F
632 flag, see the
633 .Sx FORMATS
634 section.
635 .It Ic lock-session Op Fl t Ar target-session
636 .D1 (alias: Ic locks )
637 Lock all clients attached to
638 .Ar target-session .
639 .It Xo Ic new-session
640 .Op Fl d
641 .Op Fl n Ar window-name
642 .Op Fl s Ar session-name
643 .Op Fl t Ar target-session
644 .Op Fl x Ar width
645 .Op Fl y Ar height
646 .Op Ar shell-command
648 .D1 (alias: Ic new )
649 Create a new session with name
650 .Ar session-name .
652 The new session is attached to the current terminal unless
653 .Fl d
654 is given.
655 .Ar window-name
657 .Ar shell-command
658 are the name of and shell command to execute in the initial window.
660 .Fl d
661 is used,
662 .Fl x
664 .Fl y
665 specify the size of the initial window (80 by 24 if not given).
667 If run from a terminal, any
668 .Xr termios 4
669 special characters are saved and used for new windows in the new session.
672 .Fl t
673 is given, the new session is
674 .Em grouped
675 with
676 .Ar target-session .
677 This means they share the same set of windows - all windows from
678 .Ar target-session
679 are linked to the new session and any subsequent new windows or windows being
680 closed are applied to both sessions.
681 The current and previous window and any session options remain independent and
682 either session may be killed without affecting the other.
683 Giving
684 .Fl n
686 .Ar shell-command
687 are invalid if
688 .Fl t
689 is used.
690 .It Ic refresh-client Op Fl t Ar target-client
691 .D1 (alias: Ic refresh )
692 Refresh the current client if bound to a key, or a single client if one is given
693 with
694 .Fl t .
695 .It Xo Ic rename-session
696 .Op Fl t Ar target-session
697 .Ar new-name
699 .D1 (alias: Ic rename )
700 Rename the session to
701 .Ar new-name .
702 .It Xo Ic show-messages
703 .Op Fl t Ar target-client
705 .D1 (alias: Ic showmsgs )
706 Any messages displayed on the status line are saved in a per-client message
707 log, up to a maximum of the limit set by the
708 .Ar message-limit
709 session option for the session attached to that client.
710 This command displays the log for
711 .Ar target-client .
712 .It Ic source-file Ar path
713 .D1 (alias: Ic source )
714 Execute commands from
715 .Ar path .
716 .It Ic start-server
717 .D1 (alias: Ic start )
718 Start the
720 server, if not already running, without creating any sessions.
721 .It Xo Ic suspend-client
722 .Op Fl t Ar target-client
724 .D1 (alias: Ic suspendc )
725 Suspend a client by sending
726 .Dv SIGTSTP
727 (tty stop).
728 .It Xo Ic switch-client
729 .Op Fl lnpr
730 .Op Fl c Ar target-client
731 .Op Fl t Ar target-session
733 .D1 (alias: Ic switchc )
734 Switch the current session for client
735 .Ar target-client
737 .Ar target-session .
739 .Fl l ,
740 .Fl n
742 .Fl p
743 is used, the client is moved to the last, next or previous session
744 respectively.
745 .Fl r
746 toggles whether a client is read-only (see the
747 .Ic attach-session
748 command).
750 .Sh WINDOWS AND PANES
753 window may be in one of several modes.
754 The default permits direct access to the terminal attached to the window.
755 The other is copy mode, which permits a section of a window or its
756 history to be copied to a
757 .Em paste buffer
758 for later insertion into another window.
759 This mode is entered with the
760 .Ic copy-mode
761 command, bound to
762 .Ql \&[
763 by default.
764 It is also entered when a command that produces output, such as
765 .Ic list-keys ,
766 is executed from a key binding.
768 The keys available depend on whether emacs or vi mode is selected
769 (see the
770 .Ic mode-keys
771 option).
772 The following keys are supported as appropriate for the mode:
773 .Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
774 .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
775 .It Li "Back to indentation" Ta "^" Ta "M-m"
776 .It Li "Bottom of history" Ta "G" Ta "M-<"
777 .It Li "Clear selection" Ta "Escape" Ta "C-g"
778 .It Li "Copy selection" Ta "Enter" Ta "M-w"
779 .It Li "Cursor down" Ta "j" Ta "Down"
780 .It Li "Cursor left" Ta "h" Ta "Left"
781 .It Li "Cursor right" Ta "l" Ta "Right"
782 .It Li "Cursor to bottom line" Ta "L" Ta ""
783 .It Li "Cursor to middle line" Ta "M" Ta "M-r"
784 .It Li "Cursor to top line" Ta "H" Ta "M-R"
785 .It Li "Cursor up" Ta "k" Ta "Up"
786 .It Li "Delete entire line" Ta "d" Ta "C-u"
787 .It Li "Delete/Copy to end of line" Ta "D" Ta "C-k"
788 .It Li "End of line" Ta "$" Ta "C-e"
789 .It Li "Go to line" Ta ":" Ta "g"
790 .It Li "Half page down" Ta "C-d" Ta "M-Down"
791 .It Li "Half page up" Ta "C-u" Ta "M-Up"
792 .It Li "Jump forward" Ta "f" Ta "f"
793 .It Li "Jump backward" Ta "F" Ta "F"
794 .It Li "Jump again" Ta ";" Ta ";"
795 .It Li "Jump again in reverse" Ta "," Ta ","
796 .It Li "Next page" Ta "C-f" Ta "Page down"
797 .It Li "Next space" Ta "W" Ta ""
798 .It Li "Next space, end of word" Ta "E" Ta ""
799 .It Li "Next word" Ta "w" Ta ""
800 .It Li "Next word end" Ta "e" Ta "M-f"
801 .It Li "Paste buffer" Ta "p" Ta "C-y"
802 .It Li "Previous page" Ta "C-b" Ta "Page up"
803 .It Li "Previous word" Ta "b" Ta "M-b"
804 .It Li "Previous space" Ta "B" Ta ""
805 .It Li "Quit mode" Ta "q" Ta "Escape"
806 .It Li "Rectangle toggle" Ta "v" Ta "R"
807 .It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down"
808 .It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up"
809 .It Li "Search again" Ta "n" Ta "n"
810 .It Li "Search again in reverse" Ta "N" Ta "N"
811 .It Li "Search backward" Ta "?" Ta "C-r"
812 .It Li "Search forward" Ta "/" Ta "C-s"
813 .It Li "Start of line" Ta "0" Ta "C-a"
814 .It Li "Start selection" Ta "Space" Ta "C-Space"
815 .It Li "Top of history" Ta "g" Ta "M->"
816 .It Li "Transpose chars" Ta "" Ta "C-t"
819 The next and previous word keys use space and the
820 .Ql - ,
821 .Ql _
823 .Ql @
824 characters as word delimiters by default, but this can be adjusted by
825 setting the
826 .Em word-separators
827 window option.
828 Next word moves to the start of the next word, next word end to the end of the
829 next word and previous word to the start of the previous word.
830 The three next and previous space keys work similarly but use a space alone as
831 the word separator.
833 The jump commands enable quick movement within a line.
834 For instance, typing
835 .Ql f
836 followed by
837 .Ql /
838 will move the cursor to the next
839 .Ql /
840 character on the current line.
842 .Ql \&;
843 will then jump to the next occurrence.
845 Commands in copy mode may be prefaced by an optional repeat count.
846 With vi key bindings, a prefix is entered using the number keys; with
847 emacs, the Alt (meta) key and a number begins prefix entry.
848 For example, to move the cursor forward by ten words, use
849 .Ql M-1 0 M-f
850 in emacs mode, and
851 .Ql 10w
852 in vi.
854 Mode key bindings are defined in a set of named tables:
855 .Em vi-edit
857 .Em emacs-edit
858 for keys used when line editing at the command prompt;
859 .Em vi-choice
861 .Em emacs-choice
862 for keys used when choosing from lists (such as produced by the
863 .Ic choose-window
864 command); and
865 .Em vi-copy
867 .Em emacs-copy
868 used in copy mode.
869 The tables may be viewed with the
870 .Ic list-keys
871 command and keys modified or removed with
872 .Ic bind-key
874 .Ic unbind-key .
876 The paste buffer key pastes the first line from the top paste buffer on the
877 stack.
879 The synopsis for the
880 .Ic copy-mode
881 command is:
882 .Bl -tag -width Ds
883 .It Xo Ic copy-mode
884 .Op Fl u
885 .Op Fl t Ar target-pane
887 Enter copy mode.
889 .Fl u
890 option scrolls one page up.
893 Each window displayed by
895 may be split into one or more
896 .Em panes ;
897 each pane takes up a certain area of the display and is a separate terminal.
898 A window may be split into panes using the
899 .Ic split-window
900 command.
901 Windows may be split horizontally (with the
902 .Fl h
903 flag) or vertically.
904 Panes may be resized with the
905 .Ic resize-pane
906 command (bound to
907 .Ql C-up ,
908 .Ql C-down
909 .Ql C-left
911 .Ql C-right
912 by default), the current pane may be changed with the
913 .Ic select-pane
914 command and the
915 .Ic rotate-window
917 .Ic swap-pane
918 commands may be used to swap panes without changing their position.
919 Panes are numbered beginning from zero in the order they are created.
921 A number of preset
922 .Em layouts
923 are available.
924 These may be selected with the
925 .Ic select-layout
926 command or cycled with
927 .Ic next-layout
928 (bound to
929 .Ql Space
930 by default); once a layout is chosen, panes within it may be moved and resized
931 as normal.
933 The following layouts are supported:
934 .Bl -tag -width Ds
935 .It Ic even-horizontal
936 Panes are spread out evenly from left to right across the window.
937 .It Ic even-vertical
938 Panes are spread evenly from top to bottom.
939 .It Ic main-horizontal
940 A large (main) pane is shown at the top of the window and the remaining panes
941 are spread from left to right in the leftover space at the bottom.
942 Use the
943 .Em main-pane-height
944 window option to specify the height of the top pane.
945 .It Ic main-vertical
946 Similar to
947 .Ic main-horizontal
948 but the large pane is placed on the left and the others spread from top to
949 bottom along the right.
950 See the
951 .Em main-pane-width
952 window option.
953 .It Ic tiled
954 Panes are spread out as evenly as possible over the window in both rows and
955 columns.
958 In addition,
959 .Ic select-layout
960 may be used to apply a previously used layout - the
961 .Ic list-windows
962 command displays the layout of each window in a form suitable for use with
963 .Ic select-layout .
964 For example:
965 .Bd -literal -offset indent
966 $ tmux list-windows
967 0: ksh [159x48]
968     layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
969 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
973 automatically adjusts the size of the layout for the current window size.
974 Note that a layout cannot be applied to a window with more panes than that
975 from which the layout was originally defined.
977 Commands related to windows and panes are as follows:
978 .Bl -tag -width Ds
979 .It Xo Ic break-pane
980 .Op Fl d
981 .Op Fl t Ar target-pane
983 .D1 (alias: Ic breakp )
984 Break
985 .Ar target-pane
986 off from its containing window to make it the only pane in a new window.
988 .Fl d
989 is given, the new window does not become the current window.
990 .It Xo Ic capture-pane
991 .Op Fl b Ar buffer-index
992 .Op Fl E Ar end-line
993 .Op Fl S Ar start-line
994 .Op Fl t Ar target-pane
996 .D1 (alias: Ic capturep )
997 Capture the contents of a pane to the specified buffer, or a new buffer if none
998 is specified.
1000 .Fl S
1002 .Fl E
1003 specify the starting and ending line numbers, zero is the first line of the
1004 visible pane and negative numbers are lines in the history.
1005 The default is to capture only the visible contents of the pane.
1006 .It Xo
1007 .Ic choose-client
1008 .Op Fl t Ar target-window
1009 .Op Ar template
1011 Put a window into client choice mode, allowing a client to be selected
1012 interactively from a list.
1013 After a client is chosen,
1014 .Ql %%
1015 is replaced by the client
1016 .Xr pty 4
1017 path in
1018 .Ar template
1019 and the result executed as a command.
1021 .Ar template
1022 is not given, "detach-client -t '%%'" is used.
1023 This command works only from inside
1024 .Nm .
1025 .It Xo
1026 .Ic choose-session
1027 .Op Fl t Ar target-window
1028 .Op Ar template
1030 Put a window into session choice mode, where a session may be selected
1031 interactively from a list.
1032 When one is chosen,
1033 .Ql %%
1034 is replaced by the session name in
1035 .Ar template
1036 and the result executed as a command.
1038 .Ar template
1039 is not given, "switch-client -t '%%'" is used.
1040 This command works only from inside
1041 .Nm .
1042 .It Xo
1043 .Ic choose-window
1044 .Op Fl t Ar target-window
1045 .Op Ar template
1047 Put a window into window choice mode, where a window may be chosen
1048 interactively from a list.
1049 After a window is selected,
1050 .Ql %%
1051 is replaced by the session name and window index in
1052 .Ar template
1053 and the result executed as a command.
1055 .Ar template
1056 is not given, "select-window -t '%%'" is used.
1057 This command works only from inside
1058 .Nm .
1059 .It Ic display-panes Op Fl t Ar target-client
1060 .D1 (alias: Ic displayp)
1061 Display a visible indicator of each pane shown by
1062 .Ar target-client .
1063 See the
1064 .Ic display-panes-time ,
1065 .Ic display-panes-colour ,
1067 .Ic display-panes-active-colour
1068 session options.
1069 While the indicator is on screen, a pane may be selected with the
1070 .Ql 0
1072 .Ql 9
1073 keys.
1074 .It Xo Ic find-window
1075 .Op Fl t Ar target-window
1076 .Ar match-string
1078 .D1 (alias: Ic findw )
1079 Search for the
1080 .Xr fnmatch 3
1081 pattern
1082 .Ar match-string
1083 in window names, titles, and visible content (but not history).
1084 If only one window is matched, it'll be automatically selected, otherwise a
1085 choice list is shown.
1086 This command only works from inside
1087 .Nm .
1088 .It Xo Ic join-pane
1089 .Op Fl dhv
1090 .Oo Fl l
1091 .Ar size |
1092 .Fl p Ar percentage Oc
1093 .Op Fl s Ar src-pane
1094 .Op Fl t Ar dst-pane
1096 .D1 (alias: Ic joinp )
1097 Like
1098 .Ic split-window ,
1099 but instead of splitting
1100 .Ar dst-pane
1101 and creating a new pane, split it and move
1102 .Ar src-pane
1103 into the space.
1104 This can be used to reverse
1105 .Ic break-pane .
1106 .It Xo Ic kill-pane
1107 .Op Fl a
1108 .Op Fl t Ar target-pane
1110 .D1 (alias: Ic killp )
1111 Destroy the given pane.
1112 If no panes remain in the containing window, it is also destroyed.
1114 .Fl a
1115 option kills all but the pane given with
1116 .Fl t .
1117 .It Ic kill-window Op Fl t Ar target-window
1118 .D1 (alias: Ic killw )
1119 Kill the current window or the window at
1120 .Ar target-window ,
1121 removing it from any sessions to which it is linked.
1122 .It Ic last-pane Op Fl t Ar target-window
1123 .D1 (alias: Ic lastp )
1124 Select the last (previously selected) pane.
1125 .It Ic last-window Op Fl t Ar target-session
1126 .D1 (alias: Ic last )
1127 Select the last (previously selected) window.
1128 If no
1129 .Ar target-session
1130 is specified, select the last window of the current session.
1131 .It Xo Ic link-window
1132 .Op Fl dk
1133 .Op Fl s Ar src-window
1134 .Op Fl t Ar dst-window
1136 .D1 (alias: Ic linkw )
1137 Link the window at
1138 .Ar src-window
1139 to the specified
1140 .Ar dst-window .
1142 .Ar dst-window
1143 is specified and no such window exists, the
1144 .Ar src-window
1145 is linked there.
1147 .Fl k
1148 is given and
1149 .Ar dst-window
1150 exists, it is killed, otherwise an error is generated.
1152 .Fl d
1153 is given, the newly linked window is not selected.
1154 .It Xo Ic list-panes
1155 .Op Fl as
1156 .Op Fl F Ar format
1157 .Op Fl t Ar target
1159 .D1 (alias: Ic lsp )
1161 .Fl a
1162 is given,
1163 .Ar target
1164 is ignored and all panes on the server are listed.
1166 .Fl s
1167 is given,
1168 .Ar target
1169 is a session (or the current session).
1170 If neither is given,
1171 .Ar target
1172 is a window (or the current window).
1173 .It Xo Ic list-windows
1174 .Op Fl a
1175 .Op Fl F Ar format
1176 .Op Fl t Ar target-session
1178 .D1 (alias: Ic lsw )
1180 .Fl a
1181 is given, list all windows on the server.
1182 Otherwise, list windows in the current session or in
1183 .Ar target-session .
1184 For the meaning of the
1185 .Fl F
1186 flag, see the
1187 .Sx FORMATS
1188 section.
1189 .It Xo Ic move-window
1190 .Op Fl dk
1191 .Op Fl s Ar src-window
1192 .Op Fl t Ar dst-window
1194 .D1 (alias: Ic movew )
1195 This is similar to
1196 .Ic link-window ,
1197 except the window at
1198 .Ar src-window
1199 is moved to
1200 .Ar dst-window .
1201 .It Xo Ic new-window
1202 .Op Fl adkP
1203 .Op Fl n Ar window-name
1204 .Op Fl t Ar target-window
1205 .Op Ar shell-command
1207 .D1 (alias: Ic neww )
1208 Create a new window.
1209 With
1210 .Fl a ,
1211 the new window is inserted at the next index up from the specified
1212 .Ar target-window ,
1213 moving windows up if necessary,
1214 otherwise
1215 .Ar target-window
1216 is the new window location.
1219 .Fl d
1220 is given, the session does not make the new window the current window.
1221 .Ar target-window
1222 represents the window to be created; if the target already exists an error is
1223 shown, unless the
1224 .Fl k
1225 flag is used, in which case it is destroyed.
1226 .Ar shell-command
1227 is the command to execute.
1229 .Ar shell-command
1230 is not specified, the value of the
1231 .Ic default-command
1232 option is used.
1234 When the shell command completes, the window closes.
1235 See the
1236 .Ic remain-on-exit
1237 option to change this behaviour.
1240 .Ev TERM
1241 environment variable must be set to
1242 .Dq screen
1243 for all programs running
1244 .Em inside
1245 .Nm .
1246 New windows will automatically have
1247 .Dq TERM=screen
1248 added to their environment, but care must be taken not to reset this in shell
1249 start-up files.
1252 .Fl P
1253 option prints the location of the new window after it has been created.
1254 .It Ic next-layout Op Fl t Ar target-window
1255 .D1 (alias: Ic nextl )
1256 Move a window to the next layout and rearrange the panes to fit.
1257 .It Xo Ic next-window
1258 .Op Fl a
1259 .Op Fl t Ar target-session
1261 .D1 (alias: Ic next )
1262 Move to the next window in the session.
1264 .Fl a
1265 is used, move to the next window with a bell, activity or content alert.
1266 .It Xo Ic pipe-pane
1267 .Op Fl o
1268 .Op Fl t Ar target-pane
1269 .Op Ar shell-command
1271 .D1 (alias: Ic pipep )
1272 Pipe any output sent by the program in
1273 .Ar target-pane
1274 to a shell command.
1275 A pane may only be piped to one command at a time, any existing pipe is
1276 closed before
1277 .Ar shell-command
1278 is executed.
1280 .Ar shell-command
1281 string may contain the special character sequences supported by the
1282 .Ic status-left
1283 option.
1284 If no
1285 .Ar shell-command
1286 is given, the current pipe (if any) is closed.
1289 .Fl o
1290 option only opens a new pipe if no previous pipe exists, allowing a pipe to
1291 be toggled with a single key, for example:
1292 .Bd -literal -offset indent
1293 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1295 .It Xo Ic previous-layout
1296 .Op Fl t Ar target-window
1298 .D1 (alias: Ic prevl )
1299 Move to the previous layout in the session.
1300 .It Xo Ic previous-window
1301 .Op Fl a
1302 .Op Fl t Ar target-session
1304 .D1 (alias: Ic prev )
1305 Move to the previous window in the session.
1306 With
1307 .Fl a ,
1308 move to the previous window with a bell, activity or content alert.
1309 .It Xo Ic rename-window
1310 .Op Fl t Ar target-window
1311 .Ar new-name
1313 .D1 (alias: Ic renamew )
1314 Rename the current window, or the window at
1315 .Ar target-window
1316 if specified, to
1317 .Ar new-name .
1318 .It Xo Ic resize-pane
1319 .Op Fl DLRU
1320 .Op Fl t Ar target-pane
1321 .Op Ar adjustment
1323 .D1 (alias: Ic resizep )
1324 Resize a pane, upward with
1325 .Fl U
1326 (the default), downward with
1327 .Fl D ,
1328 to the left with
1329 .Fl L
1330 and to the right with
1331 .Fl R .
1333 .Ar adjustment
1334 is given in lines or cells (the default is 1).
1335 .It Xo Ic respawn-pane
1336 .Op Fl k
1337 .Op Fl t Ar target-pane
1338 .Op Ar shell-command
1340 .D1 (alias: Ic respawnp )
1341 Reactivate a pane in which the command has exited (see the
1342 .Ic remain-on-exit
1343 window option).
1345 .Ar shell-command
1346 is not given, the command used when the pane was created is executed.
1347 The pane must be already inactive, unless
1348 .Fl k
1349 is given, in which case any existing command is killed.
1350 .It Xo Ic respawn-window
1351 .Op Fl k
1352 .Op Fl t Ar target-window
1353 .Op Ar shell-command
1355 .D1 (alias: Ic respawnw )
1356 Reactivate a window in which the command has exited (see the
1357 .Ic remain-on-exit
1358 window option).
1360 .Ar shell-command
1361 is not given, the command used when the window was created is executed.
1362 The window must be already inactive, unless
1363 .Fl k
1364 is given, in which case any existing command is killed.
1365 .It Xo Ic rotate-window
1366 .Op Fl DU
1367 .Op Fl t Ar target-window
1369 .D1 (alias: Ic rotatew )
1370 Rotate the positions of the panes within a window, either upward (numerically
1371 lower) with
1372 .Fl U
1373 or downward (numerically higher).
1374 .It Xo Ic select-layout
1375 .Op Fl np
1376 .Op Fl t Ar target-window
1377 .Op Ar layout-name
1379 .D1 (alias: Ic selectl )
1380 Choose a specific layout for a window.
1382 .Ar layout-name
1383 is not given, the last preset layout used (if any) is reapplied.
1384 .Fl n
1386 .Fl p
1387 are equivalent to the
1388 .Ic next-layout
1390 .Ic previous-layout
1391 commands.
1392 .It Xo Ic select-pane
1393 .Op Fl lDLRU
1394 .Op Fl t Ar target-pane
1396 .D1 (alias: Ic selectp )
1397 Make pane
1398 .Ar target-pane
1399 the active pane in window
1400 .Ar target-window .
1401 If one of
1402 .Fl D ,
1403 .Fl L ,
1404 .Fl R ,
1406 .Fl U
1407 is used, respectively the pane below, to the left, to the right, or above the
1408 target pane is used.
1409 .Fl l
1410 is the same as using the
1411 .Ic last-pane
1412 command.
1413 .It Xo Ic select-window
1414 .Op Fl lnp
1415 .Op Fl t Ar target-window
1417 .D1 (alias: Ic selectw )
1418 Select the window at
1419 .Ar target-window .
1420 .Fl l ,
1421 .Fl n
1423 .Fl p
1424 are equivalent to the
1425 .Ic last-window ,
1426 .Ic next-window
1428 .Ic previous-window
1429 commands.
1430 .It Xo Ic split-window
1431 .Op Fl dhvP
1432 .Oo Fl l
1433 .Ar size |
1434 .Fl p Ar percentage Oc
1435 .Op Fl t Ar target-pane
1436 .Op Ar shell-command
1438 .D1 (alias: Ic splitw )
1439 Create a new pane by splitting
1440 .Ar target-pane :
1441 .Fl h
1442 does a horizontal split and
1443 .Fl v
1444 a vertical split; if neither is specified,
1445 .Fl v
1446 is assumed.
1448 .Fl l
1450 .Fl p
1451 options specify the size of the new pane in lines (for vertical split) or in
1452 cells (for horizontal split), or as a percentage, respectively.
1453 All other options have the same meaning as for the
1454 .Ic new-window
1455 command.
1456 .It Xo Ic swap-pane
1457 .Op Fl dDU
1458 .Op Fl s Ar src-pane
1459 .Op Fl t Ar dst-pane
1461 .D1 (alias: Ic swapp )
1462 Swap two panes.
1464 .Fl U
1465 is used and no source pane is specified with
1466 .Fl s ,
1467 .Ar dst-pane
1468 is swapped with the previous pane (before it numerically);
1469 .Fl D
1470 swaps with the next pane (after it numerically).
1471 .Fl d
1472 instructs
1474 not to change the active pane.
1475 .It Xo Ic swap-window
1476 .Op Fl d
1477 .Op Fl s Ar src-window
1478 .Op Fl t Ar dst-window
1480 .D1 (alias: Ic swapw )
1481 This is similar to
1482 .Ic link-window ,
1483 except the source and destination windows are swapped.
1484 It is an error if no window exists at
1485 .Ar src-window .
1486 .It Xo Ic unlink-window
1487 .Op Fl k
1488 .Op Fl t Ar target-window
1490 .D1 (alias: Ic unlinkw )
1491 Unlink
1492 .Ar target-window .
1493 Unless
1494 .Fl k
1495 is given, a window may be unlinked only if it is linked to multiple sessions -
1496 windows may not be linked to no sessions;
1498 .Fl k
1499 is specified and the window is linked to only one session, it is unlinked and
1500 destroyed.
1502 .Sh KEY BINDINGS
1504 allows a command to be bound to most keys, with or without a prefix key.
1505 When specifying keys, most represent themselves (for example
1506 .Ql A
1508 .Ql Z ) .
1509 Ctrl keys may be prefixed with
1510 .Ql C-
1512 .Ql ^ ,
1513 and Alt (meta) with
1514 .Ql M- .
1515 In addition, the following special key names are accepted:
1516 .Em Up ,
1517 .Em Down ,
1518 .Em Left ,
1519 .Em Right ,
1520 .Em BSpace ,
1521 .Em BTab ,
1522 .Em DC
1523 (Delete),
1524 .Em End ,
1525 .Em Enter ,
1526 .Em Escape ,
1527 .Em F1
1529 .Em F20 ,
1530 .Em Home ,
1531 .Em IC
1532 (Insert),
1533 .Em NPage
1534 (Page Up),
1535 .Em PPage
1536 (Page Down),
1537 .Em Space ,
1539 .Em Tab .
1540 Note that to bind the
1541 .Ql \&"
1543 .Ql '
1544 keys, quotation marks are necessary, for example:
1545 .Bd -literal -offset indent
1546 bind-key '"' split-window
1547 bind-key "'" new-window
1550 Commands related to key bindings are as follows:
1551 .Bl -tag -width Ds
1552 .It Xo Ic bind-key
1553 .Op Fl cnr
1554 .Op Fl t Ar key-table
1555 .Ar key Ar command Op Ar arguments
1557 .D1 (alias: Ic bind )
1558 Bind key
1559 .Ar key
1561 .Ar command .
1562 By default (without
1563 .Fl t )
1564 the primary key bindings are modified (those normally activated with the prefix
1565 key); in this case, if
1566 .Fl n
1567 is specified, it is not necessary to use the prefix key,
1568 .Ar command
1569 is bound to
1570 .Ar key
1571 alone.
1573 .Fl r
1574 flag indicates this key may repeat, see the
1575 .Ic repeat-time
1576 option.
1579 .Fl t
1580 is present,
1581 .Ar key
1582 is bound in
1583 .Ar key-table :
1584 the binding for command mode with
1585 .Fl c
1586 or for normal mode without.
1587 To view the default bindings and possible commands, see the
1588 .Ic list-keys
1589 command.
1590 .It Ic list-keys Op Fl t Ar key-table
1591 .D1 (alias: Ic lsk )
1592 List all key bindings.
1593 Without
1594 .Fl t
1595 the primary key bindings - those executed when preceded by the prefix key -
1596 are printed.
1597 Keys bound without the prefix key (see
1598 .Ic bind-key
1599 .Fl n )
1600 are marked with
1601 .Ql (no prefix) .
1603 With
1604 .Fl t ,
1605 the key bindings in
1606 .Ar key-table
1607 are listed; this may be one of:
1608 .Em vi-edit ,
1609 .Em emacs-edit ,
1610 .Em vi-choice ,
1611 .Em emacs-choice ,
1612 .Em vi-copy
1614 .Em emacs-copy .
1615 .It Xo Ic send-keys
1616 .Op Fl t Ar target-pane
1617 .Ar key Ar ...
1619 .D1 (alias: Ic send )
1620 Send a key or keys to a window.
1621 Each argument
1622 .Ar key
1623 is the name of the key (such as
1624 .Ql C-a
1626 .Ql npage
1627 ) to send; if the string is not recognised as a key, it is sent as a series of
1628 characters.
1629 All arguments are sent sequentially from first to last.
1630 .It Ic send-prefix Op Fl t Ar target-pane
1631 Send the prefix key to a window as if it was pressed.
1632 If multiple prefix keys are configured, only the first is sent.
1633 .It Xo Ic unbind-key
1634 .Op Fl acn
1635 .Op Fl t Ar key-table
1636 .Ar key
1638 .D1 (alias: Ic unbind )
1639 Unbind the command bound to
1640 .Ar key .
1641 Without
1642 .Fl t
1643 the primary key bindings are modified; in this case, if
1644 .Fl n
1645 is specified, the command bound to
1646 .Ar key
1647 without a prefix (if any) is removed.
1649 .Fl a
1650 is present, all key bindings are removed.
1653 .Fl t
1654 is present,
1655 .Ar key
1657 .Ar key-table
1658 is unbound: the binding for command mode with
1659 .Fl c
1660 or for normal mode without.
1662 .Sh OPTIONS
1663 The appearance and behaviour of
1665 may be modified by changing the value of various options.
1666 There are three types of option:
1667 .Em server options ,
1668 .Em session options
1670 .Em window options .
1674 server has a set of global options which do not apply to any particular
1675 window or session.
1676 These are altered with the
1677 .Ic set-option
1678 .Fl s
1679 command, or displayed with the
1680 .Ic show-options
1681 .Fl s
1682 command.
1684 In addition, each individual session may have a set of session options, and
1685 there is a separate set of global session options.
1686 Sessions which do not have a particular option configured inherit the value
1687 from the global session options.
1688 Session options are set or unset with the
1689 .Ic set-option
1690 command and may be listed with the
1691 .Ic show-options
1692 command.
1693 The available server and session options are listed under the
1694 .Ic set-option
1695 command.
1697 Similarly, a set of window options is attached to each window, and there is
1698 a set of global window options from which any unset options are inherited.
1699 Window options are altered with the
1700 .Ic set-window-option
1701 command and can be listed with the
1702 .Ic show-window-options
1703 command.
1704 All window options are documented with the
1705 .Ic set-window-option
1706 command.
1708 Commands which set options are as follows:
1709 .Bl -tag -width Ds
1710 .It Xo Ic set-option
1711 .Op Fl agsuw
1712 .Op Fl t Ar target-session | Ar target-window
1713 .Ar option Ar value
1715 .D1 (alias: Ic set )
1716 Set a window option with
1717 .Fl w
1718 (equivalent to the
1719 .Ic set-window-option
1720 command),
1721 a server option with
1722 .Fl s ,
1723 otherwise a session option.
1726 .Fl g
1727 is specified, the global session or window option is set.
1728 With
1729 .Fl a ,
1730 and if the option expects a string,
1731 .Ar value
1732 is appended to the existing setting.
1734 .Fl u
1735 flag unsets an option, so a session inherits the option from the global
1736 options.
1737 It is not possible to unset a global option.
1739 Available window options are listed under
1740 .Ic set-window-option .
1742 Available server options are:
1743 .Bl -tag -width Ds
1744 .It Ic buffer-limit Ar number
1745 Set the number of buffers; as new buffers are added to the top of the stack,
1746 old ones are removed from the bottom if necessary to maintain this maximum
1747 length.
1748 .It Ic escape-time Ar time
1749 Set the time in milliseconds for which
1751 waits after an escape is input to determine if it is part of a function or meta
1752 key sequences.
1753 The default is 500 milliseconds.
1754 .It Xo Ic exit-unattached
1755 .Op Ic on | off
1757 If enabled, the server will exit when there are no attached clients.
1758 .It Xo Ic quiet
1759 .Op Ic on | off
1761 Enable or disable the display of various informational messages (see also the
1762 .Fl q
1763 command line flag).
1764 .It Xo Ic set-clipboard
1765 .Op Ic on | off
1767 Attempt to set the terminal clipboard content using the
1768 \ee]52;...\e007
1769 .Xr xterm 1
1770 escape sequences.
1771 This option is on by default if there is an
1772 .Em \&Ms
1773 entry in the
1774 .Xr terminfo 5
1775 description for the client terminal.
1776 Note that this feature needs to be enabled in
1777 .Xr xterm 1
1778 by setting the resource:
1779 .Bd -literal -offset indent
1780 disallowedWindowOps: 20,21,SetXprop
1783 Or changing this property from the
1784 .Xr xterm 1
1785 interactive menu when required.
1788 Available session options are:
1789 .Bl -tag -width Ds
1790 .It Ic base-index Ar index
1791 Set the base index from which an unused index should be searched when a new
1792 window is created.
1793 The default is zero.
1794 .It Xo Ic bell-action
1795 .Op Ic any | none | current
1797 Set action on window bell.
1798 .Ic any
1799 means a bell in any window linked to a session causes a bell in the current
1800 window of that session,
1801 .Ic none
1802 means all bells are ignored and
1803 .Ic current
1804 means only bell in windows other than the current window are ignored.
1805 .It Xo Ic bell-on-alert
1806 .Op Ic on | off
1808 If on, ring the terminal bell when an activity, content or silence alert
1809 occurs.
1810 .It Ic default-command Ar shell-command
1811 Set the command used for new windows (if not specified when the window is
1812 created) to
1813 .Ar shell-command ,
1814 which may be any
1815 .Xr sh 1
1816 command.
1817 The default is an empty string, which instructs
1819 to create a login shell using the value of the
1820 .Ic default-shell
1821 option.
1822 .It Ic default-path Ar path
1823 Set the default working directory for processes created from keys, or
1824 interactively from the prompt.
1825 The default is empty, which means to use the working directory of the shell
1826 from which the server was started if it is available or the user's home if not.
1827 .It Ic default-shell Ar path
1828 Specify the default shell.
1829 This is used as the login shell for new windows when the
1830 .Ic default-command
1831 option is set to empty, and must be the full path of the executable.
1832 When started
1834 tries to set a default value from the first suitable of the
1835 .Ev SHELL
1836 environment variable, the shell returned by
1837 .Xr getpwuid 3 ,
1839 .Pa /bin/sh .
1840 This option should be configured when
1842 is used as a login shell.
1843 .It Ic default-terminal Ar terminal
1844 Set the default terminal for new windows created in this session - the
1845 default value of the
1846 .Ev TERM
1847 environment variable.
1850 to work correctly, this
1851 .Em must
1852 be set to
1853 .Ql screen
1854 or a derivative of it.
1855 .It Xo Ic destroy-unattached
1856 .Op Ic on | off
1858 If enabled and the session is no longer attached to any clients, it is
1859 destroyed.
1860 .It Xo Ic detach-on-destroy
1861 .Op Ic on | off
1863 If on (the default), the client is detached when the session it is attached to
1864 is destroyed.
1865 If off, the client is switched to the most recently active of the remaining
1866 sessions.
1867 .It Ic display-panes-active-colour Ar colour
1868 Set the colour used by the
1869 .Ic display-panes
1870 command to show the indicator for the active pane.
1871 .It Ic display-panes-colour Ar colour
1872 Set the colour used by the
1873 .Ic display-panes
1874 command to show the indicators for inactive panes.
1875 .It Ic display-panes-time Ar time
1876 Set the time in milliseconds for which the indicators shown by the
1877 .Ic display-panes
1878 command appear.
1879 .It Ic display-time Ar time
1880 Set the amount of time for which status line messages and other on-screen
1881 indicators are displayed.
1882 .Ar time
1883 is in milliseconds.
1884 .It Ic history-limit Ar lines
1885 Set the maximum number of lines held in window history.
1886 This setting applies only to new windows - existing window histories are not
1887 resized and retain the limit at the point they were created.
1888 .It Ic lock-after-time Ar number
1889 Lock the session (like the
1890 .Ic lock-session
1891 command) after
1892 .Ar number
1893 seconds of inactivity, or the entire server (all sessions) if the
1894 .Ic lock-server
1895 option is set.
1896 The default is not to lock (set to 0).
1897 .It Ic lock-command Ar shell-command
1898 Command to run when locking each client.
1899 The default is to run
1900 .Xr lock 1
1901 with
1902 .Fl np .
1903 .It Xo Ic lock-server
1904 .Op Ic on | off
1906 If this option is
1907 .Ic on
1908 (the default),
1909 instead of each session locking individually as each has been
1910 idle for
1911 .Ic lock-after-time ,
1912 the entire server will lock after
1913 .Em all
1914 sessions would have locked.
1915 This has no effect as a session option; it must be set as a global option.
1916 .It Ic message-attr Ar attributes
1917 Set status line message attributes, where
1918 .Ar attributes
1919 is either
1920 .Ic none
1921 or a comma-delimited list of one or more of:
1922 .Ic bright
1924 .Ic bold ) ,
1925 .Ic dim ,
1926 .Ic underscore ,
1927 .Ic blink ,
1928 .Ic reverse ,
1929 .Ic hidden ,
1931 .Ic italics .
1932 .It Ic message-bg Ar colour
1933 Set status line message background colour, where
1934 .Ar colour
1935 is one of:
1936 .Ic black ,
1937 .Ic red ,
1938 .Ic green ,
1939 .Ic yellow ,
1940 .Ic blue ,
1941 .Ic magenta ,
1942 .Ic cyan ,
1943 .Ic white ,
1944 .Ic colour0
1946 .Ic colour255
1947 from the 256-colour set,
1948 .Ic default ,
1949 or a hexadecimal RGB string such as
1950 .Ql #ffffff ,
1951 which chooses the closest match from the default 256-colour set.
1952 .It Ic message-fg Ar colour
1953 Set status line message foreground colour.
1954 .It Ic message-limit Ar number
1955 Set the number of error or information messages to save in the message log for
1956 each client.
1957 The default is 20.
1958 .It Xo Ic mouse-resize-pane
1959 .Op Ic on | off
1961 If on,
1963 captures the mouse and allows panes to be resized by dragging on their borders.
1964 .It Xo Ic mouse-select-pane
1965 .Op Ic on | off
1967 If on,
1969 captures the mouse and when a window is split into multiple panes the mouse may
1970 be used to select the current pane.
1971 The mouse click is also passed through to the application as normal.
1972 .It Xo Ic mouse-select-window
1973 .Op Ic on | off
1975 If on, clicking the mouse on a window name in the status line will select that
1976 window.
1977 .It Xo Ic mouse-utf8
1978 .Op Ic on | off
1980 If enabled, request mouse input as UTF-8 on UTF-8 terminals.
1981 .It Ic pane-active-border-bg Ar colour
1982 .It Ic pane-active-border-fg Ar colour
1983 Set the pane border colour for the currently active pane.
1984 .It Ic pane-border-bg Ar colour
1985 .It Ic pane-border-fg Ar colour
1986 Set the pane border colour for panes aside from the active pane.
1987 .It Ic prefix Ar keys
1988 Set the keys accepted as a prefix key.
1989 .Ar keys
1990 is a comma-separated list of key names, each of which individually behave as
1991 the prefix key.
1992 .It Ic repeat-time Ar time
1993 Allow multiple commands to be entered without pressing the prefix-key again
1994 in the specified
1995 .Ar time
1996 milliseconds (the default is 500).
1997 Whether a key repeats may be set when it is bound using the
1998 .Fl r
1999 flag to
2000 .Ic bind-key .
2001 Repeat is enabled for the default keys bound to the
2002 .Ic resize-pane
2003 command.
2004 .It Xo Ic set-remain-on-exit
2005 .Op Ic on | off
2007 Set the
2008 .Ic remain-on-exit
2009 window option for any windows first created in this session.
2010 When this option is true, windows in which the running program has
2011 exited do not close, instead remaining open but inactivate.
2012 Use the
2013 .Ic respawn-window
2014 command to reactivate such a window, or the
2015 .Ic kill-window
2016 command to destroy it.
2017 .It Xo Ic set-titles
2018 .Op Ic on | off
2020 Attempt to set the window title using the \ee]2;...\e007 xterm code if
2021 the terminal appears to be an xterm.
2022 This option is off by default.
2023 Note that elinks
2024 will only attempt to set the window title if the STY environment
2025 variable is set.
2026 .It Ic set-titles-string Ar string
2027 String used to set the window title if
2028 .Ic set-titles
2029 is on.
2030 Character sequences are replaced as for the
2031 .Ic status-left
2032 option.
2033 .It Xo Ic status
2034 .Op Ic on | off
2036 Show or hide the status line.
2037 .It Ic status-attr Ar attributes
2038 Set status line attributes.
2039 .It Ic status-bg Ar colour
2040 Set status line background colour.
2041 .It Ic status-fg Ar colour
2042 Set status line foreground colour.
2043 .It Ic status-interval Ar interval
2044 Update the status bar every
2045 .Ar interval
2046 seconds.
2047 By default, updates will occur every 15 seconds.
2048 A setting of zero disables redrawing at interval.
2049 .It Xo Ic status-justify
2050 .Op Ic left | centre | right
2052 Set the position of the window list component of the status line: left, centre
2053 or right justified.
2054 .It Xo Ic status-keys
2055 .Op Ic vi | emacs
2057 Use vi or emacs-style
2058 key bindings in the status line, for example at the command prompt.
2059 The default is emacs, unless the
2060 .Ev VISUAL
2062 .Ev EDITOR
2063 environment variables are set and contain the string
2064 .Ql vi .
2065 .It Ic status-left Ar string
2066 Display
2067 .Ar string
2068 to the left of the status bar.
2069 .Ar string
2070 will be passed through
2071 .Xr strftime 3
2072 before being used.
2073 By default, the session name is shown.
2074 .Ar string
2075 may contain any of the following special character sequences:
2076 .Bl -column "Character pair" "Replaced with" -offset indent
2077 .It Sy "Character pair" Ta Sy "Replaced with"
2078 .It Li "#(shell-command)" Ta "First line of the command's output"
2079 .It Li "#[attributes]" Ta "Colour or attribute change"
2080 .It Li "#H" Ta "Hostname of local host"
2081 .It Li "#h" Ta "Hostname of local host without the domain name"
2082 .It Li "#F" Ta "Current window flag"
2083 .It Li "#I" Ta "Current window index"
2084 .It Li "#P" Ta "Current pane index"
2085 .It Li "#S" Ta "Session name"
2086 .It Li "#T" Ta "Current window title"
2087 .It Li "#W" Ta "Current window name"
2088 .It Li "##" Ta "A literal" Ql #
2091 The #(shell-command) form executes
2092 .Ql shell-command
2093 and inserts the first line of its output.
2094 Note that shell commands are only executed once at the interval specified by
2096 .Ic status-interval
2097 option: if the status line is redrawn in the meantime, the previous result is
2098 used.
2099 Shell commands are executed with the
2101 global environment set (see the
2102 .Sx ENVIRONMENT
2103 section).
2105 The window title (#T) is the title set by the program running within the window
2106 using the OSC title setting sequence, for example:
2107 .Bd -literal -offset indent
2108 $ printf '\e033]2;My Title\e033\e\e'
2111 When a window is first created, its title is the hostname.
2113 #[attributes] allows a comma-separated list of attributes to be specified,
2114 these may be
2115 .Ql fg=colour
2116 to set the foreground colour,
2117 .Ql bg=colour
2118 to set the background colour, the name of one of the attributes (listed under
2120 .Ic message-attr
2121 option) to turn an attribute on, or an attribute prefixed with
2122 .Ql no
2123 to turn one off, for example
2124 .Ic nobright .
2125 Examples are:
2126 .Bd -literal -offset indent
2127 #(sysctl vm.loadavg)
2128 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2131 Where appropriate, special character sequences may be prefixed with a number to
2132 specify the maximum length, for example
2133 .Ql #24T .
2135 By default, UTF-8 in
2136 .Ar string
2137 is not interpreted, to enable UTF-8, use the
2138 .Ic status-utf8
2139 option.
2140 .It Ic status-left-attr Ar attributes
2141 Set the attribute of the left part of the status line.
2142 .It Ic status-left-bg Ar colour
2143 Set the background colour of the left part of the status line.
2144 .It Ic status-left-fg Ar colour
2145 Set the foreground colour of the left part of the status line.
2146 .It Ic status-left-length Ar length
2147 Set the maximum
2148 .Ar length
2149 of the left component of the status bar.
2150 The default is 10.
2151 .It Ic status-right Ar string
2152 Display
2153 .Ar string
2154 to the right of the status bar.
2155 By default, the current window title in double quotes, the date and the time
2156 are shown.
2157 As with
2158 .Ic status-left ,
2159 .Ar string
2160 will be passed to
2161 .Xr strftime 3 ,
2162 character pairs are replaced, and UTF-8 is dependent on the
2163 .Ic status-utf8
2164 option.
2165 .It Ic status-right-attr Ar attributes
2166 Set the attribute of the right part of the status line.
2167 .It Ic status-right-bg Ar colour
2168 Set the background colour of the right part of the status line.
2169 .It Ic status-right-fg Ar colour
2170 Set the foreground colour of the right part of the status line.
2171 .It Ic status-right-length Ar length
2172 Set the maximum
2173 .Ar length
2174 of the right component of the status bar.
2175 The default is 40.
2176 .It Xo Ic status-utf8
2177 .Op Ic on | off
2179 Instruct
2181 to treat top-bit-set characters in the
2182 .Ic status-left
2184 .Ic status-right
2185 strings as UTF-8; notably, this is important for wide characters.
2186 This option defaults to off.
2187 .It Ic terminal-overrides Ar string
2188 Contains a list of entries which override terminal descriptions read using
2189 .Xr terminfo 5 .
2190 .Ar string
2191 is a comma-separated list of items each a colon-separated string made up of a
2192 terminal type pattern (matched using
2193 .Xr fnmatch 3 )
2194 and a set of
2195 .Em name=value
2196 entries.
2198 For example, to set the
2199 .Ql clear
2200 .Xr terminfo 5
2201 entry to
2202 .Ql \ee[H\ee[2J
2203 for all terminal types and the
2204 .Ql dch1
2205 entry to
2206 .Ql \ee[P
2207 for the
2208 .Ql rxvt
2209 terminal type, the option could be set to the string:
2210 .Bd -literal -offset indent
2211 "*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
2214 The terminal entry value is passed through
2215 .Xr strunvis 3
2216 before interpretation.
2217 The default value forcibly corrects the
2218 .Ql colors
2219 entry for terminals which support 88 or 256 colours:
2220 .Bd -literal -offset indent
2221 "*88col*:colors=88,*256col*:colors=256,xterm*:XT"
2223 .It Ic update-environment Ar variables
2224 Set a space-separated string containing a list of environment variables to be
2225 copied into the session environment when a new session is created or an
2226 existing session is attached.
2227 Any variables that do not exist in the source environment are set to be
2228 removed from the session environment (as if
2229 .Fl r
2230 was given to the
2231 .Ic set-environment
2232 command).
2233 The default is
2234 "DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID
2235 XAUTHORITY".
2236 .It Xo Ic visual-activity
2237 .Op Ic on | off
2239 If on, display a status line message when activity occurs in a window
2240 for which the
2241 .Ic monitor-activity
2242 window option is enabled.
2243 .It Xo Ic visual-bell
2244 .Op Ic on | off
2246 If this option is on, a message is shown on a bell instead of it being passed
2247 through to the terminal (which normally makes a sound).
2248 Also see the
2249 .Ic bell-action
2250 option.
2251 .It Xo Ic visual-content
2252 .Op Ic on | off
2254 Like
2255 .Ic visual-activity ,
2256 display a message when content is present in a window
2257 for which the
2258 .Ic monitor-content
2259 window option is enabled.
2260 .It Xo Ic visual-silence
2261 .Op Ic on | off
2264 .Ic monitor-silence
2265 is enabled, prints a message after the interval has expired on a given window.
2267 .It Xo Ic set-window-option
2268 .Op Fl agu
2269 .Op Fl t Ar target-window
2270 .Ar option Ar value
2272 .D1 (alias: Ic setw )
2273 Set a window option.
2275 .Fl a ,
2276 .Fl g
2278 .Fl u
2279 flags work similarly to the
2280 .Ic set-option
2281 command.
2283 Supported window options are:
2285 .Bl -tag -width Ds -compact
2286 .It Xo Ic aggressive-resize
2287 .Op Ic on | off
2289 Aggressively resize the chosen window.
2290 This means that
2292 will resize the window to the size of the smallest session for which it is the
2293 current window, rather than the smallest session to which it is attached.
2294 The window may resize when the current window is changed on another sessions;
2295 this option is good for full-screen programs which support
2296 .Dv SIGWINCH
2297 and poor for interactive programs such as shells.
2299 .It Xo Ic alternate-screen
2300 .Op Ic on | off
2302 This option configures whether programs running inside
2304 may use the terminal alternate screen feature, which allows the
2305 .Em smcup
2307 .Em rmcup
2308 .Xr terminfo 5
2309 capabilities.
2310 The alternate screen feature preserves the contents of the window when an
2311 interactive application starts and restores it on exit, so that any output
2312 visible before the application starts reappears unchanged after it exits.
2313 The default is on.
2315 .It Xo Ic automatic-rename
2316 .Op Ic on | off
2318 Control automatic window renaming.
2319 When this setting is enabled,
2321 will attempt - on supported platforms - to rename the window to reflect the
2322 command currently running in it.
2323 This flag is automatically disabled for an individual window when a name
2324 is specified at creation with
2325 .Ic new-window
2327 .Ic new-session ,
2328 or later with
2329 .Ic rename-window .
2330 It may be switched off globally with:
2331 .Bd -literal -offset indent
2332 set-window-option -g automatic-rename off
2335 .It Ic clock-mode-colour Ar colour
2336 Set clock colour.
2338 .It Xo Ic clock-mode-style
2339 .Op Ic 12 | 24
2341 Set clock hour format.
2343 .It Ic force-height Ar height
2344 .It Ic force-width Ar width
2345 Prevent
2347 from resizing a window to greater than
2348 .Ar width
2350 .Ar height .
2351 A value of zero restores the default unlimited setting.
2353 .It Ic main-pane-height Ar height
2354 .It Ic main-pane-width Ar width
2355 Set the width or height of the main (left or top) pane in the
2356 .Ic main-horizontal
2358 .Ic main-vertical
2359 layouts.
2361 .It Ic mode-attr Ar attributes
2362 Set window modes attributes.
2364 .It Ic mode-bg Ar colour
2365 Set window modes background colour.
2367 .It Ic mode-fg Ar colour
2368 Set window modes foreground colour.
2370 .It Xo Ic mode-keys
2371 .Op Ic vi | emacs
2373 Use vi or emacs-style key bindings in copy and choice modes.
2374 As with the
2375 .Ic status-keys
2376 option, the default is emacs, unless
2377 .Ev VISUAL
2379 .Ev EDITOR
2380 contains
2381 .Ql vi .
2383 .It Xo Ic mode-mouse
2384 .Op Ic on | off | copy-mode
2386 Mouse state in modes.
2387 If on, the mouse may be used to enter copy mode and copy a selection by
2388 dragging, to enter copy mode and scroll with the mouse wheel, or to select an
2389 option in choice mode.
2390 If set to
2391 .Em copy-mode ,
2392 the mouse behaves as set to on, but cannot be used to enter copy
2393 mode.
2395 .It Xo Ic monitor-activity
2396 .Op Ic on | off
2398 Monitor for activity in the window.
2399 Windows with activity are highlighted in the status line.
2401 .It Ic monitor-content Ar match-string
2402 Monitor content in the window.
2403 When
2404 .Xr fnmatch 3
2405 pattern
2406 .Ar match-string
2407 appears in the window, it is highlighted in the status line.
2409 .It Xo Ic monitor-silence
2410 .Op Ic interval
2412 Monitor for silence (no activity) in the window within
2413 .Ic interval
2414 seconds.
2415 Windows that have been silent for the interval are highlighted in the
2416 status line.
2417 An interval of zero disables the monitoring.
2419 .It Ic other-pane-height Ar height
2420 Set the height of the other panes (not the main pane) in the
2421 .Ic main-horizontal
2422 layout.
2423 If this option is set to 0 (the default), it will have no effect.
2424 If both the
2425 .Ic main-pane-height
2427 .Ic other-pane-height
2428 options are set, the main pane will grow taller to make the other panes the
2429 specified height, but will never shrink to do so.
2431 .It Ic other-pane-width Ar width
2432 Like
2433 .Ic other-pane-height ,
2434 but set the width of other panes in the
2435 .Ic main-vertical
2436 layout.
2438 .It Ic pane-base-index Ar index
2439 Like
2440 .Ic base-index ,
2441 but set the starting index for pane numbers.
2443 .It Xo Ic remain-on-exit
2444 .Op Ic on | off
2446 A window with this flag set is not destroyed when the program running in it
2447 exits.
2448 The window may be reactivated with the
2449 .Ic respawn-window
2450 command.
2452 .It Xo Ic synchronize-panes
2453 .Op Ic on | off
2455 Duplicate input to any pane to all other panes in the same window (only
2456 for panes that are not in any special mode).
2458 .It Xo Ic utf8
2459 .Op Ic on | off
2461 Instructs
2463 to expect UTF-8 sequences to appear in this window.
2465 .It Ic window-status-alert-attr Ar attributes
2466 Set status line attributes for windows which have an alert (bell, activity
2467 or content).
2469 .It Ic window-status-alert-bg Ar colour
2470 Set status line background colour for windows with an alert.
2472 .It Ic window-status-alert-fg Ar colour
2473 Set status line foreground colour for windows with an alert.
2475 .It Ic window-status-attr Ar attributes
2476 Set status line attributes for a single window.
2478 .It Ic window-status-bg Ar colour
2479 Set status line background colour for a single window.
2481 .It Ic window-status-current-attr Ar attributes
2482 Set status line attributes for the currently active window.
2484 .It Ic window-status-current-bg Ar colour
2485 Set status line background colour for the currently active window.
2487 .It Ic window-status-current-fg Ar colour
2488 Set status line foreground colour for the currently active window.
2490 .It Ic window-status-current-format Ar string
2491 Like
2492 .Ar window-status-format ,
2493 but is the format used when the window is the current window.
2495 .It Ic window-status-fg Ar colour
2496 Set status line foreground colour for a single window.
2498 .It Ic window-status-format Ar string
2499 Set the format in which the window is displayed in the status line window list.
2500 See the
2501 .Ar status-left
2502 option for details of special character sequences available.
2503 The default is
2504 .Ql #I:#W#F .
2506 .It Ic word-separators Ar string
2507 Sets the window's conception of what characters are considered word
2508 separators, for the purposes of the next and previous word commands in
2509 copy mode.
2510 The default is
2511 .Ql \ -_@ .
2513 .It Xo Ic xterm-keys
2514 .Op Ic on | off
2516 If this option is set,
2518 will generate
2519 .Xr xterm 1 -style
2520 function key sequences; these have a number included to indicate modifiers such
2521 as Shift, Alt or Ctrl.
2522 The default is off.
2524 .It Xo Ic show-options
2525 .Op Fl gsw
2526 .Op Fl t Ar target-session | Ar target-window
2528 .D1 (alias: Ic show )
2529 Show the window options with
2530 .Fl w
2531 (equivalent to
2532 .Ic show-window-options ) ,
2533 the server options with
2534 .Fl s ,
2535 otherwise the session options for
2536 .Ar target session .
2537 Global session or window options are listed if
2538 .Fl g
2539 is used.
2540 .It Xo Ic show-window-options
2541 .Op Fl g
2542 .Op Fl t Ar target-window
2544 .D1 (alias: Ic showw )
2545 List the window options for
2546 .Ar target-window ,
2547 or the global window options if
2548 .Fl g
2549 is used.
2551 .Sh FORMATS
2553 .Ic list-sessions ,
2554 .Ic list-windows
2556 .Ic list-panes
2557 commands accept the
2558 .Fl F
2559 flag with a
2560 .Ar format
2561 argument.
2562 This is a string which controls the output format of the command.
2563 Special character sequences are replaced as documented under the
2564 .Ic status-left
2565 option and an additional long form is accepted.
2566 Replacement variables are enclosed in
2567 .Ql #{
2569 .Ql } ,
2570 for example
2571 .Ql #{session_name}
2572 is equivalent to
2573 .Ql #S .
2574 Conditionals are also accepted by prefixing with
2575 .Ql \&?
2576 and separating two alternatives with a comma;
2577 if the specified variable exists and is not zero, the first alternative
2578 is chosen, otherwise the second is used.
2579 For example
2580 .Ql #{?session_attached,attached,not attached}
2581 will include the string
2582 .Ql attached
2583 if the session is attached and the string
2584 .Ql not attached
2585 if it is unattached.
2587 The following variables are available, where appropriate:
2588 .Bl -column "session_created_string" "Replaced with" -offset indent
2589 .It Sy "Variable name" Ta Sy "Replaced with"
2590 .It Li "host" Ta "Hostname of local host"
2591 .It Li "line" Ta "Line number in the list"
2592 .It Li "pane_active" Ta "1 if active pane"
2593 .It Li "pane_dead" Ta "1 if pane is dead"
2594 .It Li "pane_height" Ta "Height of pane"
2595 .It Li "pane_id" Ta "Unique pane id"
2596 .It Li "pane_title" Ta "Title of pane"
2597 .It Li "pane_width" Ta "Width of pane"
2598 .It Li "session_attached" Ta "1 if session attached"
2599 .It Li "session_created" Ta "Integer time session created"
2600 .It Li "session_created_string" Ta "String time session created"
2601 .It Li "session_group" Ta "Number of session group"
2602 .It Li "session_grouped" Ta "1 if session in a group"
2603 .It Li "session_height" Ta "Height of session"
2604 .It Li "session_name" Ta "Name of session"
2605 .It Li "session_width" Ta "Width of session"
2606 .It Li "session_windows" Ta "Number of windows in session"
2607 .It Li "window_active" Ta "1 if window active"
2608 .It Li "window_flags" Ta "Window flags"
2609 .It Li "window_height" Ta "Height of window"
2610 .It Li "window_index" Ta "Index of window"
2611 .It Li "window_layout" Ta "Window layout description"
2612 .It Li "window_name" Ta "Name of window"
2613 .It Li "window_width" Ta "Width of window"
2615 .Sh ENVIRONMENT
2616 When the server is started,
2618 copies the environment into the
2619 .Em global environment ;
2620 in addition, each session has a
2621 .Em session environment .
2622 When a window is created, the session and global environments are merged.
2623 If a variable exists in both, the value from the session environment is used.
2624 The result is the initial environment passed to the new process.
2627 .Ic update-environment
2628 session option may be used to update the session environment from the client
2629 when a new session is created or an old reattached.
2631 also initialises the
2632 .Ev TMUX
2633 variable with some internal information to allow commands to be executed
2634 from inside, and the
2635 .Ev TERM
2636 variable with the correct terminal setting of
2637 .Ql screen .
2639 Commands to alter and view the environment are:
2640 .Bl -tag -width Ds
2641 .It Xo Ic set-environment
2642 .Op Fl gru
2643 .Op Fl t Ar target-session
2644 .Ar name Op Ar value
2646 .D1 (alias: Ic setenv )
2647 Set or unset an environment variable.
2649 .Fl g
2650 is used, the change is made in the global environment; otherwise, it is applied
2651 to the session environment for
2652 .Ar target-session .
2654 .Fl u
2655 flag unsets a variable.
2656 .Fl r
2657 indicates the variable is to be removed from the environment before starting a
2658 new process.
2659 .It Xo Ic show-environment
2660 .Op Fl g
2661 .Op Fl t Ar target-session
2663 .D1 (alias: Ic showenv )
2664 Display the environment for
2665 .Ar target-session
2666 or the global environment with
2667 .Fl g .
2668 Variables removed from the environment are prefixed with
2669 .Ql - .
2671 .Sh STATUS LINE
2673 includes an optional status line which is displayed in the bottom line of each
2674 terminal.
2675 By default, the status line is enabled (it may be disabled with the
2676 .Ic status
2677 session option) and contains, from left-to-right: the name of the current
2678 session in square brackets; the window list; the current window title in double
2679 quotes; and the time and date.
2681 The status line is made of three parts: configurable left and right sections
2682 (which may contain dynamic content such as the time or output from a shell
2683 command, see the
2684 .Ic status-left ,
2685 .Ic status-left-length ,
2686 .Ic status-right ,
2688 .Ic status-right-length
2689 options below), and a central window list.
2690 By default, the window list shows the index, name and (if any) flag of the
2691 windows present in the current session in ascending numerical order.
2692 It may be customised with the
2693 .Ar window-status-format
2695 .Ar window-status-current-format
2696 options.
2697 The flag is one of the following symbols appended to the window name:
2698 .Bl -column "Symbol" "Meaning" -offset indent
2699 .It Sy "Symbol" Ta Sy "Meaning"
2700 .It Li "*" Ta "Denotes the current window."
2701 .It Li "-" Ta "Marks the last window (previously selected)."
2702 .It Li "#" Ta "Window is monitored and activity has been detected."
2703 .It Li "!" Ta "A bell has occurred in the window."
2704 .It Li "+" Ta "Window is monitored for content and it has appeared."
2705 .It Li "~" Ta "The window has been silent for the monitor-silence interval."
2708 The # symbol relates to the
2709 .Ic monitor-activity
2710 and + to the
2711 .Ic monitor-content
2712 window options.
2713 The window name is printed in inverted colours if an alert (bell, activity or
2714 content) is present.
2716 The colour and attributes of the status line may be configured, the entire
2717 status line using the
2718 .Ic status-attr ,
2719 .Ic status-fg
2721 .Ic status-bg
2722 session options and individual windows using the
2723 .Ic window-status-attr ,
2724 .Ic window-status-fg
2726 .Ic window-status-bg
2727 window options.
2729 The status line is automatically refreshed at interval if it has changed, the
2730 interval may be controlled with the
2731 .Ic status-interval
2732 session option.
2734 Commands related to the status line are as follows:
2735 .Bl -tag -width Ds
2736 .It Xo Ic command-prompt
2737 .Op Fl I Ar inputs
2738 .Op Fl p Ar prompts
2739 .Op Fl t Ar target-client
2740 .Op Ar template
2742 Open the command prompt in a client.
2743 This may be used from inside
2745 to execute commands interactively.
2748 .Ar template
2749 is specified, it is used as the command.
2750 If present,
2751 .Fl I
2752 is a comma-separated list of the initial text for each prompt.
2754 .Fl p
2755 is given,
2756 .Ar prompts
2757 is a comma-separated list of prompts which are displayed in order; otherwise
2758 a single prompt is displayed, constructed from
2759 .Ar template
2760 if it is present, or
2761 .Ql \&:
2762 if not.
2764 Both
2765 .Ar inputs
2767 .Ar prompts
2768 may contain the special character sequences supported by the
2769 .Ic status-left
2770 option.
2772 Before the command is executed, the first occurrence of the string
2773 .Ql %%
2774 and all occurrences of
2775 .Ql %1
2776 are replaced by the response to the first prompt, the second
2777 .Ql %%
2778 and all
2779 .Ql %2
2780 are replaced with the response to the second prompt, and so on for further
2781 prompts.
2782 Up to nine prompt responses may be replaced
2784 .Ql %1
2786 .Ql %9
2787 .Pc .
2788 .It Xo Ic confirm-before
2789 .Op Fl p Ar prompt
2790 .Op Fl t Ar target-client
2791 .Ar command
2793 .D1 (alias: Ic confirm )
2794 Ask for confirmation before executing
2795 .Ar command .
2797 .Fl p
2798 is given,
2799 .Ar prompt
2800 is the prompt to display; otherwise a prompt is constructed from
2801 .Ar command .
2802 It may contain the special character sequences supported by the
2803 .Ic status-left
2804 option.
2806 This command works only from inside
2807 .Nm .
2808 .It Xo Ic display-message
2809 .Op Fl p
2810 .Op Fl c Ar target-client
2811 .Op Fl t Ar target-pane
2812 .Op Ar message
2814 .D1 (alias: Ic display )
2815 Display a message.
2817 .Fl p
2818 is given, the output is printed to stdout, otherwise it is displayed in the
2819 .Ar target-client
2820 status line.
2821 The format of
2822 .Ar message
2823 is as for
2824 .Ic status-left ,
2825 with the exception that #() are not handled; information is taken from
2826 .Ar target-pane
2828 .Fl t
2829 is given, otherwise the active pane for the session attached to
2830 .Ar target-client .
2832 .Sh BUFFERS
2834 maintains a stack of
2835 .Em paste buffers .
2836 Up to the value of the
2837 .Ic buffer-limit
2838 option are kept; when a new buffer is added, the buffer at the bottom of the
2839 stack is removed.
2840 Buffers may be added using
2841 .Ic copy-mode
2842 or the
2843 .Ic set-buffer
2844 command, and pasted into a window using the
2845 .Ic paste-buffer
2846 command.
2848 A configurable history buffer is also maintained for each window.
2849 By default, up to 2000 lines are kept; this can be altered with the
2850 .Ic history-limit
2851 option (see the
2852 .Ic set-option
2853 command above).
2855 The buffer commands are as follows:
2856 .Bl -tag -width Ds
2857 .It Xo
2858 .Ic choose-buffer
2859 .Op Fl t Ar target-window
2860 .Op Ar template
2862 Put a window into buffer choice mode, where a buffer may be chosen
2863 interactively from a list.
2864 After a buffer is selected,
2865 .Ql %%
2866 is replaced by the buffer index in
2867 .Ar template
2868 and the result executed as a command.
2870 .Ar template
2871 is not given, "paste-buffer -b '%%'" is used.
2872 This command works only from inside
2873 .Nm .
2874 .It Ic clear-history Op Fl t Ar target-pane
2875 .D1 (alias: Ic clearhist )
2876 Remove and free the history for the specified pane.
2877 .It Ic delete-buffer Op Fl b Ar buffer-index
2878 .D1 (alias: Ic deleteb )
2879 Delete the buffer at
2880 .Ar buffer-index ,
2881 or the top buffer if not specified.
2882 .It Ic list-buffers
2883 .D1 (alias: Ic lsb )
2884 List the global buffers.
2885 .It Xo Ic load-buffer
2886 .Op Fl b Ar buffer-index
2887 .Ar path
2889 .D1 (alias: Ic loadb )
2890 Load the contents of the specified paste buffer from
2891 .Ar path .
2892 .It Xo Ic paste-buffer
2893 .Op Fl dr
2894 .Op Fl b Ar buffer-index
2895 .Op Fl s Ar separator
2896 .Op Fl t Ar target-pane
2898 .D1 (alias: Ic pasteb )
2899 Insert the contents of a paste buffer into the specified pane.
2900 If not specified, paste into the current one.
2901 With
2902 .Fl d ,
2903 also delete the paste buffer from the stack.
2904 When output, any linefeed (LF) characters in the paste buffer are replaced with
2905 a separator, by default carriage return (CR).
2906 A custom separator may be specified using the
2907 .Fl s
2908 flag.
2910 .Fl r
2911 flag means to do no replacement (equivalent to a separator of LF).
2912 .It Xo Ic save-buffer
2913 .Op Fl a
2914 .Op Fl b Ar buffer-index
2915 .Ar path
2917 .D1 (alias: Ic saveb )
2918 Save the contents of the specified paste buffer to
2919 .Ar path .
2921 .Fl a
2922 option appends to rather than overwriting the file.
2923 .It Xo Ic set-buffer
2924 .Op Fl b Ar buffer-index
2925 .Ar data
2927 .D1 (alias: Ic setb )
2928 Set the contents of the specified buffer to
2929 .Ar data .
2930 .It Xo Ic show-buffer
2931 .Op Fl b Ar buffer-index
2933 .D1 (alias: Ic showb )
2934 Display the contents of the specified buffer.
2936 .Sh MISCELLANEOUS
2937 Miscellaneous commands are as follows:
2938 .Bl -tag -width Ds
2939 .It Ic clock-mode Op Fl t Ar target-pane
2940 Display a large clock.
2941 .It Ic if-shell Ar shell-command command
2942 .D1 (alias: Ic if )
2943 Execute
2944 .Ar command
2946 .Ar shell-command
2947 returns success.
2948 .It Ic lock-server
2949 .D1 (alias: Ic lock )
2950 Lock each client individually by running the command specified by the
2951 .Ic lock-command
2952 option.
2953 .It Ic run-shell Ar shell-command
2954 .D1 (alias: Ic run )
2955 Execute
2956 .Ar shell-command
2957 in the background without creating a window.
2958 After it finishes, any output to stdout is displayed in copy mode.
2959 If the command doesn't return success, the exit status is also displayed.
2960 .It Ic server-info
2961 .D1 (alias: Ic info )
2962 Show server information and terminal details.
2964 .Sh TERMINFO EXTENSIONS
2966 understands some extensions to
2967 .Xr terminfo 5 :
2968 .Bl -tag -width Ds
2969 .It Em Cc , Cr
2970 Set the cursor colour.
2971 The first takes a single string argument and is used to set the colour;
2972 the second takes no arguments and restores the default cursor colour.
2973 If set, a sequence such as this may be used
2974 to change the cursor colour from inside
2975 .Nm :
2976 .Bd -literal -offset indent
2977 $ printf '\e033]12;red\e033\e\e'
2979 .It Em Cs , Csr
2980 Change the cursor style.
2981 If set, a sequence such as this may be used
2982 to change the cursor to an underline:
2983 .Bd -literal -offset indent
2984 $ printf '\e033[4 q'
2988 .Em Csr
2989 is set, it will be used to reset the cursor style instead
2991 .Em Cs .
2992 .It Em \&Ms
2993 This sequence can be used by
2995 to store the current buffer in the host terminal's selection (clipboard).
2996 See the
2997 .Em set-clipboard
2998 option above and the
2999 .Xr xterm 1
3000 man page.
3002 .Sh FILES
3003 .Bl -tag -width "/etc/tmux.confXXX" -compact
3004 .It Pa ~/.tmux.conf
3005 Default
3007 configuration file.
3008 .It Pa /etc/tmux.conf
3009 System-wide configuration file.
3011 .Sh EXAMPLES
3012 To create a new
3014 session running
3015 .Xr vi 1 :
3017 .Dl $ tmux new-session vi
3019 Most commands have a shorter form, known as an alias.
3020 For new-session, this is
3021 .Ic new :
3023 .Dl $ tmux new vi
3025 Alternatively, the shortest unambiguous form of a command is accepted.
3026 If there are several options, they are listed:
3027 .Bd -literal -offset indent
3028 $ tmux n
3029 ambiguous command: n, could be: new-session, new-window, next-window
3032 Within an active session, a new window may be created by typing
3033 .Ql C-b c
3034 (Ctrl
3035 followed by the
3036 .Ql b
3038 followed by the
3039 .Ql c
3040 key).
3042 Windows may be navigated with:
3043 .Ql C-b 0
3044 (to select window 0),
3045 .Ql C-b 1
3046 (to select window 1), and so on;
3047 .Ql C-b n
3048 to select the next window; and
3049 .Ql C-b p
3050 to select the previous window.
3052 A session may be detached using
3053 .Ql C-b d
3054 (or by an external event such as
3055 .Xr ssh 1
3056 disconnection) and reattached with:
3058 .Dl $ tmux attach-session
3060 Typing
3061 .Ql C-b \&?
3062 lists the current key bindings in the current window; up and down may be used
3063 to navigate the list or
3064 .Ql q
3065 to exit from it.
3067 Commands to be run when the
3069 server is started may be placed in the
3070 .Pa ~/.tmux.conf
3071 configuration file.
3072 Common examples include:
3074 Changing the default prefix key:
3075 .Bd -literal -offset indent
3076 set-option -g prefix C-a
3077 unbind-key C-b
3078 bind-key C-a send-prefix
3081 Turning the status line off, or changing its colour:
3082 .Bd -literal -offset indent
3083 set-option -g status off
3084 set-option -g status-bg blue
3087 Setting other options, such as the default command,
3088 or locking after 30 minutes of inactivity:
3089 .Bd -literal -offset indent
3090 set-option -g default-command "exec /bin/ksh"
3091 set-option -g lock-after-time 1800
3094 Creating new key bindings:
3095 .Bd -literal -offset indent
3096 bind-key b set-option status
3097 bind-key / command-prompt "split-window 'exec man %%'"
3098 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3100 .Sh SEE ALSO
3101 .Xr pty 4
3102 .Sh AUTHORS
3103 .An Nicholas Marriott Aq nicm@users.sourceforge.net