Annotation of src/usr.bin/tmux/tmux.1, Revision 1.3
1.3 ! pyr 1: .\" $OpenBSD: tmux.1,v 1.2 2009/06/01 23:51:00 nicm Exp $
1.1 nicm 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 April 20, 2009
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 28dqUuv
27: .Op Fl f Ar file
28: .Op Fl L Ar socket-name
29: .Op Fl S Ar socket-path
30: .Op Ar command Op Ar flags
31: .Ek
32: .Sh DESCRIPTION
33: .Nm
34: is a terminal multiplexer; it enables a number of terminals to be accessed and
35: controlled from a single terminal.
36: .Pp
37: .Nm
38: runs as a server-client system.
39: A server is created automatically when necessary and holds a number of
40: .Em sessions ,
41: each of which may have a number of
42: .Em windows
43: linked to it.
44: A window may be split on screen into one or more
45: .Em panes ,
46: each of which is a separate terminal.
47: Any number of
48: .Em clients
49: may connect to a session, or the server
50: may be controlled by issuing commands with
51: .Nm .
52: Communication takes place through a socket, by default placed in
53: .Pa /tmp .
54: .Pp
55: The options are as follows:
56: .Bl -tag -width "XXXXXXXXXXXX"
57: .It Fl 2
58: Force
59: .Nm
60: to assume the terminal supports 256 colours.
61: .It Fl 8
62: Like
63: .Fl 2 ,
64: indicates the terminal supports 88 colours.
65: .It Fl d
66: Force
67: .Nm
68: to assume the terminal supports default colours.
69: .It Fl f Ar file
70: Specify an alternative configuration file.
71: By default,
72: .Nm
73: will look for a config file at
74: .Pa ~/.tmux.conf .
75: The configuration file is a set of
76: .Nm
77: commands which are executed in sequence when the server is first started.
78: .It Fl q
79: Prevent the server sending various information messages, for example when
80: window flags are altered.
81: .It Fl L Ar socket-name
82: .Nm
83: stores the server socket in a directory under
84: .Pa /tmp ;
85: the default socket is named
86: .Em default .
87: This option allows a different socket name to be specified, allowing several
88: independent
89: .Nm
90: servers to be run.
91: Unlike
92: .Fl S
93: a full path is not necessary: the sockets are all created in the same
94: directory.
1.2 nicm 95: .Pp
96: If the socket is accidentally removed, the
97: .Em SIGUSR1
98: signal may be sent to the
99: .Nm
100: server process to recreate it.
1.1 nicm 101: .It Fl S Ar socket-path
102: Specify a full alternative path to the server socket.
103: If
104: .Fl S
105: is specified, the default socket directory is not used and any
106: .Fl L
107: flag is ignored.
108: .It Fl U
109: Unlock the server.
110: .It Fl u
111: .Nm
1.2 nicm 112: attempts to guess if the terminal is likely to support UTF-8 by first checking
113: the
114: .Ev LANG
115: environment variable for the string "UTF-8", and then by - if the terminal
116: looks suitable - trying to print a UTF-8 character and measuring the cursor
117: movement.
118: These are not always successful: the
119: .Fl u
120: flag explicitly informs
121: .Nm
122: that the UTF-8 is supported.
1.1 nicm 123: .It Fl v
124: Request verbose logging.
125: This option may be specified multiple times for increasing verbosity.
126: Log messages will be saved into
127: .Pa tmux-client-PID.log
128: and
129: .Pa tmux-server-PID.log
130: files in the current directory, where
131: .Em PID
132: is the pid of the server or client process.
133: .It Ar command Op Ar flags
134: This specifies one of a set of commands used to control
135: .Nm ,
136: and described in the following sections.
137: If no command and flags is specified, the
138: .Ic new-session
139: command is assumed.
140: .Pp
141: .El
142: .Sh QUICK START
143: To create a new tmux session running
144: .Xr vi 1 :
145: .Pp
146: .Dl $ tmux new-session vi
147: .Pp
148: Most commands have a shorter form, known as an alias.
149: For new-session, this is
150: .Ic new :
151: .Pp
152: .Dl $ tmux new vi
153: .Pp
154: Alternatively, the shortest unambiguous form of a command is accepted.
155: If there are several options, they are listed:
156: .Bd -literal -offset indent
157: $ tmux n
158: ambiguous command: n, could be: new-session, new-window, next-window
159: $
160: .Ed
161: .Pp
162: Within an active session, a new window may be created by typing
163: .Ql C-b
164: (ctrl-b, known as the prefix key)
165: followed by the
166: .Ql c
167: key.
168: .Pp
169: Windows may be navigated with:
170: .Ql C-b 0
171: (to select window 0),
172: .Ql C-b 1
173: (to select window 1), and so on;
174: .Ql C-b n
175: to select the next window; and
176: .Ql C-b p
177: to select the previous window.
178: .Pp
179: A session may be detached using
180: .Ql C-b d
181: and reattached with:
182: .Pp
183: .Dl $ tmux attach-session
184: .Pp
185: Typing
186: .Ql C-b \&?
187: lists the current key bindings in the current window; up and down may be used
188: to navigate the list or
189: .Ql Q
190: to exit from it.
191: .Sh KEY BINDINGS
192: .Nm
193: may be controlled from an attached client by using a key combination of a
194: prefix key,
195: .Ql C-b
196: (ctrl-b) by default, followed by a command key.
197: .Pp
198: Some of the default key bindings include:
199: .Pp
200: .Bl -tag -width Ds -compact
201: .It Ql d
202: Detach current client.
203: .It Ql c
204: Create new window.
205: .It Ql n
206: Change to next window in the current session.
207: .It Ql p
208: Change to previous window in the current session.
209: .It Ql l
210: Move to last (previously selected) window in the current session.
211: .It Ql t
212: Display a large clock.
213: .It Ql \&?
214: List current key bindings.
215: .El
216: .Pp
217: A complete list may be obtained with the
218: .Ic list-keys
219: command (bound to
220: .Ql \&?
221: by default).
222: Key bindings may be changed with the
223: .Ic bind-key
224: and
225: .Ic unbind-key
226: commands.
227: .Sh HISTORY
228: .Nm
229: maintains a configurable history buffer for each window.
230: By default, up to 2000 lines are kept, this can be altered with the
231: .Ic history-limit
232: option (see the
233: .Ic set-option
234: command below).
235: .Sh MODES
236: A
237: .Nm
238: window may be in one of several modes.
239: The default permits direct access to the terminal attached to the window.
240: The others are:
241: .Bl -tag -width Ds
242: .It Em output mode
243: This is entered when a command which produces output, such as
244: .Ic list-keys ,
245: is executed from a key binding.
246: .It Em scroll mode
247: This is entered with the
248: .Ic scroll-mode
249: command (bound to
250: .Ql =
251: by default) and permits the window history buffer to be inspected.
252: .It Em copy mode
253: This permits a section of a window or its history to be copied to a
254: .Em paste buffer
255: for later insertion into another window.
256: This mode is entered with the
257: .Ic copy-mode
258: command, bound to
259: .Ql [
260: by default.
261: .El
262: .Pp
263: The keys available depend on whether
264: .Xr emacs 1
265: or
266: .Xr vi 1
267: mode is selected (see the
268: .Ic mode-keys
269: option).
270: The following keys are supported as appropriate for the mode:
271: .Bl -column "FunctionXXXXXXXXXXXX" "viXXXXXX" "emacs" -offset indent
272: .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
273: .It Li "Start of line" Ta "0 or ^" Ta "C-a"
274: .It Li "Clear selection" Ta "Escape" Ta "C-g"
275: .It Li "Copy selection" Ta "Enter" Ta "M-w"
276: .It Li "Cursor down" Ta "j" Ta "Down"
277: .It Li "End of line" Ta "$" Ta "C-e"
278: .It Li "Cursor left" Ta "h" Ta "Left"
279: .It Li "Next page" Ta "C-f" Ta "Page down"
280: .It Li "Next word" Ta "w" Ta "M-f"
281: .It Li "Previous page" Ta "C-u" Ta "Page up"
282: .It Li "Previous word" Ta "b" Ta "M-b"
283: .It Li "Quit mode" Ta "q" Ta "Escape"
284: .It Li "Cursor right" Ta "l" Ta "Right"
285: .It Li "Start selection" Ta "Space" Ta "C-Space"
286: .It Li "Cursor up" Ta "k" Ta "Up"
1.2 nicm 287: .It Li "Paste buffer" Ta "p" Ta "C-y"
1.1 nicm 288: .El
289: .Pp
1.2 nicm 290: The paste buffer key pastes the first line from the top paste buffer on the
291: stack.
1.1 nicm 292: .Sh BUFFERS
293: .Nm
294: maintains a stack of
295: .Em paste buffers
296: for each session.
297: Up to the value of the
298: .Ic buffer-limit
299: option are kept; when a new buffer is added, the buffer at the bottom of the
300: stack is removed.
301: Buffers may be added using
302: .Ic copy-mode
303: or the
304: .Ic set-buffer
305: command, and pasted into a window using the
306: .Ic paste-buffer
307: command.
308: .Sh PANES AND LAYOUTS
309: Each window displayed by
310: .Nm
311: may be split into one or more
312: .Em panes ;
313: each pane takes up a certain area of the display and is a separate terminal.
314: A window may be split into panes using the
315: .Ic split-window
316: command.
317: .Pp
318: Panes are numbered beginning from zero; in horizontal layouts zero is the
319: leftmost pane and in vertical the topmost.
320: .Pp
321: Panes may be arranged using several layouts.
322: The layout may be cycled with the
323: .Ic next-layout
324: command (bound to
325: .Ql C-space
326: by default), the current pane may be changed with the
327: .Ic up-pane
328: and
329: .Ic down-pane
330: commands and the
331: .Ic rotate-window
332: and
333: .Ic swap-pane
334: commands may be used to swap panes without changing the window layout.
335: .Pp
336: The following layouts are supported:
337: .Bl -tag -width Ds
338: .It Ic manual
339: Manual layout splits windows vertically (running across); only with this layout
340: may panes be resized using the
341: .Ic resize-pane
342: command.
343: .It Ic active-only
344: Only the active pane is shown - all other panes are hidden.
345: .It Ic even-horizontal
346: Panes are spread out evenly from left to right across the window.
347: .It Ic even-vertical
348: Panes are spread evenly from top to bottom.
1.2 nicm 349: .It Ic main-horizontal
350: A large (main) pane is shown at the top of the window and the remaining panes are
351: spread from left to right in the leftover space at the bottom.
352: Use the
353: .Em main-pane-height
354: window option to specify the height of the top pane.
1.1 nicm 355: .It Ic main-vertical
1.2 nicm 356: Similar to
357: .Ic main-horizontal
358: but the large pane is placed on the left and the others spread from top to
359: bottom along the right.
360: See the
361: .Em main-pane-width
362: window option.
1.1 nicm 363: .El
364: .Sh COMMANDS
365: This section contains a list of the commands supported by
366: .Nm .
367: Most commands accept the optional
368: .Fl t
369: argument with one of
370: .Ar target-client ,
371: .Ar target-session
372: or
373: .Ar target-window .
374: These specify the client, session or window which a command should affect.
375: .Ar target-client
376: is the name of the
377: .Xr pty 4
378: file to which the client is connected, for example
379: .Pa /dev/ttyp1 .
380: Clients may be listed with the
381: .Ic list-clients
382: command.
383: .Pp
384: .Ar target-session
385: is either the name of a session (as listed by the
386: .Ic list-sessions
387: command); or the name of a client as for
388: .Ar target-client ,
389: in this case, the session attached to the client is used.
390: An
391: .Xr fnmatch 3
392: pattern may be used to match the session name.
393: If a session is omitted when required,
394: .Nm tmux
395: attempts to use the current session; if no current session is available, the
396: most recently created is chosen.
397: If no client is specified, the current client is chosen, if possible, or an
398: error is reported.
399: .Pp
400: .Ar target-window
401: specifies a window in the form
402: .Em session Ns \&: Ns Em index ,
403: for example mysession:1.
404: The session is in the same form as for
405: .Ar target-session .
406: .Em session ,
407: .Em index
408: or both may be omitted.
409: If
410: .Em session
411: is omitted, the same rules as for
412: .Ar target-session
413: are followed; if
414: .Em index
415: is not present, the current window for the given session is used.
416: When the argument does not contain a colon (:),
417: .Nm
418: first attempts to parse it as window index; if that fails, an attempt is made
419: to match a session or client name.
420: .Pp
421: Multiple commands may be specified together as part of a
422: .Em command sequence .
423: Each command should be separated by spaces and a semicolon
424: .Eo ( Ql \& \&; \& Ec ) ;
425: commands are executed sequentially from left to right.
426: A literal semicolon may be included by escaping it with a backslash (for
427: example, when specifying a command sequence to
428: .Ic bind-key ) .
429: .Pp
430: Examples include:
431: .Pp
432: .Bd -literal -offset indent
433: refresh-client -t/dev/ttyp2
434:
435: rename-session -tfirst newname
436:
437: set-window-option -t:0 monitor-activity on
438:
439: new-window ; split-window -d
440:
441: bind-key D detach-client \e\; lock-server
442: .Ed
443: .Pp
444: The following commands are available:
445: .Bl -tag -width Ds
446: .It Xo Ic attach-session
447: .Op Fl d
448: .Op Fl t Ar target-session
449: .Xc
450: .D1 (alias: Ic attach )
451: Create a new client in the current terminal and attach it to a session.
452: If
453: .Fl d
454: is specified, any other clients attached to the session are detached.
455: .Pp
456: If no server is started,
457: .Ic attach-session
458: will attempt to start it; this will fail unless sessions are created in the
459: configuration file.
460: .It Xo Ic bind-key
461: .Op Fl r
462: .Ar key Ar command Op Ar arguments
463: .Xc
464: .D1 (alias: Ic bind )
465: Bind key
466: .Ar key
467: to
468: .Ar command .
469: Keys may be specified prefixed with
470: .Ql C-
471: or
472: .Ql ^
473: for ctrl keys, or
474: .Ql M-
475: for alt (meta) keys.
476: The
477: .Fl r
478: flag indicates this key may repeat, see the
479: .Ic repeat-time
480: option.
481: .It Xo Ic break-pane
482: .Op Fl d
483: .Op Fl p Ar pane-index
484: .Op Fl t Ar target-window
485: .Xc
486: .D1 (alias: Ic breakp)
487: Break the current pane off from its containing window to make it the only pane
488: in a new window.
489: If
490: .Fl d
491: is given, the new window does not become the current window.
492: .It Xo Ic choose-session
493: .Op Fl t Ar target-window
494: .Xc
495: Put a window into session choice mode, where the session for the current
496: client may be selected interactively from a list.
497: This command works only from inside
498: .Nm .
499: .It Xo Ic choose-window
500: .Op Fl t Ar target-window
501: .Xc
502: Put a window into window choice mode, where the window for the session
503: attached to the current client may be selected interactively from a list.
504: This command works only from inside
505: .Nm .
1.2 nicm 506: .It Xo Ic clear-history
507: .Op Fl p Ar pane-index
508: .Op Fl t Ar target-window
509: .Xc
510: .D1 (alias: Ic clearhist)
511: Remove and free the history for the specified pane.
1.1 nicm 512: .It Xo Ic clock-mode
513: .Op Fl t Ar target-window
514: .Xc
515: Display a large clock.
516: .It Xo Ic command-prompt
517: .Op Fl t Ar target-client
518: .Op Ar template
519: .Xc
520: Open the command prompt in a client.
521: This may be used from inside
522: .Nm
523: to execute commands interactively.
524: If
525: .Ar template
526: is specified, it is used as the command; any %% in the template will be
527: replaced by what is entered at the prompt.
528: .It Xo Ic confirm-before
529: .Op Fl t Ar target-client
530: .Ar command
531: .Xc
532: .D1 (alias: Ic confirm)
533: Ask for confirmation before executing
534: .Ar command .
535: This command works only from inside
536: .Nm .
537: .It Xo Ic copy-buffer
538: .Op Fl a Ar src-index
539: .Op Fl b Ar dst-index
540: .Op Fl s Ar src-session
541: .Op Fl t Ar dst-session
542: .Xc
543: .D1 (alias: Ic copyb)
544: Copy a session paste buffer to another session.
545: If no sessions are specified, the current one is used instead.
546: .It Xo Ic copy-mode
547: .Op Fl u
548: .Op Fl t Ar target-window
549: .Xc
550: Enter copy mode.
551: The
552: .Fl u
553: option scrolls one page up.
554: .It Xo Ic delete-buffer
555: .Op Fl b Ar buffer-index
556: .Op Fl t Ar target-session
557: .Xc
558: .D1 (alias: Ic deleteb )
559: Delete the buffer at
560: .Ar buffer-index ,
561: or the top buffer if not specified.
562: .It Xo Ic detach-client
563: .Op Fl t Ar target-client
564: .Xc
565: .D1 (alias: Ic detach )
566: Detach the current client if bound to a key, or the specified client with
567: .Fl t .
568: .It Xo Ic down-pane
569: .Op Fl p Ar pane-index
570: .Op Fl t Ar target-window
571: .Xc
572: .D1 (alias: Ic downp )
573: Move down a pane.
574: .It Xo Ic find-window
575: .Op Fl t Ar target-window
576: .Ar match-string
577: .Xc
578: .D1 (alias: Ic findw )
579: Search for
580: .Ar match-string
581: in window names, titles, and visible content (but not history).
582: If only one window is matched, it'll be automatically selected, otherwise a
583: choice list is shown.
584: This command only works from inside
585: .Nm .
586: .It Xo Ic has-session
587: .Op Fl t Ar target-session
588: .Xc
589: .D1 (alias: Ic has )
590: Report an error and exit with 1 if the specified session does not exist.
591: If it does exist, exit with 0.
592: .It Xo Ic kill-pane
593: .Op Fl p Ar pane-index
594: .Op Fl t Ar target-window
595: .Xc
596: .D1 (alias: Ic killp )
597: Destroy the given pane.
598: .It Xo Ic kill-server
599: .Xc
600: Kill the
601: .Nm
602: server and clients and destroy all sessions.
603: .It Xo Ic kill-session
604: .Op Fl t Ar target-session
605: .Xc
606: Destroy the given session, closing any windows linked to it and no other
607: sessions, and detaching all clients attached to it.
608: .It Xo Ic kill-window
609: .Op Fl t Ar target-window
610: .Xc
611: .D1 (alias: Ic killw )
612: Kill the current window or the window at
613: .Ar target-window ,
614: removing it from any sessions to which it is linked.
615: .It Xo Ic last-window
616: .Op Fl t Ar target-session
617: .Xc
618: .D1 (alias: Ic last )
619: Select the last (previously selected) window.
620: If no
621: .Ar target-session
622: is specified, select the last window of the current session.
623: .It Xo Ic link-window
624: .Op Fl dk
625: .Op Fl s Ar src-window
626: .Op Fl t Ar dst-window
627: .Xc
628: .D1 (alias: Ic linkw )
629: Link the window at
630: .Ar src-window
631: to the specified
632: .Ar dst-window .
633: If
634: .Ar dst-window
635: is specified and no such window exists, the
636: .Ar src-window
637: is linked there.
638: If
639: .Fl k
640: is given and
641: .Ar dst-window
642: exists, it is killed, otherwise an error is generated.
643: If
644: .Fl d
645: is given, the newly linked window is not selected.
646: .It Xo Ic list-buffers
647: .Op Fl t Ar target-session
648: .Xc
649: .D1 (alias: Ic lsb )
650: List the buffers in the given session.
651: .It Xo Ic list-clients
652: .Xc
653: .D1 (alias: Ic lsc )
654: List all clients attached to the server.
655: .It Xo Ic list-commands
656: .Xc
657: .D1 (alias: Ic lscm )
658: List the syntax of all commands supported by
659: .Nm .
660: .It Xo Ic list-keys
661: .Xc
662: .D1 (alias: Ic lsk )
663: List all key bindings.
664: .It Xo Ic list-sessions
665: .Xc
666: .D1 (alias: Ic ls )
667: List all sessions managed by the server.
668: .It Xo Ic list-windows
669: .Op Fl t Ar target-session
670: .Xc
671: .D1 (alias: Ic lsw )
672: List windows in the current session or in
673: .Ar target-session .
674: .It Xo Ic load-buffer
675: .Op Fl b Ar buffer-index
676: .Op Fl t Ar target-session
677: .Ar path
678: .Xc
679: .D1 (alias: Ic loadb )
680: Load the contents of the specified paste buffer from
681: .Ar path .
682: .It Xo Ic lock-server
683: .Xc
684: .D1 (alias: Ic lock )
685: Lock the server until a password is entered.
686: .It Xo Ic move-window
687: .Op Fl d
688: .Op Fl s Ar src-window
689: .Op Fl t Ar dst-window
690: .Xc
691: .D1 (alias: Ic movew )
692: This is similar to
693: .Ic link-window ,
694: except the window at
695: .Ar src-window
696: is moved to
697: .Ar dst-window .
698: .It Xo Ic new-session
699: .Op Fl d
700: .Op Fl n Ar window-name
701: .Op Fl s Ar session-name
702: .Op Ar command
703: .Xc
704: .D1 (alias: Ic new )
705: Create a new session with name
706: .Ar session-name .
707: The new session is attached to the current terminal unless
708: .Fl d
709: is given.
710: .Ar window-name
711: and
712: .Ar command
713: are the name of and command to execute in the initial window.
714: .It Xo Ic new-window
715: .Op Fl d
716: .Op Fl n Ar window-name
717: .Op Fl t Ar target-window
718: .Op Ar command
719: .Xc
720: .D1 (alias: Ic neww )
721: Create a new window.
722: If
723: .Fl d
724: is given, the session does not make the new window the current window.
725: .Ar target-window
726: represents the window to be created.
727: .Ar command
728: is the command to execute.
729: If
730: .Ar command
731: is not specified, the default command is used.
732: .Pp
733: The
734: .Ev TERM
735: environment variable must be set to
736: .Dq screen
737: for all programs running
738: .Em inside
739: .Nm .
740: New windows will automatically have
741: .Dq TERM=screen
742: added to their environment, but care must be taken not to reset this in shell
743: start-up files.
744: .It Xo Ic next-layout
745: .Op Fl t Ar target-window
746: .Xc
747: .D1 (alias: Ic nextl )
748: Move a window to the next layout and rearrange the panes to fit.
749: .It Xo Ic next-window
750: .Op Fl t Ar target-session
751: .Xc
752: .D1 (alias: Ic next )
753: Move to the next window in the session.
754: .It Xo Ic paste-buffer
755: .Op Fl d
756: .Op Fl b Ar buffer-index
757: .Op Fl t Ar target-window
758: .Xc
759: .D1 (alias: Ic pasteb )
760: Insert the contents of a paste buffer into the current window.
761: .It Xo Ic previous-window
762: .Op Fl t Ar target-session
763: .Xc
764: .D1 (alias: Ic prev )
765: Move to the previous window in the session.
766: .It Xo Ic refresh-client
767: .Op Fl t Ar target-client
768: .Xc
769: .D1 (alias: Ic refresh )
770: Refresh the current client if bound to a key, or a single client if one is given
771: with
772: .Fl t .
773: .It Xo Ic rename-session
774: .Op Fl t Ar target-session
775: .Ar new-name
776: .Xc
777: .D1 (alias: Ic rename )
778: Rename the session to
779: .Ar new-name .
780: .It Xo Ic rename-window
781: .Op Fl t Ar target-window
782: .Ar new-name
783: .Xc
784: .D1 (alias: Ic renamew )
785: Rename the current window, or the window at
786: .Ar target-window
787: if specified, to
788: .Ar new-name .
789: .It Xo Ic resize-pane
790: .Op Fl DU
791: .Op Fl p Ar pane-index
792: .Op Fl t Ar target-window
793: .Op Ar adjustment
794: .Xc
795: .D1 (alias: Ic resizep )
796: Resize a pane, upward with
797: .Fl U
798: (the default) or downward with
799: .Fl D .
800: The
801: .Ar adjustment
802: is given in lines (the default is 1).
803: .It Xo Ic respawn-window
804: .Op Fl k
805: .Op Fl t Ar target-window
806: .Op Ar command
807: .Xc
808: .D1 (alias: Ic respawnw )
809: Reactive a window in which the command has exited (see the
810: .Ic remain-on-exit
811: window option).
812: If
813: .Ar command
814: is not given, the command used when the window was created is executed.
815: The window must be already inactive, unless
816: .Fl k
817: is given, in which case any existing command is killed.
818: .It Xo Ic rotate-window
819: .Op Fl DU
820: .Op Fl t Ar target-window
821: .Xc
822: .D1 (alias: Ic rotatew )
823: Rotate the positions of the panes within a window, either upward (numerically
824: lower) with
825: .Fl U
826: or downward (numerically higher).
827: .It Xo Ic save-buffer
828: .Op Fl a
829: .Op Fl b Ar buffer-index
830: .Op Fl t Ar target-session
831: .Ar path
832: .Xc
833: .D1 (alias: Ic saveb )
834: Save the contents of the specified paste buffer to
835: .Ar path .
836: The
837: .Fl a
838: option appends to rather than overwriting the file.
839: .It Xo Ic scroll-mode
840: .Op Fl u
841: .Op Fl t Ar target-window
842: .Xc
843: Enter scroll mode.
844: The
845: .Fl u
846: has the same meaning as in the
847: .Ic copy-mode
848: command.
1.2 nicm 849: .It Xo Ic select-layout
850: .Op Fl t Ar target-window
851: .Ar layout-name
852: .Xc
853: .D1 (alias: selectl)
854: Choose a specific layout for a window.
1.1 nicm 855: .It Xo Ic select-pane
856: .Op Fl p Ar pane-index
857: .Op Fl t Ar target-window
858: .Xc
859: .D1 (alias: Ic selectp )
860: Make pane
861: .Ar pane-index
862: the active pane in window
863: .Ar target-window .
864: .It Xo Ic select-prompt
865: .Op Fl t Ar target-client
866: .Xc
867: Open a prompt inside
868: .Ar target-client
869: allowing a window index to be entered interactively.
870: .It Xo Ic select-window
871: .Op Fl t Ar target-window
872: .Xc
873: .D1 (alias: Ic selectw )
874: Select the window at
875: .Ar target-window .
876: .It Xo Ic send-keys
877: .Op Fl t Ar target-window
878: .Ar key Ar ...
879: .Xc
880: .D1 (alias: Ic send )
881: Send a key or keys to a window.
882: Each argument
883: .Ar key
884: is the name of the key (such as
885: .Ql C-a
886: or
887: .Ql npage
888: ) to send; if the string is not recognised as a key, it is sent as a series of
889: characters.
890: All arguments are sent sequentially from first to last.
891: .It Xo Ic send-prefix
892: .Op Fl t Ar target-window
893: .Xc
894: Send the prefix key to a window as if it was pressed.
895: .It Xo Ic server-info
896: .Xc
897: .D1 (alias: Ic info )
898: Show server information and terminal details.
899: .It Xo Ic set-buffer
900: .Op Fl b Ar buffer-index
901: .Op Fl t Ar target-session
902: .Ar data
903: .Xc
904: .D1 (alias: Ic setb )
905: Set the contents of the specified buffer to
906: .Ar data .
907: .It Xo Ic set-option
908: .Op Fl gu
909: .Op Fl t Ar target-session
910: .Ar option Ar value
911: .Xc
912: .D1 (alias: Ic set )
913: Set an option.
914: If
915: .Fl g
916: is specified, the option is set as a global option.
917: Global options apply to all sessions which don't have the option explicitly
918: set.
919: If
920: .Fl g
921: is not used, the option applies only to
922: .Ar target-session .
923: The
924: .Fl u
925: flag unsets an option, so a session inherits the option from the global
926: options - it is not possible to unset a global option.
927: .Pp
928: Possible options are:
929: .Bl -tag -width Ds
930: .It Xo Ic bell-action
931: .Op Ic any | Ic none | Ic current
932: .Xc
933: Set action on window bell.
934: .Ic any
935: means a bell in any window linked to a session causes a bell in the current
936: window of that session,
937: .Ic none
938: means all bells are ignored and
939: .Ic current
940: means only bell in windows other than the current window are ignored.
941: .It Ic buffer-limit Ar number
942: Set the number of buffers kept for each session; as new buffers are added to
943: the top of the stack, old ones are removed from the bottom if necessary to
944: maintain this maximum length.
945: .It Ic default-command Ar command
946: Set the command used for new windows (if not specified when the window is
947: created) to
948: .Ar command .
949: The default is
1.3 ! pyr 950: .Dq exec $SHELL -l .
1.1 nicm 951: .It Ic default-path Ar path
952: Set the default working directory for processes created from keys, or
953: interactively from the prompt.
954: The default is the current working directory when the server is started.
955: .It Ic history-limit Ar lines
956: Set the maximum number of lines held in window history.
957: This setting applies only to new windows - existing window histories are not
958: resized and retain the limit at the point they were created.
959: .It Ic lock-after-time Ar number
960: Lock the server after
961: .Ar number
962: seconds of inactivity.
963: The default is off (set to 0).
964: This has no effect as a session option; it must be set as a global option using
965: .Fl g .
966: .It Ic message-attr Ar attributes
967: Set status line message attributes, where
968: .Ar attributes
969: is either
970: .Ic default
971: or a comma-delimited list of one or more of:
972: .Ic bright
973: (or
974: .Ic bold ) ,
975: .Ic dim ,
976: .Ic underscore ,
977: .Ic blink ,
978: .Ic reverse ,
979: .Ic hidden ,
980: or
981: .Ic italics .
982: .It Ic message-bg Ar colour
983: Set status line message background colour, where
984: .Ar colour
985: is one of:
986: .Ic black ,
987: .Ic red ,
988: .Ic green ,
989: .Ic yellow ,
990: .Ic blue ,
991: .Ic magenta ,
992: .Ic cyan ,
993: .Ic white
994: or
995: .Ic default .
996: .It Ic message-fg Ar colour
997: Set status line message foreground colour.
998: .It Ic prefix Ar key
999: Set the current prefix key.
1000: .It Ic repeat-time Ar number
1001: Allow multiple commands to be entered without pressing the prefix-key again
1002: in the specified
1003: .Ar number
1004: milliseconds (the default is 500).
1005: Whether a key repeats may be set when it is bound using the
1006: .Fl r
1007: flag to
1008: .Ic bind-key .
1009: Repeat is enabled for the default keys of the
1010: .Ic up-pane ,
1011: .Ic down-pane ,
1012: .Ic resize-pane-up ,
1013: and
1014: .Ic resize-pane-down
1015: commands.
1016: .It Xo Ic set-remain-on-exit
1017: .Op Ic on | Ic off
1018: .Xc
1019: Set the
1020: .Ic remain-on-exit
1021: window option for any windows first created in this session.
1022: .It Xo Ic set-titles
1023: .Op Ic on | Ic off
1024: .Xc
1025: Attempt to set the window title using the \ee]2;...\e007 xterm code and
1026: the terminal appears to be an xterm.
1027: This option is enabled by default.
1028: Note that
1029: .Xr elinks 1
1030: will only attempt to set the window title if the STY environment
1031: variable is set.
1032: .It Xo Ic status
1033: .Op Ic on | Ic off
1034: .Xc
1035: Show or hide the status line.
1036: .It Ic status-attr Ar attributes
1037: Set status line attributes.
1038: .It Ic status-bg Ar colour
1039: Set status line background colour.
1040: .It Ic status-fg Ar colour
1041: Set status line foreground colour.
1042: .It Ic status-interval Ar interval
1043: Update the status bar every
1044: .Ar interval
1045: seconds.
1046: By default, updates will occur every 15 seconds.
1047: A setting of zero disables redrawing at interval.
1048: .It Xo Ic status-keys
1049: .Op Ic vi | Ic emacs
1050: .Xc
1051: Use
1052: .Xr vi 1 -
1053: or
1054: .Xr emacs 1 -style
1055: key bindings in the status line, for example at the command prompt.
1056: Defaults to emacs.
1057: .It Ic status-left Ar string
1058: Display
1059: .Ar string
1060: to the left of the status bar.
1061: .Ar string
1062: will be passed through
1063: .Xr strftime 3
1064: before being used.
1065: By default, the session name is shown.
1066: .Ar string
1067: may contain any of the following special character pairs:
1068: .Bl -column "Character pair" "Replaced with" -offset indent
1069: .It Sy "Character pair" Ta Sy "Replaced with"
1070: .It Li "#(command)" Ta "First line of command's output"
1071: .It Li "#H" Ta "Hostname of local host"
1072: .It Li "#S" Ta "Session name"
1073: .It Li "#T" Ta "Current window title"
1074: .It Li "##" Ta "A literal" Ql #
1075: .El
1076: .Pp
1077: Where appropriate, these may be prefixed with a number to specify the maximum
1078: length, for example
1079: .Ql #24T .
1080: .It Ic status-left-length Ar length
1081: Set the maximum
1082: .Ar length
1083: of the left component of the status bar.
1084: The default is 10.
1085: .It Ic status-right Ar string
1086: Display
1087: .Ar string
1088: to the right of the status bar.
1089: By default, the date and time will be shown.
1090: As with
1091: .Ic status-left ,
1092: .Ar string
1093: will be passed to
1094: .Xr strftime 3
1095: and character pairs are replaced.
1096: .It Ic status-right-length Ar length
1097: Set the maximum
1098: .Ar length
1099: of the right component of the status bar.
1100: The default is 40.
1101: .El
1102: .It Xo Ic set-password
1103: .Op Fl c
1104: .Ar password
1105: .Xc
1106: .D1 (alias: Ic pass )
1107: Set the server password.
1108: If the
1109: .Fl c
1110: option is given, a pre-encrypted password may be specified.
1111: By default, the password is blank, thus any entered password will be accepted
1112: when unlocking the server (see the
1113: .Ic lock-server
1114: command).
1115: To prevent variable expansion when an encrypted password is read from a
1116: configuration file, enclose it in single quotes (').
1117: .It Xo Ic set-window-option
1118: .Op Fl gu
1119: .Op Fl t Ar target-window
1120: .Ar option Ar value
1121: .Xc
1122: .D1 (alias: Ic setw )
1123: Set a window-specific option.
1124: The
1125: .Fl g
1126: and
1127: .Fl u
1128: flags work similarly to the
1129: .Ic set-option
1130: command.
1131: .Pp
1132: Supported options are:
1133: .Bl -tag -width Ds
1134: .It Xo Ic aggressive-resize
1135: .Op Ic on | Ic off
1136: .Xc
1137: Aggressively resize the chosen window.
1138: This means that
1139: .Nm
1140: will resize the window to the size of the smallest session for which it is the
1141: current window, rather than the smallest session to which it is attached.
1142: The window may resize when the current window is changed on another sessions;
1143: this option is good for full-screen programs which support SIGWINCH and poor for
1144: interactive programs such as shells.
1145: .It Xo Ic automatic-rename
1146: .Op Ic on | Ic off
1147: .Xc
1148: Control automatic window renaming.
1149: When this setting is enabled,
1150: .Nm
1151: will attempt - on supported platforms - to rename the window to reflect the
1152: command currently running in it.
1153: This flag is automatically disabled for an individual window when a name
1154: is specified at creation with
1155: .Ic new-window or
1156: .Ic new-session ,
1157: or later with
1158: .Ic rename-window .
1159: It may be switched off globally with:
1160: .Bd -literal -offset indent
1161: set-window-option -g automatic-rename off
1162: .Ed
1163: .It Ic clock-mode-colour Ar colour
1164: Set clock colour.
1165: .It Xo Ic clock-mode-style
1166: .Op Ic 12 | Ic 24
1167: .Xc
1168: Set clock hour format.
1169: .It Ic force-height Ar height
1170: .It Ic force-width Ar width
1171: Prevent
1172: .Nm
1173: from resizing a window to greater than
1174: .Ar width
1175: or
1176: .Ar height .
1177: A value of zero restores the default unlimited setting.
1.2 nicm 1178: .It Ic main-pane-width Ar width
1179: .It Ic main-pane-height Ar height
1180: Set the width or height of the main (left or top) pane in the
1181: .Ic main-horizontal
1182: or
1183: .Ic main-vertical
1184: layouts.
1.1 nicm 1185: .It Ic mode-attr Ar attributes
1186: Set window modes attributes.
1187: .It Ic mode-bg Ar colour
1188: Set window modes background colour.
1189: .It Ic mode-fg Ar colour
1190: Set window modes foreground colour.
1191: .It Xo Ic mode-keys
1192: .Op Ic vi | Ic emacs
1193: .Xc
1194: Use
1195: .Xr vi 1 -
1196: or
1197: .Xr emacs 1 -style
1198: key bindings in scroll and copy modes.
1199: Key bindings default to emacs.
1200: .It Xo Ic monitor-activity
1201: .Op Ic on | Ic off
1202: .Xc
1203: Monitor for activity in the window.
1204: Windows with activity are highlighted in the status line.
1205: .It Xo Ic monitor-content Ar match-string
1206: .Xc
1207: Monitor content in the window. When
1208: .Ar match-string
1209: appears in the window, it is highlighted in the status line.
1210: .It Xo Ic remain-on-exit
1211: .Op Ic on | Ic off
1212: .Xc
1213: A window with this flag set is not destroyed when the program running in it
1214: exits.
1215: The window may be reactivated with the
1216: .Ic respawn-window
1217: command.
1218: .It Xo Ic utf8
1219: .Op Ic on | Ic off
1220: .Xc
1221: Instructs
1222: .Nm
1223: to expect UTF-8 sequences to appear in this window.
1224: .It Ic window-status-attr Ar attributes
1225: Set status line attributes for a single window.
1226: .It Ic window-status-bg Ar colour
1227: Set status line background colour for a single window.
1228: .It Ic window-status-fg Ar colour
1229: Set status line foreground colour for a single window.
1230: .It Xo Ic xterm-keys
1231: .Op Ic on | Ic off
1232: .Xc
1233: If this option is set,
1234: .Nm
1235: will generate
1236: .Xr xterm 1 -style
1237: function key sequences; these have a number included to indicate modifiers such
1238: as shift, meta or ctrl.
1239: .El
1240: .It Xo Ic show-buffer
1241: .Op Fl b Ar buffer-index
1242: .Op Fl t Ar target-session
1243: .Xc
1244: .D1 (alias: Ic showb )
1245: Display the contents of the specified buffer.
1246: .It Xo Ic show-options
1247: .Op Fl t Ar target-session
1248: .Ar option Ar value
1249: .Xc
1250: .D1 (alias: Ic show )
1251: Show the currently set options.
1252: If a
1253: .Ar target-session
1254: is specified, the options for that session are shown; otherwise, the global
1255: options are listed.
1256: .It Xo Ic show-window-options
1257: .Op Fl t Ar target-window
1258: .Ar option Ar value
1259: .Xc
1260: .D1 (alias: Ic showw )
1261: List the current options for the given window.
1262: .It Xo Ic source-file
1263: .Ar path
1264: .Xc
1265: .D1 (alias: Ic source )
1266: Execute commands from
1267: .Ar path .
1268: .It Xo Ic split-window
1269: .Op Fl d
1270: .Oo Fl l
1271: .Ar lines |
1272: .Fl p Ar percentage Oc
1273: .Op Fl t Ar target-window
1274: .Op Ar command
1275: .Xc
1276: .D1 (alias: splitw )
1277: Creates a new window by splitting it vertically.
1278: The
1279: .Fl l
1280: and
1281: .Fl p
1282: options specify the size of the new window in lines, or as a percentage,
1283: respectively.
1284: All other options have the same meaning as in the
1285: .Ic new-window
1286: command.
1287: .Pp
1288: A few notes with regard to panes:
1289: .Bl -enum -compact
1290: .It
1291: If attempting to split a window with less than eight lines, an error will be
1292: shown.
1293: .It
1294: If the window is resized, as many panes are shown as can fit without reducing
1295: them below four lines.
1296: .It
1297: The minimum pane size is four lines (including the separator line).
1298: .It
1299: The panes are indexed from top (0) to bottom, with no numbers skipped.
1300: .El
1301: .It Xo Ic start-server
1302: .Xc
1303: .D1 (alias: Ic start )
1304: Start the
1305: .Nm
1306: server, if not already running, without creating any sessions.
1307: .It Xo Ic suspend-client
1308: .Op Fl c target-client
1309: .Xc
1310: .D1 (alias: Ic suspendc )
1311: Suspend a client by sending SIGTSTP (tty stop).
1312: .It Xo Ic swap-pane
1313: .Op Fl dDU
1314: .Op Fl p Ar src-index
1315: .Op Fl t Ar target-window
1316: .Op Fl q Ar dst-index
1317: .Xc
1318: .D1 (alias: Ic swapp )
1319: Swap two panes within a window.
1320: If
1321: .Fl U
1322: is used, the pane is swapped with the pane above (before it numerically);
1323: .Fl D
1324: swaps with the pane below (the next numerically); or
1325: .Ar dst-index
1326: may be give to swap with a specific pane.
1327: .It Xo Ic swap-window
1328: .Op Fl d
1329: .Op Fl s Ar src-window
1330: .Op Fl t Ar dst-window
1331: .Xc
1332: .D1 (alias: Ic swapw )
1333: This is similar to
1334: .Ic link-window ,
1335: except the source and destination windows are swapped.
1336: It is an error if no window exists at
1337: .Ar src-window .
1338: .It Xo Ic switch-client
1339: .Op Fl c Ar target-client Fl t Ar target-session
1340: .Xc
1341: .D1 (alias: Ic switchc )
1342: Switch the current session for client
1343: .Ar target-client
1344: to
1345: .Ar target-session .
1346: .It Xo Ic unbind-key
1347: .Ar key
1348: .Xc
1349: .D1 (alias: Ic unbind )
1350: Unbind the key bound to
1351: .Ar key .
1352: .It Xo Ic unlink-window
1353: .Op Fl t Ar target-window
1354: .Xc
1355: .D1 (alias: Ic unlinkw )
1356: Unlink
1357: .Ar target-window .
1358: A window may be unlinked only if it is linked to multiple sessions - windows may
1359: not be linked to no sessions.
1360: .It Xo Ic up-pane
1361: .Op Fl p Ar pane-index
1362: .Op Fl t Ar target-window
1363: .Xc
1364: .D1 (alias: Ic upp )
1365: Move up a pane.
1366: .El
1367: .Sh FILES
1368: .Bl -tag -width Ds -compact
1369: .It Pa ~/.tmux.conf
1370: default
1371: .Nm
1372: configuration file
1373: .El
1374: .Sh SEE ALSO
1375: .Xr pty 4
1376: .Sh AUTHORS
1377: .An Nicholas Marriott Aq nicm@users.sourceforge.net
![[BACK]](/icons/back.gif){kind=icon}
Return to tmux.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / tmux