Annotation of embedaddon/tmux/tmux.1, revision 1.1
1.1 ! misho 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com>
! 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: March 25 2013 $
! 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 2CluvV
! 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 C
! 102: Start in control mode (see the
! 103: .Sx CONTROL MODE
! 104: section).
! 105: Given twice
! 106: .Xo ( Fl CC ) Xc
! 107: disables echo.
! 108: .It Fl c Ar shell-command
! 109: Execute
! 110: .Ar shell-command
! 111: using the default shell.
! 112: If necessary, the
! 113: .Nm
! 114: server will be started to retrieve the
! 115: .Ic default-shell
! 116: option.
! 117: This option is for compatibility with
! 118: .Xr sh 1
! 119: when
! 120: .Nm
! 121: is used as a login shell.
! 122: .It Fl f Ar file
! 123: Specify an alternative configuration file.
! 124: By default,
! 125: .Nm
! 126: loads the system configuration file from
! 127: .Pa @SYSCONFDIR@/tmux.conf ,
! 128: if present, then looks for a user configuration file at
! 129: .Pa ~/.tmux.conf .
! 130: .Pp
! 131: The configuration file is a set of
! 132: .Nm
! 133: commands which are executed in sequence when the server is first started.
! 134: .Nm
! 135: loads configuration files once when the server process has started.
! 136: The
! 137: .Ic source-file
! 138: command may be used to load a file later.
! 139: .Pp
! 140: .Nm
! 141: shows any error messages from commands in configuration files in the first
! 142: session created, and continues to process the rest of the configuration file.
! 143: .It Fl L Ar socket-name
! 144: .Nm
! 145: stores the server socket in a directory under
! 146: .Ev TMUX_TMPDIR
! 147: or
! 148: .Pa /tmp
! 149: if it is unset.
! 150: The default socket is named
! 151: .Em default .
! 152: This option allows a different socket name to be specified, allowing several
! 153: independent
! 154: .Nm
! 155: servers to be run.
! 156: Unlike
! 157: .Fl S
! 158: a full path is not necessary: the sockets are all created in the same
! 159: directory.
! 160: .Pp
! 161: If the socket is accidentally removed, the
! 162: .Dv SIGUSR1
! 163: signal may be sent to the
! 164: .Nm
! 165: server process to recreate it (note that this will fail if any parent
! 166: directories are missing).
! 167: .It Fl l
! 168: Behave as a login shell.
! 169: This flag currently has no effect and is for compatibility with other shells
! 170: when using tmux as a login shell.
! 171: .It Fl S Ar socket-path
! 172: Specify a full alternative path to the server socket.
! 173: If
! 174: .Fl S
! 175: is specified, the default socket directory is not used and any
! 176: .Fl L
! 177: flag is ignored.
! 178: .It Fl u
! 179: When starting,
! 180: .Nm
! 181: looks for the
! 182: .Ev LC_ALL ,
! 183: .Ev LC_CTYPE
! 184: and
! 185: .Ev LANG
! 186: environment variables: if the first found contains
! 187: .Ql UTF-8 ,
! 188: then the terminal is assumed to support UTF-8.
! 189: This is not always correct: the
! 190: .Fl u
! 191: flag explicitly informs
! 192: .Nm
! 193: that UTF-8 is supported.
! 194: .Pp
! 195: Note that
! 196: .Nm
! 197: itself always accepts UTF-8; this controls whether it will send UTF-8
! 198: characters to the terminal it is running (if not, they are replaced by
! 199: .Ql _ ) .
! 200: .It Fl v
! 201: Request verbose logging.
! 202: This option may be specified multiple times for increasing verbosity.
! 203: Log messages will be saved into
! 204: .Pa tmux-client-PID.log
! 205: and
! 206: .Pa tmux-server-PID.log
! 207: files in the current directory, where
! 208: .Em PID
! 209: is the PID of the server or client process.
! 210: .It Fl V
! 211: Report the
! 212: .Nm
! 213: version.
! 214: .It Ar command Op Ar flags
! 215: This specifies one of a set of commands used to control
! 216: .Nm ,
! 217: as described in the following sections.
! 218: If no commands are specified, the
! 219: .Ic new-session
! 220: command is assumed.
! 221: .El
! 222: .Sh KEY BINDINGS
! 223: .Nm
! 224: may be controlled from an attached client by using a key combination of a
! 225: prefix key,
! 226: .Ql C-b
! 227: (Ctrl-b) by default, followed by a command key.
! 228: .Pp
! 229: The default command key bindings are:
! 230: .Pp
! 231: .Bl -tag -width "XXXXXXXXXX" -offset indent -compact
! 232: .It C-b
! 233: Send the prefix key (C-b) through to the application.
! 234: .It C-o
! 235: Rotate the panes in the current window forwards.
! 236: .It C-z
! 237: Suspend the
! 238: .Nm
! 239: client.
! 240: .It !
! 241: Break the current pane out of the window.
! 242: .It \&"
! 243: Split the current pane into two, top and bottom.
! 244: .It #
! 245: List all paste buffers.
! 246: .It $
! 247: Rename the current session.
! 248: .It %
! 249: Split the current pane into two, left and right.
! 250: .It &
! 251: Kill the current window.
! 252: .It '
! 253: Prompt for a window index to select.
! 254: .It \&(
! 255: Switch the attached client to the previous session.
! 256: .It \&)
! 257: Switch the attached client to the next session.
! 258: .It ,
! 259: Rename the current window.
! 260: .It -
! 261: Delete the most recently copied buffer of text.
! 262: .It .
! 263: Prompt for an index to move the current window.
! 264: .It 0 to 9
! 265: Select windows 0 to 9.
! 266: .It :
! 267: Enter the
! 268: .Nm
! 269: command prompt.
! 270: .It ;
! 271: Move to the previously active pane.
! 272: .It =
! 273: Choose which buffer to paste interactively from a list.
! 274: .It \&?
! 275: List all key bindings.
! 276: .It D
! 277: Choose a client to detach.
! 278: .It L
! 279: Switch the attached client back to the last session.
! 280: .It \&[
! 281: Enter copy mode to copy text or view the history.
! 282: .It \&]
! 283: Paste the most recently copied buffer of text.
! 284: .It c
! 285: Create a new window.
! 286: .It d
! 287: Detach the current client.
! 288: .It f
! 289: Prompt to search for text in open windows.
! 290: .It i
! 291: Display some information about the current window.
! 292: .It l
! 293: Move to the previously selected window.
! 294: .It n
! 295: Change to the next window.
! 296: .It o
! 297: Select the next pane in the current window.
! 298: .It p
! 299: Change to the previous window.
! 300: .It q
! 301: Briefly display pane indexes.
! 302: .It r
! 303: Force redraw of the attached client.
! 304: .It m
! 305: Mark the current pane (see
! 306: .Ic select-pane
! 307: .Fl m ) .
! 308: .It M
! 309: Clear the marked pane.
! 310: .It s
! 311: Select a new session for the attached client interactively.
! 312: .It t
! 313: Show the time.
! 314: .It w
! 315: Choose the current window interactively.
! 316: .It x
! 317: Kill the current pane.
! 318: .It z
! 319: Toggle zoom state of the current pane.
! 320: .It {
! 321: Swap the current pane with the previous pane.
! 322: .It }
! 323: Swap the current pane with the next pane.
! 324: .It ~
! 325: Show previous messages from
! 326: .Nm ,
! 327: if any.
! 328: .It Page Up
! 329: Enter copy mode and scroll one page up.
! 330: .It Up, Down
! 331: .It Left, Right
! 332: Change to the pane above, below, to the left, or to the right of the current
! 333: pane.
! 334: .It M-1 to M-5
! 335: Arrange panes in one of the five preset layouts: even-horizontal,
! 336: even-vertical, main-horizontal, main-vertical, or tiled.
! 337: .It Space
! 338: Arrange the current window in the next preset layout.
! 339: .It M-n
! 340: Move to the next window with a bell or activity marker.
! 341: .It M-o
! 342: Rotate the panes in the current window backwards.
! 343: .It M-p
! 344: Move to the previous window with a bell or activity marker.
! 345: .It C-Up, C-Down
! 346: .It C-Left, C-Right
! 347: Resize the current pane in steps of one cell.
! 348: .It M-Up, M-Down
! 349: .It M-Left, M-Right
! 350: Resize the current pane in steps of five cells.
! 351: .El
! 352: .Pp
! 353: Key bindings may be changed with the
! 354: .Ic bind-key
! 355: and
! 356: .Ic unbind-key
! 357: commands.
! 358: .Sh COMMANDS
! 359: This section contains a list of the commands supported by
! 360: .Nm .
! 361: Most commands accept the optional
! 362: .Fl t
! 363: (and sometimes
! 364: .Fl s )
! 365: argument with one of
! 366: .Ar target-client ,
! 367: .Ar target-session
! 368: .Ar target-window ,
! 369: or
! 370: .Ar target-pane .
! 371: These specify the client, session, window or pane which a command should affect.
! 372: .Pp
! 373: .Ar target-client
! 374: should be the name of the client,
! 375: typically the
! 376: .Xr pty 4
! 377: file to which the client is connected, for example either of
! 378: .Pa /dev/ttyp1
! 379: or
! 380: .Pa ttyp1
! 381: for the client attached to
! 382: .Pa /dev/ttyp1 .
! 383: If no client is specified,
! 384: .Nm
! 385: attempts to work out the client currently in use; if that fails, an error is
! 386: reported.
! 387: Clients may be listed with the
! 388: .Ic list-clients
! 389: command.
! 390: .Pp
! 391: .Ar target-session
! 392: is tried as, in order:
! 393: .Bl -enum -offset Ds
! 394: .It
! 395: A session ID prefixed with a $.
! 396: .It
! 397: An exact name of a session (as listed by the
! 398: .Ic list-sessions
! 399: command).
! 400: .It
! 401: The start of a session name, for example
! 402: .Ql mysess
! 403: would match a session named
! 404: .Ql mysession .
! 405: .It
! 406: An
! 407: .Xr fnmatch 3
! 408: pattern which is matched against the session name.
! 409: .El
! 410: .Pp
! 411: If the session name is prefixed with an
! 412: .Ql = ,
! 413: only an exact match is accepted (so
! 414: .Ql =mysess
! 415: will only match exactly
! 416: .Ql mysess ,
! 417: not
! 418: .Ql mysession ) .
! 419: .Pp
! 420: If a single session is found, it is used as the target session; multiple matches
! 421: produce an error.
! 422: If a session is omitted, the current session is used if available; if no
! 423: current session is available, the most recently used is chosen.
! 424: .Pp
! 425: .Ar target-window
! 426: (or
! 427: .Ar src-window
! 428: or
! 429: .Ar dst-window )
! 430: specifies a window in the form
! 431: .Em session Ns \&: Ns Em window .
! 432: .Em session
! 433: follows the same rules as for
! 434: .Ar target-session ,
! 435: and
! 436: .Em window
! 437: is looked for in order as:
! 438: .Bl -enum -offset Ds
! 439: .It
! 440: A special token, listed below.
! 441: .It
! 442: A window index, for example
! 443: .Ql mysession:1
! 444: is window 1 in session
! 445: .Ql mysession .
! 446: .It
! 447: A window ID, such as @1.
! 448: .It
! 449: An exact window name, such as
! 450: .Ql mysession:mywindow .
! 451: .It
! 452: The start of a window name, such as
! 453: .Ql mysession:mywin .
! 454: .It
! 455: As an
! 456: .Xr fnmatch 3
! 457: pattern matched against the window name.
! 458: .El
! 459: .Pp
! 460: Like sessions, a
! 461: .Ql =
! 462: prefix will do an exact match only.
! 463: An empty window name specifies the next unused index if appropriate (for
! 464: example the
! 465: .Ic new-window
! 466: and
! 467: .Ic link-window
! 468: commands)
! 469: otherwise the current window in
! 470: .Em session
! 471: is chosen.
! 472: .Pp
! 473: The following special tokens are available to indicate particular windows.
! 474: Each has a single-character alternative form.
! 475: .Bl -column "XXXXXXXXXX" "X"
! 476: .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
! 477: .It Li "{start}" Ta "^" Ta "The lowest-numbered window"
! 478: .It Li "{end}" Ta "$" Ta "The highest-numbered window"
! 479: .It Li "{last}" Ta "!" Ta "The last (previously current) window"
! 480: .It Li "{next}" Ta "+" Ta "The next window by number"
! 481: .It Li "{previous}" Ta "-" Ta "The previous window by number"
! 482: .El
! 483: .Pp
! 484: .Ar target-pane
! 485: (or
! 486: .Ar src-pane
! 487: or
! 488: .Ar dst-pane )
! 489: may be a pane ID or takes a similar form to
! 490: .Ar target-window
! 491: but with the optional addition of a period followed by a pane index or pane ID,
! 492: for example:
! 493: .Ql mysession:mywindow.1 .
! 494: If the pane index is omitted, the currently active pane in the specified
! 495: window is used.
! 496: The following special tokens are available for the pane index:
! 497: .Bl -column "XXXXXXXXXXXXXX" "X"
! 498: .It Sy "Token" Ta Sy "" Ta Sy "Meaning"
! 499: .It Li "{last}" Ta "!" Ta "The last (previously active) pane"
! 500: .It Li "{next}" Ta "+" Ta "The next pane by number"
! 501: .It Li "{previous}" Ta "-" Ta "The previous pane by number"
! 502: .It Li "{top}" Ta "" Ta "The top pane"
! 503: .It Li "{bottom}" Ta "" Ta "The bottom pane"
! 504: .It Li "{left}" Ta "" Ta "The leftmost pane"
! 505: .It Li "{right}" Ta "" Ta "The rightmost pane"
! 506: .It Li "{top-left}" Ta "" Ta "The top-left pane"
! 507: .It Li "{top-right}" Ta "" Ta "The top-right pane"
! 508: .It Li "{bottom-left}" Ta "" Ta "The bottom-left pane"
! 509: .It Li "{bottom-right}" Ta "" Ta "The bottom-right pane"
! 510: .It Li "{up-of}" Ta "" Ta "The pane above the active pane"
! 511: .It Li "{down-of}" Ta "" Ta "The pane below the active pane"
! 512: .It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane"
! 513: .It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane"
! 514: .El
! 515: .Pp
! 516: The tokens
! 517: .Ql +
! 518: and
! 519: .Ql -
! 520: may be followed by an offset, for example:
! 521: .Bd -literal -offset indent
! 522: select-window -t:+2
! 523: .Ed
! 524: .Pp
! 525: In addition,
! 526: .Em target-session ,
! 527: .Em target-window
! 528: or
! 529: .Em target-pane
! 530: may consist entirely of the token
! 531: .Ql {mouse}
! 532: (alternative form
! 533: .Ql = )
! 534: to specify the most recent mouse event
! 535: (see the
! 536: .Sx MOUSE SUPPORT
! 537: section)
! 538: or
! 539: .Ql {marked}
! 540: (alternative form
! 541: .Ql ~ )
! 542: to specify the marked pane (see
! 543: .Ic select-pane
! 544: .Fl m ) .
! 545: .Pp
! 546: Sessions, window and panes are each numbered with a unique ID; session IDs are
! 547: prefixed with a
! 548: .Ql $ ,
! 549: windows with a
! 550: .Ql @ ,
! 551: and panes with a
! 552: .Ql % .
! 553: These are unique and are unchanged for the life of the session, window or pane
! 554: in the
! 555: .Nm
! 556: server.
! 557: The pane ID is passed to the child process of the pane in the
! 558: .Ev TMUX_PANE
! 559: environment variable.
! 560: IDs may be displayed using the
! 561: .Ql session_id ,
! 562: .Ql window_id ,
! 563: or
! 564: .Ql pane_id
! 565: formats (see the
! 566: .Sx FORMATS
! 567: section) and the
! 568: .Ic display-message ,
! 569: .Ic list-sessions ,
! 570: .Ic list-windows
! 571: or
! 572: .Ic list-panes
! 573: commands.
! 574: .Pp
! 575: .Ar shell-command
! 576: arguments are
! 577: .Xr sh 1
! 578: commands.
! 579: This may be a single argument passed to the shell, for example:
! 580: .Bd -literal -offset indent
! 581: new-window 'vi /etc/passwd'
! 582: .Ed
! 583: .Pp
! 584: Will run:
! 585: .Bd -literal -offset indent
! 586: /bin/sh -c 'vi /etc/passwd'
! 587: .Ed
! 588: .Pp
! 589: Additionally, the
! 590: .Ic new-window ,
! 591: .Ic new-session ,
! 592: .Ic split-window ,
! 593: .Ic respawn-window
! 594: and
! 595: .Ic respawn-pane
! 596: commands allow
! 597: .Ar shell-command
! 598: to be given as multiple arguments and executed directly (without
! 599: .Ql sh -c ) .
! 600: This can avoid issues with shell quoting.
! 601: For example:
! 602: .Bd -literal -offset indent
! 603: $ tmux new-window vi /etc/passwd
! 604: .Ed
! 605: .Pp
! 606: Will run
! 607: .Xr vi 1
! 608: directly without invoking the shell.
! 609: .Pp
! 610: .Ar command
! 611: .Op Ar arguments
! 612: refers to a
! 613: .Nm
! 614: command, passed with the command and arguments separately, for example:
! 615: .Bd -literal -offset indent
! 616: bind-key F1 set-window-option force-width 81
! 617: .Ed
! 618: .Pp
! 619: Or if using
! 620: .Xr sh 1 :
! 621: .Bd -literal -offset indent
! 622: $ tmux bind-key F1 set-window-option force-width 81
! 623: .Ed
! 624: .Pp
! 625: Multiple commands may be specified together as part of a
! 626: .Em command sequence .
! 627: Each command should be separated by spaces and a semicolon;
! 628: commands are executed sequentially from left to right and
! 629: lines ending with a backslash continue on to the next line,
! 630: except when escaped by another backslash.
! 631: A literal semicolon may be included by escaping it with a backslash (for
! 632: example, when specifying a command sequence to
! 633: .Ic bind-key ) .
! 634: .Pp
! 635: Example
! 636: .Nm
! 637: commands include:
! 638: .Bd -literal -offset indent
! 639: refresh-client -t/dev/ttyp2
! 640:
! 641: rename-session -tfirst newname
! 642:
! 643: set-window-option -t:0 monitor-activity on
! 644:
! 645: new-window ; split-window -d
! 646:
! 647: bind-key R source-file ~/.tmux.conf \e; \e
! 648: display-message "source-file done"
! 649: .Ed
! 650: .Pp
! 651: Or from
! 652: .Xr sh 1 :
! 653: .Bd -literal -offset indent
! 654: $ tmux kill-window -t :1
! 655:
! 656: $ tmux new-window \e; split-window -d
! 657:
! 658: $ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach
! 659: .Ed
! 660: .Sh CLIENTS AND SESSIONS
! 661: The
! 662: .Nm
! 663: server manages clients, sessions, windows and panes.
! 664: Clients are attached to sessions to interact with them, either
! 665: when they are created with the
! 666: .Ic new-session
! 667: command, or later with the
! 668: .Ic attach-session
! 669: command.
! 670: Each session has one or more windows
! 671: .Em linked
! 672: into it.
! 673: Windows may be linked to multiple sessions and are made up of one or
! 674: more panes,
! 675: each of which contains a pseudo terminal.
! 676: Commands for creating, linking and otherwise manipulating windows
! 677: are covered
! 678: in the
! 679: .Sx WINDOWS AND PANES
! 680: section.
! 681: .Pp
! 682: The following commands are available to manage clients and sessions:
! 683: .Bl -tag -width Ds
! 684: .It Xo Ic attach-session
! 685: .Op Fl dEr
! 686: .Op Fl c Ar working-directory
! 687: .Op Fl t Ar target-session
! 688: .Xc
! 689: .D1 (alias: Ic attach )
! 690: If run from outside
! 691: .Nm ,
! 692: create a new client in the current terminal and attach it to
! 693: .Ar target-session .
! 694: If used from inside, switch the current client.
! 695: If
! 696: .Fl d
! 697: is specified, any other clients attached to the session are detached.
! 698: .Fl r
! 699: signifies the client is read-only (only keys bound to the
! 700: .Ic detach-client
! 701: or
! 702: .Ic switch-client
! 703: commands have any effect)
! 704: .Pp
! 705: If no server is started,
! 706: .Ic attach-session
! 707: will attempt to start it; this will fail unless sessions are created in the
! 708: configuration file.
! 709: .Pp
! 710: The
! 711: .Ar target-session
! 712: rules for
! 713: .Ic attach-session
! 714: are slightly adjusted: if
! 715: .Nm
! 716: needs to select the most recently used session, it will prefer the most
! 717: recently used
! 718: .Em unattached
! 719: session.
! 720: .Pp
! 721: .Fl c
! 722: will set the session working directory (used for new windows) to
! 723: .Ar working-directory .
! 724: .Pp
! 725: If
! 726: .Fl E
! 727: is used, the
! 728: .Ic update-environment
! 729: option will not be applied.
! 730: .It Xo Ic detach-client
! 731: .Op Fl aP
! 732: .Op Fl E Ar shell-command
! 733: .Op Fl s Ar target-session
! 734: .Op Fl t Ar target-client
! 735: .Xc
! 736: .D1 (alias: Ic detach )
! 737: Detach the current client if bound to a key, the client specified with
! 738: .Fl t ,
! 739: or all clients currently attached to the session specified by
! 740: .Fl s .
! 741: The
! 742: .Fl a
! 743: option kills all but the client given with
! 744: .Fl t .
! 745: If
! 746: .Fl P
! 747: is given, send SIGHUP to the parent process of the client, typically causing it
! 748: to exit.
! 749: With
! 750: .Fl E ,
! 751: run
! 752: .Ar shell-command
! 753: to replace the client.
! 754: .It Ic has-session Op Fl t Ar target-session
! 755: .D1 (alias: Ic has )
! 756: Report an error and exit with 1 if the specified session does not exist.
! 757: If it does exist, exit with 0.
! 758: .It Ic kill-server
! 759: Kill the
! 760: .Nm
! 761: server and clients and destroy all sessions.
! 762: .It Xo Ic kill-session
! 763: .Op Fl aC
! 764: .Op Fl t Ar target-session
! 765: .Xc
! 766: Destroy the given session, closing any windows linked to it and no other
! 767: sessions, and detaching all clients attached to it.
! 768: If
! 769: .Fl a
! 770: is given, all sessions but the specified one is killed.
! 771: The
! 772: .Fl C
! 773: flag clears alerts (bell, activity, or silence) in all windows linked to the
! 774: session.
! 775: .It Xo Ic list-clients
! 776: .Op Fl F Ar format
! 777: .Op Fl t Ar target-session
! 778: .Xc
! 779: .D1 (alias: Ic lsc )
! 780: List all clients attached to the server.
! 781: For the meaning of the
! 782: .Fl F
! 783: flag, see the
! 784: .Sx FORMATS
! 785: section.
! 786: If
! 787: .Ar target-session
! 788: is specified, list only clients connected to that session.
! 789: .It Xo Ic list-commands
! 790: .Op Fl F Ar format
! 791: .Xc
! 792: .D1 (alias: Ic lscm )
! 793: List the syntax of all commands supported by
! 794: .Nm .
! 795: .It Ic list-sessions Op Fl F Ar format
! 796: .D1 (alias: Ic ls )
! 797: List all sessions managed by the server.
! 798: For the meaning of the
! 799: .Fl F
! 800: flag, see the
! 801: .Sx FORMATS
! 802: section.
! 803: .It Ic lock-client Op Fl t Ar target-client
! 804: .D1 (alias: Ic lockc )
! 805: Lock
! 806: .Ar target-client ,
! 807: see the
! 808: .Ic lock-server
! 809: command.
! 810: .It Ic lock-session Op Fl t Ar target-session
! 811: .D1 (alias: Ic locks )
! 812: Lock all clients attached to
! 813: .Ar target-session .
! 814: .It Xo Ic new-session
! 815: .Op Fl AdDEP
! 816: .Op Fl c Ar start-directory
! 817: .Op Fl F Ar format
! 818: .Op Fl n Ar window-name
! 819: .Op Fl s Ar session-name
! 820: .Op Fl t Ar group-name
! 821: .Op Fl x Ar width
! 822: .Op Fl y Ar height
! 823: .Op Ar shell-command
! 824: .Xc
! 825: .D1 (alias: Ic new )
! 826: Create a new session with name
! 827: .Ar session-name .
! 828: .Pp
! 829: The new session is attached to the current terminal unless
! 830: .Fl d
! 831: is given.
! 832: .Ar window-name
! 833: and
! 834: .Ar shell-command
! 835: are the name of and shell command to execute in the initial window.
! 836: If
! 837: .Fl d
! 838: is used,
! 839: .Fl x
! 840: and
! 841: .Fl y
! 842: specify the size of the initial window.
! 843: .Pp
! 844: If run from a terminal, any
! 845: .Xr termios 4
! 846: special characters are saved and used for new windows in the new session.
! 847: .Pp
! 848: The
! 849: .Fl A
! 850: flag makes
! 851: .Ic new-session
! 852: behave like
! 853: .Ic attach-session
! 854: if
! 855: .Ar session-name
! 856: already exists; in this case,
! 857: .Fl D
! 858: behaves like
! 859: .Fl d
! 860: to
! 861: .Ic attach-session .
! 862: .Pp
! 863: If
! 864: .Fl t
! 865: is given, it specifies a
! 866: .Ic session group .
! 867: Sessions in the same group share the same set of windows - new windows are
! 868: linked to all sessions in the group and any windows closed removed from all
! 869: sessions.
! 870: The current and previous window and any session options remain independent and
! 871: any session in a group may be killed without affecting the others.
! 872: The
! 873: .Ar group-name
! 874: argument may be:
! 875: .Bl -enum -width Ds
! 876: .It
! 877: the name of an existing group, in which case the new session is added to that
! 878: group;
! 879: .It
! 880: the name of an existing session - the new session is added to the same group
! 881: as that session, creating a new group if necessary;
! 882: .It
! 883: the name for a new group containing only the new session.
! 884: .El
! 885: .Pp
! 886: .Fl n
! 887: and
! 888: .Ar shell-command
! 889: are invalid if
! 890: .Fl t
! 891: is used.
! 892: .Pp
! 893: The
! 894: .Fl P
! 895: option prints information about the new session after it has been created.
! 896: By default, it uses the format
! 897: .Ql #{session_name}:
! 898: but a different format may be specified with
! 899: .Fl F .
! 900: .Pp
! 901: If
! 902: .Fl E
! 903: is used, the
! 904: .Ic update-environment
! 905: option will not be applied.
! 906: .It Xo Ic refresh-client
! 907: .Op Fl C Ar width,height
! 908: .Op Fl S
! 909: .Op Fl t Ar target-client
! 910: .Xc
! 911: .D1 (alias: Ic refresh )
! 912: Refresh the current client if bound to a key, or a single client if one is given
! 913: with
! 914: .Fl t .
! 915: If
! 916: .Fl S
! 917: is specified, only update the client's status line.
! 918: .Pp
! 919: .Fl C
! 920: sets the width and height of a control client.
! 921: .It Xo Ic rename-session
! 922: .Op Fl t Ar target-session
! 923: .Ar new-name
! 924: .Xc
! 925: .D1 (alias: Ic rename )
! 926: Rename the session to
! 927: .Ar new-name .
! 928: .It Xo Ic show-messages
! 929: .Op Fl JT
! 930: .Op Fl t Ar target-client
! 931: .Xc
! 932: .D1 (alias: Ic showmsgs )
! 933: Show client messages or server information.
! 934: Any messages displayed on the status line are saved in a per-client message
! 935: log, up to a maximum of the limit set by the
! 936: .Ar message-limit
! 937: server option.
! 938: With
! 939: .Fl t ,
! 940: display the log for
! 941: .Ar target-client .
! 942: .Fl J
! 943: and
! 944: .Fl T
! 945: show debugging information about jobs and terminals.
! 946: .It Xo Ic source-file
! 947: .Op Fl q
! 948: .Ar path
! 949: .Xc
! 950: .D1 (alias: Ic source )
! 951: Execute commands from
! 952: .Ar path
! 953: (which may be a
! 954: .Xr glob 3
! 955: pattern).
! 956: If
! 957: .Fl q
! 958: is given, no error will be returned if
! 959: .Ar path
! 960: does not exist.
! 961: .Pp
! 962: Within a configuration file, commands may be made conditional by surrounding
! 963: them with
! 964: .Em %if
! 965: and
! 966: .Em %endif
! 967: lines.
! 968: The argument to
! 969: .Em %if
! 970: is expanded as a format and if it evaluates to false
! 971: (zero or empty), subsequent lines are ignored until
! 972: .Em %endif .
! 973: For example:
! 974: .Bd -literal -offset indent
! 975: %if #{==:#{host},myhost}
! 976: set -g status-style bg=red
! 977: %endif
! 978: .Ed
! 979: .Pp
! 980: Will change the status line to red if running on
! 981: .Ql myhost .
! 982: .Em %if
! 983: may not be nested.
! 984: .It Ic start-server
! 985: .D1 (alias: Ic start )
! 986: Start the
! 987: .Nm
! 988: server, if not already running, without creating any sessions.
! 989: .It Xo Ic suspend-client
! 990: .Op Fl t Ar target-client
! 991: .Xc
! 992: .D1 (alias: Ic suspendc )
! 993: Suspend a client by sending
! 994: .Dv SIGTSTP
! 995: (tty stop).
! 996: .It Xo Ic switch-client
! 997: .Op Fl Elnpr
! 998: .Op Fl c Ar target-client
! 999: .Op Fl t Ar target-session
! 1000: .Op Fl T Ar key-table
! 1001: .Xc
! 1002: .D1 (alias: Ic switchc )
! 1003: Switch the current session for client
! 1004: .Ar target-client
! 1005: to
! 1006: .Ar target-session .
! 1007: If
! 1008: .Fl l ,
! 1009: .Fl n
! 1010: or
! 1011: .Fl p
! 1012: is used, the client is moved to the last, next or previous session
! 1013: respectively.
! 1014: .Fl r
! 1015: toggles whether a client is read-only (see the
! 1016: .Ic attach-session
! 1017: command).
! 1018: .Pp
! 1019: If
! 1020: .Fl E
! 1021: is used,
! 1022: .Ic update-environment
! 1023: option will not be applied.
! 1024: .Pp
! 1025: .Fl T
! 1026: sets the client's key table; the next key from the client will be interpreted from
! 1027: .Ar key-table .
! 1028: This may be used to configure multiple prefix keys, or to bind commands to
! 1029: sequences of keys.
! 1030: For example, to make typing
! 1031: .Ql abc
! 1032: run the
! 1033: .Ic list-keys
! 1034: command:
! 1035: .Bd -literal -offset indent
! 1036: bind-key -Ttable2 c list-keys
! 1037: bind-key -Ttable1 b switch-client -Ttable2
! 1038: bind-key -Troot a switch-client -Ttable1
! 1039: .Ed
! 1040: .El
! 1041: .Sh WINDOWS AND PANES
! 1042: A
! 1043: .Nm
! 1044: window may be in one of two modes.
! 1045: The default permits direct access to the terminal attached to the window.
! 1046: The other is copy mode, which permits a section of a window or its
! 1047: history to be copied to a
! 1048: .Em paste buffer
! 1049: for later insertion into another window.
! 1050: This mode is entered with the
! 1051: .Ic copy-mode
! 1052: command, bound to
! 1053: .Ql \&[
! 1054: by default.
! 1055: It is also entered when a command that produces output, such as
! 1056: .Ic list-keys ,
! 1057: is executed from a key binding.
! 1058: .Pp
! 1059: Commands are sent to copy mode using the
! 1060: .Fl X
! 1061: flag to the
! 1062: .Ic send-keys
! 1063: command.
! 1064: When a key is pressed, copy mode automatically uses one of two key tables,
! 1065: depending on the
! 1066: .Ic mode-keys
! 1067: option:
! 1068: .Ic copy-mode
! 1069: for emacs, or
! 1070: .Ic copy-mode-vi
! 1071: for vi.
! 1072: Key tables may be viewed with the
! 1073: .Ic list-keys
! 1074: command.
! 1075: .Pp
! 1076: The following commands are supported in copy mode:
! 1077: .Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
! 1078: .It Sy "Command" Ta Sy "vi" Ta Sy "emacs"
! 1079: .It Li "append-selection" Ta "" Ta ""
! 1080: .It Li "append-selection-and-cancel" Ta "A" Ta ""
! 1081: .It Li "back-to-indentation" Ta "^" Ta "M-m"
! 1082: .It Li "begin-selection" Ta "Space" Ta "C-Space"
! 1083: .It Li "bottom-line" Ta "L" Ta ""
! 1084: .It Li "cancel" Ta "q" Ta "Escape"
! 1085: .It Li "clear-selection" Ta "Escape" Ta "C-g"
! 1086: .It Li "copy-end-of-line" Ta "D" Ta "C-k"
! 1087: .It Li "copy-line" Ta "" Ta ""
! 1088: .It Li "copy-pipe <command>" Ta "" Ta ""
! 1089: .It Li "copy-pipe-and-cancel <command>" Ta "" Ta ""
! 1090: .It Li "copy-selection" Ta "" Ta ""
! 1091: .It Li "copy-selection-and-cancel" Ta "Enter" Ta "M-w"
! 1092: .It Li "cursor-down" Ta "j" Ta "Down"
! 1093: .It Li "cursor-left" Ta "h" Ta "Left"
! 1094: .It Li "cursor-right" Ta "l" Ta "Right"
! 1095: .It Li "cursor-up" Ta "k" Ta "Up"
! 1096: .It Li "end-of-line" Ta "$" Ta "C-e"
! 1097: .It Li "goto-line <line>" Ta ":" Ta "g"
! 1098: .It Li "halfpage-down" Ta "C-d" Ta "M-Down"
! 1099: .It Li "halfpage-up" Ta "C-u" Ta "M-Up"
! 1100: .It Li "history-bottom" Ta "G" Ta "M-<"
! 1101: .It Li "history-top" Ta "g" Ta "M->"
! 1102: .It Li "jump-again" Ta ";" Ta ";"
! 1103: .It Li "jump-backward <to>" Ta "F" Ta "F"
! 1104: .It Li "jump-forward <to>" Ta "f" Ta "f"
! 1105: .It Li "jump-reverse" Ta "," Ta ","
! 1106: .It Li "jump-to-backward <to>" Ta "T" Ta ""
! 1107: .It Li "jump-to-forward <to>" Ta "t" Ta ""
! 1108: .It Li "middle-line" Ta "M" Ta "M-r"
! 1109: .It Li "next-paragraph" Ta "}" Ta "M-}"
! 1110: .It Li "next-space" Ta "W" Ta ""
! 1111: .It Li "next-space-end" Ta "E" Ta ""
! 1112: .It Li "next-word" Ta "w" Ta ""
! 1113: .It Li "next-word-end" Ta "e" Ta "M-f"
! 1114: .It Li "other-end" Ta "o" Ta ""
! 1115: .It Li "page-down" Ta "C-f" Ta "PageDown"
! 1116: .It Li "page-up" Ta "C-b" Ta "PageUp"
! 1117: .It Li "previous-paragraph" Ta "{" Ta "M-{"
! 1118: .It Li "previous-space" Ta "B" Ta ""
! 1119: .It Li "previous-word" Ta "b" Ta "M-b"
! 1120: .It Li "rectangle-toggle" Ta "v" Ta "R"
! 1121: .It Li "scroll-down" Ta "C-e" Ta "C-Down"
! 1122: .It Li "scroll-up" Ta "C-y" Ta "C-Up"
! 1123: .It Li "search-again" Ta "n" Ta "n"
! 1124: .It Li "search-backward <for>" Ta "?" Ta ""
! 1125: .It Li "search-forward <for>" Ta "/" Ta ""
! 1126: .It Li "search-backward-incremental <for>" Ta "" Ta "C-r"
! 1127: .It Li "search-forward-incremental <for>" Ta "" Ta "C-s"
! 1128: .It Li "search-reverse" Ta "N" Ta "N"
! 1129: .It Li "select-line" Ta "V" Ta ""
! 1130: .It Li "start-of-line" Ta "0" Ta "C-a"
! 1131: .It Li "stop-selection" Ta "" Ta ""
! 1132: .It Li "top-line" Ta "H" Ta "M-R"
! 1133: .El
! 1134: .Pp
! 1135: The next and previous word keys use space and the
! 1136: .Ql - ,
! 1137: .Ql _
! 1138: and
! 1139: .Ql @
! 1140: characters as word delimiters by default, but this can be adjusted by
! 1141: setting the
! 1142: .Em word-separators
! 1143: session option.
! 1144: Next word moves to the start of the next word, next word end to the end of the
! 1145: next word and previous word to the start of the previous word.
! 1146: The three next and previous space keys work similarly but use a space alone as
! 1147: the word separator.
! 1148: .Pp
! 1149: The jump commands enable quick movement within a line.
! 1150: For instance, typing
! 1151: .Ql f
! 1152: followed by
! 1153: .Ql /
! 1154: will move the cursor to the next
! 1155: .Ql /
! 1156: character on the current line.
! 1157: A
! 1158: .Ql \&;
! 1159: will then jump to the next occurrence.
! 1160: .Pp
! 1161: Commands in copy mode may be prefaced by an optional repeat count.
! 1162: With vi key bindings, a prefix is entered using the number keys; with
! 1163: emacs, the Alt (meta) key and a number begins prefix entry.
! 1164: .Pp
! 1165: The synopsis for the
! 1166: .Ic copy-mode
! 1167: command is:
! 1168: .Bl -tag -width Ds
! 1169: .It Xo Ic copy-mode
! 1170: .Op Fl Meu
! 1171: .Op Fl t Ar target-pane
! 1172: .Xc
! 1173: Enter copy mode.
! 1174: The
! 1175: .Fl u
! 1176: option scrolls one page up.
! 1177: .Fl M
! 1178: begins a mouse drag (only valid if bound to a mouse key binding, see
! 1179: .Sx MOUSE SUPPORT ) .
! 1180: .Fl e
! 1181: specifies that scrolling to the bottom of the history (to the visible screen)
! 1182: should exit copy mode.
! 1183: While in copy mode, pressing a key other than those used for scrolling will
! 1184: disable this behaviour.
! 1185: This is intended to allow fast scrolling through a pane's history, for
! 1186: example with:
! 1187: .Bd -literal -offset indent
! 1188: bind PageUp copy-mode -eu
! 1189: .Ed
! 1190: .El
! 1191: .Pp
! 1192: Each window displayed by
! 1193: .Nm
! 1194: may be split into one or more
! 1195: .Em panes ;
! 1196: each pane takes up a certain area of the display and is a separate terminal.
! 1197: A window may be split into panes using the
! 1198: .Ic split-window
! 1199: command.
! 1200: Windows may be split horizontally (with the
! 1201: .Fl h
! 1202: flag) or vertically.
! 1203: Panes may be resized with the
! 1204: .Ic resize-pane
! 1205: command (bound to
! 1206: .Ql C-Up ,
! 1207: .Ql C-Down
! 1208: .Ql C-Left
! 1209: and
! 1210: .Ql C-Right
! 1211: by default), the current pane may be changed with the
! 1212: .Ic select-pane
! 1213: command and the
! 1214: .Ic rotate-window
! 1215: and
! 1216: .Ic swap-pane
! 1217: commands may be used to swap panes without changing their position.
! 1218: Panes are numbered beginning from zero in the order they are created.
! 1219: .Pp
! 1220: A number of preset
! 1221: .Em layouts
! 1222: are available.
! 1223: These may be selected with the
! 1224: .Ic select-layout
! 1225: command or cycled with
! 1226: .Ic next-layout
! 1227: (bound to
! 1228: .Ql Space
! 1229: by default); once a layout is chosen, panes within it may be moved and resized
! 1230: as normal.
! 1231: .Pp
! 1232: The following layouts are supported:
! 1233: .Bl -tag -width Ds
! 1234: .It Ic even-horizontal
! 1235: Panes are spread out evenly from left to right across the window.
! 1236: .It Ic even-vertical
! 1237: Panes are spread evenly from top to bottom.
! 1238: .It Ic main-horizontal
! 1239: A large (main) pane is shown at the top of the window and the remaining panes
! 1240: are spread from left to right in the leftover space at the bottom.
! 1241: Use the
! 1242: .Em main-pane-height
! 1243: window option to specify the height of the top pane.
! 1244: .It Ic main-vertical
! 1245: Similar to
! 1246: .Ic main-horizontal
! 1247: but the large pane is placed on the left and the others spread from top to
! 1248: bottom along the right.
! 1249: See the
! 1250: .Em main-pane-width
! 1251: window option.
! 1252: .It Ic tiled
! 1253: Panes are spread out as evenly as possible over the window in both rows and
! 1254: columns.
! 1255: .El
! 1256: .Pp
! 1257: In addition,
! 1258: .Ic select-layout
! 1259: may be used to apply a previously used layout - the
! 1260: .Ic list-windows
! 1261: command displays the layout of each window in a form suitable for use with
! 1262: .Ic select-layout .
! 1263: For example:
! 1264: .Bd -literal -offset indent
! 1265: $ tmux list-windows
! 1266: 0: ksh [159x48]
! 1267: layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
! 1268: $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
! 1269: .Ed
! 1270: .Pp
! 1271: .Nm
! 1272: automatically adjusts the size of the layout for the current window size.
! 1273: Note that a layout cannot be applied to a window with more panes than that
! 1274: from which the layout was originally defined.
! 1275: .Pp
! 1276: Commands related to windows and panes are as follows:
! 1277: .Bl -tag -width Ds
! 1278: .It Xo Ic break-pane
! 1279: .Op Fl dP
! 1280: .Op Fl F Ar format
! 1281: .Op Fl n Ar window-name
! 1282: .Op Fl s Ar src-pane
! 1283: .Op Fl t Ar dst-window
! 1284: .Xc
! 1285: .D1 (alias: Ic breakp )
! 1286: Break
! 1287: .Ar src-pane
! 1288: off from its containing window to make it the only pane in
! 1289: .Ar dst-window .
! 1290: If
! 1291: .Fl d
! 1292: is given, the new window does not become the current window.
! 1293: The
! 1294: .Fl P
! 1295: option prints information about the new window after it has been created.
! 1296: By default, it uses the format
! 1297: .Ql #{session_name}:#{window_index}
! 1298: but a different format may be specified with
! 1299: .Fl F .
! 1300: .It Xo Ic capture-pane
! 1301: .Op Fl aepPqCJ
! 1302: .Op Fl b Ar buffer-name
! 1303: .Op Fl E Ar end-line
! 1304: .Op Fl S Ar start-line
! 1305: .Op Fl t Ar target-pane
! 1306: .Xc
! 1307: .D1 (alias: Ic capturep )
! 1308: Capture the contents of a pane.
! 1309: If
! 1310: .Fl p
! 1311: is given, the output goes to stdout, otherwise to the buffer specified with
! 1312: .Fl b
! 1313: or a new buffer if omitted.
! 1314: If
! 1315: .Fl a
! 1316: is given, the alternate screen is used, and the history is not accessible.
! 1317: If no alternate screen exists, an error will be returned unless
! 1318: .Fl q
! 1319: is given.
! 1320: If
! 1321: .Fl e
! 1322: is given, the output includes escape sequences for text and background
! 1323: attributes.
! 1324: .Fl C
! 1325: also escapes non-printable characters as octal \exxx.
! 1326: .Fl J
! 1327: joins wrapped lines and preserves trailing spaces at each line's end.
! 1328: .Fl P
! 1329: captures only any output that the pane has received that is the beginning of an
! 1330: as-yet incomplete escape sequence.
! 1331: .Pp
! 1332: .Fl S
! 1333: and
! 1334: .Fl E
! 1335: specify the starting and ending line numbers, zero is the first line of the
! 1336: visible pane and negative numbers are lines in the history.
! 1337: .Ql -
! 1338: to
! 1339: .Fl S
! 1340: is the start of the history and to
! 1341: .Fl E
! 1342: the end of the visible pane.
! 1343: The default is to capture only the visible contents of the pane.
! 1344: .It Xo
! 1345: .Ic choose-client
! 1346: .Op Fl F Ar format
! 1347: .Op Fl t Ar target-window
! 1348: .Op Ar template
! 1349: .Xc
! 1350: Put a window into client choice mode, allowing a client to be selected
! 1351: interactively from a list.
! 1352: After a client is chosen,
! 1353: .Ql %%
! 1354: is replaced by the client
! 1355: .Xr pty 4
! 1356: path in
! 1357: .Ar template
! 1358: and the result executed as a command.
! 1359: If
! 1360: .Ar template
! 1361: is not given, "detach-client -t '%%'" is used.
! 1362: For the meaning of the
! 1363: .Fl F
! 1364: flag, see the
! 1365: .Sx FORMATS
! 1366: section.
! 1367: This command works only if at least one client is attached.
! 1368: .It Xo
! 1369: .Ic choose-session
! 1370: .Op Fl F Ar format
! 1371: .Op Fl t Ar target-window
! 1372: .Op Ar template
! 1373: .Xc
! 1374: Put a window into session choice mode, where a session may be selected
! 1375: interactively from a list.
! 1376: When one is chosen,
! 1377: .Ql %%
! 1378: is replaced by the session name in
! 1379: .Ar template
! 1380: and the result executed as a command.
! 1381: If
! 1382: .Ar template
! 1383: is not given, "switch-client -t '%%'" is used.
! 1384: For the meaning of the
! 1385: .Fl F
! 1386: flag, see the
! 1387: .Sx FORMATS
! 1388: section.
! 1389: This command works only if at least one client is attached.
! 1390: .It Xo
! 1391: .Ic choose-tree
! 1392: .Op Fl suw
! 1393: .Op Fl b Ar session-template
! 1394: .Op Fl c Ar window-template
! 1395: .Op Fl S Ar format
! 1396: .Op Fl W Ar format
! 1397: .Op Fl t Ar target-window
! 1398: .Xc
! 1399: Put a window into tree choice mode, where either sessions or windows may be
! 1400: selected interactively from a list.
! 1401: By default, windows belonging to a session are indented to show their
! 1402: relationship to a session.
! 1403: .Pp
! 1404: Note that the
! 1405: .Ic choose-window
! 1406: and
! 1407: .Ic choose-session
! 1408: commands are wrappers around
! 1409: .Ic choose-tree .
! 1410: .Pp
! 1411: If
! 1412: .Fl s
! 1413: is given, will show sessions.
! 1414: If
! 1415: .Fl w
! 1416: is given, will show windows.
! 1417: .Pp
! 1418: By default, the tree is collapsed and sessions must be expanded to windows
! 1419: with the right arrow key.
! 1420: The
! 1421: .Fl u
! 1422: option will start with all sessions expanded instead.
! 1423: .Pp
! 1424: If
! 1425: .Fl b
! 1426: is given, will override the default session command.
! 1427: Note that
! 1428: .Ql %%
! 1429: can be used and will be replaced with the session name.
! 1430: The default option if not specified is "switch-client -t '%%'".
! 1431: If
! 1432: .Fl c
! 1433: is given, will override the default window command.
! 1434: Like
! 1435: .Fl b ,
! 1436: .Ql %%
! 1437: can be used and will be replaced with the session name and window index.
! 1438: When a window is chosen from the list, the session command is run before the
! 1439: window command.
! 1440: .Pp
! 1441: .Fl S
! 1442: uses
! 1443: .Ar format
! 1444: instead of the default session
! 1445: format and
! 1446: .Fl W
! 1447: instead of the default window format.
! 1448: For the meaning of
! 1449: .Ar format ,
! 1450: see the
! 1451: .Sx FORMATS
! 1452: section.
! 1453: .Pp
! 1454: This command works only if at least one client is attached.
! 1455: .It Xo
! 1456: .Ic choose-window
! 1457: .Op Fl F Ar format
! 1458: .Op Fl t Ar target-window
! 1459: .Op Ar template
! 1460: .Xc
! 1461: Put a window into window choice mode, where a window may be chosen
! 1462: interactively from a list.
! 1463: After a window is selected,
! 1464: .Ql %%
! 1465: is replaced by the session name and window index in
! 1466: .Ar template
! 1467: and the result executed as a command.
! 1468: If
! 1469: .Ar template
! 1470: is not given, "select-window -t '%%'" is used.
! 1471: For the meaning of the
! 1472: .Fl F
! 1473: flag, see the
! 1474: .Sx FORMATS
! 1475: section.
! 1476: This command works only if at least one client is attached.
! 1477: .It Xo
! 1478: .Ic display-panes
! 1479: .Op Fl t Ar target-client
! 1480: .Op Ar template
! 1481: .Xc
! 1482: .D1 (alias: Ic displayp )
! 1483: Display a visible indicator of each pane shown by
! 1484: .Ar target-client .
! 1485: See the
! 1486: .Ic display-panes-time ,
! 1487: .Ic display-panes-colour ,
! 1488: and
! 1489: .Ic display-panes-active-colour
! 1490: session options.
! 1491: While the indicator is on screen, a pane may be chosen with the
! 1492: .Ql 0
! 1493: to
! 1494: .Ql 9
! 1495: keys, which will cause
! 1496: .Ar template
! 1497: to be executed as a command with
! 1498: .Ql %%
! 1499: substituted by the pane ID.
! 1500: The default
! 1501: .Ar template
! 1502: is "select-pane -t '%%'".
! 1503: .It Xo Ic find-window
! 1504: .Op Fl CNT
! 1505: .Op Fl F Ar format
! 1506: .Op Fl t Ar target-window
! 1507: .Ar match-string
! 1508: .Xc
! 1509: .D1 (alias: Ic findw )
! 1510: Search for the
! 1511: .Xr fnmatch 3
! 1512: pattern
! 1513: .Ar match-string
! 1514: in window names, titles, and visible content (but not history).
! 1515: The flags control matching behavior:
! 1516: .Fl C
! 1517: matches only visible window contents,
! 1518: .Fl N
! 1519: matches only the window name and
! 1520: .Fl T
! 1521: matches only the window title.
! 1522: The default is
! 1523: .Fl CNT .
! 1524: If only one window is matched, it'll be automatically selected,
! 1525: otherwise a choice list is shown.
! 1526: For the meaning of the
! 1527: .Fl F
! 1528: flag, see the
! 1529: .Sx FORMATS
! 1530: section.
! 1531: This command works only if at least one client is attached.
! 1532: .It Xo Ic join-pane
! 1533: .Op Fl bdhv
! 1534: .Oo Fl l
! 1535: .Ar size |
! 1536: .Fl p Ar percentage Oc
! 1537: .Op Fl s Ar src-pane
! 1538: .Op Fl t Ar dst-pane
! 1539: .Xc
! 1540: .D1 (alias: Ic joinp )
! 1541: Like
! 1542: .Ic split-window ,
! 1543: but instead of splitting
! 1544: .Ar dst-pane
! 1545: and creating a new pane, split it and move
! 1546: .Ar src-pane
! 1547: into the space.
! 1548: This can be used to reverse
! 1549: .Ic break-pane .
! 1550: The
! 1551: .Fl b
! 1552: option causes
! 1553: .Ar src-pane
! 1554: to be joined to left of or above
! 1555: .Ar dst-pane .
! 1556: .Pp
! 1557: If
! 1558: .Fl s
! 1559: is omitted and a marked pane is present (see
! 1560: .Ic select-pane
! 1561: .Fl m ) ,
! 1562: the marked pane is used rather than the current pane.
! 1563: .It Xo Ic kill-pane
! 1564: .Op Fl a
! 1565: .Op Fl t Ar target-pane
! 1566: .Xc
! 1567: .D1 (alias: Ic killp )
! 1568: Destroy the given pane.
! 1569: If no panes remain in the containing window, it is also destroyed.
! 1570: The
! 1571: .Fl a
! 1572: option kills all but the pane given with
! 1573: .Fl t .
! 1574: .It Xo Ic kill-window
! 1575: .Op Fl a
! 1576: .Op Fl t Ar target-window
! 1577: .Xc
! 1578: .D1 (alias: Ic killw )
! 1579: Kill the current window or the window at
! 1580: .Ar target-window ,
! 1581: removing it from any sessions to which it is linked.
! 1582: The
! 1583: .Fl a
! 1584: option kills all but the window given with
! 1585: .Fl t .
! 1586: .It Xo Ic last-pane
! 1587: .Op Fl de
! 1588: .Op Fl t Ar target-window
! 1589: .Xc
! 1590: .D1 (alias: Ic lastp )
! 1591: Select the last (previously selected) pane.
! 1592: .Fl e
! 1593: enables or
! 1594: .Fl d
! 1595: disables input to the pane.
! 1596: .It Ic last-window Op Fl t Ar target-session
! 1597: .D1 (alias: Ic last )
! 1598: Select the last (previously selected) window.
! 1599: If no
! 1600: .Ar target-session
! 1601: is specified, select the last window of the current session.
! 1602: .It Xo Ic link-window
! 1603: .Op Fl adk
! 1604: .Op Fl s Ar src-window
! 1605: .Op Fl t Ar dst-window
! 1606: .Xc
! 1607: .D1 (alias: Ic linkw )
! 1608: Link the window at
! 1609: .Ar src-window
! 1610: to the specified
! 1611: .Ar dst-window .
! 1612: If
! 1613: .Ar dst-window
! 1614: is specified and no such window exists, the
! 1615: .Ar src-window
! 1616: is linked there.
! 1617: With
! 1618: .Fl a ,
! 1619: the window is moved to the next index up (following windows
! 1620: are moved if necessary).
! 1621: If
! 1622: .Fl k
! 1623: is given and
! 1624: .Ar dst-window
! 1625: exists, it is killed, otherwise an error is generated.
! 1626: If
! 1627: .Fl d
! 1628: is given, the newly linked window is not selected.
! 1629: .It Xo Ic list-panes
! 1630: .Op Fl as
! 1631: .Op Fl F Ar format
! 1632: .Op Fl t Ar target
! 1633: .Xc
! 1634: .D1 (alias: Ic lsp )
! 1635: If
! 1636: .Fl a
! 1637: is given,
! 1638: .Ar target
! 1639: is ignored and all panes on the server are listed.
! 1640: If
! 1641: .Fl s
! 1642: is given,
! 1643: .Ar target
! 1644: is a session (or the current session).
! 1645: If neither is given,
! 1646: .Ar target
! 1647: is a window (or the current window).
! 1648: For the meaning of the
! 1649: .Fl F
! 1650: flag, see the
! 1651: .Sx FORMATS
! 1652: section.
! 1653: .It Xo Ic list-windows
! 1654: .Op Fl a
! 1655: .Op Fl F Ar format
! 1656: .Op Fl t Ar target-session
! 1657: .Xc
! 1658: .D1 (alias: Ic lsw )
! 1659: If
! 1660: .Fl a
! 1661: is given, list all windows on the server.
! 1662: Otherwise, list windows in the current session or in
! 1663: .Ar target-session .
! 1664: For the meaning of the
! 1665: .Fl F
! 1666: flag, see the
! 1667: .Sx FORMATS
! 1668: section.
! 1669: .It Xo Ic move-pane
! 1670: .Op Fl bdhv
! 1671: .Oo Fl l
! 1672: .Ar size |
! 1673: .Fl p Ar percentage Oc
! 1674: .Op Fl s Ar src-pane
! 1675: .Op Fl t Ar dst-pane
! 1676: .Xc
! 1677: .D1 (alias: Ic movep )
! 1678: Like
! 1679: .Ic join-pane ,
! 1680: but
! 1681: .Ar src-pane
! 1682: and
! 1683: .Ar dst-pane
! 1684: may belong to the same window.
! 1685: .It Xo Ic move-window
! 1686: .Op Fl ardk
! 1687: .Op Fl s Ar src-window
! 1688: .Op Fl t Ar dst-window
! 1689: .Xc
! 1690: .D1 (alias: Ic movew )
! 1691: This is similar to
! 1692: .Ic link-window ,
! 1693: except the window at
! 1694: .Ar src-window
! 1695: is moved to
! 1696: .Ar dst-window .
! 1697: With
! 1698: .Fl r ,
! 1699: all windows in the session are renumbered in sequential order, respecting
! 1700: the
! 1701: .Ic base-index
! 1702: option.
! 1703: .It Xo Ic new-window
! 1704: .Op Fl adkP
! 1705: .Op Fl c Ar start-directory
! 1706: .Op Fl F Ar format
! 1707: .Op Fl n Ar window-name
! 1708: .Op Fl t Ar target-window
! 1709: .Op Ar shell-command
! 1710: .Xc
! 1711: .D1 (alias: Ic neww )
! 1712: Create a new window.
! 1713: With
! 1714: .Fl a ,
! 1715: the new window is inserted at the next index up from the specified
! 1716: .Ar target-window ,
! 1717: moving windows up if necessary,
! 1718: otherwise
! 1719: .Ar target-window
! 1720: is the new window location.
! 1721: .Pp
! 1722: If
! 1723: .Fl d
! 1724: is given, the session does not make the new window the current window.
! 1725: .Ar target-window
! 1726: represents the window to be created; if the target already exists an error is
! 1727: shown, unless the
! 1728: .Fl k
! 1729: flag is used, in which case it is destroyed.
! 1730: .Ar shell-command
! 1731: is the command to execute.
! 1732: If
! 1733: .Ar shell-command
! 1734: is not specified, the value of the
! 1735: .Ic default-command
! 1736: option is used.
! 1737: .Fl c
! 1738: specifies the working directory in which the new window is created.
! 1739: .Pp
! 1740: When the shell command completes, the window closes.
! 1741: See the
! 1742: .Ic remain-on-exit
! 1743: option to change this behaviour.
! 1744: .Pp
! 1745: The
! 1746: .Ev TERM
! 1747: environment variable must be set to
! 1748: .Ql screen
! 1749: or
! 1750: .Ql tmux
! 1751: for all programs running
! 1752: .Em inside
! 1753: .Nm .
! 1754: New windows will automatically have
! 1755: .Ql TERM=screen
! 1756: added to their environment, but care must be taken not to reset this in shell
! 1757: start-up files.
! 1758: .Pp
! 1759: The
! 1760: .Fl P
! 1761: option prints information about the new window after it has been created.
! 1762: By default, it uses the format
! 1763: .Ql #{session_name}:#{window_index}
! 1764: but a different format may be specified with
! 1765: .Fl F .
! 1766: .It Ic next-layout Op Fl t Ar target-window
! 1767: .D1 (alias: Ic nextl )
! 1768: Move a window to the next layout and rearrange the panes to fit.
! 1769: .It Xo Ic next-window
! 1770: .Op Fl a
! 1771: .Op Fl t Ar target-session
! 1772: .Xc
! 1773: .D1 (alias: Ic next )
! 1774: Move to the next window in the session.
! 1775: If
! 1776: .Fl a
! 1777: is used, move to the next window with an alert.
! 1778: .It Xo Ic pipe-pane
! 1779: .Op Fl o
! 1780: .Op Fl t Ar target-pane
! 1781: .Op Ar shell-command
! 1782: .Xc
! 1783: .D1 (alias: Ic pipep )
! 1784: Pipe any output sent by the program in
! 1785: .Ar target-pane
! 1786: to a shell command.
! 1787: A pane may only be piped to one command at a time, any existing pipe is
! 1788: closed before
! 1789: .Ar shell-command
! 1790: is executed.
! 1791: The
! 1792: .Ar shell-command
! 1793: string may contain the special character sequences supported by the
! 1794: .Ic status-left
! 1795: option.
! 1796: If no
! 1797: .Ar shell-command
! 1798: is given, the current pipe (if any) is closed.
! 1799: .Pp
! 1800: The
! 1801: .Fl o
! 1802: option only opens a new pipe if no previous pipe exists, allowing a pipe to
! 1803: be toggled with a single key, for example:
! 1804: .Bd -literal -offset indent
! 1805: bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
! 1806: .Ed
! 1807: .It Xo Ic previous-layout
! 1808: .Op Fl t Ar target-window
! 1809: .Xc
! 1810: .D1 (alias: Ic prevl )
! 1811: Move to the previous layout in the session.
! 1812: .It Xo Ic previous-window
! 1813: .Op Fl a
! 1814: .Op Fl t Ar target-session
! 1815: .Xc
! 1816: .D1 (alias: Ic prev )
! 1817: Move to the previous window in the session.
! 1818: With
! 1819: .Fl a ,
! 1820: move to the previous window with an alert.
! 1821: .It Xo Ic rename-window
! 1822: .Op Fl t Ar target-window
! 1823: .Ar new-name
! 1824: .Xc
! 1825: .D1 (alias: Ic renamew )
! 1826: Rename the current window, or the window at
! 1827: .Ar target-window
! 1828: if specified, to
! 1829: .Ar new-name .
! 1830: .It Xo Ic resize-pane
! 1831: .Op Fl DLMRUZ
! 1832: .Op Fl t Ar target-pane
! 1833: .Op Fl x Ar width
! 1834: .Op Fl y Ar height
! 1835: .Op Ar adjustment
! 1836: .Xc
! 1837: .D1 (alias: Ic resizep )
! 1838: Resize a pane, up, down, left or right by
! 1839: .Ar adjustment
! 1840: with
! 1841: .Fl U ,
! 1842: .Fl D ,
! 1843: .Fl L
! 1844: or
! 1845: .Fl R ,
! 1846: or
! 1847: to an absolute size
! 1848: with
! 1849: .Fl x
! 1850: or
! 1851: .Fl y .
! 1852: The
! 1853: .Ar adjustment
! 1854: is given in lines or cells (the default is 1).
! 1855: .Pp
! 1856: With
! 1857: .Fl Z ,
! 1858: the active pane is toggled between zoomed (occupying the whole of the window)
! 1859: and unzoomed (its normal position in the layout).
! 1860: .Pp
! 1861: .Fl M
! 1862: begins mouse resizing (only valid if bound to a mouse key binding, see
! 1863: .Sx MOUSE SUPPORT ) .
! 1864: .It Xo Ic respawn-pane
! 1865: .Op Fl k
! 1866: .Op Fl t Ar target-pane
! 1867: .Op Ar shell-command
! 1868: .Xc
! 1869: .D1 (alias: Ic respawnp )
! 1870: Reactivate a pane in which the command has exited (see the
! 1871: .Ic remain-on-exit
! 1872: window option).
! 1873: If
! 1874: .Ar shell-command
! 1875: is not given, the command used when the pane was created is executed.
! 1876: The pane must be already inactive, unless
! 1877: .Fl k
! 1878: is given, in which case any existing command is killed.
! 1879: .It Xo Ic respawn-window
! 1880: .Op Fl k
! 1881: .Op Fl t Ar target-window
! 1882: .Op Ar shell-command
! 1883: .Xc
! 1884: .D1 (alias: Ic respawnw )
! 1885: Reactivate a window in which the command has exited (see the
! 1886: .Ic remain-on-exit
! 1887: window option).
! 1888: If
! 1889: .Ar shell-command
! 1890: is not given, the command used when the window was created is executed.
! 1891: The window must be already inactive, unless
! 1892: .Fl k
! 1893: is given, in which case any existing command is killed.
! 1894: .It Xo Ic rotate-window
! 1895: .Op Fl DU
! 1896: .Op Fl t Ar target-window
! 1897: .Xc
! 1898: .D1 (alias: Ic rotatew )
! 1899: Rotate the positions of the panes within a window, either upward (numerically
! 1900: lower) with
! 1901: .Fl U
! 1902: or downward (numerically higher).
! 1903: .It Xo Ic select-layout
! 1904: .Op Fl nop
! 1905: .Op Fl t Ar target-window
! 1906: .Op Ar layout-name
! 1907: .Xc
! 1908: .D1 (alias: Ic selectl )
! 1909: Choose a specific layout for a window.
! 1910: If
! 1911: .Ar layout-name
! 1912: is not given, the last preset layout used (if any) is reapplied.
! 1913: .Fl n
! 1914: and
! 1915: .Fl p
! 1916: are equivalent to the
! 1917: .Ic next-layout
! 1918: and
! 1919: .Ic previous-layout
! 1920: commands.
! 1921: .Fl o
! 1922: applies the last set layout if possible (undoes the most recent layout change).
! 1923: .It Xo Ic select-pane
! 1924: .Op Fl DdegLlMmRU
! 1925: .Op Fl P Ar style
! 1926: .Op Fl t Ar target-pane
! 1927: .Xc
! 1928: .D1 (alias: Ic selectp )
! 1929: Make pane
! 1930: .Ar target-pane
! 1931: the active pane in window
! 1932: .Ar target-window ,
! 1933: or set its style (with
! 1934: .Fl P ) .
! 1935: If one of
! 1936: .Fl D ,
! 1937: .Fl L ,
! 1938: .Fl R ,
! 1939: or
! 1940: .Fl U
! 1941: is used, respectively the pane below, to the left, to the right, or above the
! 1942: target pane is used.
! 1943: .Fl l
! 1944: is the same as using the
! 1945: .Ic last-pane
! 1946: command.
! 1947: .Fl e
! 1948: enables or
! 1949: .Fl d
! 1950: disables input to the pane.
! 1951: .Pp
! 1952: .Fl m
! 1953: and
! 1954: .Fl M
! 1955: are used to set and clear the
! 1956: .Em marked pane .
! 1957: There is one marked pane at a time, setting a new marked pane clears the last.
! 1958: The marked pane is the default target for
! 1959: .Fl s
! 1960: to
! 1961: .Ic join-pane ,
! 1962: .Ic swap-pane
! 1963: and
! 1964: .Ic swap-window .
! 1965: .Pp
! 1966: Each pane has a style: by default the
! 1967: .Ic window-style
! 1968: and
! 1969: .Ic window-active-style
! 1970: options are used,
! 1971: .Ic select-pane
! 1972: .Fl P
! 1973: sets the style for a single pane.
! 1974: For example, to set the pane 1 background to red:
! 1975: .Bd -literal -offset indent
! 1976: select-pane -t:.1 -P 'bg=red'
! 1977: .Ed
! 1978: .Pp
! 1979: .Fl g
! 1980: shows the current pane style.
! 1981: .It Xo Ic select-window
! 1982: .Op Fl lnpT
! 1983: .Op Fl t Ar target-window
! 1984: .Xc
! 1985: .D1 (alias: Ic selectw )
! 1986: Select the window at
! 1987: .Ar target-window .
! 1988: .Fl l ,
! 1989: .Fl n
! 1990: and
! 1991: .Fl p
! 1992: are equivalent to the
! 1993: .Ic last-window ,
! 1994: .Ic next-window
! 1995: and
! 1996: .Ic previous-window
! 1997: commands.
! 1998: If
! 1999: .Fl T
! 2000: is given and the selected window is already the current window,
! 2001: the command behaves like
! 2002: .Ic last-window .
! 2003: .It Xo Ic split-window
! 2004: .Op Fl bdfhvP
! 2005: .Op Fl c Ar start-directory
! 2006: .Oo Fl l
! 2007: .Ar size |
! 2008: .Fl p Ar percentage Oc
! 2009: .Op Fl t Ar target-pane
! 2010: .Op Ar shell-command
! 2011: .Op Fl F Ar format
! 2012: .Xc
! 2013: .D1 (alias: Ic splitw )
! 2014: Create a new pane by splitting
! 2015: .Ar target-pane :
! 2016: .Fl h
! 2017: does a horizontal split and
! 2018: .Fl v
! 2019: a vertical split; if neither is specified,
! 2020: .Fl v
! 2021: is assumed.
! 2022: The
! 2023: .Fl l
! 2024: and
! 2025: .Fl p
! 2026: options specify the size of the new pane in lines (for vertical split) or in
! 2027: cells (for horizontal split), or as a percentage, respectively.
! 2028: The
! 2029: .Fl b
! 2030: option causes the new pane to be created to the left of or above
! 2031: .Ar target-pane .
! 2032: The
! 2033: .Fl f
! 2034: option creates a new pane spanning the full window height (with
! 2035: .Fl h )
! 2036: or full window width (with
! 2037: .Fl v ) ,
! 2038: instead of splitting the active pane.
! 2039: All other options have the same meaning as for the
! 2040: .Ic new-window
! 2041: command.
! 2042: .It Xo Ic swap-pane
! 2043: .Op Fl dDU
! 2044: .Op Fl s Ar src-pane
! 2045: .Op Fl t Ar dst-pane
! 2046: .Xc
! 2047: .D1 (alias: Ic swapp )
! 2048: Swap two panes.
! 2049: If
! 2050: .Fl U
! 2051: is used and no source pane is specified with
! 2052: .Fl s ,
! 2053: .Ar dst-pane
! 2054: is swapped with the previous pane (before it numerically);
! 2055: .Fl D
! 2056: swaps with the next pane (after it numerically).
! 2057: .Fl d
! 2058: instructs
! 2059: .Nm
! 2060: not to change the active pane.
! 2061: .Pp
! 2062: If
! 2063: .Fl s
! 2064: is omitted and a marked pane is present (see
! 2065: .Ic select-pane
! 2066: .Fl m ) ,
! 2067: the marked pane is used rather than the current pane.
! 2068: .It Xo Ic swap-window
! 2069: .Op Fl d
! 2070: .Op Fl s Ar src-window
! 2071: .Op Fl t Ar dst-window
! 2072: .Xc
! 2073: .D1 (alias: Ic swapw )
! 2074: This is similar to
! 2075: .Ic link-window ,
! 2076: except the source and destination windows are swapped.
! 2077: It is an error if no window exists at
! 2078: .Ar src-window .
! 2079: .Pp
! 2080: Like
! 2081: .Ic swap-pane ,
! 2082: if
! 2083: .Fl s
! 2084: is omitted and a marked pane is present (see
! 2085: .Ic select-pane
! 2086: .Fl m ) ,
! 2087: the window containing the marked pane is used rather than the current window.
! 2088: .It Xo Ic unlink-window
! 2089: .Op Fl k
! 2090: .Op Fl t Ar target-window
! 2091: .Xc
! 2092: .D1 (alias: Ic unlinkw )
! 2093: Unlink
! 2094: .Ar target-window .
! 2095: Unless
! 2096: .Fl k
! 2097: is given, a window may be unlinked only if it is linked to multiple sessions -
! 2098: windows may not be linked to no sessions;
! 2099: if
! 2100: .Fl k
! 2101: is specified and the window is linked to only one session, it is unlinked and
! 2102: destroyed.
! 2103: .El
! 2104: .Sh KEY BINDINGS
! 2105: .Nm
! 2106: allows a command to be bound to most keys, with or without a prefix key.
! 2107: When specifying keys, most represent themselves (for example
! 2108: .Ql A
! 2109: to
! 2110: .Ql Z ) .
! 2111: Ctrl keys may be prefixed with
! 2112: .Ql C-
! 2113: or
! 2114: .Ql ^ ,
! 2115: and Alt (meta) with
! 2116: .Ql M- .
! 2117: In addition, the following special key names are accepted:
! 2118: .Em Up ,
! 2119: .Em Down ,
! 2120: .Em Left ,
! 2121: .Em Right ,
! 2122: .Em BSpace ,
! 2123: .Em BTab ,
! 2124: .Em DC
! 2125: (Delete),
! 2126: .Em End ,
! 2127: .Em Enter ,
! 2128: .Em Escape ,
! 2129: .Em F1
! 2130: to
! 2131: .Em F12 ,
! 2132: .Em Home ,
! 2133: .Em IC
! 2134: (Insert),
! 2135: .Em NPage/PageDown/PgDn ,
! 2136: .Em PPage/PageUp/PgUp ,
! 2137: .Em Space ,
! 2138: and
! 2139: .Em Tab .
! 2140: Note that to bind the
! 2141: .Ql \&"
! 2142: or
! 2143: .Ql '
! 2144: keys, quotation marks are necessary, for example:
! 2145: .Bd -literal -offset indent
! 2146: bind-key '"' split-window
! 2147: bind-key "'" new-window
! 2148: .Ed
! 2149: .Pp
! 2150: Commands related to key bindings are as follows:
! 2151: .Bl -tag -width Ds
! 2152: .It Xo Ic bind-key
! 2153: .Op Fl nr
! 2154: .Op Fl T Ar key-table
! 2155: .Ar key Ar command Op Ar arguments
! 2156: .Xc
! 2157: .D1 (alias: Ic bind )
! 2158: Bind key
! 2159: .Ar key
! 2160: to
! 2161: .Ar command .
! 2162: Keys are bound in a key table.
! 2163: By default (without -T), the key is bound in
! 2164: the
! 2165: .Em prefix
! 2166: key table.
! 2167: This table is used for keys pressed after the prefix key (for example,
! 2168: by default
! 2169: .Ql c
! 2170: is bound to
! 2171: .Ic new-window
! 2172: in the
! 2173: .Em prefix
! 2174: table, so
! 2175: .Ql C-b c
! 2176: creates a new window).
! 2177: The
! 2178: .Em root
! 2179: table is used for keys pressed without the prefix key: binding
! 2180: .Ql c
! 2181: to
! 2182: .Ic new-window
! 2183: in the
! 2184: .Em root
! 2185: table (not recommended) means a plain
! 2186: .Ql c
! 2187: will create a new window.
! 2188: .Fl n
! 2189: is an alias
! 2190: for
! 2191: .Fl T Ar root .
! 2192: Keys may also be bound in custom key tables and the
! 2193: .Ic switch-client
! 2194: .Fl T
! 2195: command used to switch to them from a key binding.
! 2196: The
! 2197: .Fl r
! 2198: flag indicates this key may repeat, see the
! 2199: .Ic repeat-time
! 2200: option.
! 2201: .Pp
! 2202: To view the default bindings and possible commands, see the
! 2203: .Ic list-keys
! 2204: command.
! 2205: .It Xo Ic list-keys
! 2206: .Op Fl T Ar key-table
! 2207: .Xc
! 2208: .D1 (alias: Ic lsk )
! 2209: List all key bindings.
! 2210: Without
! 2211: .Fl T
! 2212: all key tables are printed.
! 2213: With
! 2214: .Fl T
! 2215: only
! 2216: .Ar key-table .
! 2217: .It Xo Ic send-keys
! 2218: .Op Fl lMRX
! 2219: .Op Fl N Ar repeat-count
! 2220: .Op Fl t Ar target-pane
! 2221: .Ar key Ar ...
! 2222: .Xc
! 2223: .D1 (alias: Ic send )
! 2224: Send a key or keys to a window.
! 2225: Each argument
! 2226: .Ar key
! 2227: is the name of the key (such as
! 2228: .Ql C-a
! 2229: or
! 2230: .Ql NPage )
! 2231: to send; if the string is not recognised as a key, it is sent as a series of
! 2232: characters.
! 2233: The
! 2234: .Fl l
! 2235: flag disables key name lookup and sends the keys literally.
! 2236: All arguments are sent sequentially from first to last.
! 2237: The
! 2238: .Fl R
! 2239: flag causes the terminal state to be reset.
! 2240: .Pp
! 2241: .Fl M
! 2242: passes through a mouse event (only valid if bound to a mouse key binding, see
! 2243: .Sx MOUSE SUPPORT ) .
! 2244: .Pp
! 2245: .Fl X
! 2246: is used to send a command into copy mode - see
! 2247: the
! 2248: .Sx WINDOWS AND PANES
! 2249: section.
! 2250: .Fl N
! 2251: specifies a repeat count.
! 2252: .It Xo Ic send-prefix
! 2253: .Op Fl 2
! 2254: .Op Fl t Ar target-pane
! 2255: .Xc
! 2256: Send the prefix key, or with
! 2257: .Fl 2
! 2258: the secondary prefix key, to a window as if it was pressed.
! 2259: .It Xo Ic unbind-key
! 2260: .Op Fl an
! 2261: .Op Fl T Ar key-table
! 2262: .Ar key
! 2263: .Xc
! 2264: .D1 (alias: Ic unbind )
! 2265: Unbind the command bound to
! 2266: .Ar key .
! 2267: .Fl n
! 2268: and
! 2269: .Fl T
! 2270: are the same as for
! 2271: .Ic bind-key .
! 2272: If
! 2273: .Fl a
! 2274: is present, all key bindings are removed.
! 2275: .El
! 2276: .Sh OPTIONS
! 2277: The appearance and behaviour of
! 2278: .Nm
! 2279: may be modified by changing the value of various options.
! 2280: There are three types of option:
! 2281: .Em server options ,
! 2282: .Em session options
! 2283: and
! 2284: .Em window options .
! 2285: .Pp
! 2286: The
! 2287: .Nm
! 2288: server has a set of global options which do not apply to any particular
! 2289: window or session.
! 2290: These are altered with the
! 2291: .Ic set-option
! 2292: .Fl s
! 2293: command, or displayed with the
! 2294: .Ic show-options
! 2295: .Fl s
! 2296: command.
! 2297: .Pp
! 2298: In addition, each individual session may have a set of session options, and
! 2299: there is a separate set of global session options.
! 2300: Sessions which do not have a particular option configured inherit the value
! 2301: from the global session options.
! 2302: Session options are set or unset with the
! 2303: .Ic set-option
! 2304: command and may be listed with the
! 2305: .Ic show-options
! 2306: command.
! 2307: The available server and session options are listed under the
! 2308: .Ic set-option
! 2309: command.
! 2310: .Pp
! 2311: Similarly, a set of window options is attached to each window, and there is
! 2312: a set of global window options from which any unset options are inherited.
! 2313: Window options are altered with the
! 2314: .Ic set-window-option
! 2315: command and can be listed with the
! 2316: .Ic show-window-options
! 2317: command.
! 2318: All window options are documented with the
! 2319: .Ic set-window-option
! 2320: command.
! 2321: .Pp
! 2322: .Nm
! 2323: also supports user options which are prefixed with a
! 2324: .Ql \&@ .
! 2325: User options may have any name, so long as they are prefixed with
! 2326: .Ql \&@ ,
! 2327: and be set to any string.
! 2328: For example:
! 2329: .Bd -literal -offset indent
! 2330: $ tmux setw -q @foo "abc123"
! 2331: $ tmux showw -v @foo
! 2332: abc123
! 2333: .Ed
! 2334: .Pp
! 2335: Commands which set options are as follows:
! 2336: .Bl -tag -width Ds
! 2337: .It Xo Ic set-option
! 2338: .Op Fl agoqsuw
! 2339: .Op Fl t Ar target-session | Ar target-window
! 2340: .Ar option Ar value
! 2341: .Xc
! 2342: .D1 (alias: Ic set )
! 2343: Set a window option with
! 2344: .Fl w
! 2345: (equivalent to the
! 2346: .Ic set-window-option
! 2347: command),
! 2348: a server option with
! 2349: .Fl s ,
! 2350: otherwise a session option.
! 2351: If
! 2352: .Fl g
! 2353: is given, the global session or window option is set.
! 2354: The
! 2355: .Fl u
! 2356: flag unsets an option, so a session inherits the option from the global
! 2357: options (or with
! 2358: .Fl g ,
! 2359: restores a global option to the default).
! 2360: .Pp
! 2361: The
! 2362: .Fl o
! 2363: flag prevents setting an option that is already set and the
! 2364: .Fl q
! 2365: flag suppresses errors about unknown or ambiguous options.
! 2366: .Pp
! 2367: With
! 2368: .Fl a ,
! 2369: and if the option expects a string or a style,
! 2370: .Ar value
! 2371: is appended to the existing setting.
! 2372: For example:
! 2373: .Bd -literal -offset indent
! 2374: set -g status-left "foo"
! 2375: set -ag status-left "bar"
! 2376: .Ed
! 2377: .Pp
! 2378: Will result in
! 2379: .Ql foobar .
! 2380: And:
! 2381: .Bd -literal -offset indent
! 2382: set -g status-style "bg=red"
! 2383: set -ag status-style "fg=blue"
! 2384: .Ed
! 2385: .Pp
! 2386: Will result in a red background
! 2387: .Em and
! 2388: blue foreground.
! 2389: Without
! 2390: .Fl a ,
! 2391: the result would be the default background and a blue foreground.
! 2392: .Pp
! 2393: Available window options are listed under
! 2394: .Ic set-window-option .
! 2395: .Pp
! 2396: .Ar value
! 2397: depends on the option and may be a number, a string, or a flag (on, off, or
! 2398: omitted to toggle).
! 2399: .Pp
! 2400: Available server options are:
! 2401: .Bl -tag -width Ds
! 2402: .It Ic buffer-limit Ar number
! 2403: Set the number of buffers; as new buffers are added to the top of the stack,
! 2404: old ones are removed from the bottom if necessary to maintain this maximum
! 2405: length.
! 2406: .It Xo Ic command-alias[]
! 2407: .Ar name=value
! 2408: .Xc
! 2409: This is an array of custom aliases for commands.
! 2410: If an unknown command matches
! 2411: .Ar name ,
! 2412: it is replaced with
! 2413: .Ar value .
! 2414: For example, after:
! 2415: .Pp
! 2416: .Dl set -s command-alias[2] zoom='resize-pane -Z'
! 2417: .Pp
! 2418: Using:
! 2419: .Pp
! 2420: .Dl zoom -t:.1
! 2421: .Pp
! 2422: Is equivalent to:
! 2423: .Pp
! 2424: .Dl resize-pane -Z -t:.1
! 2425: .Pp
! 2426: Note that aliases are expanded when a command is parsed rather than when it is
! 2427: executed, so binding an alias with
! 2428: .Ic bind-key
! 2429: will bind the expanded form.
! 2430: .It Ic default-terminal Ar terminal
! 2431: Set the default terminal for new windows created in this session - the
! 2432: default value of the
! 2433: .Ev TERM
! 2434: environment variable.
! 2435: For
! 2436: .Nm
! 2437: to work correctly, this
! 2438: .Em must
! 2439: be set to
! 2440: .Ql screen ,
! 2441: .Ql tmux
! 2442: or a derivative of them.
! 2443: .It Ic escape-time Ar time
! 2444: Set the time in milliseconds for which
! 2445: .Nm
! 2446: waits after an escape is input to determine if it is part of a function or meta
! 2447: key sequences.
! 2448: The default is 500 milliseconds.
! 2449: .It Xo Ic exit-unattached
! 2450: .Op Ic on | off
! 2451: .Xc
! 2452: If enabled, the server will exit when there are no attached clients.
! 2453: .It Xo Ic focus-events
! 2454: .Op Ic on | off
! 2455: .Xc
! 2456: When enabled, focus events are requested from the terminal if supported and
! 2457: passed through to applications running in
! 2458: .Nm .
! 2459: Attached clients should be detached and attached again after changing this
! 2460: option.
! 2461: .It Ic history-file Ar path
! 2462: If not empty, a file to which
! 2463: .Nm
! 2464: will write command prompt history on exit and load it from on start.
! 2465: .It Ic message-limit Ar number
! 2466: Set the number of error or information messages to save in the message log for
! 2467: each client.
! 2468: The default is 100.
! 2469: .It Xo Ic set-clipboard
! 2470: .Op Ic on | off
! 2471: .Xc
! 2472: Attempt to set the terminal clipboard content using the
! 2473: \ee]52;...\e007
! 2474: .Xr xterm 1
! 2475: escape sequences.
! 2476: This option is on by default if there is an
! 2477: .Em \&Ms
! 2478: entry in the
! 2479: .Xr terminfo 5
! 2480: description for the client terminal.
! 2481: Note that this feature needs to be enabled in
! 2482: .Xr xterm 1
! 2483: by setting the resource:
! 2484: .Bd -literal -offset indent
! 2485: disallowedWindowOps: 20,21,SetXprop
! 2486: .Ed
! 2487: .Pp
! 2488: Or changing this property from the
! 2489: .Xr xterm 1
! 2490: interactive menu when required.
! 2491: .It Ic terminal-overrides[] Ar string
! 2492: Allow terminal descriptions read using
! 2493: .Xr terminfo 5
! 2494: to be overridden.
! 2495: Each entry is a colon-separated string made up of a terminal type pattern
! 2496: (matched using
! 2497: .Xr fnmatch 3 )
! 2498: and a set of
! 2499: .Em name=value
! 2500: entries.
! 2501: .Pp
! 2502: For example, to set the
! 2503: .Ql clear
! 2504: .Xr terminfo 5
! 2505: entry to
! 2506: .Ql \ee[H\ee[2J
! 2507: for all terminal types matching
! 2508: .Ql rxvt* :
! 2509: .Pp
! 2510: .Dl "rxvt*:clear=\ee[H\ee[2J"
! 2511: .Pp
! 2512: The terminal entry value is passed through
! 2513: .Xr strunvis 3
! 2514: before interpretation.
! 2515: .El
! 2516: .Pp
! 2517: Available session options are:
! 2518: .Bl -tag -width Ds
! 2519: .It Ic assume-paste-time Ar milliseconds
! 2520: If keys are entered faster than one in
! 2521: .Ar milliseconds ,
! 2522: they are assumed to have been pasted rather than typed and
! 2523: .Nm
! 2524: key bindings are not processed.
! 2525: The default is one millisecond and zero disables.
! 2526: .It Ic base-index Ar index
! 2527: Set the base index from which an unused index should be searched when a new
! 2528: window is created.
! 2529: The default is zero.
! 2530: .It Xo Ic bell-action
! 2531: .Op Ic any | none | current | other
! 2532: .Xc
! 2533: Set action on window bell.
! 2534: .Ic any
! 2535: means a bell in any window linked to a session causes a bell in the current
! 2536: window of that session,
! 2537: .Ic none
! 2538: means all bells are ignored,
! 2539: .Ic current
! 2540: means only bells in windows other than the current window are ignored and
! 2541: .Ic other
! 2542: means bells in the current window are ignored but not those in other windows.
! 2543: .It Xo Ic bell-on-alert
! 2544: .Op Ic on | off
! 2545: .Xc
! 2546: If on, ring the terminal bell when an alert
! 2547: occurs.
! 2548: .It Ic default-command Ar shell-command
! 2549: Set the command used for new windows (if not specified when the window is
! 2550: created) to
! 2551: .Ar shell-command ,
! 2552: which may be any
! 2553: .Xr sh 1
! 2554: command.
! 2555: The default is an empty string, which instructs
! 2556: .Nm
! 2557: to create a login shell using the value of the
! 2558: .Ic default-shell
! 2559: option.
! 2560: .It Ic default-shell Ar path
! 2561: Specify the default shell.
! 2562: This is used as the login shell for new windows when the
! 2563: .Ic default-command
! 2564: option is set to empty, and must be the full path of the executable.
! 2565: When started
! 2566: .Nm
! 2567: tries to set a default value from the first suitable of the
! 2568: .Ev SHELL
! 2569: environment variable, the shell returned by
! 2570: .Xr getpwuid 3 ,
! 2571: or
! 2572: .Pa /bin/sh .
! 2573: This option should be configured when
! 2574: .Nm
! 2575: is used as a login shell.
! 2576: .It Xo Ic destroy-unattached
! 2577: .Op Ic on | off
! 2578: .Xc
! 2579: If enabled and the session is no longer attached to any clients, it is
! 2580: destroyed.
! 2581: .It Xo Ic detach-on-destroy
! 2582: .Op Ic on | off
! 2583: .Xc
! 2584: If on (the default), the client is detached when the session it is attached to
! 2585: is destroyed.
! 2586: If off, the client is switched to the most recently active of the remaining
! 2587: sessions.
! 2588: .It Ic display-panes-active-colour Ar colour
! 2589: Set the colour used by the
! 2590: .Ic display-panes
! 2591: command to show the indicator for the active pane.
! 2592: .It Ic display-panes-colour Ar colour
! 2593: Set the colour used by the
! 2594: .Ic display-panes
! 2595: command to show the indicators for inactive panes.
! 2596: .It Ic display-panes-time Ar time
! 2597: Set the time in milliseconds for which the indicators shown by the
! 2598: .Ic display-panes
! 2599: command appear.
! 2600: .It Ic display-time Ar time
! 2601: Set the amount of time for which status line messages and other on-screen
! 2602: indicators are displayed.
! 2603: If set to 0, messages and indicators are displayed until a key is pressed.
! 2604: .Ar time
! 2605: is in milliseconds.
! 2606: .It Ic history-limit Ar lines
! 2607: Set the maximum number of lines held in window history.
! 2608: This setting applies only to new windows - existing window histories are not
! 2609: resized and retain the limit at the point they were created.
! 2610: .It Ic key-table Ar key-table
! 2611: Set the default key table to
! 2612: .Ar key-table
! 2613: instead of
! 2614: .Em root .
! 2615: .It Ic lock-after-time Ar number
! 2616: Lock the session (like the
! 2617: .Ic lock-session
! 2618: command) after
! 2619: .Ar number
! 2620: seconds of inactivity.
! 2621: The default is not to lock (set to 0).
! 2622: .It Ic lock-command Ar shell-command
! 2623: Command to run when locking each client.
! 2624: The default is to run
! 2625: .Xr lock 1
! 2626: with
! 2627: .Fl np .
! 2628: .It Ic message-command-style Ar style
! 2629: Set status line message command style, where
! 2630: .Ar style
! 2631: is a comma-separated list of characteristics to be specified.
! 2632: .Pp
! 2633: These may be
! 2634: .Ql bg=colour
! 2635: to set the background colour,
! 2636: .Ql fg=colour
! 2637: to set the foreground colour, and a list of attributes as specified below.
! 2638: .Pp
! 2639: The colour is one of:
! 2640: .Ic black ,
! 2641: .Ic red ,
! 2642: .Ic green ,
! 2643: .Ic yellow ,
! 2644: .Ic blue ,
! 2645: .Ic magenta ,
! 2646: .Ic cyan ,
! 2647: .Ic white ,
! 2648: aixterm bright variants (if supported:
! 2649: .Ic brightred ,
! 2650: .Ic brightgreen ,
! 2651: and so on),
! 2652: .Ic colour0
! 2653: to
! 2654: .Ic colour255
! 2655: from the 256-colour set,
! 2656: .Ic default ,
! 2657: or a hexadecimal RGB string such as
! 2658: .Ql #ffffff ,
! 2659: which chooses the closest match from the default 256-colour set.
! 2660: .Pp
! 2661: The attributes is either
! 2662: .Ic none
! 2663: or a comma-delimited list of one or more of:
! 2664: .Ic bright
! 2665: (or
! 2666: .Ic bold ) ,
! 2667: .Ic dim ,
! 2668: .Ic underscore ,
! 2669: .Ic blink ,
! 2670: .Ic reverse ,
! 2671: .Ic hidden ,
! 2672: .Ic italics ,
! 2673: or
! 2674: .Ic strikethrough
! 2675: to turn an attribute on, or an attribute prefixed with
! 2676: .Ql no
! 2677: to turn one off.
! 2678: .Pp
! 2679: Examples are:
! 2680: .Bd -literal -offset indent
! 2681: fg=yellow,bold,underscore,blink
! 2682: bg=black,fg=default,noreverse
! 2683: .Ed
! 2684: .Pp
! 2685: With the
! 2686: .Fl a
! 2687: flag to the
! 2688: .Ic set-option
! 2689: command the new style is added otherwise the existing style is replaced.
! 2690: .It Ic message-style Ar style
! 2691: Set status line message style.
! 2692: For how to specify
! 2693: .Ar style ,
! 2694: see the
! 2695: .Ic message-command-style
! 2696: option.
! 2697: .It Xo Ic mouse
! 2698: .Op Ic on | off
! 2699: .Xc
! 2700: If on,
! 2701: .Nm
! 2702: captures the mouse and allows mouse events to be bound as key bindings.
! 2703: See the
! 2704: .Sx MOUSE SUPPORT
! 2705: section for details.
! 2706: .It Ic prefix Ar key
! 2707: Set the key accepted as a prefix key.
! 2708: In addition to the standard keys described under
! 2709: .Sx KEY BINDINGS ,
! 2710: .Ic prefix
! 2711: can be set to the special key
! 2712: .Ql None
! 2713: to set no prefix.
! 2714: .It Ic prefix2 Ar key
! 2715: Set a secondary key accepted as a prefix key.
! 2716: Like
! 2717: .Ic prefix ,
! 2718: .Ic prefix2
! 2719: can be set to
! 2720: .Ql None .
! 2721: .It Xo Ic renumber-windows
! 2722: .Op Ic on | off
! 2723: .Xc
! 2724: If on, when a window is closed in a session, automatically renumber the other
! 2725: windows in numerical order.
! 2726: This respects the
! 2727: .Ic base-index
! 2728: option if it has been set.
! 2729: If off, do not renumber the windows.
! 2730: .It Ic repeat-time Ar time
! 2731: Allow multiple commands to be entered without pressing the prefix-key again
! 2732: in the specified
! 2733: .Ar time
! 2734: milliseconds (the default is 500).
! 2735: Whether a key repeats may be set when it is bound using the
! 2736: .Fl r
! 2737: flag to
! 2738: .Ic bind-key .
! 2739: Repeat is enabled for the default keys bound to the
! 2740: .Ic resize-pane
! 2741: command.
! 2742: .It Xo Ic set-titles
! 2743: .Op Ic on | off
! 2744: .Xc
! 2745: Attempt to set the client terminal title using the
! 2746: .Em tsl
! 2747: and
! 2748: .Em fsl
! 2749: .Xr terminfo 5
! 2750: entries if they exist.
! 2751: .Nm
! 2752: automatically sets these to the \ee]0;...\e007 sequence if
! 2753: the terminal appears to be
! 2754: .Xr xterm 1 .
! 2755: This option is off by default.
! 2756: .It Ic set-titles-string Ar string
! 2757: String used to set the window title if
! 2758: .Ic set-titles
! 2759: is on.
! 2760: Formats are expanded, see the
! 2761: .Sx FORMATS
! 2762: section.
! 2763: .It Xo Ic status
! 2764: .Op Ic on | off
! 2765: .Xc
! 2766: Show or hide the status line.
! 2767: .It Ic status-interval Ar interval
! 2768: Update the status line every
! 2769: .Ar interval
! 2770: seconds.
! 2771: By default, updates will occur every 15 seconds.
! 2772: A setting of zero disables redrawing at interval.
! 2773: .It Xo Ic status-justify
! 2774: .Op Ic left | centre | right
! 2775: .Xc
! 2776: Set the position of the window list component of the status line: left, centre
! 2777: or right justified.
! 2778: .It Xo Ic status-keys
! 2779: .Op Ic vi | emacs
! 2780: .Xc
! 2781: Use vi or emacs-style
! 2782: key bindings in the status line, for example at the command prompt.
! 2783: The default is emacs, unless the
! 2784: .Ev VISUAL
! 2785: or
! 2786: .Ev EDITOR
! 2787: environment variables are set and contain the string
! 2788: .Ql vi .
! 2789: .It Ic status-left Ar string
! 2790: Display
! 2791: .Ar string
! 2792: (by default the session name) to the left of the status line.
! 2793: .Ar string
! 2794: will be passed through
! 2795: .Xr strftime 3
! 2796: and formats (see
! 2797: .Sx FORMATS )
! 2798: will be expanded.
! 2799: It may also contain the special character sequence #[] to change the colour
! 2800: or attributes, for example
! 2801: .Ql #[fg=red,bright]
! 2802: to set a bright red foreground.
! 2803: See the
! 2804: .Ic message-command-style
! 2805: option for a description of colours and attributes.
! 2806: .Pp
! 2807: For details on how the names and titles can be set see the
! 2808: .Sx "NAMES AND TITLES"
! 2809: section.
! 2810: .Pp
! 2811: Examples are:
! 2812: .Bd -literal -offset indent
! 2813: #(sysctl vm.loadavg)
! 2814: #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
! 2815: .Ed
! 2816: .Pp
! 2817: The default is
! 2818: .Ql "[#S] " .
! 2819: .It Ic status-left-length Ar length
! 2820: Set the maximum
! 2821: .Ar length
! 2822: of the left component of the status line.
! 2823: The default is 10.
! 2824: .It Ic status-left-style Ar style
! 2825: Set the style of the left part of the status line.
! 2826: For how to specify
! 2827: .Ar style ,
! 2828: see the
! 2829: .Ic message-command-style
! 2830: option.
! 2831: .It Xo Ic status-position
! 2832: .Op Ic top | bottom
! 2833: .Xc
! 2834: Set the position of the status line.
! 2835: .It Ic status-right Ar string
! 2836: Display
! 2837: .Ar string
! 2838: to the right of the status line.
! 2839: By default, the current window title in double quotes, the date and the time
! 2840: are shown.
! 2841: As with
! 2842: .Ic status-left ,
! 2843: .Ar string
! 2844: will be passed to
! 2845: .Xr strftime 3
! 2846: and character pairs are replaced.
! 2847: .It Ic status-right-length Ar length
! 2848: Set the maximum
! 2849: .Ar length
! 2850: of the right component of the status line.
! 2851: The default is 40.
! 2852: .It Ic status-right-style Ar style
! 2853: Set the style of the right part of the status line.
! 2854: For how to specify
! 2855: .Ar style ,
! 2856: see the
! 2857: .Ic message-command-style
! 2858: option.
! 2859: .It Ic status-style Ar style
! 2860: Set status line style.
! 2861: For how to specify
! 2862: .Ar style ,
! 2863: see the
! 2864: .Ic message-command-style
! 2865: option.
! 2866: .It Ic update-environment[] Ar variable
! 2867: Set list of environment variables to be copied into the session environment
! 2868: when a new session is created or an existing session is attached.
! 2869: Any variables that do not exist in the source environment are set to be
! 2870: removed from the session environment (as if
! 2871: .Fl r
! 2872: was given to the
! 2873: .Ic set-environment
! 2874: command).
! 2875: .It Xo Ic visual-activity
! 2876: .Op Ic on | off
! 2877: .Xc
! 2878: If on, display a status line message when activity occurs in a window
! 2879: for which the
! 2880: .Ic monitor-activity
! 2881: window option is enabled.
! 2882: .It Xo Ic visual-bell
! 2883: .Op Ic on | off
! 2884: .Xc
! 2885: If this option is on, a message is shown on a bell instead of it being passed
! 2886: through to the terminal (which normally makes a sound).
! 2887: Also see the
! 2888: .Ic bell-action
! 2889: option.
! 2890: .It Xo Ic visual-silence
! 2891: .Op Ic on | off
! 2892: .Xc
! 2893: If
! 2894: .Ic monitor-silence
! 2895: is enabled, prints a message after the interval has expired on a given window.
! 2896: .It Ic word-separators Ar string
! 2897: Sets the session's conception of what characters are considered word
! 2898: separators, for the purposes of the next and previous word commands in
! 2899: copy mode.
! 2900: The default is
! 2901: .Ql \ -_@ .
! 2902: .El
! 2903: .It Xo Ic set-window-option
! 2904: .Op Fl agoqu
! 2905: .Op Fl t Ar target-window
! 2906: .Ar option Ar value
! 2907: .Xc
! 2908: .D1 (alias: Ic setw )
! 2909: Set a window option.
! 2910: The
! 2911: .Fl a ,
! 2912: .Fl g ,
! 2913: .Fl o ,
! 2914: .Fl q
! 2915: and
! 2916: .Fl u
! 2917: flags work similarly to the
! 2918: .Ic set-option
! 2919: command.
! 2920: .Pp
! 2921: Supported window options are:
! 2922: .Pp
! 2923: .Bl -tag -width Ds -compact
! 2924: .It Xo Ic aggressive-resize
! 2925: .Op Ic on | off
! 2926: .Xc
! 2927: Aggressively resize the chosen window.
! 2928: This means that
! 2929: .Nm
! 2930: will resize the window to the size of the smallest session for which it is the
! 2931: current window, rather than the smallest session to which it is attached.
! 2932: The window may resize when the current window is changed on another sessions;
! 2933: this option is good for full-screen programs which support
! 2934: .Dv SIGWINCH
! 2935: and poor for interactive programs such as shells.
! 2936: .Pp
! 2937: .It Xo Ic allow-rename
! 2938: .Op Ic on | off
! 2939: .Xc
! 2940: Allow programs to change the window name using a terminal escape
! 2941: sequence (\eek...\ee\e\e).
! 2942: The default is on.
! 2943: .Pp
! 2944: .It Xo Ic alternate-screen
! 2945: .Op Ic on | off
! 2946: .Xc
! 2947: This option configures whether programs running inside
! 2948: .Nm
! 2949: may use the terminal alternate screen feature, which allows the
! 2950: .Em smcup
! 2951: and
! 2952: .Em rmcup
! 2953: .Xr terminfo 5
! 2954: capabilities.
! 2955: The alternate screen feature preserves the contents of the window when an
! 2956: interactive application starts and restores it on exit, so that any output
! 2957: visible before the application starts reappears unchanged after it exits.
! 2958: The default is on.
! 2959: .Pp
! 2960: .It Xo Ic automatic-rename
! 2961: .Op Ic on | off
! 2962: .Xc
! 2963: Control automatic window renaming.
! 2964: When this setting is enabled,
! 2965: .Nm
! 2966: will rename the window automatically using the format specified by
! 2967: .Ic automatic-rename-format .
! 2968: This flag is automatically disabled for an individual window when a name
! 2969: is specified at creation with
! 2970: .Ic new-window
! 2971: or
! 2972: .Ic new-session ,
! 2973: or later with
! 2974: .Ic rename-window ,
! 2975: or with a terminal escape sequence.
! 2976: It may be switched off globally with:
! 2977: .Bd -literal -offset indent
! 2978: set-window-option -g automatic-rename off
! 2979: .Ed
! 2980: .Pp
! 2981: .It Ic automatic-rename-format Ar format
! 2982: The format (see
! 2983: .Sx FORMATS )
! 2984: used when the
! 2985: .Ic automatic-rename
! 2986: option is enabled.
! 2987: .Pp
! 2988: .It Ic clock-mode-colour Ar colour
! 2989: Set clock colour.
! 2990: .Pp
! 2991: .It Xo Ic clock-mode-style
! 2992: .Op Ic 12 | 24
! 2993: .Xc
! 2994: Set clock hour format.
! 2995: .Pp
! 2996: .It Ic force-height Ar height
! 2997: .It Ic force-width Ar width
! 2998: Prevent
! 2999: .Nm
! 3000: from resizing a window to greater than
! 3001: .Ar width
! 3002: or
! 3003: .Ar height .
! 3004: A value of zero restores the default unlimited setting.
! 3005: .Pp
! 3006: .It Ic main-pane-height Ar height
! 3007: .It Ic main-pane-width Ar width
! 3008: Set the width or height of the main (left or top) pane in the
! 3009: .Ic main-horizontal
! 3010: or
! 3011: .Ic main-vertical
! 3012: layouts.
! 3013: .Pp
! 3014: .It Xo Ic mode-keys
! 3015: .Op Ic vi | emacs
! 3016: .Xc
! 3017: Use vi or emacs-style key bindings in copy mode.
! 3018: The default is emacs, unless
! 3019: .Ev VISUAL
! 3020: or
! 3021: .Ev EDITOR
! 3022: contains
! 3023: .Ql vi .
! 3024: .Pp
! 3025: .It Ic mode-style Ar style
! 3026: Set window modes style.
! 3027: For how to specify
! 3028: .Ar style ,
! 3029: see the
! 3030: .Ic message-command-style
! 3031: option.
! 3032: .Pp
! 3033: .It Xo Ic monitor-activity
! 3034: .Op Ic on | off
! 3035: .Xc
! 3036: Monitor for activity in the window.
! 3037: Windows with activity are highlighted in the status line.
! 3038: .Pp
! 3039: .It Xo Ic monitor-silence
! 3040: .Op Ic interval
! 3041: .Xc
! 3042: Monitor for silence (no activity) in the window within
! 3043: .Ic interval
! 3044: seconds.
! 3045: Windows that have been silent for the interval are highlighted in the
! 3046: status line.
! 3047: An interval of zero disables the monitoring.
! 3048: .Pp
! 3049: .It Ic other-pane-height Ar height
! 3050: Set the height of the other panes (not the main pane) in the
! 3051: .Ic main-horizontal
! 3052: layout.
! 3053: If this option is set to 0 (the default), it will have no effect.
! 3054: If both the
! 3055: .Ic main-pane-height
! 3056: and
! 3057: .Ic other-pane-height
! 3058: options are set, the main pane will grow taller to make the other panes the
! 3059: specified height, but will never shrink to do so.
! 3060: .Pp
! 3061: .It Ic other-pane-width Ar width
! 3062: Like
! 3063: .Ic other-pane-height ,
! 3064: but set the width of other panes in the
! 3065: .Ic main-vertical
! 3066: layout.
! 3067: .Pp
! 3068: .It Ic pane-active-border-style Ar style
! 3069: Set the pane border style for the currently active pane.
! 3070: For how to specify
! 3071: .Ar style ,
! 3072: see the
! 3073: .Ic message-command-style
! 3074: option.
! 3075: Attributes are ignored.
! 3076: .Pp
! 3077: .It Ic pane-base-index Ar index
! 3078: Like
! 3079: .Ic base-index ,
! 3080: but set the starting index for pane numbers.
! 3081: .Pp
! 3082: .It Ic pane-border-format Ar format
! 3083: Set the text shown in pane border status lines.
! 3084: .Pp
! 3085: .It Xo Ic pane-border-status
! 3086: .Op Ic off | top | bottom
! 3087: .Xc
! 3088: Turn pane border status lines off or set their position.
! 3089: .Pp
! 3090: .It Ic pane-border-style Ar style
! 3091: Set the pane border style for panes aside from the active pane.
! 3092: For how to specify
! 3093: .Ar style ,
! 3094: see the
! 3095: .Ic message-command-style
! 3096: option.
! 3097: Attributes are ignored.
! 3098: .Pp
! 3099: .It Xo Ic remain-on-exit
! 3100: .Op Ic on | off
! 3101: .Xc
! 3102: A window with this flag set is not destroyed when the program running in it
! 3103: exits.
! 3104: The window may be reactivated with the
! 3105: .Ic respawn-window
! 3106: command.
! 3107: .Pp
! 3108: .It Xo Ic synchronize-panes
! 3109: .Op Ic on | off
! 3110: .Xc
! 3111: Duplicate input to any pane to all other panes in the same window (only
! 3112: for panes that are not in any special mode).
! 3113: .Pp
! 3114: .It Ic window-active-style Ar style
! 3115: Set the style for the window's active pane.
! 3116: For how to specify
! 3117: .Ar style ,
! 3118: see the
! 3119: .Ic message-command-style
! 3120: option.
! 3121: .Pp
! 3122: .It Ic window-status-activity-style Ar style
! 3123: Set status line style for windows with an activity alert.
! 3124: For how to specify
! 3125: .Ar style ,
! 3126: see the
! 3127: .Ic message-command-style
! 3128: option.
! 3129: .Pp
! 3130: .It Ic window-status-bell-style Ar style
! 3131: Set status line style for windows with a bell alert.
! 3132: For how to specify
! 3133: .Ar style ,
! 3134: see the
! 3135: .Ic message-command-style
! 3136: option.
! 3137: .Pp
! 3138: .It Ic window-status-current-format Ar string
! 3139: Like
! 3140: .Ar window-status-format ,
! 3141: but is the format used when the window is the current window.
! 3142: .Pp
! 3143: .It Ic window-status-current-style Ar style
! 3144: Set status line style for the currently active window.
! 3145: For how to specify
! 3146: .Ar style ,
! 3147: see the
! 3148: .Ic message-command-style
! 3149: option.
! 3150: .Pp
! 3151: .It Ic window-status-format Ar string
! 3152: Set the format in which the window is displayed in the status line window list.
! 3153: See the
! 3154: .Ar status-left
! 3155: option for details of special character sequences available.
! 3156: The default is
! 3157: .Ql #I:#W#F .
! 3158: .Pp
! 3159: .It Ic window-status-last-style Ar style
! 3160: Set status line style for the last active window.
! 3161: For how to specify
! 3162: .Ar style ,
! 3163: see the
! 3164: .Ic message-command-style
! 3165: option.
! 3166: .Pp
! 3167: .It Ic window-status-separator Ar string
! 3168: Sets the separator drawn between windows in the status line.
! 3169: The default is a single space character.
! 3170: .Pp
! 3171: .It Ic window-status-style Ar style
! 3172: Set status line style for a single window.
! 3173: For how to specify
! 3174: .Ar style ,
! 3175: see the
! 3176: .Ic message-command-style
! 3177: option.
! 3178: .Pp
! 3179: .It Ic window-style Ar style
! 3180: Set the default window style.
! 3181: For how to specify
! 3182: .Ar style ,
! 3183: see the
! 3184: .Ic message-command-style
! 3185: option.
! 3186: .Pp
! 3187: .It Xo Ic wrap-search
! 3188: .Op Ic on | off
! 3189: .Xc
! 3190: If this option is set, searches will wrap around the end of the pane contents.
! 3191: The default is on.
! 3192: .Pp
! 3193: .It Xo Ic xterm-keys
! 3194: .Op Ic on | off
! 3195: .Xc
! 3196: If this option is set,
! 3197: .Nm
! 3198: will generate
! 3199: .Xr xterm 1 -style
! 3200: function key sequences; these have a number included to indicate modifiers such
! 3201: as Shift, Alt or Ctrl.
! 3202: The default is off.
! 3203: .El
! 3204: .It Xo Ic show-options
! 3205: .Op Fl gqsvw
! 3206: .Op Fl t Ar target-session | Ar target-window
! 3207: .Op Ar option
! 3208: .Xc
! 3209: .D1 (alias: Ic show )
! 3210: Show the window options (or a single window option if given) with
! 3211: .Fl w
! 3212: (equivalent to
! 3213: .Ic show-window-options ) ,
! 3214: the server options with
! 3215: .Fl s ,
! 3216: otherwise the session options for
! 3217: .Ar target session .
! 3218: Global session or window options are listed if
! 3219: .Fl g
! 3220: is used.
! 3221: .Fl v
! 3222: shows only the option value, not the name.
! 3223: If
! 3224: .Fl q
! 3225: is set, no error will be returned if
! 3226: .Ar option
! 3227: is unset.
! 3228: .It Xo Ic show-window-options
! 3229: .Op Fl gv
! 3230: .Op Fl t Ar target-window
! 3231: .Op Ar option
! 3232: .Xc
! 3233: .D1 (alias: Ic showw )
! 3234: List the window options or a single option for
! 3235: .Ar target-window ,
! 3236: or the global window options if
! 3237: .Fl g
! 3238: is used.
! 3239: .Fl v
! 3240: shows only the option value, not the name.
! 3241: .El
! 3242: .Sh HOOKS
! 3243: .Nm
! 3244: allows commands to run on various triggers, called
! 3245: .Em hooks .
! 3246: Most
! 3247: .Nm
! 3248: commands have an
! 3249: .Em after
! 3250: hook and there are a number of hooks not associated with commands.
! 3251: .Pp
! 3252: A command's after
! 3253: hook is run after it completes, except when the command is run as part of a hook
! 3254: itself.
! 3255: They are named with an
! 3256: .Ql after-
! 3257: prefix.
! 3258: For example, the following command adds a hook to select the even-vertical
! 3259: layout after every
! 3260: .Ic split-window :
! 3261: .Bd -literal -offset indent
! 3262: set-hook after-split-window "selectl even-vertical"
! 3263: .Ed
! 3264: .Pp
! 3265: In addition, the following hooks are available:
! 3266: .Bl -tag -width "XXXXXXXXXXXXXXXX"
! 3267: .It alert-activity
! 3268: Run when a window has activity.
! 3269: See
! 3270: .Ic monitor-activity .
! 3271: .It alert-bell
! 3272: Run when a window has received a bell.
! 3273: .It alert-silence
! 3274: Run when a window has been silent.
! 3275: See
! 3276: .Ic monitor-silence .
! 3277: .It client-attached
! 3278: Run when a client is attached.
! 3279: .It client-detached
! 3280: Run when a client is detached
! 3281: .It client-resized
! 3282: Run when a client is resized.
! 3283: .It client-session-changed
! 3284: Run when a client's attached session is changed.
! 3285: .It pane-died
! 3286: Run when the program running in a pane exits, but
! 3287: .Ic remain-on-exit
! 3288: is on so the pane has not closed.
! 3289: .It pane-exited
! 3290: Run when the program running in a pane exits.
! 3291: .It session-created
! 3292: Run when a new session created.
! 3293: .It session-closed
! 3294: Run when a session closed.
! 3295: .It session-renamed
! 3296: Run when a session is renamed.
! 3297: .It window-linked
! 3298: Run when a window is linked into a session.
! 3299: .It window-renamed
! 3300: Run when a window is renamed.
! 3301: .It window-unlinked
! 3302: Run when a window is unlinked from a session.
! 3303: .El
! 3304: .Pp
! 3305: Hooks are managed with these commands:
! 3306: .Bl -tag -width Ds
! 3307: .It Xo Ic set-hook
! 3308: .Op Fl gu
! 3309: .Op Fl t Ar target-session
! 3310: .Ar hook-name
! 3311: .Ar command
! 3312: .Xc
! 3313: Sets (or with
! 3314: .Fl u
! 3315: unsets) hook
! 3316: .Ar hook-name
! 3317: to
! 3318: .Ar command .
! 3319: If
! 3320: .Fl g
! 3321: is given,
! 3322: .Em hook-name
! 3323: is added to the global list of hooks, otherwise it is added to the session
! 3324: hooks (for
! 3325: .Ar target-session
! 3326: with
! 3327: .Fl t ) .
! 3328: Like options, session hooks inherit from the global ones.
! 3329: .It Xo Ic show-hooks
! 3330: .Op Fl g
! 3331: .Op Fl t Ar target-session
! 3332: .Xc
! 3333: Shows the global list of hooks with
! 3334: .Fl g ,
! 3335: otherwise the session hooks.
! 3336: .El
! 3337: .Sh MOUSE SUPPORT
! 3338: If the
! 3339: .Ic mouse
! 3340: option is on (the default is off),
! 3341: .Nm
! 3342: allows mouse events to be bound as keys.
! 3343: The name of each key is made up of a mouse event (such as
! 3344: .Ql MouseUp1 )
! 3345: and a location suffix (one of
! 3346: .Ql Pane
! 3347: for the contents of a pane,
! 3348: .Ql Border
! 3349: for a pane border or
! 3350: .Ql Status
! 3351: for the status line).
! 3352: The following mouse events are available:
! 3353: .Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
! 3354: .It Li "WheelUp" Ta "WheelDown" Ta ""
! 3355: .It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
! 3356: .It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
! 3357: .It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
! 3358: .It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3" Ta "WheelUp"
! 3359: .It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3" Ta "WheelDown"
! 3360: .El
! 3361: .Pp
! 3362: Each should be suffixed with a location, for example
! 3363: .Ql MouseDown1Status .
! 3364: .Pp
! 3365: The special token
! 3366: .Ql {mouse}
! 3367: or
! 3368: .Ql =
! 3369: may be used as
! 3370: .Ar target-window
! 3371: or
! 3372: .Ar target-pane
! 3373: in commands bound to mouse key bindings.
! 3374: It resolves to the window or pane over which the mouse event took place
! 3375: (for example, the window in the status line over which button 1 was released for a
! 3376: .Ql MouseUp1Status
! 3377: binding, or the pane over which the wheel was scrolled for a
! 3378: .Ql WheelDownPane
! 3379: binding).
! 3380: .Pp
! 3381: The
! 3382: .Ic send-keys
! 3383: .Fl M
! 3384: flag may be used to forward a mouse event to a pane.
! 3385: .Pp
! 3386: The default key bindings allow the mouse to be used to select and resize panes,
! 3387: to copy text and to change window using the status line.
! 3388: These take effect if the
! 3389: .Ic mouse
! 3390: option is turned on.
! 3391: .Sh FORMATS
! 3392: Certain commands accept the
! 3393: .Fl F
! 3394: flag with a
! 3395: .Ar format
! 3396: argument.
! 3397: This is a string which controls the output format of the command.
! 3398: Replacement variables are enclosed in
! 3399: .Ql #{
! 3400: and
! 3401: .Ql } ,
! 3402: for example
! 3403: .Ql #{session_name} .
! 3404: The possible variables are listed in the table below, or the name of a
! 3405: .Nm
! 3406: option may be used for an option's value.
! 3407: Some variables have a shorter alias such as
! 3408: .Ql #S ,
! 3409: and
! 3410: .Ql ##
! 3411: is replaced by a single
! 3412: .Ql # .
! 3413: .Pp
! 3414: Conditionals are available by prefixing with
! 3415: .Ql \&?
! 3416: and separating two alternatives with a comma;
! 3417: if the specified variable exists and is not zero, the first alternative
! 3418: is chosen, otherwise the second is used.
! 3419: For example
! 3420: .Ql #{?session_attached,attached,not attached}
! 3421: will include the string
! 3422: .Ql attached
! 3423: if the session is attached and the string
! 3424: .Ql not attached
! 3425: if it is unattached, or
! 3426: .Ql #{?automatic-rename,yes,no}
! 3427: will include
! 3428: .Ql yes
! 3429: if
! 3430: .Ic automatic-rename
! 3431: is enabled, or
! 3432: .Ql no
! 3433: if not.
! 3434: .Pp
! 3435: Simple comparisons may be expressed by prefixing two comma-separated
! 3436: alternatives by
! 3437: .Ql ==
! 3438: or
! 3439: .Ql !=
! 3440: and a colon.
! 3441: For example
! 3442: .Ql #{==,#{host},myhost}
! 3443: will be replaced by
! 3444: .Ql 1
! 3445: if running on
! 3446: .Ql myhost ,
! 3447: otherwise by
! 3448: .Ql 0.
! 3449: .Pp
! 3450: A limit may be placed on the length of the resultant string by prefixing it
! 3451: by an
! 3452: .Ql = ,
! 3453: a number and a colon.
! 3454: Positive numbers count from the start of the string and negative from the end,
! 3455: so
! 3456: .Ql #{=5:pane_title}
! 3457: will include at most the first 5 characters of the pane title, or
! 3458: .Ql #{=-5:pane_title}
! 3459: the last 5 characters.
! 3460: Prefixing a time variable with
! 3461: .Ql t:
! 3462: will convert it to a string, so if
! 3463: .Ql #{window_activity}
! 3464: gives
! 3465: .Ql 1445765102 ,
! 3466: .Ql #{t:window_activity}
! 3467: gives
! 3468: .Ql Sun Oct 25 09:25:02 2015 .
! 3469: The
! 3470: .Ql b:
! 3471: and
! 3472: .Ql d:
! 3473: prefixes are
! 3474: .Xr basename 3
! 3475: and
! 3476: .Xr dirname 3
! 3477: of the variable respectively.
! 3478: A prefix of the form
! 3479: .Ql s/foo/bar/:
! 3480: will substitute
! 3481: .Ql foo
! 3482: with
! 3483: .Ql bar
! 3484: throughout.
! 3485: .Pp
! 3486: In addition, the first line of a shell command's output may be inserted using
! 3487: .Ql #() .
! 3488: For example,
! 3489: .Ql #(uptime)
! 3490: will insert the system's uptime.
! 3491: When constructing formats,
! 3492: .Nm
! 3493: does not wait for
! 3494: .Ql #()
! 3495: commands to finish; instead, the previous result from running the same command is used,
! 3496: or a placeholder if the command has not been run before.
! 3497: Commands are executed with the
! 3498: .Nm
! 3499: global environment set (see the
! 3500: .Sx ENVIRONMENT
! 3501: section).
! 3502: .Pp
! 3503: The following variables are available, where appropriate:
! 3504: .Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
! 3505: .It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
! 3506: .It Li "alternate_on" Ta "" Ta "If pane is in alternate screen"
! 3507: .It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
! 3508: .It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
! 3509: .It Li "buffer_name" Ta "" Ta "Name of buffer"
! 3510: .It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
! 3511: .It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
! 3512: .It Li "client_activity" Ta "" Ta "Integer time client last had activity"
! 3513: .It Li "client_created" Ta "" Ta "Integer time client created"
! 3514: .It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
! 3515: .It Li "client_height" Ta "" Ta "Height of client"
! 3516: .It Li "client_key_table" Ta "" Ta "Current key table"
! 3517: .It Li "client_last_session" Ta "" Ta "Name of the client's last session"
! 3518: .It Li "client_name" Ta "" Ta "Name of client"
! 3519: .It Li "client_pid" Ta "" Ta "PID of client process"
! 3520: .It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
! 3521: .It Li "client_readonly" Ta "" Ta "1 if client is readonly"
! 3522: .It Li "client_session" Ta "" Ta "Name of the client's session"
! 3523: .It Li "client_termname" Ta "" Ta "Terminal name of client"
! 3524: .It Li "client_termtype" Ta "" Ta "Terminal type of client"
! 3525: .It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
! 3526: .It Li "client_utf8" Ta "" Ta "1 if client supports utf8"
! 3527: .It Li "client_width" Ta "" Ta "Width of client"
! 3528: .It Li "client_written" Ta "" Ta "Bytes written to client"
! 3529: .It Li "command" Ta "" Ta "Name of command in use, if any"
! 3530: .It Li "command_list_name" Ta "" Ta "Command name if listing commands"
! 3531: .It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
! 3532: .It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
! 3533: .It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
! 3534: .It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
! 3535: .It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
! 3536: .It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
! 3537: .It Li "history_limit" Ta "" Ta "Maximum window history lines"
! 3538: .It Li "history_size" Ta "" Ta "Size of history in bytes"
! 3539: .It Li "hook" Ta "" Ta "Name of running hook, if any"
! 3540: .It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
! 3541: .It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
! 3542: .It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
! 3543: .It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
! 3544: .It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
! 3545: .It Li "host" Ta "#H" Ta "Hostname of local host"
! 3546: .It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
! 3547: .It Li "insert_flag" Ta "" Ta "Pane insert flag"
! 3548: .It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
! 3549: .It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
! 3550: .It Li "line" Ta "" Ta "Line number in the list"
! 3551: .It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
! 3552: .It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
! 3553: .It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
! 3554: .It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
! 3555: .It Li "pane_active" Ta "" Ta "1 if active pane"
! 3556: .It Li "pane_bottom" Ta "" Ta "Bottom of pane"
! 3557: .It Li "pane_current_command" Ta "" Ta "Current command if available"
! 3558: .It Li "pane_current_path" Ta "" Ta "Current path if available"
! 3559: .It Li "pane_dead" Ta "" Ta "1 if pane is dead"
! 3560: .It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
! 3561: .It Li "pane_height" Ta "" Ta "Height of pane"
! 3562: .It Li "pane_id" Ta "#D" Ta "Unique pane ID"
! 3563: .It Li "pane_in_mode" Ta "" Ta "If pane is in a mode"
! 3564: .It Li "pane_input_off" Ta "" Ta "If input to pane is disabled"
! 3565: .It Li "pane_index" Ta "#P" Ta "Index of pane"
! 3566: .It Li "pane_left" Ta "" Ta "Left of pane"
! 3567: .It Li "pane_pid" Ta "" Ta "PID of first process in pane"
! 3568: .It Li "pane_right" Ta "" Ta "Right of pane"
! 3569: .It Li "pane_start_command" Ta "" Ta "Command pane started with"
! 3570: .It Li "pane_synchronized" Ta "" Ta "If pane is synchronized"
! 3571: .It Li "pane_tabs" Ta "" Ta "Pane tab positions"
! 3572: .It Li "pane_title" Ta "#T" Ta "Title of pane"
! 3573: .It Li "pane_top" Ta "" Ta "Top of pane"
! 3574: .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
! 3575: .It Li "pane_width" Ta "" Ta "Width of pane"
! 3576: .It Li "pid" Ta "" Ta "Server PID"
! 3577: .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
! 3578: .It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
! 3579: .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
! 3580: .It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
! 3581: .It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
! 3582: .It Li "session_activity" Ta "" Ta "Integer time of session last activity"
! 3583: .It Li "session_created" Ta "" Ta "Integer time session created"
! 3584: .It Li "session_last_attached" Ta "" Ta "Integer time session last attached"
! 3585: .It Li "session_group" Ta "" Ta "Name of session group"
! 3586: .It Li "session_grouped" Ta "" Ta "1 if session in a group"
! 3587: .It Li "session_height" Ta "" Ta "Height of session"
! 3588: .It Li "session_id" Ta "" Ta "Unique session ID"
! 3589: .It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
! 3590: .It Li "session_name" Ta "#S" Ta "Name of session"
! 3591: .It Li "session_width" Ta "" Ta "Width of session"
! 3592: .It Li "session_windows" Ta "" Ta "Number of windows in session"
! 3593: .It Li "socket_path" Ta "" Ta "Server socket path"
! 3594: .It Li "start_time" Ta "" Ta "Server start time"
! 3595: .It Li "version" Ta "" Ta "Server version"
! 3596: .It Li "window_activity" Ta "" Ta "Integer time of window last activity"
! 3597: .It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
! 3598: .It Li "window_active" Ta "" Ta "1 if window active"
! 3599: .It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
! 3600: .It Li "window_find_matches" Ta "" Ta "Matched data from the find-window"
! 3601: .It Li "window_flags" Ta "#F" Ta "Window flags"
! 3602: .It Li "window_height" Ta "" Ta "Height of window"
! 3603: .It Li "window_id" Ta "" Ta "Unique window ID"
! 3604: .It Li "window_index" Ta "#I" Ta "Index of window"
! 3605: .It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
! 3606: .It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
! 3607: .It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
! 3608: .It Li "window_name" Ta "#W" Ta "Name of window"
! 3609: .It Li "window_panes" Ta "" Ta "Number of panes in window"
! 3610: .It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
! 3611: .It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
! 3612: .It Li "window_width" Ta "" Ta "Width of window"
! 3613: .It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
! 3614: .It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
! 3615: .El
! 3616: .Sh NAMES AND TITLES
! 3617: .Nm
! 3618: distinguishes between names and titles.
! 3619: Windows and sessions have names, which may be used to specify them in targets
! 3620: and are displayed in the status line and various lists: the name is the
! 3621: .Nm
! 3622: identifier for a window or session.
! 3623: Only panes have titles.
! 3624: A pane's title is typically set by the program running inside the pane and
! 3625: is not modified by
! 3626: .Nm .
! 3627: It is the same mechanism used to set for example the
! 3628: .Xr xterm 1
! 3629: window title in an
! 3630: .Xr X 7
! 3631: window manager.
! 3632: Windows themselves do not have titles - a window's title is the title of its
! 3633: active pane.
! 3634: .Nm
! 3635: itself may set the title of the terminal in which the client is running, see
! 3636: the
! 3637: .Ic set-titles
! 3638: option.
! 3639: .Pp
! 3640: A session's name is set with the
! 3641: .Ic new-session
! 3642: and
! 3643: .Ic rename-session
! 3644: commands.
! 3645: A window's name is set with one of:
! 3646: .Bl -enum -width Ds
! 3647: .It
! 3648: A command argument (such as
! 3649: .Fl n
! 3650: for
! 3651: .Ic new-window
! 3652: or
! 3653: .Ic new-session ) .
! 3654: .It
! 3655: An escape sequence:
! 3656: .Bd -literal -offset indent
! 3657: $ printf '\e033kWINDOW_NAME\e033\e\e'
! 3658: .Ed
! 3659: .It
! 3660: Automatic renaming, which sets the name to the active command in the window's
! 3661: active pane.
! 3662: See the
! 3663: .Ic automatic-rename
! 3664: option.
! 3665: .El
! 3666: .Pp
! 3667: When a pane is first created, its title is the hostname.
! 3668: A pane's title can be set via the OSC title setting sequence, for example:
! 3669: .Bd -literal -offset indent
! 3670: $ printf '\e033]2;My Title\e033\e\e'
! 3671: .Ed
! 3672: .Sh ENVIRONMENT
! 3673: When the server is started,
! 3674: .Nm
! 3675: copies the environment into the
! 3676: .Em global environment ;
! 3677: in addition, each session has a
! 3678: .Em session environment .
! 3679: When a window is created, the session and global environments are merged.
! 3680: If a variable exists in both, the value from the session environment is used.
! 3681: The result is the initial environment passed to the new process.
! 3682: .Pp
! 3683: The
! 3684: .Ic update-environment
! 3685: session option may be used to update the session environment from the client
! 3686: when a new session is created or an old reattached.
! 3687: .Nm
! 3688: also initialises the
! 3689: .Ev TMUX
! 3690: variable with some internal information to allow commands to be executed
! 3691: from inside, and the
! 3692: .Ev TERM
! 3693: variable with the correct terminal setting of
! 3694: .Ql screen .
! 3695: .Pp
! 3696: Commands to alter and view the environment are:
! 3697: .Bl -tag -width Ds
! 3698: .It Xo Ic set-environment
! 3699: .Op Fl gru
! 3700: .Op Fl t Ar target-session
! 3701: .Ar name Op Ar value
! 3702: .Xc
! 3703: .D1 (alias: Ic setenv )
! 3704: Set or unset an environment variable.
! 3705: If
! 3706: .Fl g
! 3707: is used, the change is made in the global environment; otherwise, it is applied
! 3708: to the session environment for
! 3709: .Ar target-session .
! 3710: The
! 3711: .Fl u
! 3712: flag unsets a variable.
! 3713: .Fl r
! 3714: indicates the variable is to be removed from the environment before starting a
! 3715: new process.
! 3716: .It Xo Ic show-environment
! 3717: .Op Fl gs
! 3718: .Op Fl t Ar target-session
! 3719: .Op Ar variable
! 3720: .Xc
! 3721: .D1 (alias: Ic showenv )
! 3722: Display the environment for
! 3723: .Ar target-session
! 3724: or the global environment with
! 3725: .Fl g .
! 3726: If
! 3727: .Ar variable
! 3728: is omitted, all variables are shown.
! 3729: Variables removed from the environment are prefixed with
! 3730: .Ql - .
! 3731: If
! 3732: .Fl s
! 3733: is used, the output is formatted as a set of Bourne shell commands.
! 3734: .El
! 3735: .Sh STATUS LINE
! 3736: .Nm
! 3737: includes an optional status line which is displayed in the bottom line of each
! 3738: terminal.
! 3739: By default, the status line is enabled (it may be disabled with the
! 3740: .Ic status
! 3741: session option) and contains, from left-to-right: the name of the current
! 3742: session in square brackets; the window list; the title of the active pane
! 3743: in double quotes; and the time and date.
! 3744: .Pp
! 3745: The status line is made of three parts: configurable left and right sections
! 3746: (which may contain dynamic content such as the time or output from a shell
! 3747: command, see the
! 3748: .Ic status-left ,
! 3749: .Ic status-left-length ,
! 3750: .Ic status-right ,
! 3751: and
! 3752: .Ic status-right-length
! 3753: options below), and a central window list.
! 3754: By default, the window list shows the index, name and (if any) flag of the
! 3755: windows present in the current session in ascending numerical order.
! 3756: It may be customised with the
! 3757: .Ar window-status-format
! 3758: and
! 3759: .Ar window-status-current-format
! 3760: options.
! 3761: The flag is one of the following symbols appended to the window name:
! 3762: .Bl -column "Symbol" "Meaning" -offset indent
! 3763: .It Sy "Symbol" Ta Sy "Meaning"
! 3764: .It Li "*" Ta "Denotes the current window."
! 3765: .It Li "-" Ta "Marks the last window (previously selected)."
! 3766: .It Li "#" Ta "Window is monitored and activity has been detected."
! 3767: .It Li "!" Ta "A bell has occurred in the window."
! 3768: .It Li "~" Ta "The window has been silent for the monitor-silence interval."
! 3769: .It Li "M" Ta "The window contains the marked pane."
! 3770: .It Li "Z" Ta "The window's active pane is zoomed."
! 3771: .El
! 3772: .Pp
! 3773: The # symbol relates to the
! 3774: .Ic monitor-activity
! 3775: window option.
! 3776: The window name is printed in inverted colours if an alert (bell, activity or
! 3777: silence) is present.
! 3778: .Pp
! 3779: The colour and attributes of the status line may be configured, the entire
! 3780: status line using the
! 3781: .Ic status-style
! 3782: session option and individual windows using the
! 3783: .Ic window-status-style
! 3784: window option.
! 3785: .Pp
! 3786: The status line is automatically refreshed at interval if it has changed, the
! 3787: interval may be controlled with the
! 3788: .Ic status-interval
! 3789: session option.
! 3790: .Pp
! 3791: Commands related to the status line are as follows:
! 3792: .Bl -tag -width Ds
! 3793: .It Xo Ic command-prompt
! 3794: .Op Fl 1i
! 3795: .Op Fl I Ar inputs
! 3796: .Op Fl p Ar prompts
! 3797: .Op Fl t Ar target-client
! 3798: .Op Ar template
! 3799: .Xc
! 3800: Open the command prompt in a client.
! 3801: This may be used from inside
! 3802: .Nm
! 3803: to execute commands interactively.
! 3804: .Pp
! 3805: If
! 3806: .Ar template
! 3807: is specified, it is used as the command.
! 3808: If present,
! 3809: .Fl I
! 3810: is a comma-separated list of the initial text for each prompt.
! 3811: If
! 3812: .Fl p
! 3813: is given,
! 3814: .Ar prompts
! 3815: is a comma-separated list of prompts which are displayed in order; otherwise
! 3816: a single prompt is displayed, constructed from
! 3817: .Ar template
! 3818: if it is present, or
! 3819: .Ql \&:
! 3820: if not.
! 3821: .Pp
! 3822: Before the command is executed, the first occurrence of the string
! 3823: .Ql %%
! 3824: and all occurrences of
! 3825: .Ql %1
! 3826: are replaced by the response to the first prompt, all
! 3827: .Ql %2
! 3828: are replaced with the response to the second prompt, and so on for further
! 3829: prompts.
! 3830: Up to nine prompt responses may be replaced
! 3831: .Po
! 3832: .Ql %1
! 3833: to
! 3834: .Ql %9
! 3835: .Pc .
! 3836: .Ql %%%
! 3837: is like
! 3838: .Ql %%
! 3839: but any quotation marks are escaped.
! 3840: .Pp
! 3841: .Fl 1
! 3842: makes the prompt only accept one key press, in this case the resulting input
! 3843: is a single character.
! 3844: .Fl i
! 3845: executes the command every time the prompt input changes instead of when the
! 3846: user exits the command prompt.
! 3847: .Pp
! 3848: The following keys have a special meaning in the command prompt, depending
! 3849: on the value of the
! 3850: .Ic status-keys
! 3851: option:
! 3852: .Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
! 3853: .It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
! 3854: .It Li "Cancel command prompt" Ta "Escape" Ta "Escape"
! 3855: .It Li "Delete current word" Ta "" Ta "C-w"
! 3856: .It Li "Delete entire command" Ta "d" Ta "C-u"
! 3857: .It Li "Delete from cursor to end" Ta "D" Ta "C-k"
! 3858: .It Li "Execute command" Ta "Enter" Ta "Enter"
! 3859: .It Li "Get next command from history" Ta "" Ta "Down"
! 3860: .It Li "Get previous command from history" Ta "" Ta "Up"
! 3861: .It Li "Insert top paste buffer" Ta "p" Ta "C-y"
! 3862: .It Li "Look for completions" Ta "Tab" Ta "Tab"
! 3863: .It Li "Move cursor left" Ta "h" Ta "Left"
! 3864: .It Li "Move cursor right" Ta "l" Ta "Right"
! 3865: .It Li "Move cursor to end" Ta "$" Ta "C-e"
! 3866: .It Li "Move cursor to next word" Ta "w" Ta "M-f"
! 3867: .It Li "Move cursor to previous word" Ta "b" Ta "M-b"
! 3868: .It Li "Move cursor to start" Ta "0" Ta "C-a"
! 3869: .It Li "Transpose characters" Ta "" Ta "C-t"
! 3870: .El
! 3871: .It Xo Ic confirm-before
! 3872: .Op Fl p Ar prompt
! 3873: .Op Fl t Ar target-client
! 3874: .Ar command
! 3875: .Xc
! 3876: .D1 (alias: Ic confirm )
! 3877: Ask for confirmation before executing
! 3878: .Ar command .
! 3879: If
! 3880: .Fl p
! 3881: is given,
! 3882: .Ar prompt
! 3883: is the prompt to display; otherwise a prompt is constructed from
! 3884: .Ar command .
! 3885: It may contain the special character sequences supported by the
! 3886: .Ic status-left
! 3887: option.
! 3888: .Pp
! 3889: This command works only from inside
! 3890: .Nm .
! 3891: .It Xo Ic display-message
! 3892: .Op Fl p
! 3893: .Op Fl c Ar target-client
! 3894: .Op Fl t Ar target-pane
! 3895: .Op Ar message
! 3896: .Xc
! 3897: .D1 (alias: Ic display )
! 3898: Display a message.
! 3899: If
! 3900: .Fl p
! 3901: is given, the output is printed to stdout, otherwise it is displayed in the
! 3902: .Ar target-client
! 3903: status line.
! 3904: The format of
! 3905: .Ar message
! 3906: is described in the
! 3907: .Sx FORMATS
! 3908: section; information is taken from
! 3909: .Ar target-pane
! 3910: if
! 3911: .Fl t
! 3912: is given, otherwise the active pane for the session attached to
! 3913: .Ar target-client .
! 3914: .El
! 3915: .Sh BUFFERS
! 3916: .Nm
! 3917: maintains a set of named
! 3918: .Em paste buffers .
! 3919: Each buffer may be either explicitly or automatically named.
! 3920: Explicitly named buffers are named when created with the
! 3921: .Ic set-buffer
! 3922: or
! 3923: .Ic load-buffer
! 3924: commands, or by renaming an automatically named buffer with
! 3925: .Ic set-buffer
! 3926: .Fl n .
! 3927: Automatically named buffers are given a name such as
! 3928: .Ql buffer0001 ,
! 3929: .Ql buffer0002
! 3930: and so on.
! 3931: When the
! 3932: .Ic buffer-limit
! 3933: option is reached, the oldest automatically named buffer is deleted.
! 3934: Explicitly named buffers are not subject to
! 3935: .Ic buffer-limit
! 3936: and may be deleted with
! 3937: .Ic delete-buffer
! 3938: command.
! 3939: .Pp
! 3940: Buffers may be added using
! 3941: .Ic copy-mode
! 3942: or the
! 3943: .Ic set-buffer
! 3944: and
! 3945: .Ic load-buffer
! 3946: commands, and pasted into a window using the
! 3947: .Ic paste-buffer
! 3948: command.
! 3949: If a buffer command is used and no buffer is specified, the most
! 3950: recently added automatically named buffer is assumed.
! 3951: .Pp
! 3952: A configurable history buffer is also maintained for each window.
! 3953: By default, up to 2000 lines are kept; this can be altered with the
! 3954: .Ic history-limit
! 3955: option (see the
! 3956: .Ic set-option
! 3957: command above).
! 3958: .Pp
! 3959: The buffer commands are as follows:
! 3960: .Bl -tag -width Ds
! 3961: .It Xo
! 3962: .Ic choose-buffer
! 3963: .Op Fl F Ar format
! 3964: .Op Fl t Ar target-window
! 3965: .Op Ar template
! 3966: .Xc
! 3967: Put a window into buffer choice mode, where a buffer may be chosen
! 3968: interactively from a list.
! 3969: After a buffer is selected,
! 3970: .Ql %%
! 3971: is replaced by the buffer name in
! 3972: .Ar template
! 3973: and the result executed as a command.
! 3974: If
! 3975: .Ar template
! 3976: is not given, "paste-buffer -b '%%'" is used.
! 3977: For the meaning of the
! 3978: .Fl F
! 3979: flag, see the
! 3980: .Sx FORMATS
! 3981: section.
! 3982: This command works only if at least one client is attached.
! 3983: .It Ic clear-history Op Fl t Ar target-pane
! 3984: .D1 (alias: Ic clearhist )
! 3985: Remove and free the history for the specified pane.
! 3986: .It Ic delete-buffer Op Fl b Ar buffer-name
! 3987: .D1 (alias: Ic deleteb )
! 3988: Delete the buffer named
! 3989: .Ar buffer-name ,
! 3990: or the most recently added automatically named buffer if not specified.
! 3991: .It Xo Ic list-buffers
! 3992: .Op Fl F Ar format
! 3993: .Xc
! 3994: .D1 (alias: Ic lsb )
! 3995: List the global buffers.
! 3996: For the meaning of the
! 3997: .Fl F
! 3998: flag, see the
! 3999: .Sx FORMATS
! 4000: section.
! 4001: .It Xo Ic load-buffer
! 4002: .Op Fl b Ar buffer-name
! 4003: .Ar path
! 4004: .Xc
! 4005: .D1 (alias: Ic loadb )
! 4006: Load the contents of the specified paste buffer from
! 4007: .Ar path .
! 4008: .It Xo Ic paste-buffer
! 4009: .Op Fl dpr
! 4010: .Op Fl b Ar buffer-name
! 4011: .Op Fl s Ar separator
! 4012: .Op Fl t Ar target-pane
! 4013: .Xc
! 4014: .D1 (alias: Ic pasteb )
! 4015: Insert the contents of a paste buffer into the specified pane.
! 4016: If not specified, paste into the current one.
! 4017: With
! 4018: .Fl d ,
! 4019: also delete the paste buffer.
! 4020: When output, any linefeed (LF) characters in the paste buffer are replaced with
! 4021: a separator, by default carriage return (CR).
! 4022: A custom separator may be specified using the
! 4023: .Fl s
! 4024: flag.
! 4025: The
! 4026: .Fl r
! 4027: flag means to do no replacement (equivalent to a separator of LF).
! 4028: If
! 4029: .Fl p
! 4030: is specified, paste bracket control codes are inserted around the
! 4031: buffer if the application has requested bracketed paste mode.
! 4032: .It Xo Ic save-buffer
! 4033: .Op Fl a
! 4034: .Op Fl b Ar buffer-name
! 4035: .Ar path
! 4036: .Xc
! 4037: .D1 (alias: Ic saveb )
! 4038: Save the contents of the specified paste buffer to
! 4039: .Ar path .
! 4040: The
! 4041: .Fl a
! 4042: option appends to rather than overwriting the file.
! 4043: .It Xo Ic set-buffer
! 4044: .Op Fl a
! 4045: .Op Fl b Ar buffer-name
! 4046: .Op Fl n Ar new-buffer-name
! 4047: .Ar data
! 4048: .Xc
! 4049: .D1 (alias: Ic setb )
! 4050: Set the contents of the specified buffer to
! 4051: .Ar data .
! 4052: The
! 4053: .Fl a
! 4054: option appends to rather than overwriting the buffer.
! 4055: The
! 4056: .Fl n
! 4057: option renames the buffer to
! 4058: .Ar new-buffer-name .
! 4059: .It Xo Ic show-buffer
! 4060: .Op Fl b Ar buffer-name
! 4061: .Xc
! 4062: .D1 (alias: Ic showb )
! 4063: Display the contents of the specified buffer.
! 4064: .El
! 4065: .Sh MISCELLANEOUS
! 4066: Miscellaneous commands are as follows:
! 4067: .Bl -tag -width Ds
! 4068: .It Ic clock-mode Op Fl t Ar target-pane
! 4069: Display a large clock.
! 4070: .It Xo Ic if-shell
! 4071: .Op Fl bF
! 4072: .Op Fl t Ar target-pane
! 4073: .Ar shell-command command
! 4074: .Op Ar command
! 4075: .Xc
! 4076: .D1 (alias: Ic if )
! 4077: Execute the first
! 4078: .Ar command
! 4079: if
! 4080: .Ar shell-command
! 4081: returns success or the second
! 4082: .Ar command
! 4083: otherwise.
! 4084: Before being executed,
! 4085: .Ar shell-command
! 4086: is expanded using the rules specified in the
! 4087: .Sx FORMATS
! 4088: section, including those relevant to
! 4089: .Ar target-pane .
! 4090: With
! 4091: .Fl b ,
! 4092: .Ar shell-command
! 4093: is run in the background.
! 4094: .Pp
! 4095: If
! 4096: .Fl F
! 4097: is given,
! 4098: .Ar shell-command
! 4099: is not executed but considered success if neither empty nor zero (after formats
! 4100: are expanded).
! 4101: .It Ic lock-server
! 4102: .D1 (alias: Ic lock )
! 4103: Lock each client individually by running the command specified by the
! 4104: .Ic lock-command
! 4105: option.
! 4106: .It Xo Ic run-shell
! 4107: .Op Fl b
! 4108: .Op Fl t Ar target-pane
! 4109: .Ar shell-command
! 4110: .Xc
! 4111: .D1 (alias: Ic run )
! 4112: Execute
! 4113: .Ar shell-command
! 4114: in the background without creating a window.
! 4115: Before being executed, shell-command is expanded using the rules specified in
! 4116: the
! 4117: .Sx FORMATS
! 4118: section.
! 4119: With
! 4120: .Fl b ,
! 4121: the command is run in the background.
! 4122: After it finishes, any output to stdout is displayed in copy mode (in the pane
! 4123: specified by
! 4124: .Fl t
! 4125: or the current pane if omitted).
! 4126: If the command doesn't return success, the exit status is also displayed.
! 4127: .It Xo Ic wait-for
! 4128: .Op Fl L | S | U
! 4129: .Ar channel
! 4130: .Xc
! 4131: .D1 (alias: Ic wait )
! 4132: When used without options, prevents the client from exiting until woken using
! 4133: .Ic wait-for
! 4134: .Fl S
! 4135: with the same channel.
! 4136: When
! 4137: .Fl L
! 4138: is used, the channel is locked and any clients that try to lock the same
! 4139: channel are made to wait until the channel is unlocked with
! 4140: .Ic wait-for
! 4141: .Fl U .
! 4142: This command only works from outside
! 4143: .Nm .
! 4144: .El
! 4145: .Sh TERMINFO EXTENSIONS
! 4146: .Nm
! 4147: understands some unofficial extensions to
! 4148: .Xr terminfo 5 :
! 4149: .Bl -tag -width Ds
! 4150: .It Em Cs , Cr
! 4151: Set the cursor colour.
! 4152: The first takes a single string argument and is used to set the colour;
! 4153: the second takes no arguments and restores the default cursor colour.
! 4154: If set, a sequence such as this may be used
! 4155: to change the cursor colour from inside
! 4156: .Nm :
! 4157: .Bd -literal -offset indent
! 4158: $ printf '\e033]12;red\e033\e\e'
! 4159: .Ed
! 4160: .It Em \&Ss , Se
! 4161: Set or reset the cursor style.
! 4162: If set, a sequence such as this may be used
! 4163: to change the cursor to an underline:
! 4164: .Bd -literal -offset indent
! 4165: $ printf '\e033[4 q'
! 4166: .Ed
! 4167: .Pp
! 4168: If
! 4169: .Em Se
! 4170: is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
! 4171: .It Em \&Tc
! 4172: Indicate that the terminal supports the
! 4173: .Ql direct colour
! 4174: RGB escape sequence (for example, \ee[38;2;255;255;255m).
! 4175: .Pp
! 4176: If supported, this is used for the OSC initialize colour escape sequence (which
! 4177: may be enabled by adding the
! 4178: .Ql initc
! 4179: and
! 4180: .Ql ccc
! 4181: capabilities to the
! 4182: .Nm
! 4183: .Xr terminfo 5
! 4184: entry).
! 4185: .It Em \&Ms
! 4186: Store the current buffer in the host terminal's selection (clipboard).
! 4187: See the
! 4188: .Em set-clipboard
! 4189: option above and the
! 4190: .Xr xterm 1
! 4191: man page.
! 4192: .El
! 4193: .Sh CONTROL MODE
! 4194: .Nm
! 4195: offers a textual interface called
! 4196: .Em control mode .
! 4197: This allows applications to communicate with
! 4198: .Nm
! 4199: using a simple text-only protocol.
! 4200: .Pp
! 4201: In control mode, a client sends
! 4202: .Nm
! 4203: commands or command sequences terminated by newlines on standard input.
! 4204: Each command will produce one block of output on standard output.
! 4205: An output block consists of a
! 4206: .Em %begin
! 4207: line followed by the output (which may be empty).
! 4208: The output block ends with a
! 4209: .Em %end
! 4210: or
! 4211: .Em %error .
! 4212: .Em %begin
! 4213: and matching
! 4214: .Em %end
! 4215: or
! 4216: .Em %error
! 4217: have two arguments: an integer time (as seconds from epoch) and command number.
! 4218: For example:
! 4219: .Bd -literal -offset indent
! 4220: %begin 1363006971 2
! 4221: 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
! 4222: %end 1363006971 2
! 4223: .Ed
! 4224: .Pp
! 4225: The
! 4226: .Ic refresh-client
! 4227: .Fl C
! 4228: command may be used to set the size of a client in control mode.
! 4229: .Pp
! 4230: In control mode,
! 4231: .Nm
! 4232: outputs notifications.
! 4233: A notification will never occur inside an output block.
! 4234: .Pp
! 4235: The following notifications are defined:
! 4236: .Bl -tag -width Ds
! 4237: .It Ic %exit Op Ar reason
! 4238: The
! 4239: .Nm
! 4240: client is exiting immediately, either because it is not attached to any session
! 4241: or an error occurred.
! 4242: If present,
! 4243: .Ar reason
! 4244: describes why the client exited.
! 4245: .It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags
! 4246: The layout of a window with ID
! 4247: .Ar window-id
! 4248: changed.
! 4249: The new layout is
! 4250: .Ar window-layout .
! 4251: The window's visible layout is
! 4252: .Ar window-visible-layout
! 4253: and the window flags are
! 4254: .Ar window-flags .
! 4255: .It Ic %output Ar pane-id Ar value
! 4256: A window pane produced output.
! 4257: .Ar value
! 4258: escapes non-printable characters and backslash as octal \\xxx.
! 4259: .It Ic %session-changed Ar session-id Ar name
! 4260: The client is now attached to the session with ID
! 4261: .Ar session-id ,
! 4262: which is named
! 4263: .Ar name .
! 4264: .It Ic %session-renamed Ar name
! 4265: The current session was renamed to
! 4266: .Ar name .
! 4267: .It Ic %sessions-changed
! 4268: A session was created or destroyed.
! 4269: .It Ic %unlinked-window-add Ar window-id
! 4270: The window with ID
! 4271: .Ar window-id
! 4272: was created but is not linked to the current session.
! 4273: .It Ic %window-add Ar window-id
! 4274: The window with ID
! 4275: .Ar window-id
! 4276: was linked to the current session.
! 4277: .It Ic %window-close Ar window-id
! 4278: The window with ID
! 4279: .Ar window-id
! 4280: closed.
! 4281: .It Ic %window-renamed Ar window-id Ar name
! 4282: The window with ID
! 4283: .Ar window-id
! 4284: was renamed to
! 4285: .Ar name .
! 4286: .El
! 4287: .Sh FILES
! 4288: .Bl -tag -width "@SYSCONFDIR@/tmux.confXXX" -compact
! 4289: .It Pa ~/.tmux.conf
! 4290: Default
! 4291: .Nm
! 4292: configuration file.
! 4293: .It Pa @SYSCONFDIR@/tmux.conf
! 4294: System-wide configuration file.
! 4295: .El
! 4296: .Sh EXAMPLES
! 4297: To create a new
! 4298: .Nm
! 4299: session running
! 4300: .Xr vi 1 :
! 4301: .Pp
! 4302: .Dl $ tmux new-session vi
! 4303: .Pp
! 4304: Most commands have a shorter form, known as an alias.
! 4305: For new-session, this is
! 4306: .Ic new :
! 4307: .Pp
! 4308: .Dl $ tmux new vi
! 4309: .Pp
! 4310: Alternatively, the shortest unambiguous form of a command is accepted.
! 4311: If there are several options, they are listed:
! 4312: .Bd -literal -offset indent
! 4313: $ tmux n
! 4314: ambiguous command: n, could be: new-session, new-window, next-window
! 4315: .Ed
! 4316: .Pp
! 4317: Within an active session, a new window may be created by typing
! 4318: .Ql C-b c
! 4319: (Ctrl
! 4320: followed by the
! 4321: .Ql b
! 4322: key
! 4323: followed by the
! 4324: .Ql c
! 4325: key).
! 4326: .Pp
! 4327: Windows may be navigated with:
! 4328: .Ql C-b 0
! 4329: (to select window 0),
! 4330: .Ql C-b 1
! 4331: (to select window 1), and so on;
! 4332: .Ql C-b n
! 4333: to select the next window; and
! 4334: .Ql C-b p
! 4335: to select the previous window.
! 4336: .Pp
! 4337: A session may be detached using
! 4338: .Ql C-b d
! 4339: (or by an external event such as
! 4340: .Xr ssh 1
! 4341: disconnection) and reattached with:
! 4342: .Pp
! 4343: .Dl $ tmux attach-session
! 4344: .Pp
! 4345: Typing
! 4346: .Ql C-b \&?
! 4347: lists the current key bindings in the current window; up and down may be used
! 4348: to navigate the list or
! 4349: .Ql q
! 4350: to exit from it.
! 4351: .Pp
! 4352: Commands to be run when the
! 4353: .Nm
! 4354: server is started may be placed in the
! 4355: .Pa ~/.tmux.conf
! 4356: configuration file.
! 4357: Common examples include:
! 4358: .Pp
! 4359: Changing the default prefix key:
! 4360: .Bd -literal -offset indent
! 4361: set-option -g prefix C-a
! 4362: unbind-key C-b
! 4363: bind-key C-a send-prefix
! 4364: .Ed
! 4365: .Pp
! 4366: Turning the status line off, or changing its colour:
! 4367: .Bd -literal -offset indent
! 4368: set-option -g status off
! 4369: set-option -g status-style bg=blue
! 4370: .Ed
! 4371: .Pp
! 4372: Setting other options, such as the default command,
! 4373: or locking after 30 minutes of inactivity:
! 4374: .Bd -literal -offset indent
! 4375: set-option -g default-command "exec /bin/ksh"
! 4376: set-option -g lock-after-time 1800
! 4377: .Ed
! 4378: .Pp
! 4379: Creating new key bindings:
! 4380: .Bd -literal -offset indent
! 4381: bind-key b set-option status
! 4382: bind-key / command-prompt "split-window 'exec man %%'"
! 4383: bind-key S command-prompt "new-window -n %1 'ssh %1'"
! 4384: .Ed
! 4385: .Sh SEE ALSO
! 4386: .Xr pty 4
! 4387: .Sh AUTHORS
! 4388: .An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to tmux.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / tmux