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