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