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