1.\" $OpenBSD: tmux.1,v 1.615 2018/11/07 07:58:16 nicm Exp $ 2.\" 3.\" Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER 14.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING 15.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 7 2018 $ 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 2Cluv 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 C 102Start in control mode (see the 103.Sx CONTROL MODE 104section). 105Given twice 106.Xo ( Fl CC ) Xc 107disables echo. 108.It Fl c Ar shell-command 109Execute 110.Ar shell-command 111using the default shell. 112If necessary, the 113.Nm 114server will be started to retrieve the 115.Ic default-shell 116option. 117This option is for compatibility with 118.Xr sh 1 119when 120.Nm 121is used as a login shell. 122.It Fl f Ar file 123Specify an alternative configuration file. 124By default, 125.Nm 126loads the system configuration file from 127.Pa /etc/tmux.conf , 128if present, then looks for a user configuration file at 129.Pa ~/.tmux.conf . 130.Pp 131The configuration file is a set of 132.Nm 133commands which are executed in sequence when the server is first started. 134.Nm 135loads configuration files once when the server process has started. 136The 137.Ic source-file 138command may be used to load a file later. 139.Pp 140.Nm 141shows any error messages from commands in configuration files in the first 142session created, and continues to process the rest of the configuration file. 143.It Fl L Ar socket-name 144.Nm 145stores the server socket in a directory under 146.Ev TMUX_TMPDIR 147or 148.Pa /tmp 149if it is unset. 150The default socket is named 151.Em default . 152This option allows a different socket name to be specified, allowing several 153independent 154.Nm 155servers to be run. 156Unlike 157.Fl S 158a full path is not necessary: the sockets are all created in the same 159directory. 160.Pp 161If the socket is accidentally removed, the 162.Dv SIGUSR1 163signal may be sent to the 164.Nm 165server process to recreate it (note that this will fail if any parent 166directories are missing). 167.It Fl l 168Behave as a login shell. 169This flag currently has no effect and is for compatibility with other shells 170when using tmux as a login shell. 171.It Fl S Ar socket-path 172Specify a full alternative path to the server socket. 173If 174.Fl S 175is specified, the default socket directory is not used and any 176.Fl L 177flag is ignored. 178.It Fl u 179When starting, 180.Nm 181looks for the 182.Ev LC_ALL , 183.Ev LC_CTYPE 184and 185.Ev LANG 186environment variables: if the first found contains 187.Ql UTF-8 , 188then the terminal is assumed to support UTF-8. 189This is not always correct: the 190.Fl u 191flag explicitly informs 192.Nm 193that UTF-8 is supported. 194.Pp 195Note that 196.Nm 197itself always accepts UTF-8; this controls whether it will send UTF-8 198characters to the terminal it is running (if not, they are replaced by 199.Ql _ ) . 200.It Fl v 201Request verbose logging. 202Log messages will be saved into 203.Pa tmux-client-PID.log 204and 205.Pa tmux-server-PID.log 206files in the current directory, where 207.Em PID 208is the PID of the server or client process. 209.Pp 210If 211.Fl v 212is specified twice, an additional 213.Pa tmux-out-PID.log 214file is generated with a copy of everything 215.Nm 216writes to the terminal. 217.Pp 218The 219.Dv SIGUSR2 220signal may be sent to the 221.Nm 222server process to toggle logging between on (as if 223.Fl v 224was given) and off. 225.It Ar command Op Ar flags 226This specifies one of a set of commands used to control 227.Nm , 228as described in the following sections. 229If no commands are specified, the 230.Ic new-session 231command is assumed. 232.El 233.Sh KEY BINDINGS 234.Nm 235may be controlled from an attached client by using a key combination of a 236prefix key, 237.Ql C-b 238(Ctrl-b) by default, followed by a command key. 239.Pp 240The default command key bindings are: 241.Pp 242.Bl -tag -width "XXXXXXXXXX" -offset indent -compact 243.It C-b 244Send the prefix key (C-b) through to the application. 245.It C-o 246Rotate the panes in the current window forwards. 247.It C-z 248Suspend the 249.Nm 250client. 251.It ! 252Break the current pane out of the window. 253.It \&" 254Split the current pane into two, top and bottom. 255.It # 256List all paste buffers. 257.It $ 258Rename the current session. 259.It % 260Split the current pane into two, left and right. 261.It & 262Kill the current window. 263.It ' 264Prompt for a window index to select. 265.It \&( 266Switch the attached client to the previous session. 267.It \&) 268Switch the attached client to the next session. 269.It , 270Rename the current window. 271.It - 272Delete the most recently copied buffer of text. 273.It . 274Prompt for an index to move the current window. 275.It 0 to 9 276Select windows 0 to 9. 277.It : 278Enter the 279.Nm 280command prompt. 281.It ; 282Move to the previously active pane. 283.It = 284Choose which buffer to paste interactively from a list. 285.It \&? 286List all key bindings. 287.It D 288Choose a client to detach. 289.It L 290Switch the attached client back to the last session. 291.It \&[ 292Enter copy mode to copy text or view the history. 293.It \&] 294Paste the most recently copied buffer of text. 295.It c 296Create a new window. 297.It d 298Detach the current client. 299.It f 300Prompt to search for text in open windows. 301.It i 302Display some information about the current window. 303.It l 304Move to the previously selected window. 305.It n 306Change to the next window. 307.It o 308Select the next pane in the current window. 309.It p 310Change to the previous window. 311.It q 312Briefly display pane indexes. 313.It r 314Force redraw of the attached client. 315.It m 316Mark the current pane (see 317.Ic select-pane 318.Fl m ) . 319.It M 320Clear the marked pane. 321.It s 322Select a new session for the attached client interactively. 323.It t 324Show the time. 325.It w 326Choose the current window interactively. 327.It x 328Kill the current pane. 329.It z 330Toggle zoom state of the current pane. 331.It { 332Swap the current pane with the previous pane. 333.It } 334Swap the current pane with the next pane. 335.It ~ 336Show previous messages from 337.Nm , 338if any. 339.It Page Up 340Enter copy mode and scroll one page up. 341.It Up, Down 342.It Left, Right 343Change to the pane above, below, to the left, or to the right of the current 344pane. 345.It M-1 to M-5 346Arrange panes in one of the five preset layouts: even-horizontal, 347even-vertical, main-horizontal, main-vertical, or tiled. 348.It Space 349Arrange the current window in the next preset layout. 350.It M-n 351Move to the next window with a bell or activity marker. 352.It M-o 353Rotate the panes in the current window backwards. 354.It M-p 355Move to the previous window with a bell or activity marker. 356.It C-Up, C-Down 357.It C-Left, C-Right 358Resize the current pane in steps of one cell. 359.It M-Up, M-Down 360.It M-Left, M-Right 361Resize the current pane in steps of five cells. 362.El 363.Pp 364Key bindings may be changed with the 365.Ic bind-key 366and 367.Ic unbind-key 368commands. 369.Sh COMMANDS 370This section contains a list of the commands supported by 371.Nm . 372Most commands accept the optional 373.Fl t 374(and sometimes 375.Fl s ) 376argument with one of 377.Ar target-client , 378.Ar target-session 379.Ar target-window , 380or 381.Ar target-pane . 382These specify the client, session, window or pane which a command should affect. 383.Pp 384.Ar target-client 385should be the name of the client, 386typically the 387.Xr pty 4 388file to which the client is connected, for example either of 389.Pa /dev/ttyp1 390or 391.Pa ttyp1 392for the client attached to 393.Pa /dev/ttyp1 . 394If no client is specified, 395.Nm 396attempts to work out the client currently in use; if that fails, an error is 397reported. 398Clients may be listed with the 399.Ic list-clients 400command. 401.Pp 402.Ar target-session 403is tried as, in order: 404.Bl -enum -offset Ds 405.It 406A session ID prefixed with a $. 407.It 408An exact name of a session (as listed by the 409.Ic list-sessions 410command). 411.It 412The start of a session name, for example 413.Ql mysess 414would match a session named 415.Ql mysession . 416.It 417An 418.Xr fnmatch 3 419pattern which is matched against the session name. 420.El 421.Pp 422If the session name is prefixed with an 423.Ql = , 424only an exact match is accepted (so 425.Ql =mysess 426will only match exactly 427.Ql mysess , 428not 429.Ql mysession ) . 430.Pp 431If a single session is found, it is used as the target session; multiple matches 432produce an error. 433If a session is omitted, the current session is used if available; if no 434current session is available, the most recently used is chosen. 435.Pp 436.Ar target-window 437(or 438.Ar src-window 439or 440.Ar dst-window ) 441specifies a window in the form 442.Em session Ns \&: Ns Em window . 443.Em session 444follows the same rules as for 445.Ar target-session , 446and 447.Em window 448is looked for in order as: 449.Bl -enum -offset Ds 450.It 451A special token, listed below. 452.It 453A window index, for example 454.Ql mysession:1 455is window 1 in session 456.Ql mysession . 457.It 458A window ID, such as @1. 459.It 460An exact window name, such as 461.Ql mysession:mywindow . 462.It 463The start of a window name, such as 464.Ql mysession:mywin . 465.It 466As an 467.Xr fnmatch 3 468pattern matched against the window name. 469.El 470.Pp 471Like sessions, a 472.Ql = 473prefix will do an exact match only. 474An empty window name specifies the next unused index if appropriate (for 475example the 476.Ic new-window 477and 478.Ic link-window 479commands) 480otherwise the current window in 481.Em session 482is chosen. 483.Pp 484The following special tokens are available to indicate particular windows. 485Each has a single-character alternative form. 486.Bl -column "XXXXXXXXXX" "X" 487.It Sy "Token" Ta Sy "" Ta Sy "Meaning" 488.It Li "{start}" Ta "^" Ta "The lowest-numbered window" 489.It Li "{end}" Ta "$" Ta "The highest-numbered window" 490.It Li "{last}" Ta "!" Ta "The last (previously current) window" 491.It Li "{next}" Ta "+" Ta "The next window by number" 492.It Li "{previous}" Ta "-" Ta "The previous window by number" 493.El 494.Pp 495.Ar target-pane 496(or 497.Ar src-pane 498or 499.Ar dst-pane ) 500may be a pane ID or takes a similar form to 501.Ar target-window 502but with the optional addition of a period followed by a pane index or pane ID, 503for example: 504.Ql mysession:mywindow.1 . 505If the pane index is omitted, the currently active pane in the specified 506window is used. 507The following special tokens are available for the pane index: 508.Bl -column "XXXXXXXXXXXXXX" "X" 509.It Sy "Token" Ta Sy "" Ta Sy "Meaning" 510.It Li "{last}" Ta "!" Ta "The last (previously active) pane" 511.It Li "{next}" Ta "+" Ta "The next pane by number" 512.It Li "{previous}" Ta "-" Ta "The previous pane by number" 513.It Li "{top}" Ta "" Ta "The top pane" 514.It Li "{bottom}" Ta "" Ta "The bottom pane" 515.It Li "{left}" Ta "" Ta "The leftmost pane" 516.It Li "{right}" Ta "" Ta "The rightmost pane" 517.It Li "{top-left}" Ta "" Ta "The top-left pane" 518.It Li "{top-right}" Ta "" Ta "The top-right pane" 519.It Li "{bottom-left}" Ta "" Ta "The bottom-left pane" 520.It Li "{bottom-right}" Ta "" Ta "The bottom-right pane" 521.It Li "{up-of}" Ta "" Ta "The pane above the active pane" 522.It Li "{down-of}" Ta "" Ta "The pane below the active pane" 523.It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane" 524.It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane" 525.El 526.Pp 527The tokens 528.Ql + 529and 530.Ql - 531may be followed by an offset, for example: 532.Bd -literal -offset indent 533select-window -t:+2 534.Ed 535.Pp 536In addition, 537.Em target-session , 538.Em target-window 539or 540.Em target-pane 541may consist entirely of the token 542.Ql {mouse} 543(alternative form 544.Ql = ) 545to specify the most recent mouse event 546(see the 547.Sx MOUSE SUPPORT 548section) 549or 550.Ql {marked} 551(alternative form 552.Ql ~ ) 553to specify the marked pane (see 554.Ic select-pane 555.Fl m ) . 556.Pp 557Sessions, window and panes are each numbered with a unique ID; session IDs are 558prefixed with a 559.Ql $ , 560windows with a 561.Ql @ , 562and panes with a 563.Ql % . 564These are unique and are unchanged for the life of the session, window or pane 565in the 566.Nm 567server. 568The pane ID is passed to the child process of the pane in the 569.Ev TMUX_PANE 570environment variable. 571IDs may be displayed using the 572.Ql session_id , 573.Ql window_id , 574or 575.Ql pane_id 576formats (see the 577.Sx FORMATS 578section) and the 579.Ic display-message , 580.Ic list-sessions , 581.Ic list-windows 582or 583.Ic list-panes 584commands. 585.Pp 586.Ar shell-command 587arguments are 588.Xr sh 1 589commands. 590This may be a single argument passed to the shell, for example: 591.Bd -literal -offset indent 592new-window 'vi /etc/passwd' 593.Ed 594.Pp 595Will run: 596.Bd -literal -offset indent 597/bin/sh -c 'vi /etc/passwd' 598.Ed 599.Pp 600Additionally, the 601.Ic new-window , 602.Ic new-session , 603.Ic split-window , 604.Ic respawn-window 605and 606.Ic respawn-pane 607commands allow 608.Ar shell-command 609to be given as multiple arguments and executed directly (without 610.Ql sh -c ) . 611This can avoid issues with shell quoting. 612For example: 613.Bd -literal -offset indent 614$ tmux new-window vi /etc/passwd 615.Ed 616.Pp 617Will run 618.Xr vi 1 619directly without invoking the shell. 620.Pp 621.Ar command 622.Op Ar arguments 623refers to a 624.Nm 625command, passed with the command and arguments separately, for example: 626.Bd -literal -offset indent 627bind-key F1 set-window-option force-width 81 628.Ed 629.Pp 630Or if using 631.Xr sh 1 : 632.Bd -literal -offset indent 633$ tmux bind-key F1 set-window-option force-width 81 634.Ed 635.Pp 636Multiple commands may be specified together as part of a 637.Em command sequence . 638Each command should be separated by spaces and a semicolon; 639commands are executed sequentially from left to right and 640lines ending with a backslash continue on to the next line, 641except when escaped by another backslash. 642A literal semicolon may be included by escaping it with a backslash (for 643example, when specifying a command sequence to 644.Ic bind-key ) . 645.Pp 646Example 647.Nm 648commands include: 649.Bd -literal -offset indent 650refresh-client -t/dev/ttyp2 651 652rename-session -tfirst newname 653 654set-window-option -t:0 monitor-activity on 655 656new-window ; split-window -d 657 658bind-key R source-file ~/.tmux.conf \e; \e 659 display-message "source-file done" 660.Ed 661.Pp 662Or from 663.Xr sh 1 : 664.Bd -literal -offset indent 665$ tmux kill-window -t :1 666 667$ tmux new-window \e; split-window -d 668 669$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach 670.Ed 671.Sh CLIENTS AND SESSIONS 672The 673.Nm 674server manages clients, sessions, windows and panes. 675Clients are attached to sessions to interact with them, either 676when they are created with the 677.Ic new-session 678command, or later with the 679.Ic attach-session 680command. 681Each session has one or more windows 682.Em linked 683into it. 684Windows may be linked to multiple sessions and are made up of one or 685more panes, 686each of which contains a pseudo terminal. 687Commands for creating, linking and otherwise manipulating windows 688are covered 689in the 690.Sx WINDOWS AND PANES 691section. 692.Pp 693The following commands are available to manage clients and sessions: 694.Bl -tag -width Ds 695.It Xo Ic attach-session 696.Op Fl dEr 697.Op Fl c Ar working-directory 698.Op Fl t Ar target-session 699.Xc 700.D1 (alias: Ic attach ) 701If run from outside 702.Nm , 703create a new client in the current terminal and attach it to 704.Ar target-session . 705If used from inside, switch the current client. 706If 707.Fl d 708is specified, any other clients attached to the session are detached. 709.Fl r 710signifies the client is read-only (only keys bound to the 711.Ic detach-client 712or 713.Ic switch-client 714commands have any effect) 715.Pp 716If no server is started, 717.Ic attach-session 718will attempt to start it; this will fail unless sessions are created in the 719configuration file. 720.Pp 721The 722.Ar target-session 723rules for 724.Ic attach-session 725are slightly adjusted: if 726.Nm 727needs to select the most recently used session, it will prefer the most 728recently used 729.Em unattached 730session. 731.Pp 732.Fl c 733will set the session working directory (used for new windows) to 734.Ar working-directory . 735.Pp 736If 737.Fl E 738is used, the 739.Ic update-environment 740option will not be applied. 741.It Xo Ic detach-client 742.Op Fl aP 743.Op Fl E Ar shell-command 744.Op Fl s Ar target-session 745.Op Fl t Ar target-client 746.Xc 747.D1 (alias: Ic detach ) 748Detach the current client if bound to a key, the client specified with 749.Fl t , 750or all clients currently attached to the session specified by 751.Fl s . 752The 753.Fl a 754option kills all but the client given with 755.Fl t . 756If 757.Fl P 758is given, send SIGHUP to the parent process of the client, typically causing it 759to exit. 760With 761.Fl E , 762run 763.Ar shell-command 764to replace the client. 765.It Ic has-session Op Fl t Ar target-session 766.D1 (alias: Ic has ) 767Report an error and exit with 1 if the specified session does not exist. 768If it does exist, exit with 0. 769.It Ic kill-server 770Kill the 771.Nm 772server and clients and destroy all sessions. 773.It Xo Ic kill-session 774.Op Fl aC 775.Op Fl t Ar target-session 776.Xc 777Destroy the given session, closing any windows linked to it and no other 778sessions, and detaching all clients attached to it. 779If 780.Fl a 781is given, all sessions but the specified one is killed. 782The 783.Fl C 784flag clears alerts (bell, activity, or silence) in all windows linked to the 785session. 786.It Xo Ic list-clients 787.Op Fl F Ar format 788.Op Fl t Ar target-session 789.Xc 790.D1 (alias: Ic lsc ) 791List all clients attached to the server. 792For the meaning of the 793.Fl F 794flag, see the 795.Sx FORMATS 796section. 797If 798.Ar target-session 799is specified, list only clients connected to that session. 800.It Xo Ic list-commands 801.Op Fl F Ar format 802.Xc 803.D1 (alias: Ic lscm ) 804List the syntax of all commands supported by 805.Nm . 806.It Ic list-sessions Op Fl F Ar format 807.D1 (alias: Ic ls ) 808List all sessions managed by the server. 809For the meaning of the 810.Fl F 811flag, see the 812.Sx FORMATS 813section. 814.It Ic lock-client Op Fl t Ar target-client 815.D1 (alias: Ic lockc ) 816Lock 817.Ar target-client , 818see the 819.Ic lock-server 820command. 821.It Ic lock-session Op Fl t Ar target-session 822.D1 (alias: Ic locks ) 823Lock all clients attached to 824.Ar target-session . 825.It Xo Ic new-session 826.Op Fl AdDEP 827.Op Fl c Ar start-directory 828.Op Fl F Ar format 829.Op Fl n Ar window-name 830.Op Fl s Ar session-name 831.Op Fl t Ar group-name 832.Op Fl x Ar width 833.Op Fl y Ar height 834.Op Ar shell-command 835.Xc 836.D1 (alias: Ic new ) 837Create a new session with name 838.Ar session-name . 839.Pp 840The new session is attached to the current terminal unless 841.Fl d 842is given. 843.Ar window-name 844and 845.Ar shell-command 846are the name of and shell command to execute in the initial window. 847With 848.Fl d , 849the initial size is 80 x 24; 850.Fl x 851and 852.Fl y 853can be used to specify a different size. 854.Ql - 855uses the size of the current client if any. 856.Pp 857If run from a terminal, any 858.Xr termios 4 859special characters are saved and used for new windows in the new session. 860.Pp 861The 862.Fl A 863flag makes 864.Ic new-session 865behave like 866.Ic attach-session 867if 868.Ar session-name 869already exists; in this case, 870.Fl D 871behaves like 872.Fl d 873to 874.Ic attach-session . 875.Pp 876If 877.Fl t 878is given, it specifies a 879.Ic session group . 880Sessions in the same group share the same set of windows - new windows are 881linked to all sessions in the group and any windows closed removed from all 882sessions. 883The current and previous window and any session options remain independent and 884any session in a group may be killed without affecting the others. 885The 886.Ar group-name 887argument may be: 888.Bl -enum -width Ds 889.It 890the name of an existing group, in which case the new session is added to that 891group; 892.It 893the name of an existing session - the new session is added to the same group 894as that session, creating a new group if necessary; 895.It 896the name for a new group containing only the new session. 897.El 898.Pp 899.Fl n 900and 901.Ar shell-command 902are invalid if 903.Fl t 904is used. 905.Pp 906The 907.Fl P 908option prints information about the new session after it has been created. 909By default, it uses the format 910.Ql #{session_name}: 911but a different format may be specified with 912.Fl F . 913.Pp 914If 915.Fl E 916is used, the 917.Ic update-environment 918option will not be applied. 919.It Xo Ic refresh-client 920.Op Fl cDlLRSU 921.Op Fl C Ar width,height 922.Op Fl t Ar target-client 923.Op Ar adjustment 924.Xc 925.D1 (alias: Ic refresh ) 926Refresh the current client if bound to a key, or a single client if one is given 927with 928.Fl t . 929If 930.Fl S 931is specified, only update the client's status line. 932.Pp 933.Fl C 934sets the width and height of a control client. 935.Fl l 936requests the clipboard from the client using the 937.Xr xterm 1 938escape sequence and stores it in a new paste buffer. 939.Pp 940.Fl L , 941.Fl R , 942.Fl U 943and 944.Fl D 945move the visible portion of the window left, right, up or down 946by 947.Ar adjustment , 948if the window is larger than the client. 949.Fl c 950resets so that the position follows the cursor. 951See the 952.Ic window-size 953option. 954.It Xo Ic rename-session 955.Op Fl t Ar target-session 956.Ar new-name 957.Xc 958.D1 (alias: Ic rename ) 959Rename the session to 960.Ar new-name . 961.It Xo Ic show-messages 962.Op Fl JT 963.Op Fl t Ar target-client 964.Xc 965.D1 (alias: Ic showmsgs ) 966Show client messages or server information. 967Any messages displayed on the status line are saved in a per-client message 968log, up to a maximum of the limit set by the 969.Ar message-limit 970server option. 971With 972.Fl t , 973display the log for 974.Ar target-client . 975.Fl J 976and 977.Fl T 978show debugging information about jobs and terminals. 979.It Xo Ic source-file 980.Op Fl q 981.Ar path 982.Xc 983.D1 (alias: Ic source ) 984Execute commands from 985.Ar path 986(which may be a 987.Xr glob 7 988pattern). 989If 990.Fl q 991is given, no error will be returned if 992.Ar path 993does not exist. 994.Pp 995Within a configuration file, commands may be made conditional by surrounding 996them with 997.Em %if 998and 999.Em %endif 1000lines. 1001Additional 1002.Em %elif 1003and 1004.Em %else 1005lines may also be used. 1006The argument to 1007.Em %if 1008and 1009.Em %elif 1010is expanded as a format and if it evaluates to false (zero or empty), 1011subsequent lines are ignored until the next 1012.Em %elif , 1013.Em %else 1014or 1015.Em %endif . 1016For example: 1017.Bd -literal -offset indent 1018%if #{==:#{host},myhost} 1019set -g status-style bg=red 1020%elif #{==:#{host},myotherhost} 1021set -g status-style bg=green 1022%else 1023set -g status-style bg=blue 1024%endif 1025.Ed 1026.Pp 1027Will change the status line to red if running on 1028.Ql myhost , 1029green if running on 1030.Ql myotherhost , 1031or blue if running on another host. 1032.It Ic start-server 1033.D1 (alias: Ic start ) 1034Start the 1035.Nm 1036server, if not already running, without creating any sessions. 1037.It Xo Ic suspend-client 1038.Op Fl t Ar target-client 1039.Xc 1040.D1 (alias: Ic suspendc ) 1041Suspend a client by sending 1042.Dv SIGTSTP 1043(tty stop). 1044.It Xo Ic switch-client 1045.Op Fl Elnpr 1046.Op Fl c Ar target-client 1047.Op Fl t Ar target-session 1048.Op Fl T Ar key-table 1049.Xc 1050.D1 (alias: Ic switchc ) 1051Switch the current session for client 1052.Ar target-client 1053to 1054.Ar target-session . 1055If 1056.Fl l , 1057.Fl n 1058or 1059.Fl p 1060is used, the client is moved to the last, next or previous session 1061respectively. 1062.Fl r 1063toggles whether a client is read-only (see the 1064.Ic attach-session 1065command). 1066.Pp 1067If 1068.Fl E 1069is used, 1070.Ic update-environment 1071option will not be applied. 1072.Pp 1073.Fl T 1074sets the client's key table; the next key from the client will be interpreted from 1075.Ar key-table . 1076This may be used to configure multiple prefix keys, or to bind commands to 1077sequences of keys. 1078For example, to make typing 1079.Ql abc 1080run the 1081.Ic list-keys 1082command: 1083.Bd -literal -offset indent 1084bind-key -Ttable2 c list-keys 1085bind-key -Ttable1 b switch-client -Ttable2 1086bind-key -Troot a switch-client -Ttable1 1087.Ed 1088.El 1089.Sh WINDOWS AND PANES 1090A 1091.Nm 1092window may be in one of two modes. 1093The default permits direct access to the terminal attached to the window. 1094The other is copy mode, which permits a section of a window or its 1095history to be copied to a 1096.Em paste buffer 1097for later insertion into another window. 1098This mode is entered with the 1099.Ic copy-mode 1100command, bound to 1101.Ql \&[ 1102by default. 1103It is also entered when a command that produces output, such as 1104.Ic list-keys , 1105is executed from a key binding. 1106.Pp 1107Commands are sent to copy mode using the 1108.Fl X 1109flag to the 1110.Ic send-keys 1111command. 1112When a key is pressed, copy mode automatically uses one of two key tables, 1113depending on the 1114.Ic mode-keys 1115option: 1116.Ic copy-mode 1117for emacs, or 1118.Ic copy-mode-vi 1119for vi. 1120Key tables may be viewed with the 1121.Ic list-keys 1122command. 1123.Pp 1124The following commands are supported in copy mode: 1125.Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent 1126.It Sy "Command" Ta Sy "vi" Ta Sy "emacs" 1127.It Li "append-selection" Ta "" Ta "" 1128.It Li "append-selection-and-cancel" Ta "A" Ta "" 1129.It Li "back-to-indentation" Ta "^" Ta "M-m" 1130.It Li "begin-selection" Ta "Space" Ta "C-Space" 1131.It Li "bottom-line" Ta "L" Ta "" 1132.It Li "cancel" Ta "q" Ta "Escape" 1133.It Li "clear-selection" Ta "Escape" Ta "C-g" 1134.It Li "copy-end-of-line" Ta "D" Ta "C-k" 1135.It Li "copy-line" Ta "" Ta "" 1136.It Li "copy-pipe <command>" Ta "" Ta "" 1137.It Li "copy-pipe-and-cancel <command>" Ta "" Ta "" 1138.It Li "copy-selection" Ta "" Ta "" 1139.It Li "copy-selection-and-cancel" Ta "Enter" Ta "M-w" 1140.It Li "cursor-down" Ta "j" Ta "Down" 1141.It Li "cursor-left" Ta "h" Ta "Left" 1142.It Li "cursor-right" Ta "l" Ta "Right" 1143.It Li "cursor-up" Ta "k" Ta "Up" 1144.It Li "end-of-line" Ta "$" Ta "C-e" 1145.It Li "goto-line <line>" Ta ":" Ta "g" 1146.It Li "halfpage-down" Ta "C-d" Ta "M-Down" 1147.It Li "halfpage-down-and-cancel" Ta "" Ta "" 1148.It Li "halfpage-up" Ta "C-u" Ta "M-Up" 1149.It Li "history-bottom" Ta "G" Ta "M->" 1150.It Li "history-top" Ta "g" Ta "M-<" 1151.It Li "jump-again" Ta ";" Ta ";" 1152.It Li "jump-backward <to>" Ta "F" Ta "F" 1153.It Li "jump-forward <to>" Ta "f" Ta "f" 1154.It Li "jump-reverse" Ta "," Ta "," 1155.It Li "jump-to-backward <to>" Ta "T" Ta "" 1156.It Li "jump-to-forward <to>" Ta "t" Ta "" 1157.It Li "middle-line" Ta "M" Ta "M-r" 1158.It Li "next-paragraph" Ta "}" Ta "M-}" 1159.It Li "next-space" Ta "W" Ta "" 1160.It Li "next-space-end" Ta "E" Ta "" 1161.It Li "next-word" Ta "w" Ta "" 1162.It Li "next-word-end" Ta "e" Ta "M-f" 1163.It Li "other-end" Ta "o" Ta "" 1164.It Li "page-down" Ta "C-f" Ta "PageDown" 1165.It Li "page-down-and-cancel" Ta "" Ta "" 1166.It Li "page-up" Ta "C-b" Ta "PageUp" 1167.It Li "previous-paragraph" Ta "{" Ta "M-{" 1168.It Li "previous-space" Ta "B" Ta "" 1169.It Li "previous-word" Ta "b" Ta "M-b" 1170.It Li "rectangle-toggle" Ta "v" Ta "R" 1171.It Li "scroll-down" Ta "C-e" Ta "C-Down" 1172.It Li "scroll-down-and-cancel" Ta "" Ta "" 1173.It Li "scroll-up" Ta "C-y" Ta "C-Up" 1174.It Li "search-again" Ta "n" Ta "n" 1175.It Li "search-backward <for>" Ta "?" Ta "" 1176.It Li "search-forward <for>" Ta "/" Ta "" 1177.It Li "search-backward-incremental <for>" Ta "" Ta "C-r" 1178.It Li "search-forward-incremental <for>" Ta "" Ta "C-s" 1179.It Li "search-reverse" Ta "N" Ta "N" 1180.It Li "select-line" Ta "V" Ta "" 1181.It Li "start-of-line" Ta "0" Ta "C-a" 1182.It Li "stop-selection" Ta "" Ta "" 1183.It Li "top-line" Ta "H" Ta "M-R" 1184.El 1185.Pp 1186The 1187.Ql -and-cancel 1188variants of some commands exit copy mode after they have completed (for copy 1189commands) or when the cursor reaches the bottom (for scrolling commands). 1190.Pp 1191The next and previous word keys use space and the 1192.Ql - , 1193.Ql _ 1194and 1195.Ql @ 1196characters as word delimiters by default, but this can be adjusted by 1197setting the 1198.Em word-separators 1199session option. 1200Next word moves to the start of the next word, next word end to the end of the 1201next word and previous word to the start of the previous word. 1202The three next and previous space keys work similarly but use a space alone as 1203the word separator. 1204.Pp 1205The jump commands enable quick movement within a line. 1206For instance, typing 1207.Ql f 1208followed by 1209.Ql / 1210will move the cursor to the next 1211.Ql / 1212character on the current line. 1213A 1214.Ql \&; 1215will then jump to the next occurrence. 1216.Pp 1217Commands in copy mode may be prefaced by an optional repeat count. 1218With vi key bindings, a prefix is entered using the number keys; with 1219emacs, the Alt (meta) key and a number begins prefix entry. 1220.Pp 1221The synopsis for the 1222.Ic copy-mode 1223command is: 1224.Bl -tag -width Ds 1225.It Xo Ic copy-mode 1226.Op Fl Meu 1227.Op Fl t Ar target-pane 1228.Xc 1229Enter copy mode. 1230The 1231.Fl u 1232option scrolls one page up. 1233.Fl M 1234begins a mouse drag (only valid if bound to a mouse key binding, see 1235.Sx MOUSE SUPPORT ) . 1236.Fl e 1237specifies that scrolling to the bottom of the history (to the visible screen) 1238should exit copy mode. 1239While in copy mode, pressing a key other than those used for scrolling will 1240disable this behaviour. 1241This is intended to allow fast scrolling through a pane's history, for 1242example with: 1243.Bd -literal -offset indent 1244bind PageUp copy-mode -eu 1245.Ed 1246.El 1247.Pp 1248Each window displayed by 1249.Nm 1250may be split into one or more 1251.Em panes ; 1252each pane takes up a certain area of the display and is a separate terminal. 1253A window may be split into panes using the 1254.Ic split-window 1255command. 1256Windows may be split horizontally (with the 1257.Fl h 1258flag) or vertically. 1259Panes may be resized with the 1260.Ic resize-pane 1261command (bound to 1262.Ql C-Up , 1263.Ql C-Down 1264.Ql C-Left 1265and 1266.Ql C-Right 1267by default), the current pane may be changed with the 1268.Ic select-pane 1269command and the 1270.Ic rotate-window 1271and 1272.Ic swap-pane 1273commands may be used to swap panes without changing their position. 1274Panes are numbered beginning from zero in the order they are created. 1275.Pp 1276A number of preset 1277.Em layouts 1278are available. 1279These may be selected with the 1280.Ic select-layout 1281command or cycled with 1282.Ic next-layout 1283(bound to 1284.Ql Space 1285by default); once a layout is chosen, panes within it may be moved and resized 1286as normal. 1287.Pp 1288The following layouts are supported: 1289.Bl -tag -width Ds 1290.It Ic even-horizontal 1291Panes are spread out evenly from left to right across the window. 1292.It Ic even-vertical 1293Panes are spread evenly from top to bottom. 1294.It Ic main-horizontal 1295A large (main) pane is shown at the top of the window and the remaining panes 1296are spread from left to right in the leftover space at the bottom. 1297Use the 1298.Em main-pane-height 1299window option to specify the height of the top pane. 1300.It Ic main-vertical 1301Similar to 1302.Ic main-horizontal 1303but the large pane is placed on the left and the others spread from top to 1304bottom along the right. 1305See the 1306.Em main-pane-width 1307window option. 1308.It Ic tiled 1309Panes are spread out as evenly as possible over the window in both rows and 1310columns. 1311.El 1312.Pp 1313In addition, 1314.Ic select-layout 1315may be used to apply a previously used layout - the 1316.Ic list-windows 1317command displays the layout of each window in a form suitable for use with 1318.Ic select-layout . 1319For example: 1320.Bd -literal -offset indent 1321$ tmux list-windows 13220: ksh [159x48] 1323 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} 1324$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} 1325.Ed 1326.Pp 1327.Nm 1328automatically adjusts the size of the layout for the current window size. 1329Note that a layout cannot be applied to a window with more panes than that 1330from which the layout was originally defined. 1331.Pp 1332Commands related to windows and panes are as follows: 1333.Bl -tag -width Ds 1334.It Xo Ic break-pane 1335.Op Fl dP 1336.Op Fl F Ar format 1337.Op Fl n Ar window-name 1338.Op Fl s Ar src-pane 1339.Op Fl t Ar dst-window 1340.Xc 1341.D1 (alias: Ic breakp ) 1342Break 1343.Ar src-pane 1344off from its containing window to make it the only pane in 1345.Ar dst-window . 1346If 1347.Fl d 1348is given, the new window does not become the current window. 1349The 1350.Fl P 1351option prints information about the new window after it has been created. 1352By default, it uses the format 1353.Ql #{session_name}:#{window_index} 1354but a different format may be specified with 1355.Fl F . 1356.It Xo Ic capture-pane 1357.Op Fl aepPqCJ 1358.Op Fl b Ar buffer-name 1359.Op Fl E Ar end-line 1360.Op Fl S Ar start-line 1361.Op Fl t Ar target-pane 1362.Xc 1363.D1 (alias: Ic capturep ) 1364Capture the contents of a pane. 1365If 1366.Fl p 1367is given, the output goes to stdout, otherwise to the buffer specified with 1368.Fl b 1369or a new buffer if omitted. 1370If 1371.Fl a 1372is given, the alternate screen is used, and the history is not accessible. 1373If no alternate screen exists, an error will be returned unless 1374.Fl q 1375is given. 1376If 1377.Fl e 1378is given, the output includes escape sequences for text and background 1379attributes. 1380.Fl C 1381also escapes non-printable characters as octal \exxx. 1382.Fl J 1383joins wrapped lines and preserves trailing spaces at each line's end. 1384.Fl P 1385captures only any output that the pane has received that is the beginning of an 1386as-yet incomplete escape sequence. 1387.Pp 1388.Fl S 1389and 1390.Fl E 1391specify the starting and ending line numbers, zero is the first line of the 1392visible pane and negative numbers are lines in the history. 1393.Ql - 1394to 1395.Fl S 1396is the start of the history and to 1397.Fl E 1398the end of the visible pane. 1399The default is to capture only the visible contents of the pane. 1400.It Xo 1401.Ic choose-client 1402.Op Fl NZ 1403.Op Fl F Ar format 1404.Op Fl f Ar filter 1405.Op Fl O Ar sort-order 1406.Op Fl t Ar target-pane 1407.Op Ar template 1408.Xc 1409Put a pane into client mode, allowing a client to be selected interactively from 1410a list. 1411.Fl Z 1412zooms the pane. 1413The following keys may be used in client mode: 1414.Bl -column "Key" "Function" -offset indent 1415.It Sy "Key" Ta Sy "Function" 1416.It Li "Enter" Ta "Choose selected client" 1417.It Li "Up" Ta "Select previous client" 1418.It Li "Down" Ta "Select next client" 1419.It Li "C-s" Ta "Search by name" 1420.It Li "n" Ta "Repeat last search" 1421.It Li "t" Ta "Toggle if client is tagged" 1422.It Li "T" Ta "Tag no clients" 1423.It Li "C-t" Ta "Tag all clients" 1424.It Li "d" Ta "Detach selected client" 1425.It Li "D" Ta "Detach tagged clients" 1426.It Li "x" Ta "Detach and HUP selected client" 1427.It Li "X" Ta "Detach and HUP tagged clients" 1428.It Li "z" Ta "Suspend selected client" 1429.It Li "Z" Ta "Suspend tagged clients" 1430.It Li "f" Ta "Enter a format to filter items" 1431.It Li "O" Ta "Change sort order" 1432.It Li "v" Ta "Toggle preview" 1433.It Li "q" Ta "Exit mode" 1434.El 1435.Pp 1436After a client is chosen, 1437.Ql %% 1438is replaced by the client name in 1439.Ar template 1440and the result executed as a command. 1441If 1442.Ar template 1443is not given, "detach-client -t '%%'" is used. 1444.Pp 1445.Fl O 1446specifies the initial sort order: one of 1447.Ql name , 1448.Ql size , 1449.Ql creation , 1450or 1451.Ql activity . 1452.Fl f 1453specifies an initial filter: the filter is a format - if it evaluates to zero, 1454the item in the list is not shown, otherwise it is shown. 1455If a filter would lead to an empty list, it is ignored. 1456.Fl F 1457specifies the format for each item in the list. 1458.Fl N 1459starts without the preview. 1460This command works only if at least one client is attached. 1461.It Xo 1462.Ic choose-tree 1463.Op Fl GNswZ 1464.Op Fl F Ar format 1465.Op Fl f Ar filter 1466.Op Fl O Ar sort-order 1467.Op Fl t Ar target-pane 1468.Op Ar template 1469.Xc 1470Put a pane into tree mode, where a session, window or pane may be chosen 1471interactively from a list. 1472.Fl s 1473starts with sessions collapsed and 1474.Fl w 1475with windows collapsed. 1476.Fl Z 1477zooms the pane. 1478The following keys may be used in tree mode: 1479.Bl -column "Key" "Function" -offset indent 1480.It Sy "Key" Ta Sy "Function" 1481.It Li "Enter" Ta "Choose selected item" 1482.It Li "Up" Ta "Select previous item" 1483.It Li "Down" Ta "Select next item" 1484.It Li "x" Ta "Kill selected item" 1485.It Li "X" Ta "Kill tagged items" 1486.It Li "<" Ta "Scroll list of previews left" 1487.It Li ">" Ta "Scroll list of previews right" 1488.It Li "C-s" Ta "Search by name" 1489.It Li "n" Ta "Repeat last search" 1490.It Li "t" Ta "Toggle if item is tagged" 1491.It Li "T" Ta "Tag no items" 1492.It Li "C-t" Ta "Tag all items" 1493.It Li "\&:" Ta "Run a command for each tagged item" 1494.It Li "f" Ta "Enter a format to filter items" 1495.It Li "O" Ta "Change sort order" 1496.It Li "v" Ta "Toggle preview" 1497.It Li "q" Ta "Exit mode" 1498.El 1499.Pp 1500After a session, window or pane is chosen, 1501.Ql %% 1502is replaced by the target in 1503.Ar template 1504and the result executed as a command. 1505If 1506.Ar template 1507is not given, "switch-client -t '%%'" is used. 1508.Pp 1509.Fl O 1510specifies the initial sort order: one of 1511.Ql index , 1512.Ql name , 1513or 1514.Ql time . 1515.Fl f 1516specifies an initial filter: the filter is a format - if it evaluates to zero, 1517the item in the list is not shown, otherwise it is shown. 1518If a filter would lead to an empty list, it is ignored. 1519.Fl F 1520specifies the format for each item in the tree. 1521.Fl N 1522starts without the preview. 1523.Fl G 1524includes all sessions in any session groups in the tree rather than only the 1525first. 1526This command works only if at least one client is attached. 1527.It Xo 1528.Ic display-panes 1529.Op Fl d Ar duration 1530.Op Fl t Ar target-client 1531.Op Ar template 1532.Xc 1533.D1 (alias: Ic displayp ) 1534Display a visible indicator of each pane shown by 1535.Ar target-client . 1536See the 1537.Ic display-panes-colour 1538and 1539.Ic display-panes-active-colour 1540session options. 1541The indicator is closed when a key is pressed or 1542.Ar duration 1543milliseconds have passed. 1544If 1545.Fl d 1546is not given, 1547.Ic display-panes-time 1548is used. 1549A duration of zero means the indicator stays until a key is pressed. 1550While the indicator is on screen, a pane may be chosen with the 1551.Ql 0 1552to 1553.Ql 9 1554keys, which will cause 1555.Ar template 1556to be executed as a command with 1557.Ql %% 1558substituted by the pane ID. 1559The default 1560.Ar template 1561is "select-pane -t '%%'". 1562.It Xo Ic find-window 1563.Op Fl CNTZ 1564.Op Fl t Ar target-pane 1565.Ar match-string 1566.Xc 1567.D1 (alias: Ic findw ) 1568Search for the 1569.Xr fnmatch 3 1570pattern 1571.Ar match-string 1572in window names, titles, and visible content (but not history). 1573The flags control matching behavior: 1574.Fl C 1575matches only visible window contents, 1576.Fl N 1577matches only the window name and 1578.Fl T 1579matches only the window title. 1580The default is 1581.Fl CNT . 1582.Fl Z 1583zooms the pane. 1584.Pp 1585This command works only if at least one client is attached. 1586.It Xo Ic join-pane 1587.Op Fl bdhv 1588.Oo Fl l 1589.Ar size | 1590.Fl p Ar percentage Oc 1591.Op Fl s Ar src-pane 1592.Op Fl t Ar dst-pane 1593.Xc 1594.D1 (alias: Ic joinp ) 1595Like 1596.Ic split-window , 1597but instead of splitting 1598.Ar dst-pane 1599and creating a new pane, split it and move 1600.Ar src-pane 1601into the space. 1602This can be used to reverse 1603.Ic break-pane . 1604The 1605.Fl b 1606option causes 1607.Ar src-pane 1608to be joined to left of or above 1609.Ar dst-pane . 1610.Pp 1611If 1612.Fl s 1613is omitted and a marked pane is present (see 1614.Ic select-pane 1615.Fl m ) , 1616the marked pane is used rather than the current pane. 1617.It Xo Ic kill-pane 1618.Op Fl a 1619.Op Fl t Ar target-pane 1620.Xc 1621.D1 (alias: Ic killp ) 1622Destroy the given pane. 1623If no panes remain in the containing window, it is also destroyed. 1624The 1625.Fl a 1626option kills all but the pane given with 1627.Fl t . 1628.It Xo Ic kill-window 1629.Op Fl a 1630.Op Fl t Ar target-window 1631.Xc 1632.D1 (alias: Ic killw ) 1633Kill the current window or the window at 1634.Ar target-window , 1635removing it from any sessions to which it is linked. 1636The 1637.Fl a 1638option kills all but the window given with 1639.Fl t . 1640.It Xo Ic last-pane 1641.Op Fl de 1642.Op Fl t Ar target-window 1643.Xc 1644.D1 (alias: Ic lastp ) 1645Select the last (previously selected) pane. 1646.Fl e 1647enables or 1648.Fl d 1649disables input to the pane. 1650.It Ic last-window Op Fl t Ar target-session 1651.D1 (alias: Ic last ) 1652Select the last (previously selected) window. 1653If no 1654.Ar target-session 1655is specified, select the last window of the current session. 1656.It Xo Ic link-window 1657.Op Fl adk 1658.Op Fl s Ar src-window 1659.Op Fl t Ar dst-window 1660.Xc 1661.D1 (alias: Ic linkw ) 1662Link the window at 1663.Ar src-window 1664to the specified 1665.Ar dst-window . 1666If 1667.Ar dst-window 1668is specified and no such window exists, the 1669.Ar src-window 1670is linked there. 1671With 1672.Fl a , 1673the window is moved to the next index up (following windows 1674are moved if necessary). 1675If 1676.Fl k 1677is given and 1678.Ar dst-window 1679exists, it is killed, otherwise an error is generated. 1680If 1681.Fl d 1682is given, the newly linked window is not selected. 1683.It Xo Ic list-panes 1684.Op Fl as 1685.Op Fl F Ar format 1686.Op Fl t Ar target 1687.Xc 1688.D1 (alias: Ic lsp ) 1689If 1690.Fl a 1691is given, 1692.Ar target 1693is ignored and all panes on the server are listed. 1694If 1695.Fl s 1696is given, 1697.Ar target 1698is a session (or the current session). 1699If neither is given, 1700.Ar target 1701is a window (or the current window). 1702For the meaning of the 1703.Fl F 1704flag, see the 1705.Sx FORMATS 1706section. 1707.It Xo Ic list-windows 1708.Op Fl a 1709.Op Fl F Ar format 1710.Op Fl t Ar target-session 1711.Xc 1712.D1 (alias: Ic lsw ) 1713If 1714.Fl a 1715is given, list all windows on the server. 1716Otherwise, list windows in the current session or in 1717.Ar target-session . 1718For the meaning of the 1719.Fl F 1720flag, see the 1721.Sx FORMATS 1722section. 1723.It Xo Ic move-pane 1724.Op Fl bdhv 1725.Oo Fl l 1726.Ar size | 1727.Fl p Ar percentage Oc 1728.Op Fl s Ar src-pane 1729.Op Fl t Ar dst-pane 1730.Xc 1731.D1 (alias: Ic movep ) 1732Like 1733.Ic join-pane , 1734but 1735.Ar src-pane 1736and 1737.Ar dst-pane 1738may belong to the same window. 1739.It Xo Ic move-window 1740.Op Fl ardk 1741.Op Fl s Ar src-window 1742.Op Fl t Ar dst-window 1743.Xc 1744.D1 (alias: Ic movew ) 1745This is similar to 1746.Ic link-window , 1747except the window at 1748.Ar src-window 1749is moved to 1750.Ar dst-window . 1751With 1752.Fl r , 1753all windows in the session are renumbered in sequential order, respecting 1754the 1755.Ic base-index 1756option. 1757.It Xo Ic new-window 1758.Op Fl adkP 1759.Op Fl c Ar start-directory 1760.Op Fl F Ar format 1761.Op Fl n Ar window-name 1762.Op Fl t Ar target-window 1763.Op Ar shell-command 1764.Xc 1765.D1 (alias: Ic neww ) 1766Create a new window. 1767With 1768.Fl a , 1769the new window is inserted at the next index up from the specified 1770.Ar target-window , 1771moving windows up if necessary, 1772otherwise 1773.Ar target-window 1774is the new window location. 1775.Pp 1776If 1777.Fl d 1778is given, the session does not make the new window the current window. 1779.Ar target-window 1780represents the window to be created; if the target already exists an error is 1781shown, unless the 1782.Fl k 1783flag is used, in which case it is destroyed. 1784.Ar shell-command 1785is the command to execute. 1786If 1787.Ar shell-command 1788is not specified, the value of the 1789.Ic default-command 1790option is used. 1791.Fl c 1792specifies the working directory in which the new window is created. 1793.Pp 1794When the shell command completes, the window closes. 1795See the 1796.Ic remain-on-exit 1797option to change this behaviour. 1798.Pp 1799The 1800.Ev TERM 1801environment variable must be set to 1802.Ql screen 1803or 1804.Ql tmux 1805for all programs running 1806.Em inside 1807.Nm . 1808New windows will automatically have 1809.Ql TERM=screen 1810added to their environment, but care must be taken not to reset this in shell 1811start-up files. 1812.Pp 1813The 1814.Fl P 1815option prints information about the new window after it has been created. 1816By default, it uses the format 1817.Ql #{session_name}:#{window_index} 1818but a different format may be specified with 1819.Fl F . 1820.It Ic next-layout Op Fl t Ar target-window 1821.D1 (alias: Ic nextl ) 1822Move a window to the next layout and rearrange the panes to fit. 1823.It Xo Ic next-window 1824.Op Fl a 1825.Op Fl t Ar target-session 1826.Xc 1827.D1 (alias: Ic next ) 1828Move to the next window in the session. 1829If 1830.Fl a 1831is used, move to the next window with an alert. 1832.It Xo Ic pipe-pane 1833.Op Fl IOo 1834.Op Fl t Ar target-pane 1835.Op Ar shell-command 1836.Xc 1837.D1 (alias: Ic pipep ) 1838Pipe output sent by the program in 1839.Ar target-pane 1840to a shell command or vice versa. 1841A pane may only be connected to one command at a time, any existing pipe is 1842closed before 1843.Ar shell-command 1844is executed. 1845The 1846.Ar shell-command 1847string may contain the special character sequences supported by the 1848.Ic status-left 1849option. 1850If no 1851.Ar shell-command 1852is given, the current pipe (if any) is closed. 1853.Pp 1854.Fl I 1855and 1856.Fl O 1857specify which of the 1858.Ar shell-command 1859output streams are connected to the pane: 1860with 1861.Fl I 1862stdout is connected (so anything 1863.Ar shell-command 1864prints is written to the pane as if it were typed); 1865with 1866.Fl O 1867stdin is connected (so any output in the pane is piped to 1868.Ar shell-command ) . 1869Both may be used together and if neither are specified, 1870.Fl O 1871is used. 1872.Pp 1873The 1874.Fl o 1875option only opens a new pipe if no previous pipe exists, allowing a pipe to 1876be toggled with a single key, for example: 1877.Bd -literal -offset indent 1878bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' 1879.Ed 1880.It Xo Ic previous-layout 1881.Op Fl t Ar target-window 1882.Xc 1883.D1 (alias: Ic prevl ) 1884Move to the previous layout in the session. 1885.It Xo Ic previous-window 1886.Op Fl a 1887.Op Fl t Ar target-session 1888.Xc 1889.D1 (alias: Ic prev ) 1890Move to the previous window in the session. 1891With 1892.Fl a , 1893move to the previous window with an alert. 1894.It Xo Ic rename-window 1895.Op Fl t Ar target-window 1896.Ar new-name 1897.Xc 1898.D1 (alias: Ic renamew ) 1899Rename the current window, or the window at 1900.Ar target-window 1901if specified, to 1902.Ar new-name . 1903.It Xo Ic resize-pane 1904.Op Fl DLMRUZ 1905.Op Fl t Ar target-pane 1906.Op Fl x Ar width 1907.Op Fl y Ar height 1908.Op Ar adjustment 1909.Xc 1910.D1 (alias: Ic resizep ) 1911Resize a pane, up, down, left or right by 1912.Ar adjustment 1913with 1914.Fl U , 1915.Fl D , 1916.Fl L 1917or 1918.Fl R , 1919or 1920to an absolute size 1921with 1922.Fl x 1923or 1924.Fl y . 1925The 1926.Ar adjustment 1927is given in lines or cells (the default is 1). 1928.Pp 1929With 1930.Fl Z , 1931the active pane is toggled between zoomed (occupying the whole of the window) 1932and unzoomed (its normal position in the layout). 1933.Pp 1934.Fl M 1935begins mouse resizing (only valid if bound to a mouse key binding, see 1936.Sx MOUSE SUPPORT ) . 1937.It Xo Ic respawn-pane 1938.Op Fl c Ar start-directory 1939.Op Fl k 1940.Op Fl t Ar target-pane 1941.Op Ar shell-command 1942.Xc 1943.D1 (alias: Ic respawnp ) 1944Reactivate a pane in which the command has exited (see the 1945.Ic remain-on-exit 1946window option). 1947If 1948.Ar shell-command 1949is not given, the command used when the pane was created is executed. 1950The pane must be already inactive, unless 1951.Fl k 1952is given, in which case any existing command is killed. 1953.Fl c 1954specifies a new working directory for the pane. 1955.It Xo Ic respawn-window 1956.Op Fl c Ar start-directory 1957.Op Fl k 1958.Op Fl t Ar target-window 1959.Op Ar shell-command 1960.Xc 1961.D1 (alias: Ic respawnw ) 1962Reactivate a window in which the command has exited (see the 1963.Ic remain-on-exit 1964window option). 1965If 1966.Ar shell-command 1967is not given, the command used when the window was created is executed. 1968The window must be already inactive, unless 1969.Fl k 1970is given, in which case any existing command is killed. 1971.Fl c 1972specifies a new working directory for the window. 1973.It Xo Ic rotate-window 1974.Op Fl DU 1975.Op Fl t Ar target-window 1976.Xc 1977.D1 (alias: Ic rotatew ) 1978Rotate the positions of the panes within a window, either upward (numerically 1979lower) with 1980.Fl U 1981or downward (numerically higher). 1982.It Xo Ic select-layout 1983.Op Fl Enop 1984.Op Fl t Ar target-pane 1985.Op Ar layout-name 1986.Xc 1987.D1 (alias: Ic selectl ) 1988Choose a specific layout for a window. 1989If 1990.Ar layout-name 1991is not given, the last preset layout used (if any) is reapplied. 1992.Fl n 1993and 1994.Fl p 1995are equivalent to the 1996.Ic next-layout 1997and 1998.Ic previous-layout 1999commands. 2000.Fl o 2001applies the last set layout if possible (undoes the most recent layout change). 2002.Fl E 2003spreads the current pane and any panes next to it out evenly. 2004.It Xo Ic select-pane 2005.Op Fl DdegLlMmRU 2006.Op Fl P Ar style 2007.Op Fl T Ar title 2008.Op Fl t Ar target-pane 2009.Xc 2010.D1 (alias: Ic selectp ) 2011Make pane 2012.Ar target-pane 2013the active pane in window 2014.Ar target-window , 2015or set its style (with 2016.Fl P ) . 2017If one of 2018.Fl D , 2019.Fl L , 2020.Fl R , 2021or 2022.Fl U 2023is used, respectively the pane below, to the left, to the right, or above the 2024target pane is used. 2025.Fl l 2026is the same as using the 2027.Ic last-pane 2028command. 2029.Fl e 2030enables or 2031.Fl d 2032disables input to the pane. 2033.Pp 2034.Fl m 2035and 2036.Fl M 2037are used to set and clear the 2038.Em marked pane . 2039There is one marked pane at a time, setting a new marked pane clears the last. 2040The marked pane is the default target for 2041.Fl s 2042to 2043.Ic join-pane , 2044.Ic swap-pane 2045and 2046.Ic swap-window . 2047.Pp 2048Each pane has a style: by default the 2049.Ic window-style 2050and 2051.Ic window-active-style 2052options are used, 2053.Ic select-pane 2054.Fl P 2055sets the style for a single pane. 2056For example, to set the pane 1 background to red: 2057.Bd -literal -offset indent 2058select-pane -t:.1 -P 'bg=red' 2059.Ed 2060.Pp 2061.Fl g 2062shows the current pane style. 2063.Pp 2064.Fl T 2065sets the pane title. 2066.It Xo Ic select-window 2067.Op Fl lnpT 2068.Op Fl t Ar target-window 2069.Xc 2070.D1 (alias: Ic selectw ) 2071Select the window at 2072.Ar target-window . 2073.Fl l , 2074.Fl n 2075and 2076.Fl p 2077are equivalent to the 2078.Ic last-window , 2079.Ic next-window 2080and 2081.Ic previous-window 2082commands. 2083If 2084.Fl T 2085is given and the selected window is already the current window, 2086the command behaves like 2087.Ic last-window . 2088.It Xo Ic split-window 2089.Op Fl bdfhvP 2090.Op Fl c Ar start-directory 2091.Oo Fl l 2092.Ar size | 2093.Fl p Ar percentage Oc 2094.Op Fl t Ar target-pane 2095.Op Ar shell-command 2096.Op Fl F Ar format 2097.Xc 2098.D1 (alias: Ic splitw ) 2099Create a new pane by splitting 2100.Ar target-pane : 2101.Fl h 2102does a horizontal split and 2103.Fl v 2104a vertical split; if neither is specified, 2105.Fl v 2106is assumed. 2107The 2108.Fl l 2109and 2110.Fl p 2111options specify the size of the new pane in lines (for vertical split) or in 2112cells (for horizontal split), or as a percentage, respectively. 2113The 2114.Fl b 2115option causes the new pane to be created to the left of or above 2116.Ar target-pane . 2117The 2118.Fl f 2119option creates a new pane spanning the full window height (with 2120.Fl h ) 2121or full window width (with 2122.Fl v ) , 2123instead of splitting the active pane. 2124All other options have the same meaning as for the 2125.Ic new-window 2126command. 2127.It Xo Ic swap-pane 2128.Op Fl dDU 2129.Op Fl s Ar src-pane 2130.Op Fl t Ar dst-pane 2131.Xc 2132.D1 (alias: Ic swapp ) 2133Swap two panes. 2134If 2135.Fl U 2136is used and no source pane is specified with 2137.Fl s , 2138.Ar dst-pane 2139is swapped with the previous pane (before it numerically); 2140.Fl D 2141swaps with the next pane (after it numerically). 2142.Fl d 2143instructs 2144.Nm 2145not to change the active pane. 2146.Pp 2147If 2148.Fl s 2149is omitted and a marked pane is present (see 2150.Ic select-pane 2151.Fl m ) , 2152the marked pane is used rather than the current pane. 2153.It Xo Ic swap-window 2154.Op Fl d 2155.Op Fl s Ar src-window 2156.Op Fl t Ar dst-window 2157.Xc 2158.D1 (alias: Ic swapw ) 2159This is similar to 2160.Ic link-window , 2161except the source and destination windows are swapped. 2162It is an error if no window exists at 2163.Ar src-window . 2164.Pp 2165Like 2166.Ic swap-pane , 2167if 2168.Fl s 2169is omitted and a marked pane is present (see 2170.Ic select-pane 2171.Fl m ) , 2172the window containing the marked pane is used rather than the current window. 2173.It Xo Ic unlink-window 2174.Op Fl k 2175.Op Fl t Ar target-window 2176.Xc 2177.D1 (alias: Ic unlinkw ) 2178Unlink 2179.Ar target-window . 2180Unless 2181.Fl k 2182is given, a window may be unlinked only if it is linked to multiple sessions - 2183windows may not be linked to no sessions; 2184if 2185.Fl k 2186is specified and the window is linked to only one session, it is unlinked and 2187destroyed. 2188.El 2189.Sh KEY BINDINGS 2190.Nm 2191allows a command to be bound to most keys, with or without a prefix key. 2192When specifying keys, most represent themselves (for example 2193.Ql A 2194to 2195.Ql Z ) . 2196Ctrl keys may be prefixed with 2197.Ql C- 2198or 2199.Ql ^ , 2200and Alt (meta) with 2201.Ql M- . 2202In addition, the following special key names are accepted: 2203.Em Up , 2204.Em Down , 2205.Em Left , 2206.Em Right , 2207.Em BSpace , 2208.Em BTab , 2209.Em DC 2210(Delete), 2211.Em End , 2212.Em Enter , 2213.Em Escape , 2214.Em F1 2215to 2216.Em F12 , 2217.Em Home , 2218.Em IC 2219(Insert), 2220.Em NPage/PageDown/PgDn , 2221.Em PPage/PageUp/PgUp , 2222.Em Space , 2223and 2224.Em Tab . 2225Note that to bind the 2226.Ql \&" 2227or 2228.Ql ' 2229keys, quotation marks are necessary, for example: 2230.Bd -literal -offset indent 2231bind-key '"' split-window 2232bind-key "'" new-window 2233.Ed 2234.Pp 2235Commands related to key bindings are as follows: 2236.Bl -tag -width Ds 2237.It Xo Ic bind-key 2238.Op Fl nr 2239.Op Fl T Ar key-table 2240.Ar key Ar command Op Ar arguments 2241.Xc 2242.D1 (alias: Ic bind ) 2243Bind key 2244.Ar key 2245to 2246.Ar command . 2247Keys are bound in a key table. 2248By default (without -T), the key is bound in 2249the 2250.Em prefix 2251key table. 2252This table is used for keys pressed after the prefix key (for example, 2253by default 2254.Ql c 2255is bound to 2256.Ic new-window 2257in the 2258.Em prefix 2259table, so 2260.Ql C-b c 2261creates a new window). 2262The 2263.Em root 2264table is used for keys pressed without the prefix key: binding 2265.Ql c 2266to 2267.Ic new-window 2268in the 2269.Em root 2270table (not recommended) means a plain 2271.Ql c 2272will create a new window. 2273.Fl n 2274is an alias 2275for 2276.Fl T Ar root . 2277Keys may also be bound in custom key tables and the 2278.Ic switch-client 2279.Fl T 2280command used to switch to them from a key binding. 2281The 2282.Fl r 2283flag indicates this key may repeat, see the 2284.Ic repeat-time 2285option. 2286.Pp 2287To view the default bindings and possible commands, see the 2288.Ic list-keys 2289command. 2290.It Xo Ic list-keys 2291.Op Fl T Ar key-table 2292.Xc 2293.D1 (alias: Ic lsk ) 2294List all key bindings. 2295Without 2296.Fl T 2297all key tables are printed. 2298With 2299.Fl T 2300only 2301.Ar key-table . 2302.It Xo Ic send-keys 2303.Op Fl lMRX 2304.Op Fl N Ar repeat-count 2305.Op Fl t Ar target-pane 2306.Ar key Ar ... 2307.Xc 2308.D1 (alias: Ic send ) 2309Send a key or keys to a window. 2310Each argument 2311.Ar key 2312is the name of the key (such as 2313.Ql C-a 2314or 2315.Ql NPage ) 2316to send; if the string is not recognised as a key, it is sent as a series of 2317characters. 2318The 2319.Fl l 2320flag disables key name lookup and sends the keys literally. 2321All arguments are sent sequentially from first to last. 2322The 2323.Fl R 2324flag causes the terminal state to be reset. 2325.Pp 2326.Fl M 2327passes through a mouse event (only valid if bound to a mouse key binding, see 2328.Sx MOUSE SUPPORT ) . 2329.Pp 2330.Fl X 2331is used to send a command into copy mode - see 2332the 2333.Sx WINDOWS AND PANES 2334section. 2335.Fl N 2336specifies a repeat count. 2337.It Xo Ic send-prefix 2338.Op Fl 2 2339.Op Fl t Ar target-pane 2340.Xc 2341Send the prefix key, or with 2342.Fl 2 2343the secondary prefix key, to a window as if it was pressed. 2344.It Xo Ic unbind-key 2345.Op Fl an 2346.Op Fl T Ar key-table 2347.Ar key 2348.Xc 2349.D1 (alias: Ic unbind ) 2350Unbind the command bound to 2351.Ar key . 2352.Fl n 2353and 2354.Fl T 2355are the same as for 2356.Ic bind-key . 2357If 2358.Fl a 2359is present, all key bindings are removed. 2360.El 2361.Sh OPTIONS 2362The appearance and behaviour of 2363.Nm 2364may be modified by changing the value of various options. 2365There are three types of option: 2366.Em server options , 2367.Em session options 2368and 2369.Em window options . 2370.Pp 2371The 2372.Nm 2373server has a set of global options which do not apply to any particular 2374window or session. 2375These are altered with the 2376.Ic set-option 2377.Fl s 2378command, or displayed with the 2379.Ic show-options 2380.Fl s 2381command. 2382.Pp 2383In addition, each individual session may have a set of session options, and 2384there is a separate set of global session options. 2385Sessions which do not have a particular option configured inherit the value 2386from the global session options. 2387Session options are set or unset with the 2388.Ic set-option 2389command and may be listed with the 2390.Ic show-options 2391command. 2392The available server and session options are listed under the 2393.Ic set-option 2394command. 2395.Pp 2396Similarly, a set of window options is attached to each window, and there is 2397a set of global window options from which any unset options are inherited. 2398Window options are altered with the 2399.Ic set-window-option 2400command and can be listed with the 2401.Ic show-window-options 2402command. 2403All window options are documented with the 2404.Ic set-window-option 2405command. 2406.Pp 2407.Nm 2408also supports user options which are prefixed with a 2409.Ql \&@ . 2410User options may have any name, so long as they are prefixed with 2411.Ql \&@ , 2412and be set to any string. 2413For example: 2414.Bd -literal -offset indent 2415$ tmux setw -q @foo "abc123" 2416$ tmux showw -v @foo 2417abc123 2418.Ed 2419.Pp 2420Commands which set options are as follows: 2421.Bl -tag -width Ds 2422.It Xo Ic set-option 2423.Op Fl aFgoqsuw 2424.Op Fl t Ar target-session | Ar target-window 2425.Ar option Ar value 2426.Xc 2427.D1 (alias: Ic set ) 2428Set a window option with 2429.Fl w 2430(equivalent to the 2431.Ic set-window-option 2432command), 2433a server option with 2434.Fl s , 2435otherwise a session option. 2436If 2437.Fl g 2438is given, the global session or window option is set. 2439.Fl F 2440expands formats in the option value. 2441The 2442.Fl u 2443flag unsets an option, so a session inherits the option from the global 2444options (or with 2445.Fl g , 2446restores a global option to the default). 2447.Pp 2448The 2449.Fl o 2450flag prevents setting an option that is already set and the 2451.Fl q 2452flag suppresses errors about unknown or ambiguous options. 2453.Pp 2454With 2455.Fl a , 2456and if the option expects a string or a style, 2457.Ar value 2458is appended to the existing setting. 2459For example: 2460.Bd -literal -offset indent 2461set -g status-left "foo" 2462set -ag status-left "bar" 2463.Ed 2464.Pp 2465Will result in 2466.Ql foobar . 2467And: 2468.Bd -literal -offset indent 2469set -g status-style "bg=red" 2470set -ag status-style "fg=blue" 2471.Ed 2472.Pp 2473Will result in a red background 2474.Em and 2475blue foreground. 2476Without 2477.Fl a , 2478the result would be the default background and a blue foreground. 2479.Pp 2480Available window options are listed under 2481.Ic set-window-option . 2482.Pp 2483.Ar value 2484depends on the option and may be a number, a string, or a flag (on, off, or 2485omitted to toggle). 2486.Pp 2487Available server options are: 2488.Bl -tag -width Ds 2489.It Ic buffer-limit Ar number 2490Set the number of buffers; as new buffers are added to the top of the stack, 2491old ones are removed from the bottom if necessary to maintain this maximum 2492length. 2493.It Xo Ic command-alias[] 2494.Ar name=value 2495.Xc 2496This is an array of custom aliases for commands. 2497If an unknown command matches 2498.Ar name , 2499it is replaced with 2500.Ar value . 2501For example, after: 2502.Pp 2503.Dl set -s command-alias[100] zoom='resize-pane -Z' 2504.Pp 2505Using: 2506.Pp 2507.Dl zoom -t:.1 2508.Pp 2509Is equivalent to: 2510.Pp 2511.Dl resize-pane -Z -t:.1 2512.Pp 2513Note that aliases are expanded when a command is parsed rather than when it is 2514executed, so binding an alias with 2515.Ic bind-key 2516will bind the expanded form. 2517.It Ic default-terminal Ar terminal 2518Set the default terminal for new windows created in this session - the 2519default value of the 2520.Ev TERM 2521environment variable. 2522For 2523.Nm 2524to work correctly, this 2525.Em must 2526be set to 2527.Ql screen , 2528.Ql tmux 2529or a derivative of them. 2530.It Ic escape-time Ar time 2531Set the time in milliseconds for which 2532.Nm 2533waits after an escape is input to determine if it is part of a function or meta 2534key sequences. 2535The default is 500 milliseconds. 2536.It Xo Ic exit-empty 2537.Op Ic on | off 2538.Xc 2539If enabled (the default), the server will exit when there are no active 2540sessions. 2541.It Xo Ic exit-unattached 2542.Op Ic on | off 2543.Xc 2544If enabled, the server will exit when there are no attached clients. 2545.It Xo Ic focus-events 2546.Op Ic on | off 2547.Xc 2548When enabled, focus events are requested from the terminal if supported and 2549passed through to applications running in 2550.Nm . 2551Attached clients should be detached and attached again after changing this 2552option. 2553.It Ic history-file Ar path 2554If not empty, a file to which 2555.Nm 2556will write command prompt history on exit and load it from on start. 2557.It Ic message-limit Ar number 2558Set the number of error or information messages to save in the message log for 2559each client. 2560The default is 100. 2561.It Xo Ic set-clipboard 2562.Op Ic on | external | off 2563.Xc 2564Attempt to set the terminal clipboard content using the 2565.Xr xterm 1 2566escape sequence, if there is an 2567.Em \&Ms 2568entry in the 2569.Xr terminfo 5 2570description (see the 2571.Sx TERMINFO EXTENSIONS 2572section). 2573.Pp 2574If set to 2575.Ic on , 2576.Nm 2577will both accept the escape sequence to create a buffer and attempt to set 2578the terminal clipboard. 2579If set to 2580.Ic external , 2581.Nm 2582will attempt to set the terminal clipboard but ignore attempts 2583by applications to set 2584.Nm 2585buffers. 2586If 2587.Ic off , 2588.Nm 2589will neither accept the clipboard escape sequence nor attempt to set the 2590clipboard. 2591.Pp 2592Note that this feature needs to be enabled in 2593.Xr xterm 1 2594by setting the resource: 2595.Bd -literal -offset indent 2596disallowedWindowOps: 20,21,SetXprop 2597.Ed 2598.Pp 2599Or changing this property from the 2600.Xr xterm 1 2601interactive menu when required. 2602.It Ic terminal-overrides[] Ar string 2603Allow terminal descriptions read using 2604.Xr terminfo 5 2605to be overridden. 2606Each entry is a colon-separated string made up of a terminal type pattern 2607(matched using 2608.Xr fnmatch 3 ) 2609and a set of 2610.Em name=value 2611entries. 2612.Pp 2613For example, to set the 2614.Ql clear 2615.Xr terminfo 5 2616entry to 2617.Ql \ee[H\ee[2J 2618for all terminal types matching 2619.Ql rxvt* : 2620.Pp 2621.Dl "rxvt*:clear=\ee[H\ee[2J" 2622.Pp 2623The terminal entry value is passed through 2624.Xr strunvis 3 2625before interpretation. 2626.El 2627.Pp 2628Available session options are: 2629.Bl -tag -width Ds 2630.It Xo Ic activity-action 2631.Op Ic any | none | current | other 2632.Xc 2633Set action on window activity when 2634.Ic monitor-activity 2635is on. 2636.Ic any 2637means activity in any window linked to a session causes a bell or message 2638(depending on 2639.Ic visual-activity ) 2640in the current window of that session, 2641.Ic none 2642means all activity is ignored (equivalent to 2643.Ic monitor-activity 2644being off), 2645.Ic current 2646means only activity in windows other than the current window are ignored and 2647.Ic other 2648means activity in the current window is ignored but not those in other windows. 2649.It Ic assume-paste-time Ar milliseconds 2650If keys are entered faster than one in 2651.Ar milliseconds , 2652they are assumed to have been pasted rather than typed and 2653.Nm 2654key bindings are not processed. 2655The default is one millisecond and zero disables. 2656.It Ic base-index Ar index 2657Set the base index from which an unused index should be searched when a new 2658window is created. 2659The default is zero. 2660.It Xo Ic bell-action 2661.Op Ic any | none | current | other 2662.Xc 2663Set action on a bell in a window when 2664.Ic monitor-bell 2665is on. 2666The values are the same as those for 2667.Ic activity-action . 2668.It Ic default-command Ar shell-command 2669Set the command used for new windows (if not specified when the window is 2670created) to 2671.Ar shell-command , 2672which may be any 2673.Xr sh 1 2674command. 2675The default is an empty string, which instructs 2676.Nm 2677to create a login shell using the value of the 2678.Ic default-shell 2679option. 2680.It Ic default-shell Ar path 2681Specify the default shell. 2682This is used as the login shell for new windows when the 2683.Ic default-command 2684option is set to empty, and must be the full path of the executable. 2685When started 2686.Nm 2687tries to set a default value from the first suitable of the 2688.Ev SHELL 2689environment variable, the shell returned by 2690.Xr getpwuid 3 , 2691or 2692.Pa /bin/sh . 2693This option should be configured when 2694.Nm 2695is used as a login shell. 2696.It Xo Ic destroy-unattached 2697.Op Ic on | off 2698.Xc 2699If enabled and the session is no longer attached to any clients, it is 2700destroyed. 2701.It Xo Ic detach-on-destroy 2702.Op Ic on | off 2703.Xc 2704If on (the default), the client is detached when the session it is attached to 2705is destroyed. 2706If off, the client is switched to the most recently active of the remaining 2707sessions. 2708.It Ic display-panes-active-colour Ar colour 2709Set the colour used by the 2710.Ic display-panes 2711command to show the indicator for the active pane. 2712.It Ic display-panes-colour Ar colour 2713Set the colour used by the 2714.Ic display-panes 2715command to show the indicators for inactive panes. 2716.It Ic display-panes-time Ar time 2717Set the time in milliseconds for which the indicators shown by the 2718.Ic display-panes 2719command appear. 2720.It Ic display-time Ar time 2721Set the amount of time for which status line messages and other on-screen 2722indicators are displayed. 2723If set to 0, messages and indicators are displayed until a key is pressed. 2724.Ar time 2725is in milliseconds. 2726.It Ic history-limit Ar lines 2727Set the maximum number of lines held in window history. 2728This setting applies only to new windows - existing window histories are not 2729resized and retain the limit at the point they were created. 2730.It Ic key-table Ar key-table 2731Set the default key table to 2732.Ar key-table 2733instead of 2734.Em root . 2735.It Ic lock-after-time Ar number 2736Lock the session (like the 2737.Ic lock-session 2738command) after 2739.Ar number 2740seconds of inactivity. 2741The default is not to lock (set to 0). 2742.It Ic lock-command Ar shell-command 2743Command to run when locking each client. 2744The default is to run 2745.Xr lock 1 2746with 2747.Fl np . 2748.It Ic message-command-style Ar style 2749Set status line message command style, where 2750.Ar style 2751is a comma-separated list of characteristics to be specified. 2752.Pp 2753The style format is shared by many options and may be: 2754.Ql bg=colour 2755to set the background colour, 2756.Ql fg=colour 2757to set the foreground colour, and a list of attributes as specified below. 2758.Pp 2759The colour is one of: 2760.Ic black , 2761.Ic red , 2762.Ic green , 2763.Ic yellow , 2764.Ic blue , 2765.Ic magenta , 2766.Ic cyan , 2767.Ic white , 2768aixterm bright variants (if supported: 2769.Ic brightred , 2770.Ic brightgreen , 2771and so on), 2772.Ic colour0 2773to 2774.Ic colour255 2775from the 256-colour set, 2776.Ic default 2777for the default colour (inherited from another option in the case of some options, for example 2778.Ic window-status-style 2779inherits from 2780.Ic status-style ) , 2781.Ic terminal 2782for the terminal default colour, or a hexadecimal RGB string such as 2783.Ql #ffffff . 2784.Pp 2785The attributes is either 2786.Ic none 2787or a comma-delimited list of one or more of: 2788.Ic bright 2789(or 2790.Ic bold ) , 2791.Ic dim , 2792.Ic underscore , 2793.Ic blink , 2794.Ic reverse , 2795.Ic hidden , 2796.Ic italics , 2797.Ic strikethrough , 2798.Ic double-underscore 2799.Ic curly-underscore 2800.Ic dotted-underscore 2801or 2802.Ic dashed-underscore 2803to turn an attribute on, or an attribute prefixed with 2804.Ql no 2805to turn one off. 2806.Pp 2807Examples are: 2808.Bd -literal -offset indent 2809fg=yellow,bold,underscore,blink 2810bg=black,fg=default,noreverse 2811.Ed 2812.Pp 2813With the 2814.Fl a 2815flag to the 2816.Ic set-option 2817command the new style is added otherwise the existing style is replaced. 2818.It Ic message-style Ar style 2819Set status line message style. 2820For how to specify 2821.Ar style , 2822see the 2823.Ic message-command-style 2824option. 2825.It Xo Ic mouse 2826.Op Ic on | off 2827.Xc 2828If on, 2829.Nm 2830captures the mouse and allows mouse events to be bound as key bindings. 2831See the 2832.Sx MOUSE SUPPORT 2833section for details. 2834.It Ic prefix Ar key 2835Set the key accepted as a prefix key. 2836In addition to the standard keys described under 2837.Sx KEY BINDINGS , 2838.Ic prefix 2839can be set to the special key 2840.Ql None 2841to set no prefix. 2842.It Ic prefix2 Ar key 2843Set a secondary key accepted as a prefix key. 2844Like 2845.Ic prefix , 2846.Ic prefix2 2847can be set to 2848.Ql None . 2849.It Xo Ic renumber-windows 2850.Op Ic on | off 2851.Xc 2852If on, when a window is closed in a session, automatically renumber the other 2853windows in numerical order. 2854This respects the 2855.Ic base-index 2856option if it has been set. 2857If off, do not renumber the windows. 2858.It Ic repeat-time Ar time 2859Allow multiple commands to be entered without pressing the prefix-key again 2860in the specified 2861.Ar time 2862milliseconds (the default is 500). 2863Whether a key repeats may be set when it is bound using the 2864.Fl r 2865flag to 2866.Ic bind-key . 2867Repeat is enabled for the default keys bound to the 2868.Ic resize-pane 2869command. 2870.It Xo Ic set-titles 2871.Op Ic on | off 2872.Xc 2873Attempt to set the client terminal title using the 2874.Em tsl 2875and 2876.Em fsl 2877.Xr terminfo 5 2878entries if they exist. 2879.Nm 2880automatically sets these to the \ee]0;...\e007 sequence if 2881the terminal appears to be 2882.Xr xterm 1 . 2883This option is off by default. 2884.It Ic set-titles-string Ar string 2885String used to set the window title if 2886.Ic set-titles 2887is on. 2888Formats are expanded, see the 2889.Sx FORMATS 2890section. 2891.It Xo Ic silence-action 2892.Op Ic any | none | current | other 2893.Xc 2894Set action on window silence when 2895.Ic monitor-silence 2896is on. 2897The values are the same as those for 2898.Ic activity-action . 2899.It Xo Ic status 2900.Op Ic on | off 2901.Xc 2902Show or hide the status line. 2903.It Ic status-interval Ar interval 2904Update the status line every 2905.Ar interval 2906seconds. 2907By default, updates will occur every 15 seconds. 2908A setting of zero disables redrawing at interval. 2909.It Xo Ic status-justify 2910.Op Ic left | centre | right 2911.Xc 2912Set the position of the window list component of the status line: left, centre 2913or right justified. 2914.It Xo Ic status-keys 2915.Op Ic vi | emacs 2916.Xc 2917Use vi or emacs-style 2918key bindings in the status line, for example at the command prompt. 2919The default is emacs, unless the 2920.Ev VISUAL 2921or 2922.Ev EDITOR 2923environment variables are set and contain the string 2924.Ql vi . 2925.It Ic status-left Ar string 2926Display 2927.Ar string 2928(by default the session name) to the left of the status line. 2929.Ar string 2930will be passed through 2931.Xr strftime 3 2932and formats (see 2933.Sx FORMATS ) 2934will be expanded. 2935It may also contain the special character sequence #[] to change the colour 2936or attributes, for example 2937.Ql #[fg=red,bright] 2938to set a bright red foreground. 2939See the 2940.Ic message-command-style 2941option for a description of colours and attributes. 2942.Pp 2943For details on how the names and titles can be set see the 2944.Sx "NAMES AND TITLES" 2945section. 2946.Pp 2947Examples are: 2948.Bd -literal -offset indent 2949#(sysctl vm.loadavg) 2950#[fg=yellow,bold]#(apm -l)%%#[default] [#S] 2951.Ed 2952.Pp 2953The default is 2954.Ql "[#S] " . 2955.It Ic status-left-length Ar length 2956Set the maximum 2957.Ar length 2958of the left component of the status line. 2959The default is 10. 2960.It Ic status-left-style Ar style 2961Set the style of the left part of the status line. 2962For how to specify 2963.Ar style , 2964see the 2965.Ic message-command-style 2966option. 2967.It Xo Ic status-position 2968.Op Ic top | bottom 2969.Xc 2970Set the position of the status line. 2971.It Ic status-right Ar string 2972Display 2973.Ar string 2974to the right of the status line. 2975By default, the current pane title in double quotes, the date and the time 2976are shown. 2977As with 2978.Ic status-left , 2979.Ar string 2980will be passed to 2981.Xr strftime 3 2982and character pairs are replaced. 2983.It Ic status-right-length Ar length 2984Set the maximum 2985.Ar length 2986of the right component of the status line. 2987The default is 40. 2988.It Ic status-right-style Ar style 2989Set the style of the right part of the status line. 2990For how to specify 2991.Ar style , 2992see the 2993.Ic message-command-style 2994option. 2995.It Ic status-style Ar style 2996Set status line style. 2997For how to specify 2998.Ar style , 2999see the 3000.Ic message-command-style 3001option. 3002.It Ic update-environment[] Ar variable 3003Set list of environment variables to be copied into the session environment 3004when a new session is created or an existing session is attached. 3005Any variables that do not exist in the source environment are set to be 3006removed from the session environment (as if 3007.Fl r 3008was given to the 3009.Ic set-environment 3010command). 3011.It Ic user-keys[] Ar key 3012Set list of user-defined key escape sequences. 3013Each item is associated with a key named 3014.Ql User0 , 3015.Ql User1 , 3016and so on. 3017.Pp 3018For example: 3019.Bd -literal -offset indent 3020set -s user-keys[0] "\ee[5;30012~" 3021bind User0 resize-pane -L 3 3022.Ed 3023.It Xo Ic visual-activity 3024.Op Ic on | off | both 3025.Xc 3026If on, display a message instead of sending a bell when activity occurs in a 3027window for which the 3028.Ic monitor-activity 3029window option is enabled. 3030If set to both, a bell and a message are produced. 3031.It Xo Ic visual-bell 3032.Op Ic on | off | both 3033.Xc 3034If on, a message is shown on a bell in a window for which the 3035.Ic monitor-bell 3036window option is enabled instead of it being passed through to the 3037terminal (which normally makes a sound). 3038If set to both, a bell and a message are produced. 3039Also see the 3040.Ic bell-action 3041option. 3042.It Xo Ic visual-silence 3043.Op Ic on | off | both 3044.Xc 3045If 3046.Ic monitor-silence 3047is enabled, prints a message after the interval has expired on a given window 3048instead of sending a bell. 3049If set to both, a bell and a message are produced. 3050.It Ic word-separators Ar string 3051Sets the session's conception of what characters are considered word 3052separators, for the purposes of the next and previous word commands in 3053copy mode. 3054The default is 3055.Ql \ -_@ . 3056.El 3057.It Xo Ic set-window-option 3058.Op Fl aFgoqu 3059.Op Fl t Ar target-window 3060.Ar option Ar value 3061.Xc 3062.D1 (alias: Ic setw ) 3063Set a window option. 3064The 3065.Fl a , 3066.Fl F , 3067.Fl g , 3068.Fl o , 3069.Fl q 3070and 3071.Fl u 3072flags work similarly to the 3073.Ic set-option 3074command. 3075.Pp 3076Supported window options are: 3077.Pp 3078.Bl -tag -width Ds -compact 3079.It Xo Ic aggressive-resize 3080.Op Ic on | off 3081.Xc 3082Aggressively resize the chosen window. 3083This means that 3084.Nm 3085will resize the window to the size of the smallest session for which it is the 3086current window, rather than the smallest session to which it is attached. 3087The window may resize when the current window is changed on another sessions; 3088this option is good for full-screen programs which support 3089.Dv SIGWINCH 3090and poor for interactive programs such as shells. 3091.Pp 3092.It Xo Ic allow-rename 3093.Op Ic on | off 3094.Xc 3095Allow programs to change the window name using a terminal escape 3096sequence (\eek...\ee\e\e). 3097The default is off. 3098.Pp 3099.It Xo Ic alternate-screen 3100.Op Ic on | off 3101.Xc 3102This option configures whether programs running inside 3103.Nm 3104may use the terminal alternate screen feature, which allows the 3105.Em smcup 3106and 3107.Em rmcup 3108.Xr terminfo 5 3109capabilities. 3110The alternate screen feature preserves the contents of the window when an 3111interactive application starts and restores it on exit, so that any output 3112visible before the application starts reappears unchanged after it exits. 3113The default is on. 3114.Pp 3115.It Xo Ic automatic-rename 3116.Op Ic on | off 3117.Xc 3118Control automatic window renaming. 3119When this setting is enabled, 3120.Nm 3121will rename the window automatically using the format specified by 3122.Ic automatic-rename-format . 3123This flag is automatically disabled for an individual window when a name 3124is specified at creation with 3125.Ic new-window 3126or 3127.Ic new-session , 3128or later with 3129.Ic rename-window , 3130or with a terminal escape sequence. 3131It may be switched off globally with: 3132.Bd -literal -offset indent 3133set-window-option -g automatic-rename off 3134.Ed 3135.Pp 3136.It Ic automatic-rename-format Ar format 3137The format (see 3138.Sx FORMATS ) 3139used when the 3140.Ic automatic-rename 3141option is enabled. 3142.Pp 3143.It Ic clock-mode-colour Ar colour 3144Set clock colour. 3145.Pp 3146.It Xo Ic clock-mode-style 3147.Op Ic 12 | 24 3148.Xc 3149Set clock hour format. 3150.Pp 3151.It Ic force-height Ar height 3152.It Ic force-width Ar width 3153Prevent 3154.Nm 3155from resizing a window to greater than 3156.Ar width 3157or 3158.Ar height . 3159A value of zero restores the default unlimited setting. 3160.Pp 3161.It Ic main-pane-height Ar height 3162.It Ic main-pane-width Ar width 3163Set the width or height of the main (left or top) pane in the 3164.Ic main-horizontal 3165or 3166.Ic main-vertical 3167layouts. 3168.Pp 3169.It Xo Ic mode-keys 3170.Op Ic vi | emacs 3171.Xc 3172Use vi or emacs-style key bindings in copy mode. 3173The default is emacs, unless 3174.Ev VISUAL 3175or 3176.Ev EDITOR 3177contains 3178.Ql vi . 3179.Pp 3180.It Ic mode-style Ar style 3181Set window modes style. 3182For how to specify 3183.Ar style , 3184see the 3185.Ic message-command-style 3186option. 3187.Pp 3188.It Xo Ic monitor-activity 3189.Op Ic on | off 3190.Xc 3191Monitor for activity in the window. 3192Windows with activity are highlighted in the status line. 3193.Pp 3194.It Xo Ic monitor-bell 3195.Op Ic on | off 3196.Xc 3197Monitor for a bell in the window. 3198Windows with a bell are highlighted in the status line. 3199.Pp 3200.It Xo Ic monitor-silence 3201.Op Ic interval 3202.Xc 3203Monitor for silence (no activity) in the window within 3204.Ic interval 3205seconds. 3206Windows that have been silent for the interval are highlighted in the 3207status line. 3208An interval of zero disables the monitoring. 3209.Pp 3210.It Ic other-pane-height Ar height 3211Set the height of the other panes (not the main pane) in the 3212.Ic main-horizontal 3213layout. 3214If this option is set to 0 (the default), it will have no effect. 3215If both the 3216.Ic main-pane-height 3217and 3218.Ic other-pane-height 3219options are set, the main pane will grow taller to make the other panes the 3220specified height, but will never shrink to do so. 3221.Pp 3222.It Ic other-pane-width Ar width 3223Like 3224.Ic other-pane-height , 3225but set the width of other panes in the 3226.Ic main-vertical 3227layout. 3228.Pp 3229.It Ic pane-active-border-style Ar style 3230Set the pane border style for the currently active pane. 3231For how to specify 3232.Ar style , 3233see the 3234.Ic message-command-style 3235option. 3236Attributes are ignored. 3237.Pp 3238.It Ic pane-base-index Ar index 3239Like 3240.Ic base-index , 3241but set the starting index for pane numbers. 3242.Pp 3243.It Ic pane-border-format Ar format 3244Set the text shown in pane border status lines. 3245.Pp 3246.It Xo Ic pane-border-status 3247.Op Ic off | top | bottom 3248.Xc 3249Turn pane border status lines off or set their position. 3250.Pp 3251.It Ic pane-border-style Ar style 3252Set the pane border style for panes aside from the active pane. 3253For how to specify 3254.Ar style , 3255see the 3256.Ic message-command-style 3257option. 3258Attributes are ignored. 3259.Pp 3260.It Xo Ic remain-on-exit 3261.Op Ic on | off 3262.Xc 3263A window with this flag set is not destroyed when the program running in it 3264exits. 3265The window may be reactivated with the 3266.Ic respawn-window 3267command. 3268.Pp 3269.It Xo Ic synchronize-panes 3270.Op Ic on | off 3271.Xc 3272Duplicate input to any pane to all other panes in the same window (only 3273for panes that are not in any special mode). 3274.Pp 3275.It Ic window-active-style Ar style 3276Set the style for the window's active pane. 3277For how to specify 3278.Ar style , 3279see the 3280.Ic message-command-style 3281option. 3282.Pp 3283.It Ic window-status-activity-style Ar style 3284Set status line style for windows with an activity alert. 3285For how to specify 3286.Ar style , 3287see the 3288.Ic message-command-style 3289option. 3290.Pp 3291.It Ic window-status-bell-style Ar style 3292Set status line style for windows with a bell alert. 3293For how to specify 3294.Ar style , 3295see the 3296.Ic message-command-style 3297option. 3298.Pp 3299.It Ic window-status-current-format Ar string 3300Like 3301.Ar window-status-format , 3302but is the format used when the window is the current window. 3303.Pp 3304.It Ic window-status-current-style Ar style 3305Set status line style for the currently active window. 3306For how to specify 3307.Ar style , 3308see the 3309.Ic message-command-style 3310option. 3311.Pp 3312.It Ic window-status-format Ar string 3313Set the format in which the window is displayed in the status line window list. 3314See the 3315.Ar status-left 3316option for details of special character sequences available. 3317The default is 3318.Ql #I:#W#F . 3319.Pp 3320.It Ic window-status-last-style Ar style 3321Set status line style for the last active window. 3322For how to specify 3323.Ar style , 3324see the 3325.Ic message-command-style 3326option. 3327.Pp 3328.It Ic window-status-separator Ar string 3329Sets the separator drawn between windows in the status line. 3330The default is a single space character. 3331.Pp 3332.It Ic window-status-style Ar style 3333Set status line style for a single window. 3334For how to specify 3335.Ar style , 3336see the 3337.Ic message-command-style 3338option. 3339.Pp 3340.It Ic window-style Ar style 3341Set the default window style. 3342For how to specify 3343.Ar style , 3344see the 3345.Ic message-command-style 3346option. 3347.Pp 3348.It Xo Ic wrap-search 3349.Op Ic on | off 3350.Xc 3351If this option is set, searches will wrap around the end of the pane contents. 3352The default is on. 3353.Pp 3354.It Xo Ic xterm-keys 3355.Op Ic on | off 3356.Xc 3357If this option is set, 3358.Nm 3359will generate 3360.Xr xterm 1 -style 3361function key sequences; these have a number included to indicate modifiers such 3362as Shift, Alt or Ctrl. 3363.El 3364.It Xo Ic show-options 3365.Op Fl gqsvw 3366.Op Fl t Ar target-session | Ar target-window 3367.Op Ar option 3368.Xc 3369.D1 (alias: Ic show ) 3370Show the window options (or a single window option if given) with 3371.Fl w 3372(equivalent to 3373.Ic show-window-options ) , 3374the server options with 3375.Fl s , 3376otherwise the session options for 3377.Ar target session . 3378Global session or window options are listed if 3379.Fl g 3380is used. 3381.Fl v 3382shows only the option value, not the name. 3383If 3384.Fl q 3385is set, no error will be returned if 3386.Ar option 3387is unset. 3388.It Xo Ic show-window-options 3389.Op Fl gv 3390.Op Fl t Ar target-window 3391.Op Ar option 3392.Xc 3393.D1 (alias: Ic showw ) 3394List the window options or a single option for 3395.Ar target-window , 3396or the global window options if 3397.Fl g 3398is used. 3399.Fl v 3400shows only the option value, not the name. 3401.El 3402.Sh HOOKS 3403.Nm 3404allows commands to run on various triggers, called 3405.Em hooks . 3406Most 3407.Nm 3408commands have an 3409.Em after 3410hook and there are a number of hooks not associated with commands. 3411.Pp 3412A command's after 3413hook is run after it completes, except when the command is run as part of a hook 3414itself. 3415They are named with an 3416.Ql after- 3417prefix. 3418For example, the following command adds a hook to select the even-vertical 3419layout after every 3420.Ic split-window : 3421.Bd -literal -offset indent 3422set-hook after-split-window "selectl even-vertical" 3423.Ed 3424.Pp 3425All the notifications listed in the 3426.Sx CONTROL MODE 3427section are hooks (without any arguments), except 3428.Ic %exit . 3429The following additional hooks are available: 3430.Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX" 3431.It alert-activity 3432Run when a window has activity. 3433See 3434.Ic monitor-activity . 3435.It alert-bell 3436Run when a window has received a bell. 3437See 3438.Ic monitor-bell . 3439.It alert-silence 3440Run when a window has been silent. 3441See 3442.Ic monitor-silence . 3443.It client-attached 3444Run when a client is attached. 3445.It client-detached 3446Run when a client is detached 3447.It client-resized 3448Run when a client is resized. 3449.It client-session-changed 3450Run when a client's attached session is changed. 3451.It pane-died 3452Run when the program running in a pane exits, but 3453.Ic remain-on-exit 3454is on so the pane has not closed. 3455.It pane-exited 3456Run when the program running in a pane exits. 3457.It pane-focus-in 3458Run when the focus enters a pane, if the 3459.Ic focus-events 3460option is on. 3461.It pane-focus-out 3462Run when the focus exits a pane, if the 3463.Ic focus-events 3464option is on. 3465.It pane-set-clipboard 3466Run when the terminal clipboard is set using the 3467.Xr xterm 1 3468escape sequence. 3469.It session-created 3470Run when a new session created. 3471.It session-closed 3472Run when a session closed. 3473.It session-renamed 3474Run when a session is renamed. 3475.It window-linked 3476Run when a window is linked into a session. 3477.It window-renamed 3478Run when a window is renamed. 3479.It window-unlinked 3480Run when a window is unlinked from a session. 3481.El 3482.Pp 3483Hooks are managed with these commands: 3484.Bl -tag -width Ds 3485.It Xo Ic set-hook 3486.Op Fl gRu 3487.Op Fl t Ar target-session 3488.Ar hook-name 3489.Ar command 3490.Xc 3491Without 3492.Fl R , 3493sets (or with 3494.Fl u 3495unsets) hook 3496.Ar hook-name 3497to 3498.Ar command . 3499If 3500.Fl g 3501is given, 3502.Em hook-name 3503is added to the global list of hooks, otherwise it is added to the session 3504hooks (for 3505.Ar target-session 3506with 3507.Fl t ) . 3508Like options, session hooks inherit from the global ones. 3509.Pp 3510With 3511.Fl R , 3512run 3513.Ar hook-name 3514immediately. 3515.It Xo Ic show-hooks 3516.Op Fl g 3517.Op Fl t Ar target-session 3518.Xc 3519Shows the global list of hooks with 3520.Fl g , 3521otherwise the session hooks. 3522.El 3523.Sh MOUSE SUPPORT 3524If the 3525.Ic mouse 3526option is on (the default is off), 3527.Nm 3528allows mouse events to be bound as keys. 3529The name of each key is made up of a mouse event (such as 3530.Ql MouseUp1 ) 3531and a location suffix (one of 3532.Ql Pane 3533for the contents of a pane, 3534.Ql Border 3535for a pane border or 3536.Ql Status , 3537.Ql StatusLeft , 3538or 3539.Ql StatusRight 3540for the status line). 3541The following mouse events are available: 3542.Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent 3543.It Li "WheelUp" Ta "WheelDown" Ta "" 3544.It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1" 3545.It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2" 3546.It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3" 3547.It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3" 3548.It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3" 3549.El 3550.Pp 3551Each should be suffixed with a location, for example 3552.Ql MouseDown1Status . 3553.Pp 3554The special token 3555.Ql {mouse} 3556or 3557.Ql = 3558may be used as 3559.Ar target-window 3560or 3561.Ar target-pane 3562in commands bound to mouse key bindings. 3563It resolves to the window or pane over which the mouse event took place 3564(for example, the window in the status line over which button 1 was released for a 3565.Ql MouseUp1Status 3566binding, or the pane over which the wheel was scrolled for a 3567.Ql WheelDownPane 3568binding). 3569.Pp 3570The 3571.Ic send-keys 3572.Fl M 3573flag may be used to forward a mouse event to a pane. 3574.Pp 3575The default key bindings allow the mouse to be used to select and resize panes, 3576to copy text and to change window using the status line. 3577These take effect if the 3578.Ic mouse 3579option is turned on. 3580.Sh FORMATS 3581Certain commands accept the 3582.Fl F 3583flag with a 3584.Ar format 3585argument. 3586This is a string which controls the output format of the command. 3587Replacement variables are enclosed in 3588.Ql #{ 3589and 3590.Ql } , 3591for example 3592.Ql #{session_name} . 3593The possible variables are listed in the table below, or the name of a 3594.Nm 3595option may be used for an option's value. 3596Some variables have a shorter alias such as 3597.Ql #S ; 3598.Ql ## 3599is replaced by a single 3600.Ql # , 3601.Ql #, 3602by a 3603.Ql \&, 3604and 3605.Ql #} 3606by a 3607.Ql } . 3608.Pp 3609Conditionals are available by prefixing with 3610.Ql \&? 3611and separating two alternatives with a comma; 3612if the specified variable exists and is not zero, the first alternative 3613is chosen, otherwise the second is used. 3614For example 3615.Ql #{?session_attached,attached,not attached} 3616will include the string 3617.Ql attached 3618if the session is attached and the string 3619.Ql not attached 3620if it is unattached, or 3621.Ql #{?automatic-rename,yes,no} 3622will include 3623.Ql yes 3624if 3625.Ic automatic-rename 3626is enabled, or 3627.Ql no 3628if not. 3629Conditionals can be nested arbitrarily. 3630Inside a conditional, 3631.Ql \&, 3632and 3633.Ql } 3634must be escaped as 3635.Ql #, 3636and 3637.Ql #} , 3638unless they are part of a 3639.Ql #{...} 3640replacement. 3641For example: 3642.Bd -literal -offset indent 3643#{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W . 3644.Ed 3645.Pp 3646Comparisons may be expressed by prefixing two comma-separated 3647alternatives by 3648.Ql == 3649or 3650.Ql != 3651and a colon. 3652For example 3653.Ql #{==:#{host},myhost} 3654will be replaced by 3655.Ql 1 3656if running on 3657.Ql myhost , 3658otherwise by 3659.Ql 0 . 3660An 3661.Ql m 3662specifies an 3663.Xr fnmatch 3 3664comparison where the first argument is the pattern and the second the string to 3665compare, for example 3666.Ql #{m:*foo*,#{host}} . 3667.Ql || 3668and 3669.Ql && 3670evaluate to true if either or both of two comma-separated alternatives are 3671true, for example 3672.Ql #{||:#{pane_in_mode},#{alternate_on}} . 3673A 3674.Ql C 3675performs a search for an 3676.Xr fnmatch 3 3677pattern in the pane content and evaluates to zero if not found, or a line 3678number if found. 3679.Pp 3680A limit may be placed on the length of the resultant string by prefixing it 3681by an 3682.Ql = , 3683a number and a colon. 3684Positive numbers count from the start of the string and negative from the end, 3685so 3686.Ql #{=5:pane_title} 3687will include at most the first 5 characters of the pane title, or 3688.Ql #{=-5:pane_title} 3689the last 5 characters. 3690Prefixing a time variable with 3691.Ql t: 3692will convert it to a string, so if 3693.Ql #{window_activity} 3694gives 3695.Ql 1445765102 , 3696.Ql #{t:window_activity} 3697gives 3698.Ql Sun Oct 25 09:25:02 2015 . 3699The 3700.Ql b: 3701and 3702.Ql d: 3703prefixes are 3704.Xr basename 3 3705and 3706.Xr dirname 3 3707of the variable respectively. 3708.Ql q: 3709will escape 3710.Xr sh 1 3711special characters. 3712A prefix of the form 3713.Ql s/foo/bar/: 3714will substitute 3715.Ql foo 3716with 3717.Ql bar 3718throughout. 3719.Pp 3720In addition, the first line of a shell command's output may be inserted using 3721.Ql #() . 3722For example, 3723.Ql #(uptime) 3724will insert the system's uptime. 3725When constructing formats, 3726.Nm 3727does not wait for 3728.Ql #() 3729commands to finish; instead, the previous result from running the same command is used, 3730or a placeholder if the command has not been run before. 3731If the command hasn't exited, the most recent line of output will be used, but the status 3732line will not be updated more than once a second. 3733Commands are executed with the 3734.Nm 3735global environment set (see the 3736.Sx ENVIRONMENT 3737section). 3738.Pp 3739The following variables are available, where appropriate: 3740.Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX" 3741.It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with" 3742.It Li "alternate_on" Ta "" Ta "If pane is in alternate screen" 3743.It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen" 3744.It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen" 3745.It Li "buffer_created" Ta "" Ta "Time buffer created" 3746.It Li "buffer_name" Ta "" Ta "Name of buffer" 3747.It Li "buffer_sample" Ta "" Ta "Sample of start of buffer" 3748.It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes" 3749.It Li "client_activity" Ta "" Ta "Time client last had activity" 3750.It Li "client_created" Ta "" Ta "Time client created" 3751.It Li "client_control_mode" Ta "" Ta "1 if client is in control mode" 3752.It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind" 3753.It Li "client_height" Ta "" Ta "Height of client" 3754.It Li "client_key_table" Ta "" Ta "Current key table" 3755.It Li "client_last_session" Ta "" Ta "Name of the client's last session" 3756.It Li "client_name" Ta "" Ta "Name of client" 3757.It Li "client_pid" Ta "" Ta "PID of client process" 3758.It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed" 3759.It Li "client_readonly" Ta "" Ta "1 if client is readonly" 3760.It Li "client_session" Ta "" Ta "Name of the client's session" 3761.It Li "client_termname" Ta "" Ta "Terminal name of client" 3762.It Li "client_termtype" Ta "" Ta "Terminal type of client" 3763.It Li "client_tty" Ta "" Ta "Pseudo terminal of client" 3764.It Li "client_utf8" Ta "" Ta "1 if client supports utf8" 3765.It Li "client_width" Ta "" Ta "Width of client" 3766.It Li "client_written" Ta "" Ta "Bytes written to client" 3767.It Li "command" Ta "" Ta "Name of command in use, if any" 3768.It Li "command_list_name" Ta "" Ta "Command name if listing commands" 3769.It Li "command_list_alias" Ta "" Ta "Command alias if listing commands" 3770.It Li "command_list_usage" Ta "" Ta "Command usage if listing commands" 3771.It Li "cursor_flag" Ta "" Ta "Pane cursor flag" 3772.It Li "cursor_x" Ta "" Ta "Cursor X position in pane" 3773.It Li "cursor_y" Ta "" Ta "Cursor Y position in pane" 3774.It Li "history_bytes" Ta "" Ta "Number of bytes in window history" 3775.It Li "history_limit" Ta "" Ta "Maximum window history lines" 3776.It Li "history_size" Ta "" Ta "Size of history in lines" 3777.It Li "hook" Ta "" Ta "Name of running hook, if any" 3778.It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any" 3779.It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any" 3780.It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any" 3781.It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any" 3782.It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any" 3783.It Li "host" Ta "#H" Ta "Hostname of local host" 3784.It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)" 3785.It Li "insert_flag" Ta "" Ta "Pane insert flag" 3786.It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag" 3787.It Li "keypad_flag" Ta "" Ta "Pane keypad flag" 3788.It Li "line" Ta "" Ta "Line number in the list" 3789.It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag" 3790.It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag" 3791.It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag" 3792.It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag" 3793.It Li "pane_active" Ta "" Ta "1 if active pane" 3794.It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window" 3795.It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window" 3796.It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window" 3797.It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window" 3798.It Li "pane_bottom" Ta "" Ta "Bottom of pane" 3799.It Li "pane_current_command" Ta "" Ta "Current command if available" 3800.It Li "pane_dead" Ta "" Ta "1 if pane is dead" 3801.It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane" 3802.It Li "pane_format" Ta "" Ta "1 if format is for a pane (not assuming the current)" 3803.It Li "pane_height" Ta "" Ta "Height of pane" 3804.It Li "pane_id" Ta "#D" Ta "Unique pane ID" 3805.It Li "pane_in_mode" Ta "" Ta "If pane is in a mode" 3806.It Li "pane_input_off" Ta "" Ta "If input to pane is disabled" 3807.It Li "pane_index" Ta "#P" Ta "Index of pane" 3808.It Li "pane_left" Ta "" Ta "Left of pane" 3809.It Li "pane_mode" Ta "" Ta "Name of pane mode, if any." 3810.It Li "pane_pid" Ta "" Ta "PID of first process in pane" 3811.It Li "pane_pipe" Ta "" Ta "1 if pane is being piped" 3812.It Li "pane_right" Ta "" Ta "Right of pane" 3813.It Li "pane_search_string" Ta "" Ta "Last search string in copy mode" 3814.It Li "pane_start_command" Ta "" Ta "Command pane started with" 3815.It Li "pane_synchronized" Ta "" Ta "If pane is synchronized" 3816.It Li "pane_tabs" Ta "" Ta "Pane tab positions" 3817.It Li "pane_title" Ta "#T" Ta "Title of pane" 3818.It Li "pane_top" Ta "" Ta "Top of pane" 3819.It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane" 3820.It Li "pane_width" Ta "" Ta "Width of pane" 3821.It Li "pid" Ta "" Ta "Server PID" 3822.It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated" 3823.It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane" 3824.It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane" 3825.It Li "scroll_position" Ta "" Ta "Scroll position in copy mode" 3826.It Li "selection_present" Ta "" Ta "1 if selection started in copy mode" 3827.It Li "session_alerts" Ta "" Ta "List of window indexes with alerts" 3828.It Li "session_attached" Ta "" Ta "Number of clients session is attached to" 3829.It Li "session_activity" Ta "" Ta "Time of session last activity" 3830.It Li "session_created" Ta "" Ta "Time session created" 3831.It Li "session_format" Ta "" Ta "1 if format is for a session (not assuming the current)" 3832.It Li "session_last_attached" Ta "" Ta "Time session last attached" 3833.It Li "session_group" Ta "" Ta "Name of session group" 3834.It Li "session_group_size" Ta "" Ta "Size of session group" 3835.It Li "session_group_list" Ta "" Ta "List of sessions in group" 3836.It Li "session_grouped" Ta "" Ta "1 if session in a group" 3837.It Li "session_height" Ta "" Ta "Height of session" 3838.It Li "session_id" Ta "" Ta "Unique session ID" 3839.It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached" 3840.It Li "session_name" Ta "#S" Ta "Name of session" 3841.It Li "session_stack" Ta "" Ta "Window indexes in most recent order" 3842.It Li "session_width" Ta "" Ta "Width of session" 3843.It Li "session_windows" Ta "" Ta "Number of windows in session" 3844.It Li "socket_path" Ta "" Ta "Server socket path" 3845.It Li "start_time" Ta "" Ta "Server start time" 3846.It Li "window_activity" Ta "" Ta "Time of window last activity" 3847.It Li "window_activity_flag" Ta "" Ta "1 if window has activity" 3848.It Li "window_active" Ta "" Ta "1 if window active" 3849.It Li "window_bell_flag" Ta "" Ta "1 if window has bell" 3850.It Li "window_flags" Ta "#F" Ta "Window flags" 3851.It Li "window_format" Ta "" Ta "1 if format is for a window (not assuming the current)" 3852.It Li "window_height" Ta "" Ta "Height of window" 3853.It Li "window_id" Ta "" Ta "Unique window ID" 3854.It Li "window_index" Ta "#I" Ta "Index of window" 3855.It Li "window_last_flag" Ta "" Ta "1 if window is the last used" 3856.It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes" 3857.It Li "window_linked" Ta "" Ta "1 if window is linked across sessions" 3858.It Li "window_name" Ta "#W" Ta "Name of window" 3859.It Li "window_panes" Ta "" Ta "Number of panes in window" 3860.It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert" 3861.It Li "window_stack_index" Ta "" Ta "Index in session most recent stack" 3862.It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes" 3863.It Li "window_width" Ta "" Ta "Width of window" 3864.It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed" 3865.It Li "wrap_flag" Ta "" Ta "Pane wrap flag" 3866.El 3867.Sh NAMES AND TITLES 3868.Nm 3869distinguishes between names and titles. 3870Windows and sessions have names, which may be used to specify them in targets 3871and are displayed in the status line and various lists: the name is the 3872.Nm 3873identifier for a window or session. 3874Only panes have titles. 3875A pane's title is typically set by the program running inside the pane using 3876an escape sequence (like it would set the 3877.Xr xterm 1 3878window title in 3879.Xr X 7 ) . 3880Windows themselves do not have titles - a window's title is the title of its 3881active pane. 3882.Nm 3883itself may set the title of the terminal in which the client is running, see 3884the 3885.Ic set-titles 3886option. 3887.Pp 3888A session's name is set with the 3889.Ic new-session 3890and 3891.Ic rename-session 3892commands. 3893A window's name is set with one of: 3894.Bl -enum -width Ds 3895.It 3896A command argument (such as 3897.Fl n 3898for 3899.Ic new-window 3900or 3901.Ic new-session ) . 3902.It 3903An escape sequence (if the 3904.Ic allow-rename 3905option is turned on): 3906.Bd -literal -offset indent 3907$ printf '\e033kWINDOW_NAME\e033\e\e' 3908.Ed 3909.It 3910Automatic renaming, which sets the name to the active command in the window's 3911active pane. 3912See the 3913.Ic automatic-rename 3914option. 3915.El 3916.Pp 3917When a pane is first created, its title is the hostname. 3918A pane's title can be set via the title setting escape sequence, for example: 3919.Bd -literal -offset indent 3920$ printf '\e033]2;My Title\e033\e\e' 3921.Ed 3922.Pp 3923It can also be modified with the 3924.Ic select-pane 3925.Fl T 3926command. 3927.Sh ENVIRONMENT 3928When the server is started, 3929.Nm 3930copies the environment into the 3931.Em global environment ; 3932in addition, each session has a 3933.Em session environment . 3934When a window is created, the session and global environments are merged. 3935If a variable exists in both, the value from the session environment is used. 3936The result is the initial environment passed to the new process. 3937.Pp 3938The 3939.Ic update-environment 3940session option may be used to update the session environment from the client 3941when a new session is created or an old reattached. 3942.Nm 3943also initialises the 3944.Ev TMUX 3945variable with some internal information to allow commands to be executed 3946from inside, and the 3947.Ev TERM 3948variable with the correct terminal setting of 3949.Ql screen . 3950.Pp 3951Commands to alter and view the environment are: 3952.Bl -tag -width Ds 3953.It Xo Ic set-environment 3954.Op Fl gru 3955.Op Fl t Ar target-session 3956.Ar name Op Ar value 3957.Xc 3958.D1 (alias: Ic setenv ) 3959Set or unset an environment variable. 3960If 3961.Fl g 3962is used, the change is made in the global environment; otherwise, it is applied 3963to the session environment for 3964.Ar target-session . 3965The 3966.Fl u 3967flag unsets a variable. 3968.Fl r 3969indicates the variable is to be removed from the environment before starting a 3970new process. 3971.It Xo Ic show-environment 3972.Op Fl gs 3973.Op Fl t Ar target-session 3974.Op Ar variable 3975.Xc 3976.D1 (alias: Ic showenv ) 3977Display the environment for 3978.Ar target-session 3979or the global environment with 3980.Fl g . 3981If 3982.Ar variable 3983is omitted, all variables are shown. 3984Variables removed from the environment are prefixed with 3985.Ql - . 3986If 3987.Fl s 3988is used, the output is formatted as a set of Bourne shell commands. 3989.El 3990.Sh STATUS LINE 3991.Nm 3992includes an optional status line which is displayed in the bottom line of each 3993terminal. 3994By default, the status line is enabled (it may be disabled with the 3995.Ic status 3996session option) and contains, from left-to-right: the name of the current 3997session in square brackets; the window list; the title of the active pane 3998in double quotes; and the time and date. 3999.Pp 4000The status line is made of three parts: configurable left and right sections 4001(which may contain dynamic content such as the time or output from a shell 4002command, see the 4003.Ic status-left , 4004.Ic status-left-length , 4005.Ic status-right , 4006and 4007.Ic status-right-length 4008options below), and a central window list. 4009By default, the window list shows the index, name and (if any) flag of the 4010windows present in the current session in ascending numerical order. 4011It may be customised with the 4012.Ar window-status-format 4013and 4014.Ar window-status-current-format 4015options. 4016The flag is one of the following symbols appended to the window name: 4017.Bl -column "Symbol" "Meaning" -offset indent 4018.It Sy "Symbol" Ta Sy "Meaning" 4019.It Li "*" Ta "Denotes the current window." 4020.It Li "-" Ta "Marks the last window (previously selected)." 4021.It Li "#" Ta "Window activity is monitored and activity has been detected." 4022.It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window." 4023.It Li "~" Ta "The window has been silent for the monitor-silence interval." 4024.It Li "M" Ta "The window contains the marked pane." 4025.It Li "Z" Ta "The window's active pane is zoomed." 4026.El 4027.Pp 4028The # symbol relates to the 4029.Ic monitor-activity 4030window option. 4031The window name is printed in inverted colours if an alert (bell, activity or 4032silence) is present. 4033.Pp 4034The colour and attributes of the status line may be configured, the entire 4035status line using the 4036.Ic status-style 4037session option and individual windows using the 4038.Ic window-status-style 4039window option. 4040.Pp 4041The status line is automatically refreshed at interval if it has changed, the 4042interval may be controlled with the 4043.Ic status-interval 4044session option. 4045.Pp 4046Commands related to the status line are as follows: 4047.Bl -tag -width Ds 4048.It Xo Ic command-prompt 4049.Op Fl 1i 4050.Op Fl I Ar inputs 4051.Op Fl p Ar prompts 4052.Op Fl t Ar target-client 4053.Op Ar template 4054.Xc 4055Open the command prompt in a client. 4056This may be used from inside 4057.Nm 4058to execute commands interactively. 4059.Pp 4060If 4061.Ar template 4062is specified, it is used as the command. 4063If present, 4064.Fl I 4065is a comma-separated list of the initial text for each prompt. 4066If 4067.Fl p 4068is given, 4069.Ar prompts 4070is a comma-separated list of prompts which are displayed in order; otherwise 4071a single prompt is displayed, constructed from 4072.Ar template 4073if it is present, or 4074.Ql \&: 4075if not. 4076.Pp 4077Before the command is executed, the first occurrence of the string 4078.Ql %% 4079and all occurrences of 4080.Ql %1 4081are replaced by the response to the first prompt, all 4082.Ql %2 4083are replaced with the response to the second prompt, and so on for further 4084prompts. 4085Up to nine prompt responses may be replaced 4086.Po 4087.Ql %1 4088to 4089.Ql %9 4090.Pc . 4091.Ql %%% 4092is like 4093.Ql %% 4094but any quotation marks are escaped. 4095.Pp 4096.Fl 1 4097makes the prompt only accept one key press, in this case the resulting input 4098is a single character. 4099.Fl i 4100executes the command every time the prompt input changes instead of when the 4101user exits the command prompt. 4102.Pp 4103The following keys have a special meaning in the command prompt, depending 4104on the value of the 4105.Ic status-keys 4106option: 4107.Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent 4108.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" 4109.It Li "Cancel command prompt" Ta "Escape" Ta "Escape" 4110.It Li "Delete current word" Ta "" Ta "C-w" 4111.It Li "Delete entire command" Ta "d" Ta "C-u" 4112.It Li "Delete from cursor to end" Ta "D" Ta "C-k" 4113.It Li "Execute command" Ta "Enter" Ta "Enter" 4114.It Li "Get next command from history" Ta "" Ta "Down" 4115.It Li "Get previous command from history" Ta "" Ta "Up" 4116.It Li "Insert top paste buffer" Ta "p" Ta "C-y" 4117.It Li "Look for completions" Ta "Tab" Ta "Tab" 4118.It Li "Move cursor left" Ta "h" Ta "Left" 4119.It Li "Move cursor right" Ta "l" Ta "Right" 4120.It Li "Move cursor to end" Ta "$" Ta "C-e" 4121.It Li "Move cursor to next word" Ta "w" Ta "M-f" 4122.It Li "Move cursor to previous word" Ta "b" Ta "M-b" 4123.It Li "Move cursor to start" Ta "0" Ta "C-a" 4124.It Li "Transpose characters" Ta "" Ta "C-t" 4125.El 4126.It Xo Ic confirm-before 4127.Op Fl p Ar prompt 4128.Op Fl t Ar target-client 4129.Ar command 4130.Xc 4131.D1 (alias: Ic confirm ) 4132Ask for confirmation before executing 4133.Ar command . 4134If 4135.Fl p 4136is given, 4137.Ar prompt 4138is the prompt to display; otherwise a prompt is constructed from 4139.Ar command . 4140It may contain the special character sequences supported by the 4141.Ic status-left 4142option. 4143.Pp 4144This command works only from inside 4145.Nm . 4146.It Xo Ic display-message 4147.Op Fl p 4148.Op Fl c Ar target-client 4149.Op Fl t Ar target-pane 4150.Op Ar message 4151.Xc 4152.D1 (alias: Ic display ) 4153Display a message. 4154If 4155.Fl p 4156is given, the output is printed to stdout, otherwise it is displayed in the 4157.Ar target-client 4158status line. 4159The format of 4160.Ar message 4161is described in the 4162.Sx FORMATS 4163section; information is taken from 4164.Ar target-pane 4165if 4166.Fl t 4167is given, otherwise the active pane for the session attached to 4168.Ar target-client . 4169.El 4170.Sh BUFFERS 4171.Nm 4172maintains a set of named 4173.Em paste buffers . 4174Each buffer may be either explicitly or automatically named. 4175Explicitly named buffers are named when created with the 4176.Ic set-buffer 4177or 4178.Ic load-buffer 4179commands, or by renaming an automatically named buffer with 4180.Ic set-buffer 4181.Fl n . 4182Automatically named buffers are given a name such as 4183.Ql buffer0001 , 4184.Ql buffer0002 4185and so on. 4186When the 4187.Ic buffer-limit 4188option is reached, the oldest automatically named buffer is deleted. 4189Explicitly named buffers are not subject to 4190.Ic buffer-limit 4191and may be deleted with 4192.Ic delete-buffer 4193command. 4194.Pp 4195Buffers may be added using 4196.Ic copy-mode 4197or the 4198.Ic set-buffer 4199and 4200.Ic load-buffer 4201commands, and pasted into a window using the 4202.Ic paste-buffer 4203command. 4204If a buffer command is used and no buffer is specified, the most 4205recently added automatically named buffer is assumed. 4206.Pp 4207A configurable history buffer is also maintained for each window. 4208By default, up to 2000 lines are kept; this can be altered with the 4209.Ic history-limit 4210option (see the 4211.Ic set-option 4212command above). 4213.Pp 4214The buffer commands are as follows: 4215.Bl -tag -width Ds 4216.It Xo 4217.Ic choose-buffer 4218.Op Fl NZ 4219.Op Fl F Ar format 4220.Op Fl f Ar filter 4221.Op Fl O Ar sort-order 4222.Op Fl t Ar target-pane 4223.Op Ar template 4224.Xc 4225Put a pane into buffer mode, where a buffer may be chosen interactively from 4226a list. 4227.Fl Z 4228zooms the pane. 4229The following keys may be used in buffer mode: 4230.Bl -column "Key" "Function" -offset indent 4231.It Sy "Key" Ta Sy "Function" 4232.It Li "Enter" Ta "Paste selected buffer" 4233.It Li "Up" Ta "Select previous buffer" 4234.It Li "Down" Ta "Select next buffer" 4235.It Li "C-s" Ta "Search by name or content" 4236.It Li "n" Ta "Repeat last search" 4237.It Li "t" Ta "Toggle if buffer is tagged" 4238.It Li "T" Ta "Tag no buffers" 4239.It Li "C-t" Ta "Tag all buffers" 4240.It Li "p" Ta "Paste selected buffer" 4241.It Li "P" Ta "Paste tagged buffers" 4242.It Li "d" Ta "Delete selected buffer" 4243.It Li "D" Ta "Delete tagged buffers" 4244.It Li "f" Ta "Enter a format to filter items" 4245.It Li "O" Ta "Change sort order" 4246.It Li "v" Ta "Toggle preview" 4247.It Li "q" Ta "Exit mode" 4248.El 4249.Pp 4250After a buffer is chosen, 4251.Ql %% 4252is replaced by the buffer name in 4253.Ar template 4254and the result executed as a command. 4255If 4256.Ar template 4257is not given, "paste-buffer -b '%%'" is used. 4258.Pp 4259.Fl O 4260specifies the initial sort order: one of 4261.Ql time , 4262.Ql name 4263or 4264.Ql size . 4265.Fl f 4266specifies an initial filter: the filter is a format - if it evaluates to zero, 4267the item in the list is not shown, otherwise it is shown. 4268If a filter would lead to an empty list, it is ignored. 4269.Fl F 4270specifies the format for each item in the list. 4271.Fl N 4272starts without the preview. 4273This command works only if at least one client is attached. 4274.It Ic clear-history Op Fl t Ar target-pane 4275.D1 (alias: Ic clearhist ) 4276Remove and free the history for the specified pane. 4277.It Ic delete-buffer Op Fl b Ar buffer-name 4278.D1 (alias: Ic deleteb ) 4279Delete the buffer named 4280.Ar buffer-name , 4281or the most recently added automatically named buffer if not specified. 4282.It Xo Ic list-buffers 4283.Op Fl F Ar format 4284.Xc 4285.D1 (alias: Ic lsb ) 4286List the global buffers. 4287For the meaning of the 4288.Fl F 4289flag, see the 4290.Sx FORMATS 4291section. 4292.It Xo Ic load-buffer 4293.Op Fl b Ar buffer-name 4294.Ar path 4295.Xc 4296.D1 (alias: Ic loadb ) 4297Load the contents of the specified paste buffer from 4298.Ar path . 4299.It Xo Ic paste-buffer 4300.Op Fl dpr 4301.Op Fl b Ar buffer-name 4302.Op Fl s Ar separator 4303.Op Fl t Ar target-pane 4304.Xc 4305.D1 (alias: Ic pasteb ) 4306Insert the contents of a paste buffer into the specified pane. 4307If not specified, paste into the current one. 4308With 4309.Fl d , 4310also delete the paste buffer. 4311When output, any linefeed (LF) characters in the paste buffer are replaced with 4312a separator, by default carriage return (CR). 4313A custom separator may be specified using the 4314.Fl s 4315flag. 4316The 4317.Fl r 4318flag means to do no replacement (equivalent to a separator of LF). 4319If 4320.Fl p 4321is specified, paste bracket control codes are inserted around the 4322buffer if the application has requested bracketed paste mode. 4323.It Xo Ic save-buffer 4324.Op Fl a 4325.Op Fl b Ar buffer-name 4326.Ar path 4327.Xc 4328.D1 (alias: Ic saveb ) 4329Save the contents of the specified paste buffer to 4330.Ar path . 4331The 4332.Fl a 4333option appends to rather than overwriting the file. 4334.It Xo Ic set-buffer 4335.Op Fl a 4336.Op Fl b Ar buffer-name 4337.Op Fl n Ar new-buffer-name 4338.Ar data 4339.Xc 4340.D1 (alias: Ic setb ) 4341Set the contents of the specified buffer to 4342.Ar data . 4343The 4344.Fl a 4345option appends to rather than overwriting the buffer. 4346The 4347.Fl n 4348option renames the buffer to 4349.Ar new-buffer-name . 4350.It Xo Ic show-buffer 4351.Op Fl b Ar buffer-name 4352.Xc 4353.D1 (alias: Ic showb ) 4354Display the contents of the specified buffer. 4355.El 4356.Sh MISCELLANEOUS 4357Miscellaneous commands are as follows: 4358.Bl -tag -width Ds 4359.It Ic clock-mode Op Fl t Ar target-pane 4360Display a large clock. 4361.It Xo Ic if-shell 4362.Op Fl bF 4363.Op Fl t Ar target-pane 4364.Ar shell-command command 4365.Op Ar command 4366.Xc 4367.D1 (alias: Ic if ) 4368Execute the first 4369.Ar command 4370if 4371.Ar shell-command 4372returns success or the second 4373.Ar command 4374otherwise. 4375Before being executed, 4376.Ar shell-command 4377is expanded using the rules specified in the 4378.Sx FORMATS 4379section, including those relevant to 4380.Ar target-pane . 4381With 4382.Fl b , 4383.Ar shell-command 4384is run in the background. 4385.Pp 4386If 4387.Fl F 4388is given, 4389.Ar shell-command 4390is not executed but considered success if neither empty nor zero (after formats 4391are expanded). 4392.It Ic lock-server 4393.D1 (alias: Ic lock ) 4394Lock each client individually by running the command specified by the 4395.Ic lock-command 4396option. 4397.It Xo Ic run-shell 4398.Op Fl b 4399.Op Fl t Ar target-pane 4400.Ar shell-command 4401.Xc 4402.D1 (alias: Ic run ) 4403Execute 4404.Ar shell-command 4405in the background without creating a window. 4406Before being executed, shell-command is expanded using the rules specified in 4407the 4408.Sx FORMATS 4409section. 4410With 4411.Fl b , 4412the command is run in the background. 4413After it finishes, any output to stdout is displayed in copy mode (in the pane 4414specified by 4415.Fl t 4416or the current pane if omitted). 4417If the command doesn't return success, the exit status is also displayed. 4418.It Xo Ic wait-for 4419.Op Fl L | S | U 4420.Ar channel 4421.Xc 4422.D1 (alias: Ic wait ) 4423When used without options, prevents the client from exiting until woken using 4424.Ic wait-for 4425.Fl S 4426with the same channel. 4427When 4428.Fl L 4429is used, the channel is locked and any clients that try to lock the same 4430channel are made to wait until the channel is unlocked with 4431.Ic wait-for 4432.Fl U . 4433.El 4434.Sh TERMINFO EXTENSIONS 4435.Nm 4436understands some unofficial extensions to 4437.Xr terminfo 5 : 4438.Bl -tag -width Ds 4439.It Em Cs , Cr 4440Set the cursor colour. 4441The first takes a single string argument and is used to set the colour; 4442the second takes no arguments and restores the default cursor colour. 4443If set, a sequence such as this may be used 4444to change the cursor colour from inside 4445.Nm : 4446.Bd -literal -offset indent 4447$ printf '\e033]12;red\e033\e\e' 4448.Ed 4449.It Em \&Smulx 4450Set a styled underline. 4451The single parameter is one of: 0 for no underline, 1 for normal 4452underline, 2 for double underline, 3 for curly underline, 4 for dotted 4453underline and 5 for dashed underline. 4454.It Em \&Ss , Se 4455Set or reset the cursor style. 4456If set, a sequence such as this may be used 4457to change the cursor to an underline: 4458.Bd -literal -offset indent 4459$ printf '\e033[4 q' 4460.Ed 4461.Pp 4462If 4463.Em Se 4464is not set, \&Ss with argument 0 will be used to reset the cursor style instead. 4465.It Em \&Tc 4466Indicate that the terminal supports the 4467.Ql direct colour 4468RGB escape sequence (for example, \ee[38;2;255;255;255m). 4469.Pp 4470If supported, this is used for the initialize colour escape sequence (which 4471may be enabled by adding the 4472.Ql initc 4473and 4474.Ql ccc 4475capabilities to the 4476.Nm 4477.Xr terminfo 5 4478entry). 4479.It Em \&Ms 4480Store the current buffer in the host terminal's selection (clipboard). 4481See the 4482.Em set-clipboard 4483option above and the 4484.Xr xterm 1 4485man page. 4486.El 4487.Sh CONTROL MODE 4488.Nm 4489offers a textual interface called 4490.Em control mode . 4491This allows applications to communicate with 4492.Nm 4493using a simple text-only protocol. 4494.Pp 4495In control mode, a client sends 4496.Nm 4497commands or command sequences terminated by newlines on standard input. 4498Each command will produce one block of output on standard output. 4499An output block consists of a 4500.Em %begin 4501line followed by the output (which may be empty). 4502The output block ends with a 4503.Em %end 4504or 4505.Em %error . 4506.Em %begin 4507and matching 4508.Em %end 4509or 4510.Em %error 4511have two arguments: an integer time (as seconds from epoch) and command number. 4512For example: 4513.Bd -literal -offset indent 4514%begin 1363006971 2 45150: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) 4516%end 1363006971 2 4517.Ed 4518.Pp 4519The 4520.Ic refresh-client 4521.Fl C 4522command may be used to set the size of a client in control mode. 4523.Pp 4524In control mode, 4525.Nm 4526outputs notifications. 4527A notification will never occur inside an output block. 4528.Pp 4529The following notifications are defined: 4530.Bl -tag -width Ds 4531.It Ic %client-session-changed Ar client Ar session-id Ar name 4532The client is now attached to the session with ID 4533.Ar session-id , 4534which is named 4535.Ar name . 4536.It Ic %exit Op Ar reason 4537The 4538.Nm 4539client is exiting immediately, either because it is not attached to any session 4540or an error occurred. 4541If present, 4542.Ar reason 4543describes why the client exited. 4544.It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags 4545The layout of a window with ID 4546.Ar window-id 4547changed. 4548The new layout is 4549.Ar window-layout . 4550The window's visible layout is 4551.Ar window-visible-layout 4552and the window flags are 4553.Ar window-flags . 4554.It Ic %output Ar pane-id Ar value 4555A window pane produced output. 4556.Ar value 4557escapes non-printable characters and backslash as octal \\xxx. 4558.It Ic %pane-mode-changed Ar pane-id 4559The pane with ID 4560.Ar pane-id 4561has changed mode. 4562.It Ic %session-changed Ar session-id Ar name 4563The client is now attached to the session with ID 4564.Ar session-id , 4565which is named 4566.Ar name . 4567.It Ic %session-renamed Ar name 4568The current session was renamed to 4569.Ar name . 4570.It Ic %session-window-changed Ar session-id Ar window-id 4571The session with ID 4572.Ar session-id 4573changed its active window to the window with ID 4574.Ar window-id . 4575.It Ic %sessions-changed 4576A session was created or destroyed. 4577.It Ic %unlinked-window-add Ar window-id 4578The window with ID 4579.Ar window-id 4580was created but is not linked to the current session. 4581.It Ic %window-add Ar window-id 4582The window with ID 4583.Ar window-id 4584was linked to the current session. 4585.It Ic %window-close Ar window-id 4586The window with ID 4587.Ar window-id 4588closed. 4589.It Ic %window-pane-changed Ar window-id Ar pane-id 4590The active pane in the window with ID 4591.Ar window-id 4592changed to the pane with ID 4593.Ar pane-id . 4594.It Ic %window-renamed Ar window-id Ar name 4595The window with ID 4596.Ar window-id 4597was renamed to 4598.Ar name . 4599.El 4600.Sh FILES 4601.Bl -tag -width "/etc/tmux.confXXX" -compact 4602.It Pa ~/.tmux.conf 4603Default 4604.Nm 4605configuration file. 4606.It Pa /etc/tmux.conf 4607System-wide configuration file. 4608.El 4609.Sh EXAMPLES 4610To create a new 4611.Nm 4612session running 4613.Xr vi 1 : 4614.Pp 4615.Dl $ tmux new-session vi 4616.Pp 4617Most commands have a shorter form, known as an alias. 4618For new-session, this is 4619.Ic new : 4620.Pp 4621.Dl $ tmux new vi 4622.Pp 4623Alternatively, the shortest unambiguous form of a command is accepted. 4624If there are several options, they are listed: 4625.Bd -literal -offset indent 4626$ tmux n 4627ambiguous command: n, could be: new-session, new-window, next-window 4628.Ed 4629.Pp 4630Within an active session, a new window may be created by typing 4631.Ql C-b c 4632(Ctrl 4633followed by the 4634.Ql b 4635key 4636followed by the 4637.Ql c 4638key). 4639.Pp 4640Windows may be navigated with: 4641.Ql C-b 0 4642(to select window 0), 4643.Ql C-b 1 4644(to select window 1), and so on; 4645.Ql C-b n 4646to select the next window; and 4647.Ql C-b p 4648to select the previous window. 4649.Pp 4650A session may be detached using 4651.Ql C-b d 4652(or by an external event such as 4653.Xr ssh 1 4654disconnection) and reattached with: 4655.Pp 4656.Dl $ tmux attach-session 4657.Pp 4658Typing 4659.Ql C-b \&? 4660lists the current key bindings in the current window; up and down may be used 4661to navigate the list or 4662.Ql q 4663to exit from it. 4664.Pp 4665Commands to be run when the 4666.Nm 4667server is started may be placed in the 4668.Pa ~/.tmux.conf 4669configuration file. 4670Common examples include: 4671.Pp 4672Changing the default prefix key: 4673.Bd -literal -offset indent 4674set-option -g prefix C-a 4675unbind-key C-b 4676bind-key C-a send-prefix 4677.Ed 4678.Pp 4679Turning the status line off, or changing its colour: 4680.Bd -literal -offset indent 4681set-option -g status off 4682set-option -g status-style bg=blue 4683.Ed 4684.Pp 4685Setting other options, such as the default command, 4686or locking after 30 minutes of inactivity: 4687.Bd -literal -offset indent 4688set-option -g default-command "exec /bin/ksh" 4689set-option -g lock-after-time 1800 4690.Ed 4691.Pp 4692Creating new key bindings: 4693.Bd -literal -offset indent 4694bind-key b set-option status 4695bind-key / command-prompt "split-window 'exec man %%'" 4696bind-key S command-prompt "new-window -n %1 'ssh %1'" 4697.Ed 4698.Sh SEE ALSO 4699.Xr pty 4 4700.Sh AUTHORS 4701.An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com 4702