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