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