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