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