1.\" $OpenBSD: tmux.1,v 1.110 2009/10/13 13:45:56 nicm 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: October 13 2009 $ 18.Dt TMUX 1 19.Os 20.Sh NAME 21.Nm tmux 22.Nd terminal multiplexer 23.Sh SYNOPSIS 24.Nm tmux 25.Bk -words 26.Op Fl 28dlquv 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. 114.It Fl d 115Force 116.Nm 117to assume the terminal supports default colours. 118.It Fl f Ar file 119Specify an alternative configuration file. 120By default, 121.Nm 122loads the system configuration file from 123.Pa /etc/tmux.conf , 124if present, then looks for a user configuration file at 125.Pa ~/.tmux.conf . 126The configuration file is a set of 127.Nm 128commands which are executed in sequence when the server is first started. 129.Pp 130If a command in the configuration file fails, 131.Nm 132will report an error and exit without executing further commands. 133.It Fl l 134Behave as a login shell. 135This flag currently has no effect and is for compatibility with other shells 136when using tmux as a login shell. 137.It Fl L Ar socket-name 138.Nm 139stores the server socket in a directory under 140.Pa /tmp ; 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 q 158Prevent the server sending various informational messages, for example when 159window flags are altered. 160.It Fl S Ar socket-path 161Specify a full alternative path to the server socket. 162If 163.Fl S 164is specified, the default socket directory is not used and any 165.Fl L 166flag is ignored. 167.It Fl u 168.Nm 169attempts to guess if the terminal is likely to support UTF-8 by checking the 170first of the 171.Ev LC_ALL , 172.Ev LC_CTYPE 173and 174.Ev LANG 175environment variables to be set for the string "UTF-8". 176This is not always correct: the 177.Fl u 178flag explicitly informs 179.Nm 180that UTF-8 is supported. 181.Pp 182If the server is started from a client passed 183.Fl u 184or where UTF-8 is detected, the 185.Ic utf8 186and 187.Ic status-utf8 188options are enabled in the global window and session options respectively. 189.It Fl v 190Request verbose logging. 191This option may be specified multiple times for increasing verbosity. 192Log messages will be saved into 193.Pa tmux-client-PID.log 194and 195.Pa tmux-server-PID.log 196files in the current directory, where 197.Em PID 198is the PID of the server or client process. 199.It Ar command Op Ar flags 200This specifies one of a set of commands used to control 201.Nm , 202as described in the following sections. 203If no commands are specified, the 204.Ic new-session 205command is assumed. 206.El 207.Sh KEY BINDINGS 208.Nm 209may be controlled from an attached client by using a key combination of a 210prefix key, 211.Ql C-b 212(Ctrl-b) by default, followed by a command key. 213.Pp 214Some of the default key bindings are: 215.Pp 216.Bl -tag -width Ds -offset indent -compact 217.It c 218Create a new window. 219.It d 220Detach the current client. 221.It l 222Move to the previously selected window. 223.It n 224Change to the next window. 225.It p 226Change to the previous window. 227.It & 228Kill the current window. 229.It , 230Rename the current window. 231.It \&? 232List all key bindings. 233.El 234.Pp 235A complete list may be obtained with the 236.Ic list-keys 237command (bound to 238.Ql \&? 239by default). 240Key bindings may be changed with the 241.Ic bind-key 242and 243.Ic unbind-key 244commands. 245.Sh COMMANDS 246This section contains a list of the commands supported by 247.Nm . 248Most commands accept the optional 249.Fl t 250argument with one of 251.Ar target-client , 252.Ar target-session 253.Ar target-window , 254or 255.Ar target-pane . 256These specify the client, session, window or pane which a command should affect. 257.Ar target-client 258is the name of the 259.Xr pty 4 260file to which the client is connected, for example either of 261.Pa /dev/ttyp1 262or 263.Pa ttyp1 264for the client attached to 265.Pa /dev/ttyp1 . 266If no client is specified, the current client is chosen, if possible, or an 267error is reported. 268Clients may be listed with the 269.Ic list-clients 270command. 271.Pp 272.Ar target-session 273is either the name of a session (as listed by the 274.Ic list-sessions 275command) or the name of a client with the same syntax as 276.Ar target-client , 277in which case the session attached to the client is used. 278When looking for the session name, 279.Nm 280initially searches for an exact match; if none is found, the session names 281are checked for any for which 282.Ar target-session 283is a prefix or for which it matches as an 284.Xr fnmatch 3 285pattern. 286If a single match is found, it is used as the target session; multiple matches 287produce an error. 288If a session is omitted, the current session is used if available; if no 289current session is available, the most recently created is chosen. 290.Pp 291.Ar target-window 292specifies a window in the form 293.Em session Ns \&: Ns Em window . 294.Em session 295follows the same rules as for 296.Ar target-session , 297and 298.Em window 299is looked for in order: as a window index, for example mysession:1; as an exact 300window name, such as mysession:mywindow; then as an 301.Xr fnmatch 3 302pattern or the start of a window name, such as mysession:mywin* or 303mysession:mywin. 304An empty window name specifies the next unused index if appropriate (for 305example the 306.Ic new-window 307and 308.Ic link-window 309commands) 310otherwise the current window in 311.Em session 312is chosen. 313When the argument does not contain a colon, 314.Nm 315first attempts to parse it as window; if that fails, an attempt is made to 316match a session. 317.Pp 318.Ar target-pane 319takes a similar form to 320.Ar target-window 321but with the optional addition of a period followed by a pane index, for 322example: mysession:mywindow.1. 323If the pane index is omitted, the currently active pane in the specified 324window is used. 325If neither a colon nor period appears, 326.Nm 327first attempts to use the argument as a pane index; if that fails, it is looked 328up as for 329.Ar target-window . 330.Pp 331Multiple commands may be specified together as part of a 332.Em command sequence . 333Each command should be separated by spaces and a semicolon; 334commands are executed sequentially from left to right. 335A literal semicolon may be included by escaping it with a backslash (for 336example, when specifying a command sequence to 337.Ic bind-key ) . 338.Pp 339Examples include: 340.Bd -literal -offset indent 341refresh-client -t/dev/ttyp2 342 343rename-session -tfirst newname 344 345set-window-option -t:0 monitor-activity on 346 347new-window ; split-window -d 348.Ed 349.Sh CLIENTS AND SESSIONS 350The following commands are available: 351.Bl -tag -width Ds 352.It Xo Ic attach-session 353.Op Fl d 354.Op Fl t Ar target-session 355.Xc 356.D1 (alias: Ic attach ) 357If run from outside 358.Nm , 359create a new client in the current terminal and attach it to 360.Ar target-session . 361If used from inside, switch the current client. 362If 363.Fl d 364is specified, any other clients attached to the session are detached. 365.Pp 366If no server is started, 367.Ic attach-session 368will attempt to start it; this will fail unless sessions are created in the 369configuration file. 370.It Ic detach-client Op Fl t Ar target-client 371.D1 (alias: Ic detach ) 372Detach the current client if bound to a key, or the specified client with 373.Fl t . 374.It Ic has-session Op Fl t Ar target-session 375.D1 (alias: Ic has ) 376Report an error and exit with 1 if the specified session does not exist. 377If it does exist, exit with 0. 378.It Ic kill-server 379Kill the 380.Nm 381server and clients and destroy all sessions. 382.It Ic kill-session Op Fl t Ar target-session 383Destroy the given session, closing any windows linked to it and no other 384sessions, and detaching all clients attached to it. 385.It Ic list-clients 386.D1 (alias: Ic lsc ) 387List all clients attached to the server. 388.It Ic list-commands 389.D1 (alias: Ic lscm ) 390List the syntax of all commands supported by 391.Nm . 392.It Ic list-sessions 393.D1 (alias: Ic ls ) 394List all sessions managed by the server. 395.It Xo Ic lock-client 396.Op Fl t Ar target-client 397.Xc 398Lock 399.Ar target-client , 400see the 401.Ic lock-server 402command. 403.It Xo Ic lock-session 404.Op Fl t Ar target-session 405.Xc 406Lock all clients attached to 407.Ar target-session . 408.It Xo Ic new-session 409.Op Fl d 410.Op Fl n Ar window-name 411.Op Fl s Ar session-name 412.Op Fl t Ar target-session 413.Op Ar command 414.Xc 415.D1 (alias: Ic new ) 416Create a new session with name 417.Ar session-name . 418The new session is attached to the current terminal unless 419.Fl d 420is given. 421.Ar window-name 422and 423.Ar command 424are the name of and command to execute in the initial window. 425.Pp 426If run from a terminal, any 427.Xr termios 4 428special characters are saved and used for new windows in the new session. 429.Pp 430If 431.Fl t 432is given, the new session is 433.Em grouped 434with 435.Ar target-session . 436This means they share the same set of windows - all windows from 437.Ar target-session 438are linked to the new session and any subsequent new windows or windows being 439closed are applied to both sessions. 440The current and previous window and any session options remain independent and 441either session may be killed without affecting the other. 442Giving 443.Fl n 444or 445.Ar command 446are invalid if 447.Fl t 448is used. 449.It Ic refresh-client Op Fl t Ar target-client 450.D1 (alias: Ic refresh ) 451Refresh the current client if bound to a key, or a single client if one is given 452with 453.Fl t . 454.It Xo Ic rename-session 455.Op Fl t Ar target-session 456.Ar new-name 457.Xc 458.D1 (alias: Ic rename ) 459Rename the session to 460.Ar new-name . 461.It Ic source-file Ar path 462.D1 (alias: Ic source ) 463Execute commands from 464.Ar path . 465.It Ic start-server 466.D1 (alias: Ic start ) 467Start the 468.Nm 469server, if not already running, without creating any sessions. 470.It Xo Ic suspend-client 471.Op Fl c Ar target-client 472.Xc 473.D1 (alias: Ic suspendc ) 474Suspend a client by sending 475.Dv SIGTSTP 476(tty stop). 477.It Xo Ic switch-client 478.Op Fl c Ar target-client 479.Op Fl t Ar target-session 480.Xc 481.D1 (alias: Ic switchc ) 482Switch the current session for client 483.Ar target-client 484to 485.Ar target-session . 486.El 487.Sh WINDOWS AND PANES 488A 489.Nm 490window may be in one of several modes. 491The default permits direct access to the terminal attached to the window. 492The others are: 493.Bl -tag -width Ds 494.It Em output mode 495This is entered when a command which produces output, such as 496.Ic list-keys , 497is executed from a key binding. 498.It Em copy mode 499This permits a section of a window or its history to be copied to a 500.Em paste buffer 501for later insertion into another window. 502This mode is entered with the 503.Ic copy-mode 504command, bound to 505.Ql [ 506by default. 507.El 508.Pp 509The keys available depend on whether emacs or vi mode is selected 510(see the 511.Ic mode-keys 512option). 513The following keys are supported as appropriate for the mode: 514.Bl -column "FunctionXXXXXXXXXXXX" "viXXXXXXXXX" "emacs" -offset indent 515.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" 516.It Li "Back to indentation" Ta "^" Ta "M-m" 517.It Li "Clear selection" Ta "Escape" Ta "C-g" 518.It Li "Copy selection" Ta "Enter" Ta "M-w" 519.It Li "Cursor down" Ta "j" Ta "Down" 520.It Li "Cursor left" Ta "h" Ta "Left" 521.It Li "Cursor right" Ta "l" Ta "Right" 522.It Li "Cursor up" Ta "k" Ta "Up" 523.It Li "Delete entire line" Ta "d" Ta "C-u" 524.It Li "Delete to end of line" Ta "D" Ta "C-k" 525.It Li "End of line" Ta "$" Ta "C-e" 526.It Li "Goto line" Ta ":" Ta "g" 527.It Li "Next page" Ta "C-f" Ta "Page down" 528.It Li "Next word" Ta "w" Ta "M-f" 529.It Li "Paste buffer" Ta "p" Ta "C-y" 530.It Li "Previous page" Ta "C-u" Ta "Page up" 531.It Li "Previous word" Ta "b" Ta "M-b" 532.It Li "Quit mode" Ta "q" Ta "Escape" 533.It Li "Scroll down" Ta "C-Down or J" Ta "C-Down" 534.It Li "Scroll up" Ta "C-Up or K" Ta "C-Up" 535.It Li "Search again" Ta "n" Ta "n" 536.It Li "Search backward" Ta "?" Ta "C-r" 537.It Li "Search forward" Ta "/" Ta "C-s" 538.It Li "Start of line" Ta "0" Ta "C-a" 539.It Li "Start selection" Ta "Space" Ta "C-Space" 540.It Li "Transpose chars" Ta "" Ta "C-t" 541.It Li "Cursor to top line" Ta "H" Ta "M-R" 542.It Li "Cursor to middle line" Ta "M" Ta "M-r" 543.It Li "Cursor to bottom line" Ta "L" Ta "" 544.El 545.Pp 546These key bindings are defined in a set of named tables: 547.Em vi-edit 548and 549.Em emacs-edit 550for keys used when line editing at the command prompt; 551.Em vi-choice 552and 553.Em emacs-choice 554for keys used when choosing from lists (such as produced by the 555.Ic window-choose 556command) or in output mode; and 557.Em vi-copy 558and 559.Em emacs-copy 560used in copy mode. 561The tables may be viewed with the 562.Ic list-keys 563command and keys modified or removed with 564.Ic bind-key 565and 566.Ic unbind-key . 567.Pp 568The paste buffer key pastes the first line from the top paste buffer on the 569stack. 570.Pp 571The mode commands are as follows: 572.Bl -tag -width Ds 573.It Xo Ic copy-mode 574.Op Fl u 575.Op Fl t Ar target-pane 576.Xc 577Enter copy mode. 578The 579.Fl u 580option scrolls one page up. 581.El 582.Pp 583Each window displayed by 584.Nm 585may be split into one or more 586.Em panes ; 587each pane takes up a certain area of the display and is a separate terminal. 588A window may be split into panes using the 589.Ic split-window 590command. 591Windows may be split horizontally (with the 592.Fl h 593flag) or vertically. 594Panes may be resized with the 595.Ic resize-pane 596command (bound to 597.Ql C-up , 598.Ql C-down 599.Ql C-left 600and 601.Ql C-right 602by default), the current pane may be changed with the 603.Ic up-pane 604and 605.Ic down-pane 606commands and the 607.Ic rotate-window 608and 609.Ic swap-pane 610commands may be used to swap panes without changing their position. 611Panes are numbered beginning from zero in the order they are created. 612.Pp 613A number of preset 614.Em layouts 615are available. 616These may be selected with the 617.Ic select-layout 618command or cycled with 619.Ic next-layout 620(bound to 621.Ql C-space 622by default); once a layout is chosen, panes within it may be moved and resized as normal. 623.Pp 624The following layouts are supported: 625.Bl -tag -width Ds 626.It Ic even-horizontal 627Panes are spread out evenly from left to right across the window. 628.It Ic even-vertical 629Panes are spread evenly from top to bottom. 630.It Ic main-horizontal 631A large (main) pane is shown at the top of the window and the remaining panes are 632spread from left to right in the leftover space at the bottom. 633Use the 634.Em main-pane-height 635window option to specify the height of the top pane. 636.It Ic main-vertical 637Similar to 638.Ic main-horizontal 639but the large pane is placed on the left and the others spread from top to 640bottom along the right. 641See the 642.Em main-pane-width 643window option. 644.El 645.Pp 646Commands related to windows and panes are as follows: 647.Bl -tag -width Ds 648.It Xo Ic break-pane 649.Op Fl d 650.Op Fl t Ar target-pane 651.Xc 652.D1 (alias: Ic breakp ) 653Break 654.Ar target-pane 655off from its containing window to make it the only pane in a new window. 656If 657.Fl d 658is given, the new window does not become the current window. 659.It Xo 660.Ic choose-client 661.Op Fl t Ar target-window 662.Op Ar template 663.Xc 664Put a window into client choice mode, allowing a client to be selected 665interactively from a list. 666After a client is chosen, 667.Ql %% 668is replaced by the client 669.Xr pty 4 670path in 671.Ar template 672and the result executed as a command. 673If 674.Ar template 675is not given, "detach-client -t '%%'" is used. 676This command works only from inside 677.Nm . 678.It Xo 679.Ic choose-session 680.Op Fl t Ar target-window 681.Op Ar template 682.Xc 683Put a window into session choice mode, where a session may be selected 684interactively from a list. 685When one is chosen, 686.Ql %% 687is replaced by the session name in 688.Ar template 689and the result executed as a command. 690If 691.Ar template 692is not given, "switch-client -t '%%'" is used. 693This command works only from inside 694.Nm . 695.It Xo 696.Ic choose-window 697.Op Fl t Ar target-window 698.Op Ar template 699.Xc 700Put a window into window choice mode, where a window may be chosen 701interactively from a list. 702After a window is selected, 703.Ql %% 704is replaced by the session name and window index in 705.Ar template 706and the result executed as a command. 707If 708.Ar template 709is not given, "select-window -t '%%'" is used. 710This command works only from inside 711.Nm . 712.It Ic display-panes Op Fl t Ar target-client 713.D1 (alias: Ic displayp) 714Display a visible indicator of each pane shown by 715.Ar target-client . 716See the 717.Ic display-panes-time 718and 719.Ic display-panes-colour 720session options. 721While the indicator is on screen, a pane may be selected with the 722.Ql 0 723to 724.Ql 9 725keys. 726.It Ic down-pane Op Fl t Ar target-pane 727.D1 (alias: Ic downp ) 728Move down a pane. 729.It Xo Ic find-window 730.Op Fl t Ar target-window 731.Ar match-string 732.Xc 733.D1 (alias: Ic findw ) 734Search for the 735.Xr fnmatch 3 736pattern 737.Ar match-string 738in window names, titles, and visible content (but not history). 739If only one window is matched, it'll be automatically selected, otherwise a 740choice list is shown. 741This command only works from inside 742.Nm . 743.It Ic kill-pane Op Fl t Ar target-pane 744.D1 (alias: Ic killp ) 745Destroy the given pane. 746If no panes remain in the containing window, it is also destroyed. 747.It Ic kill-window Op Fl t Ar target-window 748.D1 (alias: Ic killw ) 749Kill the current window or the window at 750.Ar target-window , 751removing it from any sessions to which it is linked. 752.It Ic last-window Op Fl t Ar target-session 753.D1 (alias: Ic last ) 754Select the last (previously selected) window. 755If no 756.Ar target-session 757is specified, select the last window of the current session. 758.It Xo Ic link-window 759.Op Fl dk 760.Op Fl s Ar src-window 761.Op Fl t Ar dst-window 762.Xc 763.D1 (alias: Ic linkw ) 764Link the window at 765.Ar src-window 766to the specified 767.Ar dst-window . 768If 769.Ar dst-window 770is specified and no such window exists, the 771.Ar src-window 772is linked there. 773If 774.Fl k 775is given and 776.Ar dst-window 777exists, it is killed, otherwise an error is generated. 778If 779.Fl d 780is given, the newly linked window is not selected. 781.It Ic list-panes Op Fl t Ar target-window 782.D1 (alias: Ic lsp ) 783List the panes in the current window or in 784.Ar target-window . 785.It Ic list-windows Op Fl t Ar target-session 786.D1 (alias: Ic lsw ) 787List windows in the current session or in 788.Ar target-session . 789.It Xo Ic move-window 790.Op Fl d 791.Op Fl s Ar src-window 792.Op Fl t Ar dst-window 793.Xc 794.D1 (alias: Ic movew ) 795This is similar to 796.Ic link-window , 797except the window at 798.Ar src-window 799is moved to 800.Ar dst-window . 801.It Xo Ic new-window 802.Op Fl dk 803.Op Fl n Ar window-name 804.Op Fl t Ar target-window 805.Op Ar command 806.Xc 807.D1 (alias: Ic neww ) 808Create a new window. 809If 810.Fl d 811is given, the session does not make the new window the current window. 812.Ar target-window 813represents the window to be created; if the target already exists an error is 814shown, unless the 815.Fl k 816flag is used, in which case it is destroyed. 817.Ar command 818is the command to execute. 819If 820.Ar command 821is not specified, the default command is used. 822.Pp 823The 824.Ev TERM 825environment variable must be set to 826.Dq screen 827for all programs running 828.Em inside 829.Nm . 830New windows will automatically have 831.Dq TERM=screen 832added to their environment, but care must be taken not to reset this in shell 833start-up files. 834.It Ic next-layout Op Fl t Ar target-window 835.D1 (alias: Ic nextl ) 836Move a window to the next layout and rearrange the panes to fit. 837.It Xo Ic next-window 838.Op Fl a 839.Op Fl t Ar target-session 840.Xc 841.D1 (alias: Ic next ) 842Move to the next window in the session. 843If 844.Fl a 845is used, move to the next window with a bell, activity or content alert. 846.It Xo Ic pipe-pane 847.Op Fl o 848.Op Fl t Ar target-pane 849.Op Ar command 850.Xc 851.D1 (alias: Ic pipep ) 852Pipe any output sent by the program in 853.Ar target-pane 854to a shell command. 855A pane may only be piped to one command at a time, any existing pipe is 856closed before 857.Ar command 858is executed. 859If no 860.Ar command 861is given, the current pipe (if any) is closed. 862.Pp 863The 864.Fl o 865option only opens a new pipe if no previous pipe exists, allowing a pipe to 866be toggled with a single key, for example: 867.Bd -literal -offset indent 868bind-key C-p pipe-pane -o 'cat >>~/output' 869.Ed 870.It Xo Ic previous-window 871.Op Fl a 872.Op Fl t Ar target-session 873.Xc 874.D1 (alias: Ic prev ) 875Move to the previous window in the session. 876With 877.Fl a , 878move to the previous window with a bell, activity or content alert. 879.It Xo Ic rename-window 880.Op Fl t Ar target-window 881.Ar new-name 882.Xc 883.D1 (alias: Ic renamew ) 884Rename the current window, or the window at 885.Ar target-window 886if specified, to 887.Ar new-name . 888.It Xo Ic resize-pane 889.Op Fl DLRU 890.Op Fl t Ar target-pane 891.Op Ar adjustment 892.Xc 893.D1 (alias: Ic resizep ) 894Resize a pane, upward with 895.Fl U 896(the default), downward with 897.Fl D , 898to the left with 899.Fl L 900and to the right with 901.Fl R . 902The 903.Ar adjustment 904is given in lines or cells (the default is 1). 905.It Xo Ic respawn-window 906.Op Fl k 907.Op Fl t Ar target-window 908.Op Ar command 909.Xc 910.D1 (alias: Ic respawnw ) 911Reactive a window in which the command has exited (see the 912.Ic remain-on-exit 913window option). 914If 915.Ar command 916is not given, the command used when the window was created is executed. 917The window must be already inactive, unless 918.Fl k 919is given, in which case any existing command is killed. 920.It Xo Ic rotate-window 921.Op Fl DU 922.Op Fl t Ar target-window 923.Xc 924.D1 (alias: Ic rotatew ) 925Rotate the positions of the panes within a window, either upward (numerically 926lower) with 927.Fl U 928or downward (numerically higher). 929.It Xo Ic select-layout 930.Op Fl t Ar target-window 931.Op Ar layout-name 932.Xc 933.D1 (alias: selectl ) 934Choose a specific layout for a window. 935If 936.Ar layout-name 937is not given, the last layout used (if any) is reapplied. 938.It Ic select-pane Op Fl t Ar target-pane 939.D1 (alias: Ic selectp ) 940Make pane 941.Ar target-pane 942the active pane in window 943.Ar target-window . 944.It Ic select-window Op Fl t Ar target-window 945.D1 (alias: Ic selectw ) 946Select the window at 947.Ar target-window . 948.It Xo Ic split-window 949.Op Fl dhv 950.Oo Fl l 951.Ar size | 952.Fl p Ar percentage Oc 953.Op Fl t Ar target-window 954.Op Ar command 955.Xc 956.D1 (alias: splitw ) 957Creates a new pane by splitting the active pane: 958.Fl h 959does a horizontal split and 960.Fl v 961a vertical split; if neither is specified, 962.Fl v 963is assumed. 964The 965.Fl l 966and 967.Fl p 968options specify the size of the new window in lines (for vertical split) or in 969cells (for horizontal split), or as a percentage, respectively. 970All other options have the same meaning as in the 971.Ic new-window 972command. 973.It Xo Ic swap-pane 974.Op Fl dDU 975.Op Fl s Ar src-pane 976.Op Fl t Ar dst-pane 977.Xc 978.D1 (alias: Ic swapp ) 979Swap two panes. 980If 981.Fl U 982is used and no source pane is specified with 983.Fl s , 984.Ar dst-pane 985is swapped with the previous pane (before it numerically); 986.Fl D 987swaps with the next pane (after it numerically). 988.It Xo Ic swap-window 989.Op Fl d 990.Op Fl s Ar src-window 991.Op Fl t Ar dst-window 992.Xc 993.D1 (alias: Ic swapw ) 994This is similar to 995.Ic link-window , 996except the source and destination windows are swapped. 997It is an error if no window exists at 998.Ar src-window . 999.It Xo Ic unlink-window 1000.Op Fl k 1001.Op Fl t Ar target-window 1002.Xc 1003.D1 (alias: Ic unlinkw ) 1004Unlink 1005.Ar target-window . 1006Unless 1007.Fl k 1008is given, a window may be unlinked only if it is linked to multiple sessions - 1009windows may not be linked to no sessions; 1010if 1011.Fl k 1012is specified and the window is linked to only one session, it is unlinked and 1013destroyed. 1014.It Ic up-pane Op Fl t Ar target-pane 1015.D1 (alias: Ic upp ) 1016Move up a pane. 1017.El 1018.Sh KEY BINDINGS 1019.Nm 1020allows a command to be bound to most keys, with or without a prefix key. 1021When specifying keys, most represent themselves (for example 1022.Ql A 1023to 1024.Ql Z ) . 1025Ctrl keys may be prefixed with 1026.Ql C- 1027or 1028.Ql ^ , 1029and Alt (meta) with 1030.Ql M- . 1031In addition, the following special key names are accepted: 1032.Em BSpace , 1033.Em BTab , 1034.Em DC 1035(Delete), 1036.Em End , 1037.Em Enter , 1038.Em Escape , 1039.Em F1 1040to 1041.Em F20 , 1042.Em Home , 1043.Em IC 1044(Insert), 1045.Em NPage 1046(Page Up), 1047.Em PPage 1048(Page Down), 1049.Em Space , 1050and 1051.Em Tab . 1052Note that to bind the 1053.Ql \&" 1054or 1055.Ql ' 1056keys, quotation marks are necessary, for example: 1057.Bd -literal -offset indent 1058bind-key '"' split-window 1059bind-key "'" select-prompt 1060.Ed 1061.Pp 1062Commands related to key bindings are as follows: 1063.Bl -tag -width Ds 1064.It Xo Ic bind-key 1065.Op Fl cnr 1066.Op Fl t Ar key-table 1067.Ar key Ar command Op Ar arguments 1068.Xc 1069.D1 (alias: Ic bind ) 1070Bind key 1071.Ar key 1072to 1073.Ar command . 1074By default (without 1075.Fl t ) 1076the primary key bindings are modified (those normally activated with the prefix 1077key); in this case, if 1078.Fl n 1079is specified, it is not necessary to use the prefix key, 1080.Ar command 1081is bound to 1082.Ar key 1083alone. 1084The 1085.Fl r 1086flag indicates this key may repeat, see the 1087.Ic repeat-time 1088option. 1089.Pp 1090If 1091.Fl t 1092is present, 1093.Ar key 1094is bound in 1095.Ar key-table : 1096the binding for command mode with 1097.Fl c 1098or for normal mode without. 1099To view the default bindings and possible commands, see the 1100.Ic list-keys 1101command. 1102.It Ic list-keys Op Fl t Ar key-table 1103.D1 (alias: Ic lsk ) 1104List all key bindings. 1105Without 1106.Fl t 1107the primary key bindings - those executed when preceded by the prefix key - 1108are printed. 1109Keys bound without the prefix key (see 1110.Ic bind-key 1111.Fl n ) 1112are enclosed in square brackets. 1113.Pp 1114With 1115.Fl t , 1116the key bindings in 1117.Ar key-table 1118are listed; this may be one of: 1119.Em vi-edit , 1120.Em emacs-edit , 1121.Em vi-choice , 1122.Em emacs-choice , 1123.Em vi-copy 1124or 1125.Em emacs-copy . 1126.It Xo Ic send-keys 1127.Op Fl t Ar target-pane 1128.Ar key Ar ... 1129.Xc 1130.D1 (alias: Ic send ) 1131Send a key or keys to a window. 1132Each argument 1133.Ar key 1134is the name of the key (such as 1135.Ql C-a 1136or 1137.Ql npage 1138) to send; if the string is not recognised as a key, it is sent as a series of 1139characters. 1140All arguments are sent sequentially from first to last. 1141.It Ic send-prefix Op Fl t Ar target-pane 1142Send the prefix key to a window as if it was pressed. 1143If multiple prefix keys are configured, only the first is sent. 1144.It Xo Ic unbind-key 1145.Op Fl cn 1146.Op Fl t Ar key-table 1147.Ar key 1148.Xc 1149.D1 (alias: Ic unbind ) 1150Unbind the command bound to 1151.Ar key . 1152Without 1153.Fl t 1154the primary key bindings are modified; in this case, if 1155.Fl n 1156is specified, the command bound to 1157.Ar key 1158without a prefix (if any) is removed. 1159.Pp 1160If 1161.Fl t 1162is present, 1163.Ar key 1164in 1165.Ar key-table 1166is unbound: the binding for command mode with 1167.Fl c 1168or for normal mode without. 1169.El 1170.Sh OPTIONS 1171The appearance and behaviour of 1172.Nm 1173may be modified by changing the value of various options. 1174There are two types of option: 1175.Em session options 1176and 1177.Em window options . 1178.Pp 1179Each individual session may have a set of session options, and there is a 1180separate set of global session options. 1181Sessions which do not have a particular option configured inherit the value 1182from the global session options. 1183Session options are set or unset with the 1184.Ic set-option 1185command and may be listed with the 1186.Ic show-options 1187command. 1188The available session options are listed under the 1189.Ic set-option 1190command. 1191.Pp 1192Similarly, a set of window options is attached to each window, and there is 1193a set of global window options from which any unset options are inherited. 1194Window options are altered with the 1195.Ic set-window-option 1196command and can be listed with the 1197.Ic show-window-options 1198command. 1199All window options are documented with the 1200.Ic set-window-option 1201command. 1202.Pp 1203Commands which set options are as follows: 1204.Bl -tag -width Ds 1205.It Xo Ic set-option 1206.Op Fl agu 1207.Op Fl t Ar target-session 1208.Ar option Ar value 1209.Xc 1210.D1 (alias: Ic set ) 1211Set a session option. 1212With 1213.Fl a , 1214and if the option expects a string, 1215.Ar value 1216is appended to the existing setting. 1217If 1218.Fl g 1219is specified, the global session option is set. 1220The 1221.Fl u 1222flag unsets an option, so a session inherits the option from the global 1223options - it is not possible to unset a global option. 1224.Pp 1225Available session options are: 1226.Bl -tag -width Ds 1227.It Ic base-index Ar index 1228Set the base index from which an unused index should be searched when a new 1229window is created. 1230The default is zero. 1231.It Xo Ic bell-action 1232.Op Ic any | none | current 1233.Xc 1234Set action on window bell. 1235.Ic any 1236means a bell in any window linked to a session causes a bell in the current 1237window of that session, 1238.Ic none 1239means all bells are ignored and 1240.Ic current 1241means only bell in windows other than the current window are ignored. 1242.It Ic buffer-limit Ar number 1243Set the number of buffers kept for each session; as new buffers are added to 1244the top of the stack, old ones are removed from the bottom if necessary to 1245maintain this maximum length. 1246.It Ic default-command Ar command 1247Set the command used for new windows (if not specified when the window is 1248created) to 1249.Ar command , 1250which may be any 1251.Xr sh 1 1252command. 1253The default is an empty string, which instructs 1254.Nm 1255to create a login shell using the value of the 1256.Ic default-shell 1257option. 1258.It Ic default-shell Ar path 1259Specify the default shell. 1260This is used as the login shell for new windows when the 1261.Ic default-command 1262option is set to empty, and must be the full path of the executable. 1263When started 1264.Nm 1265tries to set a default value from the first suitable of the 1266.Ev SHELL 1267environment variable, the shell returned by 1268.Xr getpwuid 3 , 1269or 1270.Pa /bin/sh . 1271This option should be configured when 1272.Nm 1273is used as a login shell. 1274.It Ic default-path Ar path 1275Set the default working directory for processes created from keys, or 1276interactively from the prompt. 1277The default is the current working directory when the server is started. 1278.It Ic default-terminal Ar terminal 1279Set the default terminal for new windows created in this session - the 1280default value of the 1281.Ev TERM 1282environment variable. 1283For 1284.Nm 1285to work correctly, this 1286.Em must 1287be set to 1288.Ql screen 1289or a derivative of it. 1290.It Ic display-panes-colour Ar colour 1291Set the colour used for the 1292.Ic display-panes 1293command. 1294.It Ic display-panes-time Ar time 1295Set the time in milliseconds for which the indicators shown by the 1296.Ic display-panes 1297command appear. 1298.It Ic display-time Ar time 1299Set the amount of time for which status line messages and other on-screen 1300indicators are displayed. 1301.Ar time 1302is in milliseconds. 1303.It Ic history-limit Ar lines 1304Set the maximum number of lines held in window history. 1305This setting applies only to new windows - existing window histories are not 1306resized and retain the limit at the point they were created. 1307.It Ic lock-after-time Ar number 1308Lock the session (like the 1309.Ic lock-session 1310command) after 1311.Ar number 1312seconds of inactivity, or the entire server (all sessions) if the 1313.Ic lock-server 1314option is set. 1315The default is not to lock (set to 0). 1316.It Ic lock-command Ar command 1317Command to run when locking each client. 1318The default is to run 1319.Xr lock 1 1320with 1321.Fl np . 1322.It Xo Ic lock-server 1323.Op Ic on | off 1324.Xc 1325If this option is 1326.Ic on 1327(the default), 1328instead of each session locking individually as each has been 1329idle for 1330.Ic lock-after-time , 1331the entire server will lock after 1332.Em all 1333sessions would have locked. 1334This has no effect as a session option; it must be set as a global option. 1335.It Ic message-attr Ar attributes 1336Set status line message attributes, where 1337.Ar attributes 1338is either 1339.Ic default 1340or a comma-delimited list of one or more of: 1341.Ic bright 1342(or 1343.Ic bold ) , 1344.Ic dim , 1345.Ic underscore , 1346.Ic blink , 1347.Ic reverse , 1348.Ic hidden , 1349or 1350.Ic italics . 1351.It Ic message-bg Ar colour 1352Set status line message background colour, where 1353.Ar colour 1354is one of: 1355.Ic black , 1356.Ic red , 1357.Ic green , 1358.Ic yellow , 1359.Ic blue , 1360.Ic magenta , 1361.Ic cyan , 1362.Ic white , 1363.Ic colour0 1364to 1365.Ic colour255 1366from the 256-colour palette, or 1367.Ic default . 1368.It Ic message-fg Ar colour 1369Set status line message foreground colour. 1370.It Xo Ic mouse-select-pane 1371.Op Ic on | off 1372.Xc 1373If on, 1374.Nm 1375captures the mouse and when a window is split into multiple panes the mouse may 1376be used to select the current pane. 1377The mouse click is also passed through to the application as normal. 1378.It Ic prefix Ar keys 1379Set the keys accepted as a prefix key. 1380.Ar keys 1381is a comma-separated list of key names, each of which individually behave as 1382the prefix key. 1383.It Ic repeat-time Ar time 1384Allow multiple commands to be entered without pressing the prefix-key again 1385in the specified 1386.Ar time 1387milliseconds (the default is 500). 1388Whether a key repeats may be set when it is bound using the 1389.Fl r 1390flag to 1391.Ic bind-key . 1392Repeat is enabled for the default keys bound to the 1393.Ic resize-pane 1394command. 1395.It Xo Ic set-remain-on-exit 1396.Op Ic on | off 1397.Xc 1398Set the 1399.Ic remain-on-exit 1400window option for any windows first created in this session. 1401.It Xo Ic set-titles 1402.Op Ic on | off 1403.Xc 1404Attempt to set the window title using the \ee]2;...\e007 xterm code if 1405the terminal appears to be an xterm. 1406This option is off by default. 1407Note that elinks 1408will only attempt to set the window title if the STY environment 1409variable is set. 1410.It Ic set-titles-string Ar string 1411String used to set the window title if 1412.Ic set-titles 1413is on. 1414Character sequences are replaced as for the 1415.Ic status-left 1416option. 1417.It Xo Ic status 1418.Op Ic on | off 1419.Xc 1420Show or hide the status line. 1421.It Ic status-attr Ar attributes 1422Set status line attributes. 1423.It Ic status-bg Ar colour 1424Set status line background colour. 1425.It Ic status-fg Ar colour 1426Set status line foreground colour. 1427.It Ic status-interval Ar interval 1428Update the status bar every 1429.Ar interval 1430seconds. 1431By default, updates will occur every 15 seconds. 1432A setting of zero disables redrawing at interval. 1433.It Xo Ic status-justify 1434.Op Ic left | centre | right 1435.Xc 1436Set the position of the window list component of the status line: left, centre 1437or right justified. 1438.It Xo Ic status-keys 1439.Op Ic vi | emacs 1440.Xc 1441Use vi or emacs-style 1442key bindings in the status line, for example at the command prompt. 1443Defaults to emacs. 1444.It Ic status-left Ar string 1445Display 1446.Ar string 1447to the left of the status bar. 1448.Ar string 1449will be passed through 1450.Xr strftime 3 1451before being used. 1452By default, the session name is shown. 1453.Ar string 1454may contain any of the following special character sequences: 1455.Bl -column "Character pair" "Replaced with" -offset indent 1456.It Sy "Character pair" Ta Sy "Replaced with" 1457.It Li "#(command)" Ta "First line of command's output" 1458.It Li "#[attributes]" Ta "Colour or attribute change" 1459.It Li "#H" Ta "Hostname of local host" 1460.It Li "#I" Ta "Current window index" 1461.It Li "#P" Ta "Current pane index" 1462.It Li "#S" Ta "Session name" 1463.It Li "#T" Ta "Current window title" 1464.It Li "#W" Ta "Current window name" 1465.It Li "##" Ta "A literal" Ql # 1466.El 1467.Pp 1468The #(command) form executes 1469.Ql command 1470as a shell command and inserts the first line of its output. 1471Note that shell commands are only executed once at the interval specified by 1472the 1473.Ic status-interval 1474option: if the status line is redrawn in the meantime, the previous result is 1475used. 1476.Pp 1477#[attributes] allows a comma-separated list of attributes to be specified, 1478these may be 1479.Ql fg=colour 1480to set the foreground colour, 1481.Ql bg=colour 1482to set the background colour, the name of one of the attributes (listed under the 1483.Ic message-attr 1484option) to turn an attribute on, or an attribute prefixed with 1485.Ql no 1486to turn one off, for example 1487.Ic nobright . 1488Examples are: 1489.Bd -literal -offset indent 1490#(sysctl vm.loadavg) 1491#[fg=yellow,bold]#(apm -l)%%#[default] [#S] 1492.Ed 1493.Pp 1494Where appropriate, special character sequences may be prefixed with a number to 1495specify the maximum length, for example 1496.Ql #24T . 1497.Pp 1498By default, UTF-8 in 1499.Ar string 1500is not interpreted, to enable UTF-8, use the 1501.Ic status-utf8 1502option. 1503.It Ic status-left-attr Ar attributes 1504Set the attribute of the left part of the status line. 1505.It Ic status-left-fg Ar colour 1506Set the foreground colour of the left part of the status line. 1507.It Ic status-left-bg Ar colour 1508Set the background colour of the left part of the status line. 1509.It Ic status-left-length Ar length 1510Set the maximum 1511.Ar length 1512of the left component of the status bar. 1513The default is 10. 1514.It Ic status-right Ar string 1515Display 1516.Ar string 1517to the right of the status bar. 1518By default, the date and time will be shown. 1519As with 1520.Ic status-left , 1521.Ar string 1522will be passed to 1523.Xr strftime 3 , 1524character pairs are replaced, and UTF-8 is dependent on the 1525.Ic status-utf8 1526option. 1527.It Ic status-right-attr Ar attributes 1528Set the attribute of the right part of the status line. 1529.It Ic status-right-fg Ar colour 1530Set the foreground colour of the right part of the status line. 1531.It Ic status-right-bg Ar colour 1532Set the background colour of the right part of the status line. 1533.It Ic status-right-length Ar length 1534Set the maximum 1535.Ar length 1536of the right component of the status bar. 1537The default is 40. 1538.Pp 1539.It Xo Ic status-utf8 1540.Op Ic on | off 1541.Xc 1542Instruct 1543.Nm 1544to treat top-bit-set characters in the 1545.Ic status-left 1546and 1547.Ic status-right 1548strings as UTF-8; notably, this is important for wide characters. 1549This option defaults to off. 1550.It Ic terminal-overrides Ar string 1551Contains a list of entries which override terminal descriptions read using 1552.Xr terminfo 5 . 1553.Ar string 1554is a comma-separated list of items each a colon-separated string made up of a 1555terminal type pattern (matched using 1556.Xr fnmatch 3 ) 1557and a set of 1558.Em name=value 1559entries. 1560.Pp 1561For example, to set the 1562.Ql clear 1563.Xr terminfo 5 1564entry to 1565.Ql \ee[H\ee[2J 1566for all terminal types and the 1567.Ql dch1 1568entry to 1569.Ql \ee[P 1570for the 1571.Ql rxvt 1572terminal type, the option could be set to the string: 1573.Bd -literal -offset indent 1574"*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P" 1575.Ed 1576.Pp 1577The terminal entry value is passed through 1578.Xr strunvis 3 1579before interpretation. 1580The default value forcibly corrects the 1581.Ql colors 1582entry for terminals which support 88 or 256 colours: 1583.Bd -literal -offset indent 1584"*88col*:colors=88,*256col*:colors=256" 1585.Ed 1586.It Ic update-environment Ar variables 1587Set a space-separated string containing a list of environment variables to be 1588copied into the session environment when a new session is created or an 1589existing session is attached. 1590Any variables that do not exist in the source environment are set to be 1591removed from the session environment (as if 1592.Fl r 1593was given to the 1594.Ic set-environment 1595command). 1596The default is 1597"DISPLAY WINDOWID SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION". 1598.It Xo Ic visual-activity 1599.Op Ic on | off 1600.Xc 1601If on, display a status line message when activity occurs in a window 1602for which the 1603.Ic monitor-activity 1604window option is enabled. 1605.It Xo Ic visual-bell 1606.Op Ic on | off 1607.Xc 1608If this option is on, a message is shown on a bell instead of it being passed 1609through to the terminal (which normally makes a sound). 1610Also see the 1611.Ic bell-action 1612option. 1613.It Xo Ic visual-content 1614.Op Ic on | off 1615.Xc 1616Like 1617.Ic visual-activity , 1618display a message when content is present in a window 1619for which the 1620.Ic monitor-content 1621window option is enabled. 1622.El 1623.It Xo Ic set-window-option 1624.Op Fl agu 1625.Op Fl t Ar target-window 1626.Ar option Ar value 1627.Xc 1628.D1 (alias: Ic setw ) 1629Set a window option. 1630The 1631.Fl a , 1632.Fl g 1633and 1634.Fl u 1635flags work similarly to the 1636.Ic set-option 1637command. 1638.Pp 1639Supported window options are: 1640.Pp 1641.Bl -tag -width Ds -compact 1642.It Xo Ic aggressive-resize 1643.Op Ic on | off 1644.Xc 1645Aggressively resize the chosen window. 1646This means that 1647.Nm 1648will resize the window to the size of the smallest session for which it is the 1649current window, rather than the smallest session to which it is attached. 1650The window may resize when the current window is changed on another sessions; 1651this option is good for full-screen programs which support 1652.Dv SIGWINCH 1653and poor for interactive programs such as shells. 1654.Pp 1655.It Xo Ic automatic-rename 1656.Op Ic on | off 1657.Xc 1658Control automatic window renaming. 1659When this setting is enabled, 1660.Nm 1661will attempt - on supported platforms - to rename the window to reflect the 1662command currently running in it. 1663This flag is automatically disabled for an individual window when a name 1664is specified at creation with 1665.Ic new-window or 1666.Ic new-session , 1667or later with 1668.Ic rename-window . 1669It may be switched off globally with: 1670.Bd -literal -offset indent 1671set-window-option -g automatic-rename off 1672.Ed 1673.Pp 1674.It Ic clock-mode-colour Ar colour 1675Set clock colour. 1676.Pp 1677.It Xo Ic clock-mode-style 1678.Op Ic 12 | 24 1679.Xc 1680Set clock hour format. 1681.Pp 1682.It Ic force-height Ar height 1683.It Ic force-width Ar width 1684Prevent 1685.Nm 1686from resizing a window to greater than 1687.Ar width 1688or 1689.Ar height . 1690A value of zero restores the default unlimited setting. 1691.Pp 1692.It Ic main-pane-width Ar width 1693.It Ic main-pane-height Ar height 1694Set the width or height of the main (left or top) pane in the 1695.Ic main-horizontal 1696or 1697.Ic main-vertical 1698layouts. 1699.Pp 1700.It Ic mode-attr Ar attributes 1701Set window modes attributes. 1702.Pp 1703.It Ic mode-bg Ar colour 1704Set window modes background colour. 1705.Pp 1706.It Ic mode-fg Ar colour 1707Set window modes foreground colour. 1708.Pp 1709.It Xo Ic mode-keys 1710.Op Ic vi | emacs 1711.Xc 1712Use vi or emacs-style key bindings in copy and choice modes. 1713Key bindings default to emacs. 1714.Pp 1715.It Xo Ic mode-mouse 1716.Op Ic on | off 1717.Xc 1718Mouse state in modes. 1719If on, 1720.Nm 1721will respond to mouse clicks by moving the cursor in copy mode or selecting an 1722option in choice mode. 1723.Pp 1724.It Xo Ic monitor-activity 1725.Op Ic on | off 1726.Xc 1727Monitor for activity in the window. 1728Windows with activity are highlighted in the status line. 1729.Pp 1730.It Ic monitor-content Ar match-string 1731Monitor content in the window. 1732When 1733.Xr fnmatch 3 1734pattern 1735.Ar match-string 1736appears in the window, it is highlighted in the status line. 1737.Pp 1738.It Xo Ic remain-on-exit 1739.Op Ic on | off 1740.Xc 1741A window with this flag set is not destroyed when the program running in it 1742exits. 1743The window may be reactivated with the 1744.Ic respawn-window 1745command. 1746.Pp 1747.It Xo Ic synchronize-panes 1748.Op Ic on | off 1749.Xc 1750Duplicate input to any pane to all other panes in the same window, except 1751for panes that are not in output mode. 1752.It Xo Ic utf8 1753.Op Ic on | off 1754.Xc 1755Instructs 1756.Nm 1757to expect UTF-8 sequences to appear in this window. 1758.Pp 1759.It Ic window-status-attr Ar attributes 1760Set status line attributes for a single window. 1761.Pp 1762.It Ic window-status-bg Ar colour 1763Set status line background colour for a single window. 1764.Pp 1765.It Ic window-status-fg Ar colour 1766Set status line foreground colour for a single window. 1767.Pp 1768.It Ic window-status-current-attr Ar attributes 1769Set status line attributes for the currently active window. 1770.Pp 1771.It Ic window-status-current-bg Ar colour 1772Set status line background colour for the currently active window. 1773.Pp 1774.It Ic window-status-current-fg Ar colour 1775Set status line foreground colour for the currently active window. 1776.Pp 1777.It Xo Ic xterm-keys 1778.Op Ic on | off 1779.Xc 1780If this option is set, 1781.Nm 1782will generate 1783.Xr xterm 1 -style 1784function key sequences; these have a number included to indicate modifiers such 1785as Shift, Alt or Ctrl. 1786.El 1787.It Xo Ic show-options 1788.Op Fl g 1789.Op Fl t Ar target-session 1790.Xc 1791.D1 (alias: Ic show ) 1792Show the session options for 1793.Ar target session , 1794or the global session options with 1795.Fl g . 1796.It Xo Ic show-window-options 1797.Op Fl g 1798.Op Fl t Ar target-window 1799.Xc 1800.D1 (alias: Ic showw ) 1801List the window options for 1802.Ar target-window , 1803or the global window options if 1804.Fl g 1805is used. 1806.El 1807.Sh ENVIRONMENT 1808When the server is started, 1809.Nm 1810copies the environment into the 1811.Em global environment ; 1812in addition, each session has a 1813.Em session environment . 1814When a window is created, the session and global environments are merged with 1815the session environment overriding any variable present in both. 1816This is the initial environment passed to the new process. 1817.Pp 1818The 1819.Ic update-environment 1820session option may be used to update the session environment from the client 1821when a new session is created or an old reattached. 1822.Nm 1823also initialises the 1824.Ev TMUX 1825variable with some internal information to allow commands to be executed 1826from inside, and the 1827.Ev TERM 1828variable with the correct terminal setting of 1829.Ql screen . 1830.Pp 1831Commands to alter and view the environment are: 1832.Bl -tag -width Ds 1833.It Xo Ic set-environment 1834.Op Fl gru 1835.Op Fl t Ar target-session 1836.Ar name Op Ar value 1837.Xc 1838Set or unset an environment variable. 1839If 1840.Fl g 1841is used, the change is made in the global environment; otherwise, it is applied 1842to the session environment for 1843.Ar target-session . 1844The 1845.Fl u 1846flag unsets a variable. 1847.Fl r 1848indicates the variable is to be removed from the environment before starting a 1849new process. 1850.It Xo Ic show-environment 1851.Op Fl g 1852.Op Fl t Ar target-session 1853.Xc 1854Display the environment for 1855.Ar target-session 1856or the global environment with 1857.Fl g . 1858Variables removed from the environment are prefixed with 1859.Ql - . 1860.El 1861.Sh STATUS LINE 1862.Nm 1863includes an optional status line which is displayed in the bottom line of each 1864terminal. 1865By default, the status line is enabled (it may be disabled with the 1866.Ic status 1867session option) and contains, from left-to-right: the name of the current 1868session in square brackets; the window list; the current window title in double 1869quotes; and the time and date. 1870.Pp 1871The status line is made of three parts: configurable left and right sections 1872(which may contain dynamic content such as the time or output from a shell 1873command, see the 1874.Ic status-left , 1875.Ic status-left-length , 1876.Ic status-right , 1877and 1878.Ic status-right-length 1879options below), and a central window list. 1880The window list shows the index, name and (if any) flag of the windows 1881present in the current session in ascending numerical order. 1882The flag is one of the following symbols appended to the window name: 1883.Bl -column "Symbol" "Meaning" -offset indent 1884.It Sy "Symbol" Ta Sy "Meaning" 1885.It Li "*" Ta "Denotes the current window." 1886.It Li "-" Ta "Marks the last window (previously selected)." 1887.It Li "#" Ta "Window is monitored and activity has been detected." 1888.It Li "!" Ta "A bell has occurred in the window." 1889.It Li "+" Ta "Window is monitored for content and it has appeared." 1890.El 1891.Pp 1892The # symbol relates to the 1893.Ic monitor-activity 1894and + to the 1895.Ic monitor-content 1896window options. 1897The window name is printed in inverted colours if an alert (bell, activity or 1898content) is present. 1899.Pp 1900The colour and attributes of the status line may be configured, the entire status line using 1901the 1902.Ic status-attr , 1903.Ic status-fg 1904and 1905.Ic status-bg 1906session options and individual windows using the 1907.Ic window-status-attr , 1908.Ic window-status-fg 1909and 1910.Ic window-status-bg 1911window options. 1912.Pp 1913The status line is automatically refreshed at interval if it has changed, the interval may be 1914controlled with the 1915.Ic status-interval 1916session option. 1917.Pp 1918Commands related to the status line are as follows: 1919.Bl -tag -width Ds 1920.It Xo Ic command-prompt 1921.Op Fl p Ar prompts 1922.Op Fl t Ar target-client 1923.Op Ar template 1924.Xc 1925Open the command prompt in a client. 1926This may be used from inside 1927.Nm 1928to execute commands interactively. 1929If 1930.Ar template 1931is specified, it is used as the command. 1932If 1933.Fl p 1934is given, 1935.Ar prompts 1936is a comma-separated list of prompts which are displayed in order; otherwise 1937a single prompt is displayed, constructed from 1938.Ar template 1939if it is present, or 1940.Ql \&: 1941if not. 1942Before the command is executed, the first occurrence of the string 1943.Ql %% 1944and all occurrences of 1945.Ql %1 1946are replaced by the response to the first prompt, the second 1947.Ql %% 1948and all 1949.Ql %2 1950are replaced with the response to the second prompt, and so on for further 1951prompts. 1952Up to nine prompt responses may be replaced 1953.Po 1954.Ql %1 1955to 1956.Ql %9 1957.Pc . 1958.It Xo Ic confirm-before 1959.Op Fl t Ar target-client 1960.Ar command 1961.Xc 1962.D1 (alias: Ic confirm ) 1963Ask for confirmation before executing 1964.Ar command . 1965This command works only from inside 1966.Nm . 1967.It Xo Ic display-message 1968.Op Fl t Ar target-client 1969.Op Ar message 1970.Xc 1971.D1 (alias: Ic display ) 1972Display a message (see the 1973.Ic status-left 1974option below) 1975in the status line. 1976.It Ic select-prompt Op Fl t Ar target-client 1977Open a prompt inside 1978.Ar target-client 1979allowing a window index to be entered interactively. 1980.El 1981.Sh BUFFERS 1982.Nm 1983maintains a stack of 1984.Em paste buffers 1985for each session. 1986Up to the value of the 1987.Ic buffer-limit 1988option are kept; when a new buffer is added, the buffer at the bottom of the 1989stack is removed. 1990Buffers may be added using 1991.Ic copy-mode 1992or the 1993.Ic set-buffer 1994command, and pasted into a window using the 1995.Ic paste-buffer 1996command. 1997.Pp 1998A configurable history buffer is also maintained for each window. 1999By default, up to 2000 lines are kept; this can be altered with the 2000.Ic history-limit 2001option (see the 2002.Ic set-option 2003command above). 2004.Pp 2005The buffer commands are as follows: 2006.Bl -tag -width Ds 2007.It Ic clear-history Op Fl t Ar target-pane 2008.D1 (alias: Ic clearhist ) 2009Remove and free the history for the specified pane. 2010.It Xo Ic copy-buffer 2011.Op Fl a Ar src-index 2012.Op Fl b Ar dst-index 2013.Op Fl s Ar src-session 2014.Op Fl t Ar dst-session 2015.Xc 2016.D1 (alias: Ic copyb ) 2017Copy a session paste buffer to another session. 2018If no sessions are specified, the current one is used instead. 2019.It Xo Ic delete-buffer 2020.Op Fl b Ar buffer-index 2021.Op Fl t Ar target-session 2022.Xc 2023.D1 (alias: Ic deleteb ) 2024Delete the buffer at 2025.Ar buffer-index , 2026or the top buffer if not specified. 2027.It Ic list-buffers Op Fl t Ar target-session 2028.D1 (alias: Ic lsb ) 2029List the buffers in the given session. 2030.It Xo Ic load-buffer 2031.Op Fl b Ar buffer-index 2032.Op Fl t Ar target-session 2033.Ar path 2034.Xc 2035.D1 (alias: Ic loadb ) 2036Load the contents of the specified paste buffer from 2037.Ar path . 2038.It Xo Ic paste-buffer 2039.Op Fl dr 2040.Op Fl b Ar buffer-index 2041.Op Fl t Ar target-window 2042.Xc 2043.D1 (alias: Ic pasteb ) 2044Insert the contents of a paste buffer into the current window. 2045With 2046.Fl d , 2047also delete the paste buffer from the stack. 2048When output, any linefeed (LF) characters in the paste buffer are replaced with 2049carriage returns (CR). 2050This translation may be disabled with the 2051.Fl r 2052flag. 2053.It Xo Ic save-buffer 2054.Op Fl a 2055.Op Fl b Ar buffer-index 2056.Op Fl t Ar target-session 2057.Ar path 2058.Xc 2059.D1 (alias: Ic saveb ) 2060Save the contents of the specified paste buffer to 2061.Ar path . 2062The 2063.Fl a 2064option appends to rather than overwriting the file. 2065.It Xo Ic set-buffer 2066.Op Fl b Ar buffer-index 2067.Op Fl t Ar target-session 2068.Ar data 2069.Xc 2070.D1 (alias: Ic setb ) 2071Set the contents of the specified buffer to 2072.Ar data . 2073.It Xo Ic show-buffer 2074.Op Fl b Ar buffer-index 2075.Op Fl t Ar target-session 2076.Xc 2077.D1 (alias: Ic showb ) 2078Display the contents of the specified buffer. 2079.El 2080.Sh MISCELLANEOUS 2081.Pp 2082Miscellaneous commands are as follows: 2083.Bl -tag -width Ds 2084.It Ic clock-mode Op Fl t Ar target-pane 2085Display a large clock. 2086.It Ic if-shell Ar shell-command command 2087.D1 (alias: Ic if ) 2088Execute 2089.Ar command 2090if 2091.Ar shell-command 2092returns success. 2093.It Ic lock-server 2094.D1 (alias: Ic lock ) 2095Lock each client individually by running the command specified by the 2096.Ic lock-command 2097option. 2098.It Ic run-shell Ar command 2099.D1 (alias: Ic run ) 2100Execute 2101.Ar command 2102in the background without creating a window. 2103After the command finishes, any output to stdout is displayed in output mode. 2104If 2105.Ar command 2106doesn't return success, the exit status is also displayed. 2107.It Ic server-info 2108.D1 (alias: Ic info ) 2109Show server information and terminal details. 2110.El 2111.Sh FILES 2112.Bl -tag -width "/etc/tmux.confXXX" -compact 2113.It Pa ~/.tmux.conf 2114Default 2115.Nm 2116configuration file. 2117.It Pa /etc/tmux.conf 2118System-wide configuration file. 2119.El 2120.Sh EXAMPLES 2121To create a new 2122.Nm 2123session running 2124.Xr vi 1 : 2125.Pp 2126.Dl $ tmux new-session vi 2127.Pp 2128Most commands have a shorter form, known as an alias. 2129For new-session, this is 2130.Ic new : 2131.Pp 2132.Dl $ tmux new vi 2133.Pp 2134Alternatively, the shortest unambiguous form of a command is accepted. 2135If there are several options, they are listed: 2136.Bd -literal -offset indent 2137$ tmux n 2138ambiguous command: n, could be: new-session, new-window, next-window 2139.Ed 2140.Pp 2141Within an active session, a new window may be created by typing 2142.Ql C-b c 2143(Ctrl 2144followed by the 2145.Ql b 2146key 2147followed by the 2148.Ql c 2149key). 2150.Pp 2151Windows may be navigated with: 2152.Ql C-b 0 2153(to select window 0), 2154.Ql C-b 1 2155(to select window 1), and so on; 2156.Ql C-b n 2157to select the next window; and 2158.Ql C-b p 2159to select the previous window. 2160.Pp 2161A session may be detached using 2162.Ql C-b d 2163(or by an external event such as 2164.Xr ssh 1 2165disconnection) and reattached with: 2166.Pp 2167.Dl $ tmux attach-session 2168.Pp 2169Typing 2170.Ql C-b \&? 2171lists the current key bindings in the current window; up and down may be used 2172to navigate the list or 2173.Ql q 2174to exit from it. 2175.Pp 2176Commands to be run when the 2177.Nm 2178server is started may be placed in the 2179.Pa ~/.tmux.conf 2180configuration file. 2181Common examples include: 2182.Pp 2183Changing the default prefix key: 2184.Bd -literal -offset indent 2185set-option -g prefix C-a 2186unbind-key C-b 2187bind-key C-a send-prefix 2188.Ed 2189.Pp 2190Turning the status line off, or changing its colour: 2191.Bd -literal -offset indent 2192set-option -g status off 2193set-option -g status-bg blue 2194.Ed 2195.Pp 2196Setting other options, such as the default command, 2197or locking after 30 minutes of inactivity: 2198.Bd -literal -offset indent 2199set-option -g default-command "exec /bin/ksh" 2200set-option -g lock-after-time 1800 2201.Ed 2202.Pp 2203Creating new key bindings: 2204.Bd -literal -offset indent 2205bind-key b set-option status 2206bind-key / command-prompt "split-window 'exec man %%'" 2207bind-key S command-prompt "new-window -n %1 'ssh %1'" 2208.Ed 2209.Sh SEE ALSO 2210.Xr pty 4 2211.Sh AUTHORS 2212.An Nicholas Marriott Aq nicm@users.sourceforge.net 2213