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