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