tmux.1

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