1.\" $OpenBSD: tmux.1,v 1.809 2021/01/01 08:36:51 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 1 2021 $ 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 2CDluvV 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 Fl T Ar features 32.Op Ar command Op Ar flags 33.Ek 34.Sh DESCRIPTION 35.Nm 36is a terminal multiplexer: 37it enables a number of terminals to be created, accessed, and 38controlled from a single screen. 39.Nm 40may be detached from a screen 41and continue running in the background, 42then later reattached. 43.Pp 44When 45.Nm 46is started it creates a new 47.Em session 48with a single 49.Em window 50and displays it on screen. 51A status line at the bottom of the screen 52shows information on the current session 53and is used to enter interactive commands. 54.Pp 55A session is a single collection of 56.Em pseudo terminals 57under the management of 58.Nm . 59Each session has one or more 60windows linked to it. 61A window occupies the entire screen 62and may be split into rectangular panes, 63each of which is a separate pseudo terminal 64(the 65.Xr pty 4 66manual page documents the technical details of pseudo terminals). 67Any number of 68.Nm 69instances may connect to the same session, 70and any number of windows may be present in the same session. 71Once all sessions are killed, 72.Nm 73exits. 74.Pp 75Each session is persistent and will survive accidental disconnection 76(such as 77.Xr ssh 1 78connection timeout) or intentional detaching (with the 79.Ql C-b d 80key strokes). 81.Nm 82may be reattached using: 83.Pp 84.Dl $ tmux attach 85.Pp 86In 87.Nm , 88a session is displayed on screen by a 89.Em client 90and all sessions are managed by a single 91.Em server . 92The server and each client are separate processes which communicate through a 93socket in 94.Pa /tmp . 95.Pp 96The options are as follows: 97.Bl -tag -width "XXXXXXXXXXXX" 98.It Fl 2 99Force 100.Nm 101to assume the terminal supports 256 colours. 102This is equivalent to 103.Fl T Ar 256 . 104.It Fl C 105Start in control mode (see the 106.Sx CONTROL MODE 107section). 108Given twice 109.Xo ( Fl CC ) Xc 110disables echo. 111.It Fl c Ar shell-command 112Execute 113.Ar shell-command 114using the default shell. 115If necessary, the 116.Nm 117server will be started to retrieve the 118.Ic default-shell 119option. 120This option is for compatibility with 121.Xr sh 1 122when 123.Nm 124is used as a login shell. 125.It Fl D 126Do not start the 127.Nm 128server as a daemon. 129This also turns the 130.Ic exit-empty 131option off. 132With 133.Fl D , 134.Ar command 135may not be specified. 136.It Fl f Ar file 137Specify an alternative configuration file. 138By default, 139.Nm 140loads the system configuration file from 141.Pa /etc/tmux.conf , 142if present, then looks for a user configuration file at 143.Pa ~/.tmux.conf . 144.Pp 145The configuration file is a set of 146.Nm 147commands which are executed in sequence when the server is first started. 148.Nm 149loads configuration files once when the server process has started. 150The 151.Ic source-file 152command may be used to load a file later. 153.Pp 154.Nm 155shows any error messages from commands in configuration files in the first 156session created, and continues to process the rest of the configuration file. 157.It Fl L Ar socket-name 158.Nm 159stores the server socket in a directory under 160.Ev TMUX_TMPDIR 161or 162.Pa /tmp 163if it is unset. 164The default socket is named 165.Em default . 166This option allows a different socket name to be specified, allowing several 167independent 168.Nm 169servers to be run. 170Unlike 171.Fl S 172a full path is not necessary: the sockets are all created in a directory 173.Pa tmux-UID 174under the directory given by 175.Ev TMUX_TMPDIR 176or in 177.Pa /tmp . 178The 179.Pa tmux-UID 180directory is created by 181.Nm 182and must not be world readable, writable or executable. 183.Pp 184If the socket is accidentally removed, the 185.Dv SIGUSR1 186signal may be sent to the 187.Nm 188server process to recreate it (note that this will fail if any parent 189directories are missing). 190.It Fl l 191Behave as a login shell. 192This flag currently has no effect and is for compatibility with other shells 193when using tmux as a login shell. 194.It Fl S Ar socket-path 195Specify a full alternative path to the server socket. 196If 197.Fl S 198is specified, the default socket directory is not used and any 199.Fl L 200flag is ignored. 201.It Fl u 202Write UTF-8 output to the terminal even if the first environment 203variable of 204.Ev LC_ALL , 205.Ev LC_CTYPE , 206or 207.Ev LANG 208that is set does not contain 209.Qq UTF-8 210or 211.Qq UTF8 . 212This is equivalent to 213.Fl T Ar UTF-8 . 214.It Fl T Ar features 215Set terminal features for the client. 216This is a comma-separated list of features. 217See the 218.Ic terminal-features 219option. 220.It Fl v 221Request verbose logging. 222Log messages will be saved into 223.Pa tmux-client-PID.log 224and 225.Pa tmux-server-PID.log 226files in the current directory, where 227.Em PID 228is the PID of the server or client process. 229If 230.Fl v 231is specified twice, an additional 232.Pa tmux-out-PID.log 233file is generated with a copy of everything 234.Nm 235writes to the terminal. 236.Pp 237The 238.Dv SIGUSR2 239signal may be sent to the 240.Nm 241server process to toggle logging between on (as if 242.Fl v 243was given) and off. 244.It Fl V 245Report the 246.Nm 247version. 248.It Ar command Op Ar flags 249This specifies one of a set of commands used to control 250.Nm , 251as described in the following sections. 252If no commands are specified, the 253.Ic new-session 254command is assumed. 255.El 256.Sh DEFAULT KEY BINDINGS 257.Nm 258may be controlled from an attached client by using a key combination of a 259prefix key, 260.Ql C-b 261(Ctrl-b) by default, followed by a command key. 262.Pp 263The default command key bindings are: 264.Pp 265.Bl -tag -width "XXXXXXXXXX" -offset indent -compact 266.It C-b 267Send the prefix key (C-b) through to the application. 268.It C-o 269Rotate the panes in the current window forwards. 270.It C-z 271Suspend the 272.Nm 273client. 274.It ! 275Break the current pane out of the window. 276.It \&" 277.\" " 278Split the current pane into two, top and bottom. 279.It # 280List all paste buffers. 281.It $ 282Rename the current session. 283.It % 284Split the current pane into two, left and right. 285.It & 286Kill the current window. 287.It ' 288Prompt for a window index to select. 289.It \&( 290Switch the attached client to the previous session. 291.It \&) 292Switch the attached client to the next session. 293.It , 294Rename the current window. 295.It - 296Delete the most recently copied buffer of text. 297.It . 298Prompt for an index to move the current window. 299.It 0 to 9 300Select windows 0 to 9. 301.It : 302Enter the 303.Nm 304command prompt. 305.It ; 306Move to the previously active pane. 307.It = 308Choose which buffer to paste interactively from a list. 309.It \&? 310List all key bindings. 311.It D 312Choose a client to detach. 313.It L 314Switch the attached client back to the last session. 315.It \&[ 316Enter copy mode to copy text or view the history. 317.It \&] 318Paste the most recently copied buffer of text. 319.It c 320Create a new window. 321.It d 322Detach the current client. 323.It f 324Prompt to search for text in open windows. 325.It i 326Display some information about the current window. 327.It l 328Move to the previously selected window. 329.It m 330Mark the current pane (see 331.Ic select-pane 332.Fl m ) . 333.It M 334Clear the marked pane. 335.It n 336Change to the next window. 337.It o 338Select the next pane in the current window. 339.It p 340Change to the previous window. 341.It q 342Briefly display pane indexes. 343.It r 344Force redraw of the attached client. 345.It s 346Select a new session for the attached client interactively. 347.It t 348Show the time. 349.It w 350Choose the current window interactively. 351.It x 352Kill the current pane. 353.It z 354Toggle zoom state of the current pane. 355.It { 356Swap the current pane with the previous pane. 357.It } 358Swap the current pane with the next pane. 359.It ~ 360Show previous messages from 361.Nm , 362if any. 363.It Page Up 364Enter copy mode and scroll one page up. 365.It Up, Down 366.It Left, Right 367Change to the pane above, below, to the left, or to the right of the current 368pane. 369.It M-1 to M-5 370Arrange panes in one of the five preset layouts: even-horizontal, 371even-vertical, main-horizontal, main-vertical, or tiled. 372.It Space 373Arrange the current window in the next preset layout. 374.It M-n 375Move to the next window with a bell or activity marker. 376.It M-o 377Rotate the panes in the current window backwards. 378.It M-p 379Move to the previous window with a bell or activity marker. 380.It C-Up, C-Down 381.It C-Left, C-Right 382Resize the current pane in steps of one cell. 383.It M-Up, M-Down 384.It M-Left, M-Right 385Resize the current pane in steps of five cells. 386.El 387.Pp 388Key bindings may be changed with the 389.Ic bind-key 390and 391.Ic unbind-key 392commands. 393.Sh COMMAND PARSING AND EXECUTION 394.Nm 395supports a large number of commands which can be used to control its 396behaviour. 397Each command is named and can accept zero or more flags and arguments. 398They may be bound to a key with the 399.Ic bind-key 400command or run from the shell prompt, a shell script, a configuration file or 401the command prompt. 402For example, the same 403.Ic set-option 404command run from the shell prompt, from 405.Pa ~/.tmux.conf 406and bound to a key may look like: 407.Bd -literal -offset indent 408$ tmux set-option -g status-style bg=cyan 409 410set-option -g status-style bg=cyan 411 412bind-key C set-option -g status-style bg=cyan 413.Ed 414.Pp 415Here, the command name is 416.Ql set-option , 417.Ql Fl g 418is a flag and 419.Ql status-style 420and 421.Ql bg=cyan 422are arguments. 423.Pp 424.Nm 425distinguishes between command parsing and execution. 426In order to execute a command, 427.Nm 428needs it to be split up into its name and arguments. 429This is command parsing. 430If a command is run from the shell, the shell parses it; from inside 431.Nm 432or from a configuration file, 433.Nm 434does. 435Examples of when 436.Nm 437parses commands are: 438.Bl -dash -offset indent 439.It 440in a configuration file; 441.It 442typed at the command prompt (see 443.Ic command-prompt ) ; 444.It 445given to 446.Ic bind-key ; 447.It 448passed as arguments to 449.Ic if-shell 450or 451.Ic confirm-before . 452.El 453.Pp 454To execute commands, each client has a 455.Ql command queue . 456A global command queue not attached to any client is used on startup 457for configuration files like 458.Pa ~/.tmux.conf . 459Parsed commands added to the queue are executed in order. 460Some commands, like 461.Ic if-shell 462and 463.Ic confirm-before , 464parse their argument to create a new command which is inserted immediately 465after themselves. 466This means that arguments can be parsed twice or more - once when the parent command (such as 467.Ic if-shell ) 468is parsed and again when it parses and executes its command. 469Commands like 470.Ic if-shell , 471.Ic run-shell 472and 473.Ic display-panes 474stop execution of subsequent commands on the queue until something happens - 475.Ic if-shell 476and 477.Ic run-shell 478until a shell command finishes and 479.Ic display-panes 480until a key is pressed. 481For example, the following commands: 482.Bd -literal -offset indent 483new-session; new-window 484if-shell "true" "split-window" 485kill-session 486.Ed 487.Pp 488Will execute 489.Ic new-session , 490.Ic new-window , 491.Ic if-shell , 492the shell command 493.Xr true 1 , 494.Ic split-window 495and 496.Ic kill-session 497in that order. 498.Pp 499The 500.Sx COMMANDS 501section lists the 502.Nm 503commands and their arguments. 504.Sh PARSING SYNTAX 505This section describes the syntax of commands parsed by 506.Nm , 507for example in a configuration file or at the command prompt. 508Note that when commands are entered into the shell, they are parsed by the shell 509- see for example 510.Xr ksh 1 511or 512.Xr csh 1 . 513.Pp 514Each command is terminated by a newline or a semicolon (;). 515Commands separated by semicolons together form a 516.Ql command sequence 517- if a command in the sequence encounters an error, no subsequent commands are 518executed. 519.Pp 520Comments are marked by the unquoted # character - any remaining text after a 521comment is ignored until the end of the line. 522.Pp 523If the last character of a line is \e, the line is joined with the following 524line (the \e and the newline are completely removed). 525This is called line continuation and applies both inside and outside quoted 526strings and in comments, but not inside braces. 527.Pp 528Command arguments may be specified as strings surrounded by single (') quotes, 529double quotes (") or braces ({}). 530.\" " 531This is required when the argument contains any special character. 532Single and double quoted strings cannot span multiple lines except with line 533continuation. 534Braces can span multiple lines. 535.Pp 536Outside of quotes and inside double quotes, these replacements are performed: 537.Bl -dash -offset indent 538.It 539Environment variables preceded by $ are replaced with their value from the 540global environment (see the 541.Sx GLOBAL AND SESSION ENVIRONMENT 542section). 543.It 544A leading ~ or ~user is expanded to the home directory of the current or 545specified user. 546.It 547\euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to 548the given four or eight digit hexadecimal number. 549.It 550When preceded (escaped) by a \e, the following characters are replaced: \ee by 551the escape character; \er by a carriage return; \en by a newline; and \et by a 552tab. 553.It 554\eooo is replaced by a character of the octal value ooo. 555Three octal digits are required, for example \e001. 556The largest valid character is \e377. 557.It 558Any other characters preceded by \e are replaced by themselves (that is, the \e 559is removed) and are not treated as having any special meaning - so for example 560\e; will not mark a command sequence and \e$ will not expand an environment 561variable. 562.El 563.Pp 564Braces are parsed as a configuration file (so conditions such as 565.Ql %if 566are processed) and then converted into a string. 567They are designed to avoid the need for additional escaping when passing a 568group of 569.Nm 570commands as an argument (for example to 571.Ic if-shell ) . 572These two examples produce an identical command - note that no escaping is 573needed when using {}: 574.Bd -literal -offset indent 575if-shell true { 576 display -p 'brace-dollar-foo: }$foo' 577} 578 579if-shell true "display -p 'brace-dollar-foo: }\e$foo'" 580.Ed 581.Pp 582Braces may be enclosed inside braces, for example: 583.Bd -literal -offset indent 584bind x if-shell "true" { 585 if-shell "true" { 586 display "true!" 587 } 588} 589.Ed 590.Pp 591Environment variables may be set by using the syntax 592.Ql name=value , 593for example 594.Ql HOME=/home/user . 595Variables set during parsing are added to the global environment. 596A hidden variable may be set with 597.Ql %hidden , 598for example: 599.Bd -literal -offset indent 600%hidden MYVAR=42 601.Ed 602.Pp 603Hidden variables are not passed to the environment of processes created 604by tmux. 605See the 606.Sx GLOBAL AND SESSION ENVIRONMENT 607section. 608.Pp 609Commands may be parsed conditionally by surrounding them with 610.Ql %if , 611.Ql %elif , 612.Ql %else 613and 614.Ql %endif . 615The argument to 616.Ql %if 617and 618.Ql %elif 619is expanded as a format (see 620.Sx FORMATS ) 621and if it evaluates to false (zero or empty), subsequent text is ignored until 622the closing 623.Ql %elif , 624.Ql %else 625or 626.Ql %endif . 627For example: 628.Bd -literal -offset indent 629%if "#{==:#{host},myhost}" 630set -g status-style bg=red 631%elif "#{==:#{host},myotherhost}" 632set -g status-style bg=green 633%else 634set -g status-style bg=blue 635%endif 636.Ed 637.Pp 638Will change the status line to red if running on 639.Ql myhost , 640green if running on 641.Ql myotherhost , 642or blue if running on another host. 643Conditionals may be given on one line, for example: 644.Bd -literal -offset indent 645%if #{==:#{host},myhost} set -g status-style bg=red %endif 646.Ed 647.Sh COMMANDS 648This section describes the commands supported by 649.Nm . 650Most commands accept the optional 651.Fl t 652(and sometimes 653.Fl s ) 654argument with one of 655.Ar target-client , 656.Ar target-session , 657.Ar target-window , 658or 659.Ar target-pane . 660These specify the client, session, window or pane which a command should affect. 661.Pp 662.Ar target-client 663should be the name of the client, 664typically the 665.Xr pty 4 666file to which the client is connected, for example either of 667.Pa /dev/ttyp1 668or 669.Pa ttyp1 670for the client attached to 671.Pa /dev/ttyp1 . 672If no client is specified, 673.Nm 674attempts to work out the client currently in use; if that fails, an error is 675reported. 676Clients may be listed with the 677.Ic list-clients 678command. 679.Pp 680.Ar target-session 681is tried as, in order: 682.Bl -enum -offset Ds 683.It 684A session ID prefixed with a $. 685.It 686An exact name of a session (as listed by the 687.Ic list-sessions 688command). 689.It 690The start of a session name, for example 691.Ql mysess 692would match a session named 693.Ql mysession . 694.It 695An 696.Xr fnmatch 3 697pattern which is matched against the session name. 698.El 699.Pp 700If the session name is prefixed with an 701.Ql = , 702only an exact match is accepted (so 703.Ql =mysess 704will only match exactly 705.Ql mysess , 706not 707.Ql mysession ) . 708.Pp 709If a single session is found, it is used as the target session; multiple matches 710produce an error. 711If a session is omitted, the current session is used if available; if no 712current session is available, the most recently used is chosen. 713.Pp 714.Ar target-window 715(or 716.Ar src-window 717or 718.Ar dst-window ) 719specifies a window in the form 720.Em session Ns \&: Ns Em window . 721.Em session 722follows the same rules as for 723.Ar target-session , 724and 725.Em window 726is looked for in order as: 727.Bl -enum -offset Ds 728.It 729A special token, listed below. 730.It 731A window index, for example 732.Ql mysession:1 733is window 1 in session 734.Ql mysession . 735.It 736A window ID, such as @1. 737.It 738An exact window name, such as 739.Ql mysession:mywindow . 740.It 741The start of a window name, such as 742.Ql mysession:mywin . 743.It 744As an 745.Xr fnmatch 3 746pattern matched against the window name. 747.El 748.Pp 749Like sessions, a 750.Ql = 751prefix will do an exact match only. 752An empty window name specifies the next unused index if appropriate (for 753example the 754.Ic new-window 755and 756.Ic link-window 757commands) 758otherwise the current window in 759.Em session 760is chosen. 761.Pp 762The following special tokens are available to indicate particular windows. 763Each has a single-character alternative form. 764.Bl -column "XXXXXXXXXX" "X" 765.It Sy "Token" Ta Sy "" Ta Sy "Meaning" 766.It Li "{start}" Ta "^" Ta "The lowest-numbered window" 767.It Li "{end}" Ta "$" Ta "The highest-numbered window" 768.It Li "{last}" Ta "!" Ta "The last (previously current) window" 769.It Li "{next}" Ta "+" Ta "The next window by number" 770.It Li "{previous}" Ta "-" Ta "The previous window by number" 771.El 772.Pp 773.Ar target-pane 774(or 775.Ar src-pane 776or 777.Ar dst-pane ) 778may be a pane ID or takes a similar form to 779.Ar target-window 780but with the optional addition of a period followed by a pane index or pane ID, 781for example: 782.Ql mysession:mywindow.1 . 783If the pane index is omitted, the currently active pane in the specified 784window is used. 785The following special tokens are available for the pane index: 786.Bl -column "XXXXXXXXXXXXXX" "X" 787.It Sy "Token" Ta Sy "" Ta Sy "Meaning" 788.It Li "{last}" Ta "!" Ta "The last (previously active) pane" 789.It Li "{next}" Ta "+" Ta "The next pane by number" 790.It Li "{previous}" Ta "-" Ta "The previous pane by number" 791.It Li "{top}" Ta "" Ta "The top pane" 792.It Li "{bottom}" Ta "" Ta "The bottom pane" 793.It Li "{left}" Ta "" Ta "The leftmost pane" 794.It Li "{right}" Ta "" Ta "The rightmost pane" 795.It Li "{top-left}" Ta "" Ta "The top-left pane" 796.It Li "{top-right}" Ta "" Ta "The top-right pane" 797.It Li "{bottom-left}" Ta "" Ta "The bottom-left pane" 798.It Li "{bottom-right}" Ta "" Ta "The bottom-right pane" 799.It Li "{up-of}" Ta "" Ta "The pane above the active pane" 800.It Li "{down-of}" Ta "" Ta "The pane below the active pane" 801.It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane" 802.It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane" 803.El 804.Pp 805The tokens 806.Ql + 807and 808.Ql - 809may be followed by an offset, for example: 810.Bd -literal -offset indent 811select-window -t:+2 812.Ed 813.Pp 814In addition, 815.Em target-session , 816.Em target-window 817or 818.Em target-pane 819may consist entirely of the token 820.Ql {mouse} 821(alternative form 822.Ql = ) 823to specify the session, window or pane where the most recent mouse event occurred 824(see the 825.Sx MOUSE SUPPORT 826section) 827or 828.Ql {marked} 829(alternative form 830.Ql ~ ) 831to specify the marked pane (see 832.Ic select-pane 833.Fl m ) . 834.Pp 835Sessions, window and panes are each numbered with a unique ID; session IDs are 836prefixed with a 837.Ql $ , 838windows with a 839.Ql @ , 840and panes with a 841.Ql % . 842These are unique and are unchanged for the life of the session, window or pane 843in the 844.Nm 845server. 846The pane ID is passed to the child process of the pane in the 847.Ev TMUX_PANE 848environment variable. 849IDs may be displayed using the 850.Ql session_id , 851.Ql window_id , 852or 853.Ql pane_id 854formats (see the 855.Sx FORMATS 856section) and the 857.Ic display-message , 858.Ic list-sessions , 859.Ic list-windows 860or 861.Ic list-panes 862commands. 863.Pp 864.Ar shell-command 865arguments are 866.Xr sh 1 867commands. 868This may be a single argument passed to the shell, for example: 869.Bd -literal -offset indent 870new-window 'vi /etc/passwd' 871.Ed 872.Pp 873Will run: 874.Bd -literal -offset indent 875/bin/sh -c 'vi /etc/passwd' 876.Ed 877.Pp 878Additionally, the 879.Ic new-window , 880.Ic new-session , 881.Ic split-window , 882.Ic respawn-window 883and 884.Ic respawn-pane 885commands allow 886.Ar shell-command 887to be given as multiple arguments and executed directly (without 888.Ql sh -c ) . 889This can avoid issues with shell quoting. 890For example: 891.Bd -literal -offset indent 892$ tmux new-window vi /etc/passwd 893.Ed 894.Pp 895Will run 896.Xr vi 1 897directly without invoking the shell. 898.Pp 899.Ar command 900.Op Ar arguments 901refers to a 902.Nm 903command, either passed with the command and arguments separately, for example: 904.Bd -literal -offset indent 905bind-key F1 set-option status off 906.Ed 907.Pp 908Or passed as a single string argument in 909.Pa .tmux.conf , 910for example: 911.Bd -literal -offset indent 912bind-key F1 { set-option status off } 913.Ed 914.Pp 915Example 916.Nm 917commands include: 918.Bd -literal -offset indent 919refresh-client -t/dev/ttyp2 920 921rename-session -tfirst newname 922 923set-option -wt:0 monitor-activity on 924 925new-window ; split-window -d 926 927bind-key R source-file ~/.tmux.conf \e; \e 928 display-message "source-file done" 929.Ed 930.Pp 931Or from 932.Xr sh 1 : 933.Bd -literal -offset indent 934$ tmux kill-window -t :1 935 936$ tmux new-window \e; split-window -d 937 938$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach 939.Ed 940.Sh CLIENTS AND SESSIONS 941The 942.Nm 943server manages clients, sessions, windows and panes. 944Clients are attached to sessions to interact with them, either 945when they are created with the 946.Ic new-session 947command, or later with the 948.Ic attach-session 949command. 950Each session has one or more windows 951.Em linked 952into it. 953Windows may be linked to multiple sessions and are made up of one or 954more panes, 955each of which contains a pseudo terminal. 956Commands for creating, linking and otherwise manipulating windows 957are covered 958in the 959.Sx WINDOWS AND PANES 960section. 961.Pp 962The following commands are available to manage clients and sessions: 963.Bl -tag -width Ds 964.It Xo Ic attach-session 965.Op Fl dErx 966.Op Fl c Ar working-directory 967.Op Fl f Ar flags 968.Op Fl t Ar target-session 969.Xc 970.D1 (alias: Ic attach ) 971If run from outside 972.Nm , 973create a new client in the current terminal and attach it to 974.Ar target-session . 975If used from inside, switch the current client. 976If 977.Fl d 978is specified, any other clients attached to the session are detached. 979If 980.Fl x 981is given, send 982.Dv SIGHUP 983to the parent process of the client as well as 984detaching the client, typically causing it to exit. 985.Fl f 986sets a comma-separated list of client flags. 987The flags are: 988.Bl -tag -width Ds 989.It active-pane 990the client has an independent active pane 991.It ignore-size 992the client does not affect the size of other clients 993.It no-output 994the client does not receive pane output in control mode 995.It pause-after=seconds 996output is paused once the pane is 997.Ar seconds 998behind in control mode 999.It read-only 1000the client is read-only 1001.It wait-exit 1002wait for an empty line input before exiting in control mode 1003.El 1004.Pp 1005A leading 1006.Ql \&! 1007turns a flag off if the client is already attached. 1008.Fl r 1009is an alias for 1010.Fl f 1011.Ar read-only,ignore-size . 1012When a client is read-only, only keys bound to the 1013.Ic detach-client 1014or 1015.Ic switch-client 1016commands have any effect. 1017A client with the 1018.Ar active-pane 1019flag allows the active pane to be selected independently of the window's active 1020pane used by clients without the flag. 1021This only affects the cursor position and commands issued from the client; 1022other features such as hooks and styles continue to use the window's active 1023pane. 1024.Pp 1025If no server is started, 1026.Ic attach-session 1027will attempt to start it; this will fail unless sessions are created in the 1028configuration file. 1029.Pp 1030The 1031.Ar target-session 1032rules for 1033.Ic attach-session 1034are slightly adjusted: if 1035.Nm 1036needs to select the most recently used session, it will prefer the most 1037recently used 1038.Em unattached 1039session. 1040.Pp 1041.Fl c 1042will set the session working directory (used for new windows) to 1043.Ar working-directory . 1044.Pp 1045If 1046.Fl E 1047is used, the 1048.Ic update-environment 1049option will not be applied. 1050.It Xo Ic detach-client 1051.Op Fl aP 1052.Op Fl E Ar shell-command 1053.Op Fl s Ar target-session 1054.Op Fl t Ar target-client 1055.Xc 1056.D1 (alias: Ic detach ) 1057Detach the current client if bound to a key, the client specified with 1058.Fl t , 1059or all clients currently attached to the session specified by 1060.Fl s . 1061The 1062.Fl a 1063option kills all but the client given with 1064.Fl t . 1065If 1066.Fl P 1067is given, send 1068.Dv SIGHUP 1069to the parent process of the client, typically causing it 1070to exit. 1071With 1072.Fl E , 1073run 1074.Ar shell-command 1075to replace the client. 1076.It Ic has-session Op Fl t Ar target-session 1077.D1 (alias: Ic has ) 1078Report an error and exit with 1 if the specified session does not exist. 1079If it does exist, exit with 0. 1080.It Ic kill-server 1081Kill the 1082.Nm 1083server and clients and destroy all sessions. 1084.It Xo Ic kill-session 1085.Op Fl aC 1086.Op Fl t Ar target-session 1087.Xc 1088Destroy the given session, closing any windows linked to it and no other 1089sessions, and detaching all clients attached to it. 1090If 1091.Fl a 1092is given, all sessions but the specified one is killed. 1093The 1094.Fl C 1095flag clears alerts (bell, activity, or silence) in all windows linked to the 1096session. 1097.It Xo Ic list-clients 1098.Op Fl F Ar format 1099.Op Fl t Ar target-session 1100.Xc 1101.D1 (alias: Ic lsc ) 1102List all clients attached to the server. 1103For the meaning of the 1104.Fl F 1105flag, see the 1106.Sx FORMATS 1107section. 1108If 1109.Ar target-session 1110is specified, list only clients connected to that session. 1111.It Xo Ic list-commands 1112.Op Fl F Ar format 1113.Op Ar command 1114.Xc 1115.D1 (alias: Ic lscm ) 1116List the syntax of 1117.Ar command 1118or - if omitted - of all commands supported by 1119.Nm . 1120.It Xo Ic list-sessions 1121.Op Fl F Ar format 1122.Op Fl f Ar filter 1123.Xc 1124.D1 (alias: Ic ls ) 1125List all sessions managed by the server. 1126.Fl F 1127specifies the format of each line and 1128.Fl f 1129a filter. 1130Only sessions for which the filter is true are shown. 1131See the 1132.Sx FORMATS 1133section. 1134.It Ic lock-client Op Fl t Ar target-client 1135.D1 (alias: Ic lockc ) 1136Lock 1137.Ar target-client , 1138see the 1139.Ic lock-server 1140command. 1141.It Ic lock-session Op Fl t Ar target-session 1142.D1 (alias: Ic locks ) 1143Lock all clients attached to 1144.Ar target-session . 1145.It Xo Ic new-session 1146.Op Fl AdDEPX 1147.Op Fl c Ar start-directory 1148.Op Fl e Ar environment 1149.Op Fl f Ar flags 1150.Op Fl F Ar format 1151.Op Fl n Ar window-name 1152.Op Fl s Ar session-name 1153.Op Fl t Ar group-name 1154.Op Fl x Ar width 1155.Op Fl y Ar height 1156.Op Ar shell-command 1157.Xc 1158.D1 (alias: Ic new ) 1159Create a new session with name 1160.Ar session-name . 1161.Pp 1162The new session is attached to the current terminal unless 1163.Fl d 1164is given. 1165.Ar window-name 1166and 1167.Ar shell-command 1168are the name of and shell command to execute in the initial window. 1169With 1170.Fl d , 1171the initial size comes from the global 1172.Ic default-size 1173option; 1174.Fl x 1175and 1176.Fl y 1177can be used to specify a different size. 1178.Ql - 1179uses the size of the current client if any. 1180If 1181.Fl x 1182or 1183.Fl y 1184is given, the 1185.Ic default-size 1186option is set for the session. 1187.Fl f 1188sets a comma-separated list of client flags (see 1189.Ic attach-session ) . 1190.Pp 1191If run from a terminal, any 1192.Xr termios 4 1193special characters are saved and used for new windows in the new session. 1194.Pp 1195The 1196.Fl A 1197flag makes 1198.Ic new-session 1199behave like 1200.Ic attach-session 1201if 1202.Ar session-name 1203already exists; in this case, 1204.Fl D 1205behaves like 1206.Fl d 1207to 1208.Ic attach-session , 1209and 1210.Fl X 1211behaves like 1212.Fl x 1213to 1214.Ic attach-session . 1215.Pp 1216If 1217.Fl t 1218is given, it specifies a 1219.Ic session group . 1220Sessions in the same group share the same set of windows - new windows are 1221linked to all sessions in the group and any windows closed removed from all 1222sessions. 1223The current and previous window and any session options remain independent and 1224any session in a group may be killed without affecting the others. 1225The 1226.Ar group-name 1227argument may be: 1228.Bl -enum -width Ds 1229.It 1230the name of an existing group, in which case the new session is added to that 1231group; 1232.It 1233the name of an existing session - the new session is added to the same group 1234as that session, creating a new group if necessary; 1235.It 1236the name for a new group containing only the new session. 1237.El 1238.Pp 1239.Fl n 1240and 1241.Ar shell-command 1242are invalid if 1243.Fl t 1244is used. 1245.Pp 1246The 1247.Fl P 1248option prints information about the new session after it has been created. 1249By default, it uses the format 1250.Ql #{session_name}:\& 1251but a different format may be specified with 1252.Fl F . 1253.Pp 1254If 1255.Fl E 1256is used, the 1257.Ic update-environment 1258option will not be applied. 1259.Fl e 1260takes the form 1261.Ql VARIABLE=value 1262and sets an environment variable for the newly created session; it may be 1263specified multiple times. 1264.It Xo Ic refresh-client 1265.Op Fl cDlLRSU 1266.Op Fl A Ar pane:state 1267.Op Fl B Ar name:what:format 1268.Op Fl C Ar XxY 1269.Op Fl f Ar flags 1270.Op Fl t Ar target-client 1271.Op Ar adjustment 1272.Xc 1273.D1 (alias: Ic refresh ) 1274Refresh the current client if bound to a key, or a single client if one is given 1275with 1276.Fl t . 1277If 1278.Fl S 1279is specified, only update the client's status line. 1280.Pp 1281The 1282.Fl U , 1283.Fl D , 1284.Fl L 1285.Fl R , 1286and 1287.Fl c 1288flags allow the visible portion of a window which is larger than the client 1289to be changed. 1290.Fl U 1291moves the visible part up by 1292.Ar adjustment 1293rows and 1294.Fl D 1295down, 1296.Fl L 1297left by 1298.Ar adjustment 1299columns and 1300.Fl R 1301right. 1302.Fl c 1303returns to tracking the cursor automatically. 1304If 1305.Ar adjustment 1306is omitted, 1 is used. 1307Note that the visible position is a property of the client not of the 1308window, changing the current window in the attached session will reset 1309it. 1310.Pp 1311.Fl C 1312sets the width and height of a control mode client. 1313.Fl A 1314allows a control mode client to trigger actions on a pane. 1315The argument is a pane ID (with leading 1316.Ql % ) , 1317a colon, then one of 1318.Ql on , 1319.Ql off , 1320.Ql continue 1321or 1322.Ql pause . 1323If 1324.Ql off , 1325.Nm 1326will not send output from the pane to the client and if all clients have turned 1327the pane off, will stop reading from the pane. 1328If 1329.Ql continue , 1330.Nm 1331will return to sending output to the pane if it was paused (manually or with the 1332.Ar pause-after 1333flag). 1334If 1335.Ql pause , 1336.Nm 1337will pause the pane. 1338.Fl A 1339may be given multiple times for different panes. 1340.Pp 1341.Fl B 1342sets a subscription to a format for a control mode client. 1343The argument is split into three items by colons: 1344.Ar name 1345is a name for the subscription; 1346.Ar what 1347is a type of item to subscribe to; 1348.Ar format 1349is the format. 1350After a subscription is added, changes to the format are reported with the 1351.Ic %subscription-changed 1352notification, at most once a second. 1353If only the name is given, the subscription is removed. 1354.Ar what 1355may be empty to check the format only for the attached session, or one of: 1356a pane ID such as 1357.Ql %0 ; 1358.Ql %* 1359for all panes in the attached session; 1360an window ID such as 1361.Ql @0 ; 1362or 1363.Ql @* 1364for all windows in the attached session. 1365.Pp 1366.Fl f 1367sets a comma-separated list of client flags, see 1368.Ic attach-session . 1369.Pp 1370.Fl l 1371requests the clipboard from the client using the 1372.Xr xterm 1 1373escape sequence and stores it in a new paste buffer. 1374.Pp 1375.Fl L , 1376.Fl R , 1377.Fl U 1378and 1379.Fl D 1380move the visible portion of the window left, right, up or down 1381by 1382.Ar adjustment , 1383if the window is larger than the client. 1384.Fl c 1385resets so that the position follows the cursor. 1386See the 1387.Ic window-size 1388option. 1389.It Xo Ic rename-session 1390.Op Fl t Ar target-session 1391.Ar new-name 1392.Xc 1393.D1 (alias: Ic rename ) 1394Rename the session to 1395.Ar new-name . 1396.It Xo Ic show-messages 1397.Op Fl JT 1398.Op Fl t Ar target-client 1399.Xc 1400.D1 (alias: Ic showmsgs ) 1401Show server messages or information. 1402Messages are stored, up to a maximum of the limit set by the 1403.Ar message-limit 1404server option. 1405.Fl J 1406and 1407.Fl T 1408show debugging information about jobs and terminals. 1409.It Xo Ic source-file 1410.Op Fl Fnqv 1411.Ar path 1412.Ar ... 1413.Xc 1414.D1 (alias: Ic source ) 1415Execute commands from one or more files specified by 1416.Ar path 1417(which may be 1418.Xr glob 7 1419patterns). 1420If 1421.Fl F 1422is present, then 1423.Ar path 1424is expanded as a format. 1425If 1426.Fl q 1427is given, no error will be returned if 1428.Ar path 1429does not exist. 1430With 1431.Fl n , 1432the file is parsed but no commands are executed. 1433.Fl v 1434shows the parsed commands and line numbers if possible. 1435.It Ic start-server 1436.D1 (alias: Ic start ) 1437Start the 1438.Nm 1439server, if not already running, without creating any sessions. 1440.Pp 1441Note that as by default the 1442.Nm 1443server will exit with no sessions, this is only useful if a session is created in 1444.Pa ~/.tmux.conf , 1445.Ic exit-empty 1446is turned off, or another command is run as part of the same command sequence. 1447For example: 1448.Bd -literal -offset indent 1449$ tmux start \\; show -g 1450.Ed 1451.It Xo Ic suspend-client 1452.Op Fl t Ar target-client 1453.Xc 1454.D1 (alias: Ic suspendc ) 1455Suspend a client by sending 1456.Dv SIGTSTP 1457(tty stop). 1458.It Xo Ic switch-client 1459.Op Fl ElnprZ 1460.Op Fl c Ar target-client 1461.Op Fl t Ar target-session 1462.Op Fl T Ar key-table 1463.Xc 1464.D1 (alias: Ic switchc ) 1465Switch the current session for client 1466.Ar target-client 1467to 1468.Ar target-session . 1469As a special case, 1470.Fl t 1471may refer to a pane (a target that contains 1472.Ql \&: , 1473.Ql \&. 1474or 1475.Ql % ) , 1476to change session, window and pane. 1477In that case, 1478.Fl Z 1479keeps the window zoomed if it was zoomed. 1480If 1481.Fl l , 1482.Fl n 1483or 1484.Fl p 1485is used, the client is moved to the last, next or previous session 1486respectively. 1487.Fl r 1488toggles the client 1489.Ic read-only 1490and 1491.Ic ignore-size 1492flags (see the 1493.Ic attach-session 1494command). 1495.Pp 1496If 1497.Fl E 1498is used, 1499.Ic update-environment 1500option will not be applied. 1501.Pp 1502.Fl T 1503sets the client's key table; the next key from the client will be interpreted 1504from 1505.Ar key-table . 1506This may be used to configure multiple prefix keys, or to bind commands to 1507sequences of keys. 1508For example, to make typing 1509.Ql abc 1510run the 1511.Ic list-keys 1512command: 1513.Bd -literal -offset indent 1514bind-key -Ttable2 c list-keys 1515bind-key -Ttable1 b switch-client -Ttable2 1516bind-key -Troot a switch-client -Ttable1 1517.Ed 1518.El 1519.Sh WINDOWS AND PANES 1520Each window displayed by 1521.Nm 1522may be split into one or more 1523.Em panes ; 1524each pane takes up a certain area of the display and is a separate terminal. 1525A window may be split into panes using the 1526.Ic split-window 1527command. 1528Windows may be split horizontally (with the 1529.Fl h 1530flag) or vertically. 1531Panes may be resized with the 1532.Ic resize-pane 1533command (bound to 1534.Ql C-Up , 1535.Ql C-Down 1536.Ql C-Left 1537and 1538.Ql C-Right 1539by default), the current pane may be changed with the 1540.Ic select-pane 1541command and the 1542.Ic rotate-window 1543and 1544.Ic swap-pane 1545commands may be used to swap panes without changing their position. 1546Panes are numbered beginning from zero in the order they are created. 1547.Pp 1548By default, a 1549.Nm 1550pane permits direct access to the terminal contained in the pane. 1551A pane may also be put into one of several modes: 1552.Bl -dash -offset indent 1553.It 1554Copy mode, which permits a section of a window or its 1555history to be copied to a 1556.Em paste buffer 1557for later insertion into another window. 1558This mode is entered with the 1559.Ic copy-mode 1560command, bound to 1561.Ql \&[ 1562by default. 1563Copied text can be pasted with the 1564.Ic paste-buffer 1565command, bound to 1566.Ql \&] . 1567.It 1568View mode, which is like copy mode but is entered when a command that produces 1569output, such as 1570.Ic list-keys , 1571is executed from a key binding. 1572.It 1573Choose mode, which allows an item to be chosen from a list. 1574This may be a client, a session or window or pane, or a buffer. 1575This mode is entered with the 1576.Ic choose-buffer , 1577.Ic choose-client 1578and 1579.Ic choose-tree 1580commands. 1581.El 1582.Pp 1583In copy mode an indicator is displayed in the top-right corner of the pane with 1584the current position and the number of lines in the history. 1585.Pp 1586Commands are sent to copy mode using the 1587.Fl X 1588flag to the 1589.Ic send-keys 1590command. 1591When a key is pressed, copy mode automatically uses one of two key tables, 1592depending on the 1593.Ic mode-keys 1594option: 1595.Ic copy-mode 1596for emacs, or 1597.Ic copy-mode-vi 1598for vi. 1599Key tables may be viewed with the 1600.Ic list-keys 1601command. 1602.Pp 1603The following commands are supported in copy mode: 1604.Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent 1605.It Sy "Command" Ta Sy "vi" Ta Sy "emacs" 1606.It Li "append-selection" Ta "" Ta "" 1607.It Li "append-selection-and-cancel" Ta "A" Ta "" 1608.It Li "back-to-indentation" Ta "^" Ta "M-m" 1609.It Li "begin-selection" Ta "Space" Ta "C-Space" 1610.It Li "bottom-line" Ta "L" Ta "" 1611.It Li "cancel" Ta "q" Ta "Escape" 1612.It Li "clear-selection" Ta "Escape" Ta "C-g" 1613.It Li "copy-end-of-line [<prefix>]" Ta "D" Ta "C-k" 1614.It Li "copy-line [<prefix>]" Ta "" Ta "" 1615.It Li "copy-pipe [<command>] [<prefix>]" Ta "" Ta "" 1616.It Li "copy-pipe-no-clear [<command>] [<prefix>]" Ta "" Ta "" 1617.It Li "copy-pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta "" 1618.It Li "copy-selection [<prefix>]" Ta "" Ta "" 1619.It Li "copy-selection-no-clear [<prefix>]" Ta "" Ta "" 1620.It Li "copy-selection-and-cancel [<prefix>]" Ta "Enter" Ta "M-w" 1621.It Li "cursor-down" Ta "j" Ta "Down" 1622.It Li "cursor-down-and-cancel" Ta "" Ta "" 1623.It Li "cursor-left" Ta "h" Ta "Left" 1624.It Li "cursor-right" Ta "l" Ta "Right" 1625.It Li "cursor-up" Ta "k" Ta "Up" 1626.It Li "end-of-line" Ta "$" Ta "C-e" 1627.It Li "goto-line <line>" Ta ":" Ta "g" 1628.It Li "halfpage-down" Ta "C-d" Ta "M-Down" 1629.It Li "halfpage-down-and-cancel" Ta "" Ta "" 1630.It Li "halfpage-up" Ta "C-u" Ta "M-Up" 1631.It Li "history-bottom" Ta "G" Ta "M->" 1632.It Li "history-top" Ta "g" Ta "M-<" 1633.It Li "jump-again" Ta ";" Ta ";" 1634.It Li "jump-backward <to>" Ta "F" Ta "F" 1635.It Li "jump-forward <to>" Ta "f" Ta "f" 1636.It Li "jump-reverse" Ta "," Ta "," 1637.It Li "jump-to-backward <to>" Ta "T" Ta "" 1638.It Li "jump-to-forward <to>" Ta "t" Ta "" 1639.It Li "jump-to-mark" Ta "M-x" Ta "M-x" 1640.It Li "middle-line" Ta "M" Ta "M-r" 1641.It Li "next-matching-bracket" Ta "%" Ta "M-C-f" 1642.It Li "next-paragraph" Ta "}" Ta "M-}" 1643.It Li "next-space" Ta "W" Ta "" 1644.It Li "next-space-end" Ta "E" Ta "" 1645.It Li "next-word" Ta "w" Ta "" 1646.It Li "next-word-end" Ta "e" Ta "M-f" 1647.It Li "other-end" Ta "o" Ta "" 1648.It Li "page-down" Ta "C-f" Ta "PageDown" 1649.It Li "page-down-and-cancel" Ta "" Ta "" 1650.It Li "page-up" Ta "C-b" Ta "PageUp" 1651.It Li "previous-matching-bracket" Ta "" Ta "M-C-b" 1652.It Li "previous-paragraph" Ta "{" Ta "M-{" 1653.It Li "previous-space" Ta "B" Ta "" 1654.It Li "previous-word" Ta "b" Ta "M-b" 1655.It Li "rectangle-toggle" Ta "v" Ta "R" 1656.It Li "refresh-from-pane" Ta "r" Ta "r" 1657.It Li "scroll-down" Ta "C-e" Ta "C-Down" 1658.It Li "scroll-down-and-cancel" Ta "" Ta "" 1659.It Li "scroll-up" Ta "C-y" Ta "C-Up" 1660.It Li "search-again" Ta "n" Ta "n" 1661.It Li "search-backward <for>" Ta "?" Ta "" 1662.It Li "search-backward-incremental <for>" Ta "" Ta "C-r" 1663.It Li "search-backward-text <for>" Ta "" Ta "" 1664.It Li "search-forward <for>" Ta "/" Ta "" 1665.It Li "search-forward-incremental <for>" Ta "" Ta "C-s" 1666.It Li "search-forward-text <for>" Ta "" Ta "" 1667.It Li "search-reverse" Ta "N" Ta "N" 1668.It Li "select-line" Ta "V" Ta "" 1669.It Li "select-word" Ta "" Ta "" 1670.It Li "set-mark" Ta "X" Ta "X" 1671.It Li "start-of-line" Ta "0" Ta "C-a" 1672.It Li "stop-selection" Ta "" Ta "" 1673.It Li "top-line" Ta "H" Ta "M-R" 1674.El 1675.Pp 1676The search commands come in several varieties: 1677.Ql search-forward 1678and 1679.Ql search-backward 1680search for a regular expression; 1681the 1682.Ql -text 1683variants search for a plain text string rather than a regular expression; 1684.Ql -incremental 1685perform an incremental search and expect to be used with the 1686.Fl i 1687flag to the 1688.Ic command-prompt 1689command. 1690.Ql search-again 1691repeats the last search and 1692.Ql search-reverse 1693does the same but reverses the direction (forward becomes backward and backward 1694becomes forward). 1695.Pp 1696Copy commands may take an optional buffer prefix argument which is used 1697to generate the buffer name (the default is 1698.Ql buffer 1699so buffers are named 1700.Ql buffer0 , 1701.Ql buffer1 1702and so on). 1703Pipe commands take a command argument which is the command to which the 1704copied text is piped. 1705The 1706.Ql -and-cancel 1707variants of some commands exit copy mode after they have completed (for copy 1708commands) or when the cursor reaches the bottom (for scrolling commands). 1709.Ql -no-clear 1710variants do not clear the selection. 1711.Pp 1712The next and previous word keys use space and the 1713.Ql - , 1714.Ql _ 1715and 1716.Ql @ 1717characters as word delimiters by default, but this can be adjusted by 1718setting the 1719.Em word-separators 1720session option. 1721Next word moves to the start of the next word, next word end to the end of the 1722next word and previous word to the start of the previous word. 1723The three next and previous space keys work similarly but use a space alone as 1724the word separator. 1725.Pp 1726The jump commands enable quick movement within a line. 1727For instance, typing 1728.Ql f 1729followed by 1730.Ql / 1731will move the cursor to the next 1732.Ql / 1733character on the current line. 1734A 1735.Ql \&; 1736will then jump to the next occurrence. 1737.Pp 1738Commands in copy mode may be prefaced by an optional repeat count. 1739With vi key bindings, a prefix is entered using the number keys; with 1740emacs, the Alt (meta) key and a number begins prefix entry. 1741.Pp 1742The synopsis for the 1743.Ic copy-mode 1744command is: 1745.Bl -tag -width Ds 1746.It Xo Ic copy-mode 1747.Op Fl eHMqu 1748.Op Fl s Ar src-pane 1749.Op Fl t Ar target-pane 1750.Xc 1751Enter copy mode. 1752The 1753.Fl u 1754option scrolls one page up. 1755.Fl M 1756begins a mouse drag (only valid if bound to a mouse key binding, see 1757.Sx MOUSE SUPPORT ) . 1758.Fl H 1759hides the position indicator in the top right. 1760.Fl q 1761cancels copy mode and any other modes. 1762.Fl s 1763copies from 1764.Ar src-pane 1765instead of 1766.Ar target-pane . 1767.Pp 1768.Fl e 1769specifies that scrolling to the bottom of the history (to the visible screen) 1770should exit copy mode. 1771While in copy mode, pressing a key other than those used for scrolling will 1772disable this behaviour. 1773This is intended to allow fast scrolling through a pane's history, for 1774example with: 1775.Bd -literal -offset indent 1776bind PageUp copy-mode -eu 1777.Ed 1778.El 1779.Pp 1780A number of preset arrangements of panes are available, these are called layouts. 1781These may be selected with the 1782.Ic select-layout 1783command or cycled with 1784.Ic next-layout 1785(bound to 1786.Ql Space 1787by default); once a layout is chosen, panes within it may be moved and resized 1788as normal. 1789.Pp 1790The following layouts are supported: 1791.Bl -tag -width Ds 1792.It Ic even-horizontal 1793Panes are spread out evenly from left to right across the window. 1794.It Ic even-vertical 1795Panes are spread evenly from top to bottom. 1796.It Ic main-horizontal 1797A large (main) pane is shown at the top of the window and the remaining panes 1798are spread from left to right in the leftover space at the bottom. 1799Use the 1800.Em main-pane-height 1801window option to specify the height of the top pane. 1802.It Ic main-vertical 1803Similar to 1804.Ic main-horizontal 1805but the large pane is placed on the left and the others spread from top to 1806bottom along the right. 1807See the 1808.Em main-pane-width 1809window option. 1810.It Ic tiled 1811Panes are spread out as evenly as possible over the window in both rows and 1812columns. 1813.El 1814.Pp 1815In addition, 1816.Ic select-layout 1817may be used to apply a previously used layout - the 1818.Ic list-windows 1819command displays the layout of each window in a form suitable for use with 1820.Ic select-layout . 1821For example: 1822.Bd -literal -offset indent 1823$ tmux list-windows 18240: ksh [159x48] 1825 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} 1826$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} 1827.Ed 1828.Pp 1829.Nm 1830automatically adjusts the size of the layout for the current window size. 1831Note that a layout cannot be applied to a window with more panes than that 1832from which the layout was originally defined. 1833.Pp 1834Commands related to windows and panes are as follows: 1835.Bl -tag -width Ds 1836.It Xo Ic break-pane 1837.Op Fl abdP 1838.Op Fl F Ar format 1839.Op Fl n Ar window-name 1840.Op Fl s Ar src-pane 1841.Op Fl t Ar dst-window 1842.Xc 1843.D1 (alias: Ic breakp ) 1844Break 1845.Ar src-pane 1846off from its containing window to make it the only pane in 1847.Ar dst-window . 1848With 1849.Fl a 1850or 1851.Fl b , 1852the window is moved to the next index after or before (existing windows are 1853moved if necessary). 1854If 1855.Fl d 1856is given, the new window does not become the current window. 1857The 1858.Fl P 1859option prints information about the new window after it has been created. 1860By default, it uses the format 1861.Ql #{session_name}:#{window_index}.#{pane_index} 1862but a different format may be specified with 1863.Fl F . 1864.It Xo Ic capture-pane 1865.Op Fl aepPqCJN 1866.Op Fl b Ar buffer-name 1867.Op Fl E Ar end-line 1868.Op Fl S Ar start-line 1869.Op Fl t Ar target-pane 1870.Xc 1871.D1 (alias: Ic capturep ) 1872Capture the contents of a pane. 1873If 1874.Fl p 1875is given, the output goes to stdout, otherwise to the buffer specified with 1876.Fl b 1877or a new buffer if omitted. 1878If 1879.Fl a 1880is given, the alternate screen is used, and the history is not accessible. 1881If no alternate screen exists, an error will be returned unless 1882.Fl q 1883is given. 1884If 1885.Fl e 1886is given, the output includes escape sequences for text and background 1887attributes. 1888.Fl C 1889also escapes non-printable characters as octal \exxx. 1890.Fl N 1891preserves trailing spaces at each line's end and 1892.Fl J 1893preserves trailing spaces and joins any wrapped lines. 1894.Fl P 1895captures only any output that the pane has received that is the beginning of an 1896as-yet incomplete escape sequence. 1897.Pp 1898.Fl S 1899and 1900.Fl E 1901specify the starting and ending line numbers, zero is the first line of the 1902visible pane and negative numbers are lines in the history. 1903.Ql - 1904to 1905.Fl S 1906is the start of the history and to 1907.Fl E 1908the end of the visible pane. 1909The default is to capture only the visible contents of the pane. 1910.It Xo 1911.Ic choose-client 1912.Op Fl NrZ 1913.Op Fl F Ar format 1914.Op Fl f Ar filter 1915.Op Fl O Ar sort-order 1916.Op Fl t Ar target-pane 1917.Op Ar template 1918.Xc 1919Put a pane into client mode, allowing a client to be selected interactively from 1920a list. 1921.Fl Z 1922zooms the pane. 1923The following keys may be used in client mode: 1924.Bl -column "Key" "Function" -offset indent 1925.It Sy "Key" Ta Sy "Function" 1926.It Li "Enter" Ta "Choose selected client" 1927.It Li "Up" Ta "Select previous client" 1928.It Li "Down" Ta "Select next client" 1929.It Li "C-s" Ta "Search by name" 1930.It Li "n" Ta "Repeat last search" 1931.It Li "t" Ta "Toggle if client is tagged" 1932.It Li "T" Ta "Tag no clients" 1933.It Li "C-t" Ta "Tag all clients" 1934.It Li "d" Ta "Detach selected client" 1935.It Li "D" Ta "Detach tagged clients" 1936.It Li "x" Ta "Detach and HUP selected client" 1937.It Li "X" Ta "Detach and HUP tagged clients" 1938.It Li "z" Ta "Suspend selected client" 1939.It Li "Z" Ta "Suspend tagged clients" 1940.It Li "f" Ta "Enter a format to filter items" 1941.It Li "O" Ta "Change sort field" 1942.It Li "r" Ta "Reverse sort order" 1943.It Li "v" Ta "Toggle preview" 1944.It Li "q" Ta "Exit mode" 1945.El 1946.Pp 1947After a client is chosen, 1948.Ql %% 1949is replaced by the client name in 1950.Ar template 1951and the result executed as a command. 1952If 1953.Ar template 1954is not given, "detach-client -t '%%'" is used. 1955.Pp 1956.Fl O 1957specifies the initial sort field: one of 1958.Ql name , 1959.Ql size , 1960.Ql creation , 1961or 1962.Ql activity . 1963.Fl r 1964reverses the sort order. 1965.Fl f 1966specifies an initial filter: the filter is a format - if it evaluates to zero, 1967the item in the list is not shown, otherwise it is shown. 1968If a filter would lead to an empty list, it is ignored. 1969.Fl F 1970specifies the format for each item in the list. 1971.Fl N 1972starts without the preview. 1973This command works only if at least one client is attached. 1974.It Xo 1975.Ic choose-tree 1976.Op Fl GNrswZ 1977.Op Fl F Ar format 1978.Op Fl f Ar filter 1979.Op Fl O Ar sort-order 1980.Op Fl t Ar target-pane 1981.Op Ar template 1982.Xc 1983Put a pane into tree mode, where a session, window or pane may be chosen 1984interactively from a list. 1985.Fl s 1986starts with sessions collapsed and 1987.Fl w 1988with windows collapsed. 1989.Fl Z 1990zooms the pane. 1991The following keys may be used in tree mode: 1992.Bl -column "Key" "Function" -offset indent 1993.It Sy "Key" Ta Sy "Function" 1994.It Li "Enter" Ta "Choose selected item" 1995.It Li "Up" Ta "Select previous item" 1996.It Li "Down" Ta "Select next item" 1997.It Li "+" Ta "Expand selected item" 1998.It Li "-" Ta "Collapse selected item" 1999.It Li "M-+" Ta "Expand all items" 2000.It Li "M--" Ta "Collapse all items" 2001.It Li "x" Ta "Kill selected item" 2002.It Li "X" Ta "Kill tagged items" 2003.It Li "<" Ta "Scroll list of previews left" 2004.It Li ">" Ta "Scroll list of previews right" 2005.It Li "C-s" Ta "Search by name" 2006.It Li "m" Ta "Set the marked pane" 2007.It Li "M" Ta "Clear the marked pane" 2008.It Li "n" Ta "Repeat last search" 2009.It Li "t" Ta "Toggle if item is tagged" 2010.It Li "T" Ta "Tag no items" 2011.It Li "C-t" Ta "Tag all items" 2012.It Li "\&:" Ta "Run a command for each tagged item" 2013.It Li "f" Ta "Enter a format to filter items" 2014.It Li "H" Ta "Jump to the starting pane" 2015.It Li "O" Ta "Change sort field" 2016.It Li "r" Ta "Reverse sort order" 2017.It Li "v" Ta "Toggle preview" 2018.It Li "q" Ta "Exit mode" 2019.El 2020.Pp 2021After a session, window or pane is chosen, 2022.Ql %% 2023is replaced by the target in 2024.Ar template 2025and the result executed as a command. 2026If 2027.Ar template 2028is not given, "switch-client -t '%%'" is used. 2029.Pp 2030.Fl O 2031specifies the initial sort field: one of 2032.Ql index , 2033.Ql name , 2034or 2035.Ql time . 2036.Fl r 2037reverses the sort order. 2038.Fl f 2039specifies an initial filter: the filter is a format - if it evaluates to zero, 2040the item in the list is not shown, otherwise it is shown. 2041If a filter would lead to an empty list, it is ignored. 2042.Fl F 2043specifies the format for each item in the tree. 2044.Fl N 2045starts without the preview. 2046.Fl G 2047includes all sessions in any session groups in the tree rather than only the 2048first. 2049This command works only if at least one client is attached. 2050.It Xo 2051.Ic customize-mode 2052.Op Fl NZ 2053.Op Fl F Ar format 2054.Op Fl f Ar filter 2055.Op Fl t Ar target-pane 2056.Op Ar template 2057.Xc 2058Put a pane into customize mode, where options and key bindings may be browsed 2059and modified from a list. 2060Option values in the list are shown for the active pane in the current window. 2061.Fl Z 2062zooms the pane. 2063The following keys may be used in customize mode: 2064.Bl -column "Key" "Function" -offset indent 2065.It Sy "Key" Ta Sy "Function" 2066.It Li "Enter" Ta "Set pane, window, session or global option value" 2067.It Li "Up" Ta "Select previous item" 2068.It Li "Down" Ta "Select next item" 2069.It Li "+" Ta "Expand selected item" 2070.It Li "-" Ta "Collapse selected item" 2071.It Li "M-+" Ta "Expand all items" 2072.It Li "M--" Ta "Collapse all items" 2073.It Li "s" Ta "Set option value or key attribute" 2074.It Li "S" Ta "Set global option value" 2075.It Li "w" Ta "Set window option value, if option is for pane and window" 2076.It Li "d" Ta "Set an option or key to the default" 2077.It Li "D" Ta "Set tagged options and tagged keys to the default" 2078.It Li "u" Ta "Unset an option (set to default value if global) or unbind a key" 2079.It Li "U" Ta "Unset tagged options and unbind tagged keys" 2080.It Li "C-s" Ta "Search by name" 2081.It Li "n" Ta "Repeat last search" 2082.It Li "t" Ta "Toggle if item is tagged" 2083.It Li "T" Ta "Tag no items" 2084.It Li "C-t" Ta "Tag all items" 2085.It Li "f" Ta "Enter a format to filter items" 2086.It Li "v" Ta "Toggle option information" 2087.It Li "q" Ta "Exit mode" 2088.El 2089.Pp 2090.Fl f 2091specifies an initial filter: the filter is a format - if it evaluates to zero, 2092the item in the list is not shown, otherwise it is shown. 2093If a filter would lead to an empty list, it is ignored. 2094.Fl F 2095specifies the format for each item in the tree. 2096.Fl N 2097starts without the option information. 2098This command works only if at least one client is attached. 2099.It Xo 2100.Ic display-panes 2101.Op Fl bN 2102.Op Fl d Ar duration 2103.Op Fl t Ar target-client 2104.Op Ar template 2105.Xc 2106.D1 (alias: Ic displayp ) 2107Display a visible indicator of each pane shown by 2108.Ar target-client . 2109See the 2110.Ic display-panes-colour 2111and 2112.Ic display-panes-active-colour 2113session options. 2114The indicator is closed when a key is pressed (unless 2115.Fl N 2116is given) or 2117.Ar duration 2118milliseconds have passed. 2119If 2120.Fl d 2121is not given, 2122.Ic display-panes-time 2123is used. 2124A duration of zero means the indicator stays until a key is pressed. 2125While the indicator is on screen, a pane may be chosen with the 2126.Ql 0 2127to 2128.Ql 9 2129keys, which will cause 2130.Ar template 2131to be executed as a command with 2132.Ql %% 2133substituted by the pane ID. 2134The default 2135.Ar template 2136is "select-pane -t '%%'". 2137With 2138.Fl b , 2139other commands are not blocked from running until the indicator is closed. 2140.It Xo Ic find-window 2141.Op Fl iCNrTZ 2142.Op Fl t Ar target-pane 2143.Ar match-string 2144.Xc 2145.D1 (alias: Ic findw ) 2146Search for a 2147.Xr fnmatch 3 2148pattern or, with 2149.Fl r , 2150regular expression 2151.Ar match-string 2152in window names, titles, and visible content (but not history). 2153The flags control matching behavior: 2154.Fl C 2155matches only visible window contents, 2156.Fl N 2157matches only the window name and 2158.Fl T 2159matches only the window title. 2160.Fl i 2161makes the search ignore case. 2162The default is 2163.Fl CNT . 2164.Fl Z 2165zooms the pane. 2166.Pp 2167This command works only if at least one client is attached. 2168.It Xo Ic join-pane 2169.Op Fl bdfhv 2170.Op Fl l Ar size 2171.Op Fl s Ar src-pane 2172.Op Fl t Ar dst-pane 2173.Xc 2174.D1 (alias: Ic joinp ) 2175Like 2176.Ic split-window , 2177but instead of splitting 2178.Ar dst-pane 2179and creating a new pane, split it and move 2180.Ar src-pane 2181into the space. 2182This can be used to reverse 2183.Ic break-pane . 2184The 2185.Fl b 2186option causes 2187.Ar src-pane 2188to be joined to left of or above 2189.Ar dst-pane . 2190.Pp 2191If 2192.Fl s 2193is omitted and a marked pane is present (see 2194.Ic select-pane 2195.Fl m ) , 2196the marked pane is used rather than the current pane. 2197.It Xo Ic kill-pane 2198.Op Fl a 2199.Op Fl t Ar target-pane 2200.Xc 2201.D1 (alias: Ic killp ) 2202Destroy the given pane. 2203If no panes remain in the containing window, it is also destroyed. 2204The 2205.Fl a 2206option kills all but the pane given with 2207.Fl t . 2208.It Xo Ic kill-window 2209.Op Fl a 2210.Op Fl t Ar target-window 2211.Xc 2212.D1 (alias: Ic killw ) 2213Kill the current window or the window at 2214.Ar target-window , 2215removing it from any sessions to which it is linked. 2216The 2217.Fl a 2218option kills all but the window given with 2219.Fl t . 2220.It Xo Ic last-pane 2221.Op Fl deZ 2222.Op Fl t Ar target-window 2223.Xc 2224.D1 (alias: Ic lastp ) 2225Select the last (previously selected) pane. 2226.Fl Z 2227keeps the window zoomed if it was zoomed. 2228.Fl e 2229enables or 2230.Fl d 2231disables input to the pane. 2232.It Ic last-window Op Fl t Ar target-session 2233.D1 (alias: Ic last ) 2234Select the last (previously selected) window. 2235If no 2236.Ar target-session 2237is specified, select the last window of the current session. 2238.It Xo Ic link-window 2239.Op Fl abdk 2240.Op Fl s Ar src-window 2241.Op Fl t Ar dst-window 2242.Xc 2243.D1 (alias: Ic linkw ) 2244Link the window at 2245.Ar src-window 2246to the specified 2247.Ar dst-window . 2248If 2249.Ar dst-window 2250is specified and no such window exists, the 2251.Ar src-window 2252is linked there. 2253With 2254.Fl a 2255or 2256.Fl b 2257the window is moved to the next index after or before 2258.Ar dst-window 2259(existing windows are moved if necessary). 2260If 2261.Fl k 2262is given and 2263.Ar dst-window 2264exists, it is killed, otherwise an error is generated. 2265If 2266.Fl d 2267is given, the newly linked window is not selected. 2268.It Xo Ic list-panes 2269.Op Fl as 2270.Op Fl F Ar format 2271.Op Fl f Ar filter 2272.Op Fl t Ar target 2273.Xc 2274.D1 (alias: Ic lsp ) 2275If 2276.Fl a 2277is given, 2278.Ar target 2279is ignored and all panes on the server are listed. 2280If 2281.Fl s 2282is given, 2283.Ar target 2284is a session (or the current session). 2285If neither is given, 2286.Ar target 2287is a window (or the current window). 2288.Fl F 2289specifies the format of each line and 2290.Fl f 2291a filter. 2292Only panes for which the filter is true are shown. 2293See the 2294.Sx FORMATS 2295section. 2296.It Xo Ic list-windows 2297.Op Fl a 2298.Op Fl F Ar format 2299.Op Fl f Ar filter 2300.Op Fl t Ar target-session 2301.Xc 2302.D1 (alias: Ic lsw ) 2303If 2304.Fl a 2305is given, list all windows on the server. 2306Otherwise, list windows in the current session or in 2307.Ar target-session . 2308.Fl F 2309specifies the format of each line and 2310.Fl f 2311a filter. 2312Only windows for which the filter is true are shown. 2313See the 2314.Sx FORMATS 2315section. 2316.It Xo Ic move-pane 2317.Op Fl bdfhv 2318.Op Fl l Ar size 2319.Op Fl s Ar src-pane 2320.Op Fl t Ar dst-pane 2321.Xc 2322.D1 (alias: Ic movep ) 2323Does the same as 2324.Ic join-pane . 2325.It Xo Ic move-window 2326.Op Fl abrdk 2327.Op Fl s Ar src-window 2328.Op Fl t Ar dst-window 2329.Xc 2330.D1 (alias: Ic movew ) 2331This is similar to 2332.Ic link-window , 2333except the window at 2334.Ar src-window 2335is moved to 2336.Ar dst-window . 2337With 2338.Fl r , 2339all windows in the session are renumbered in sequential order, respecting 2340the 2341.Ic base-index 2342option. 2343.It Xo Ic new-window 2344.Op Fl abdkP 2345.Op Fl c Ar start-directory 2346.Op Fl e Ar environment 2347.Op Fl F Ar format 2348.Op Fl n Ar window-name 2349.Op Fl t Ar target-window 2350.Op Ar shell-command 2351.Xc 2352.D1 (alias: Ic neww ) 2353Create a new window. 2354With 2355.Fl a 2356or 2357.Fl b , 2358the new window is inserted at the next index after or before the specified 2359.Ar target-window , 2360moving windows up if necessary; 2361otherwise 2362.Ar target-window 2363is the new window location. 2364.Pp 2365If 2366.Fl d 2367is given, the session does not make the new window the current window. 2368.Ar target-window 2369represents the window to be created; if the target already exists an error is 2370shown, unless the 2371.Fl k 2372flag is used, in which case it is destroyed. 2373.Ar shell-command 2374is the command to execute. 2375If 2376.Ar shell-command 2377is not specified, the value of the 2378.Ic default-command 2379option is used. 2380.Fl c 2381specifies the working directory in which the new window is created. 2382.Pp 2383When the shell command completes, the window closes. 2384See the 2385.Ic remain-on-exit 2386option to change this behaviour. 2387.Pp 2388.Fl e 2389takes the form 2390.Ql VARIABLE=value 2391and sets an environment variable for the newly created window; it may be 2392specified multiple times. 2393.Pp 2394The 2395.Ev TERM 2396environment variable must be set to 2397.Ql screen 2398or 2399.Ql tmux 2400for all programs running 2401.Em inside 2402.Nm . 2403New windows will automatically have 2404.Ql TERM=screen 2405added to their environment, but care must be taken not to reset this in shell 2406start-up files or by the 2407.Fl e 2408option. 2409.Pp 2410The 2411.Fl P 2412option prints information about the new window after it has been created. 2413By default, it uses the format 2414.Ql #{session_name}:#{window_index} 2415but a different format may be specified with 2416.Fl F . 2417.It Ic next-layout Op Fl t Ar target-window 2418.D1 (alias: Ic nextl ) 2419Move a window to the next layout and rearrange the panes to fit. 2420.It Xo Ic next-window 2421.Op Fl a 2422.Op Fl t Ar target-session 2423.Xc 2424.D1 (alias: Ic next ) 2425Move to the next window in the session. 2426If 2427.Fl a 2428is used, move to the next window with an alert. 2429.It Xo Ic pipe-pane 2430.Op Fl IOo 2431.Op Fl t Ar target-pane 2432.Op Ar shell-command 2433.Xc 2434.D1 (alias: Ic pipep ) 2435Pipe output sent by the program in 2436.Ar target-pane 2437to a shell command or vice versa. 2438A pane may only be connected to one command at a time, any existing pipe is 2439closed before 2440.Ar shell-command 2441is executed. 2442The 2443.Ar shell-command 2444string may contain the special character sequences supported by the 2445.Ic status-left 2446option. 2447If no 2448.Ar shell-command 2449is given, the current pipe (if any) is closed. 2450.Pp 2451.Fl I 2452and 2453.Fl O 2454specify which of the 2455.Ar shell-command 2456output streams are connected to the pane: 2457with 2458.Fl I 2459stdout is connected (so anything 2460.Ar shell-command 2461prints is written to the pane as if it were typed); 2462with 2463.Fl O 2464stdin is connected (so any output in the pane is piped to 2465.Ar shell-command ) . 2466Both may be used together and if neither are specified, 2467.Fl O 2468is used. 2469.Pp 2470The 2471.Fl o 2472option only opens a new pipe if no previous pipe exists, allowing a pipe to 2473be toggled with a single key, for example: 2474.Bd -literal -offset indent 2475bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' 2476.Ed 2477.It Xo Ic previous-layout 2478.Op Fl t Ar target-window 2479.Xc 2480.D1 (alias: Ic prevl ) 2481Move to the previous layout in the session. 2482.It Xo Ic previous-window 2483.Op Fl a 2484.Op Fl t Ar target-session 2485.Xc 2486.D1 (alias: Ic prev ) 2487Move to the previous window in the session. 2488With 2489.Fl a , 2490move to the previous window with an alert. 2491.It Xo Ic rename-window 2492.Op Fl t Ar target-window 2493.Ar new-name 2494.Xc 2495.D1 (alias: Ic renamew ) 2496Rename the current window, or the window at 2497.Ar target-window 2498if specified, to 2499.Ar new-name . 2500.It Xo Ic resize-pane 2501.Op Fl DLMRTUZ 2502.Op Fl t Ar target-pane 2503.Op Fl x Ar width 2504.Op Fl y Ar height 2505.Op Ar adjustment 2506.Xc 2507.D1 (alias: Ic resizep ) 2508Resize a pane, up, down, left or right by 2509.Ar adjustment 2510with 2511.Fl U , 2512.Fl D , 2513.Fl L 2514or 2515.Fl R , 2516or 2517to an absolute size 2518with 2519.Fl x 2520or 2521.Fl y . 2522The 2523.Ar adjustment 2524is given in lines or columns (the default is 1); 2525.Fl x 2526and 2527.Fl y 2528may be a given as a number of lines or columns or followed by 2529.Ql % 2530for a percentage of the window size (for example 2531.Ql -x 10% ) . 2532With 2533.Fl Z , 2534the active pane is toggled between zoomed (occupying the whole of the window) 2535and unzoomed (its normal position in the layout). 2536.Pp 2537.Fl M 2538begins mouse resizing (only valid if bound to a mouse key binding, see 2539.Sx MOUSE SUPPORT ) . 2540.Pp 2541.Fl T 2542trims all lines below the current cursor position and moves lines out of the 2543history to replace them. 2544.It Xo Ic resize-window 2545.Op Fl aADLRU 2546.Op Fl t Ar target-window 2547.Op Fl x Ar width 2548.Op Fl y Ar height 2549.Op Ar adjustment 2550.Xc 2551.D1 (alias: Ic resizew ) 2552Resize a window, up, down, left or right by 2553.Ar adjustment 2554with 2555.Fl U , 2556.Fl D , 2557.Fl L 2558or 2559.Fl R , 2560or 2561to an absolute size 2562with 2563.Fl x 2564or 2565.Fl y . 2566The 2567.Ar adjustment 2568is given in lines or cells (the default is 1). 2569.Fl A 2570sets the size of the largest session containing the window; 2571.Fl a 2572the size of the smallest. 2573This command will automatically set 2574.Ic window-size 2575to manual in the window options. 2576.It Xo Ic respawn-pane 2577.Op Fl k 2578.Op Fl c Ar start-directory 2579.Op Fl e Ar environment 2580.Op Fl t Ar target-pane 2581.Op Ar shell-command 2582.Xc 2583.D1 (alias: Ic respawnp ) 2584Reactivate a pane in which the command has exited (see the 2585.Ic remain-on-exit 2586window option). 2587If 2588.Ar shell-command 2589is not given, the command used when the pane was created or last respawned is 2590executed. 2591The pane must be already inactive, unless 2592.Fl k 2593is given, in which case any existing command is killed. 2594.Fl c 2595specifies a new working directory for the pane. 2596The 2597.Fl e 2598option has the same meaning as for the 2599.Ic new-window 2600command. 2601.It Xo Ic respawn-window 2602.Op Fl k 2603.Op Fl c Ar start-directory 2604.Op Fl e Ar environment 2605.Op Fl t Ar target-window 2606.Op Ar shell-command 2607.Xc 2608.D1 (alias: Ic respawnw ) 2609Reactivate a window in which the command has exited (see the 2610.Ic remain-on-exit 2611window option). 2612If 2613.Ar shell-command 2614is not given, the command used when the window was created or last respawned is 2615executed. 2616The window must be already inactive, unless 2617.Fl k 2618is given, in which case any existing command is killed. 2619.Fl c 2620specifies a new working directory for the window. 2621The 2622.Fl e 2623option has the same meaning as for the 2624.Ic new-window 2625command. 2626.It Xo Ic rotate-window 2627.Op Fl DUZ 2628.Op Fl t Ar target-window 2629.Xc 2630.D1 (alias: Ic rotatew ) 2631Rotate the positions of the panes within a window, either upward (numerically 2632lower) with 2633.Fl U 2634or downward (numerically higher). 2635.Fl Z 2636keeps the window zoomed if it was zoomed. 2637.It Xo Ic select-layout 2638.Op Fl Enop 2639.Op Fl t Ar target-pane 2640.Op Ar layout-name 2641.Xc 2642.D1 (alias: Ic selectl ) 2643Choose a specific layout for a window. 2644If 2645.Ar layout-name 2646is not given, the last preset layout used (if any) is reapplied. 2647.Fl n 2648and 2649.Fl p 2650are equivalent to the 2651.Ic next-layout 2652and 2653.Ic previous-layout 2654commands. 2655.Fl o 2656applies the last set layout if possible (undoes the most recent layout change). 2657.Fl E 2658spreads the current pane and any panes next to it out evenly. 2659.It Xo Ic select-pane 2660.Op Fl DdeLlMmRUZ 2661.Op Fl T Ar title 2662.Op Fl t Ar target-pane 2663.Xc 2664.D1 (alias: Ic selectp ) 2665Make pane 2666.Ar target-pane 2667the active pane in its window. 2668If one of 2669.Fl D , 2670.Fl L , 2671.Fl R , 2672or 2673.Fl U 2674is used, respectively the pane below, to the left, to the right, or above the 2675target pane is used. 2676.Fl Z 2677keeps the window zoomed if it was zoomed. 2678.Fl l 2679is the same as using the 2680.Ic last-pane 2681command. 2682.Fl e 2683enables or 2684.Fl d 2685disables input to the pane. 2686.Fl T 2687sets the pane title. 2688.Pp 2689.Fl m 2690and 2691.Fl M 2692are used to set and clear the 2693.Em marked pane . 2694There is one marked pane at a time, setting a new marked pane clears the last. 2695The marked pane is the default target for 2696.Fl s 2697to 2698.Ic join-pane , 2699.Ic move-pane , 2700.Ic swap-pane 2701and 2702.Ic swap-window . 2703.It Xo Ic select-window 2704.Op Fl lnpT 2705.Op Fl t Ar target-window 2706.Xc 2707.D1 (alias: Ic selectw ) 2708Select the window at 2709.Ar target-window . 2710.Fl l , 2711.Fl n 2712and 2713.Fl p 2714are equivalent to the 2715.Ic last-window , 2716.Ic next-window 2717and 2718.Ic previous-window 2719commands. 2720If 2721.Fl T 2722is given and the selected window is already the current window, 2723the command behaves like 2724.Ic last-window . 2725.It Xo Ic split-window 2726.Op Fl bdfhIvP 2727.Op Fl c Ar start-directory 2728.Op Fl e Ar environment 2729.Op Fl l Ar size 2730.Op Fl t Ar target-pane 2731.Op Ar shell-command 2732.Op Fl F Ar format 2733.Xc 2734.D1 (alias: Ic splitw ) 2735Create a new pane by splitting 2736.Ar target-pane : 2737.Fl h 2738does a horizontal split and 2739.Fl v 2740a vertical split; if neither is specified, 2741.Fl v 2742is assumed. 2743The 2744.Fl l 2745option specifies the size of the new pane in lines (for vertical split) or in 2746columns (for horizontal split); 2747.Ar size 2748may be followed by 2749.Ql % 2750to specify a percentage of the available space. 2751The 2752.Fl b 2753option causes the new pane to be created to the left of or above 2754.Ar target-pane . 2755The 2756.Fl f 2757option creates a new pane spanning the full window height (with 2758.Fl h ) 2759or full window width (with 2760.Fl v ) , 2761instead of splitting the active pane. 2762.Pp 2763An empty 2764.Ar shell-command 2765('') will create a pane with no command running in it. 2766Output can be sent to such a pane with the 2767.Ic display-message 2768command. 2769The 2770.Fl I 2771flag (if 2772.Ar shell-command 2773is not specified or empty) 2774will create an empty pane and forward any output from stdin to it. 2775For example: 2776.Bd -literal -offset indent 2777$ make 2>&1|tmux splitw -dI & 2778.Ed 2779.Pp 2780All other options have the same meaning as for the 2781.Ic new-window 2782command. 2783.It Xo Ic swap-pane 2784.Op Fl dDUZ 2785.Op Fl s Ar src-pane 2786.Op Fl t Ar dst-pane 2787.Xc 2788.D1 (alias: Ic swapp ) 2789Swap two panes. 2790If 2791.Fl U 2792is used and no source pane is specified with 2793.Fl s , 2794.Ar dst-pane 2795is swapped with the previous pane (before it numerically); 2796.Fl D 2797swaps with the next pane (after it numerically). 2798.Fl d 2799instructs 2800.Nm 2801not to change the active pane and 2802.Fl Z 2803keeps the window zoomed if it was zoomed. 2804.Pp 2805If 2806.Fl s 2807is omitted and a marked pane is present (see 2808.Ic select-pane 2809.Fl m ) , 2810the marked pane is used rather than the current pane. 2811.It Xo Ic swap-window 2812.Op Fl d 2813.Op Fl s Ar src-window 2814.Op Fl t Ar dst-window 2815.Xc 2816.D1 (alias: Ic swapw ) 2817This is similar to 2818.Ic link-window , 2819except the source and destination windows are swapped. 2820It is an error if no window exists at 2821.Ar src-window . 2822If 2823.Fl d 2824is given, the new window does not become the current window. 2825.Pp 2826If 2827.Fl s 2828is omitted and a marked pane is present (see 2829.Ic select-pane 2830.Fl m ) , 2831the window containing the marked pane is used rather than the current window. 2832.It Xo Ic unlink-window 2833.Op Fl k 2834.Op Fl t Ar target-window 2835.Xc 2836.D1 (alias: Ic unlinkw ) 2837Unlink 2838.Ar target-window . 2839Unless 2840.Fl k 2841is given, a window may be unlinked only if it is linked to multiple sessions - 2842windows may not be linked to no sessions; 2843if 2844.Fl k 2845is specified and the window is linked to only one session, it is unlinked and 2846destroyed. 2847.El 2848.Sh KEY BINDINGS 2849.Nm 2850allows a command to be bound to most keys, with or without a prefix key. 2851When specifying keys, most represent themselves (for example 2852.Ql A 2853to 2854.Ql Z ) . 2855Ctrl keys may be prefixed with 2856.Ql C- 2857or 2858.Ql ^ , 2859and Alt (meta) with 2860.Ql M- . 2861In addition, the following special key names are accepted: 2862.Em Up , 2863.Em Down , 2864.Em Left , 2865.Em Right , 2866.Em BSpace , 2867.Em BTab , 2868.Em DC 2869(Delete), 2870.Em End , 2871.Em Enter , 2872.Em Escape , 2873.Em F1 2874to 2875.Em F12 , 2876.Em Home , 2877.Em IC 2878(Insert), 2879.Em NPage/PageDown/PgDn , 2880.Em PPage/PageUp/PgUp , 2881.Em Space , 2882and 2883.Em Tab . 2884Note that to bind the 2885.Ql \&" 2886or 2887.Ql ' 2888keys, quotation marks are necessary, for example: 2889.Bd -literal -offset indent 2890bind-key '"' split-window 2891bind-key "'" new-window 2892.Ed 2893.Pp 2894A command bound to the 2895.Em Any 2896key will execute for all keys which do not have a more specific binding. 2897.Pp 2898Commands related to key bindings are as follows: 2899.Bl -tag -width Ds 2900.It Xo Ic bind-key 2901.Op Fl nr 2902.Op Fl N Ar note 2903.Op Fl T Ar key-table 2904.Ar key command Op Ar arguments 2905.Xc 2906.D1 (alias: Ic bind ) 2907Bind key 2908.Ar key 2909to 2910.Ar command . 2911Keys are bound in a key table. 2912By default (without -T), the key is bound in 2913the 2914.Em prefix 2915key table. 2916This table is used for keys pressed after the prefix key (for example, 2917by default 2918.Ql c 2919is bound to 2920.Ic new-window 2921in the 2922.Em prefix 2923table, so 2924.Ql C-b c 2925creates a new window). 2926The 2927.Em root 2928table is used for keys pressed without the prefix key: binding 2929.Ql c 2930to 2931.Ic new-window 2932in the 2933.Em root 2934table (not recommended) means a plain 2935.Ql c 2936will create a new window. 2937.Fl n 2938is an alias 2939for 2940.Fl T Ar root . 2941Keys may also be bound in custom key tables and the 2942.Ic switch-client 2943.Fl T 2944command used to switch to them from a key binding. 2945The 2946.Fl r 2947flag indicates this key may repeat, see the 2948.Ic repeat-time 2949option. 2950.Fl N 2951attaches a note to the key (shown with 2952.Ic list-keys 2953.Fl N ) . 2954.Pp 2955To view the default bindings and possible commands, see the 2956.Ic list-keys 2957command. 2958.It Xo Ic list-keys 2959.Op Fl 1aN 2960.Op Fl P Ar prefix-string Fl T Ar key-table 2961.Op Ar key 2962.Xc 2963.D1 (alias: Ic lsk ) 2964List key bindings. 2965There are two forms: the default lists keys as 2966.Ic bind-key 2967commands; 2968.Fl N 2969lists only keys with attached notes and shows only the key and note for each 2970key. 2971.Pp 2972With the default form, all key tables are listed by default. 2973.Fl T 2974lists only keys in 2975.Ar key-table . 2976.Pp 2977With the 2978.Fl N 2979form, only keys in the 2980.Em root 2981and 2982.Em prefix 2983key tables are listed by default; 2984.Fl T 2985also lists only keys in 2986.Ar key-table . 2987.Fl P 2988specifies a prefix to print before each key and 2989.Fl 1 2990lists only the first matching key. 2991.Fl a 2992lists the command for keys that do not have a note rather than skipping them. 2993.It Xo Ic send-keys 2994.Op Fl FHlMRX 2995.Op Fl N Ar repeat-count 2996.Op Fl t Ar target-pane 2997.Ar key Ar ... 2998.Xc 2999.D1 (alias: Ic send ) 3000Send a key or keys to a window. 3001Each argument 3002.Ar key 3003is the name of the key (such as 3004.Ql C-a 3005or 3006.Ql NPage ) 3007to send; if the string is not recognised as a key, it is sent as a series of 3008characters. 3009All arguments are sent sequentially from first to last. 3010.Pp 3011The 3012.Fl l 3013flag disables key name lookup and processes the keys as literal UTF-8 3014characters. 3015The 3016.Fl H 3017flag expects each key to be a hexadecimal number for an ASCII character. 3018.Pp 3019The 3020.Fl R 3021flag causes the terminal state to be reset. 3022.Pp 3023.Fl M 3024passes through a mouse event (only valid if bound to a mouse key binding, see 3025.Sx MOUSE SUPPORT ) . 3026.Pp 3027.Fl X 3028is used to send a command into copy mode - see 3029the 3030.Sx WINDOWS AND PANES 3031section. 3032.Fl N 3033specifies a repeat count and 3034.Fl F 3035expands formats in arguments where appropriate. 3036.It Xo Ic send-prefix 3037.Op Fl 2 3038.Op Fl t Ar target-pane 3039.Xc 3040Send the prefix key, or with 3041.Fl 2 3042the secondary prefix key, to a window as if it was pressed. 3043.It Xo Ic unbind-key 3044.Op Fl anq 3045.Op Fl T Ar key-table 3046.Ar key 3047.Xc 3048.D1 (alias: Ic unbind ) 3049Unbind the command bound to 3050.Ar key . 3051.Fl n 3052and 3053.Fl T 3054are the same as for 3055.Ic bind-key . 3056If 3057.Fl a 3058is present, all key bindings are removed. 3059The 3060.Fl q 3061option prevents errors being returned. 3062.El 3063.Sh OPTIONS 3064The appearance and behaviour of 3065.Nm 3066may be modified by changing the value of various options. 3067There are four types of option: 3068.Em server options , 3069.Em session options 3070.Em window options 3071and 3072.Em pane options . 3073.Pp 3074The 3075.Nm 3076server has a set of global server options which do not apply to any particular 3077window or session or pane. 3078These are altered with the 3079.Ic set-option 3080.Fl s 3081command, or displayed with the 3082.Ic show-options 3083.Fl s 3084command. 3085.Pp 3086In addition, each individual session may have a set of session options, and 3087there is a separate set of global session options. 3088Sessions which do not have a particular option configured inherit the value 3089from the global session options. 3090Session options are set or unset with the 3091.Ic set-option 3092command and may be listed with the 3093.Ic show-options 3094command. 3095The available server and session options are listed under the 3096.Ic set-option 3097command. 3098.Pp 3099Similarly, a set of window options is attached to each window and a set of pane 3100options to each pane. 3101Pane options inherit from window options. 3102This means any pane option may be set as a window option to apply the option to 3103all panes in the window without the option set, for example these commands will 3104set the background colour to red for all panes except pane 0: 3105.Bd -literal -offset indent 3106set -w window-style bg=red 3107set -pt:.0 window-style bg=blue 3108.Ed 3109.Pp 3110There is also a set of global window options from which any unset window or 3111pane options are inherited. 3112Window and pane options are altered with 3113.Ic set-option 3114.Fl w 3115and 3116.Fl p 3117commands and displayed with 3118.Ic show-option 3119.Fl w 3120and 3121.Fl p . 3122.Pp 3123.Nm 3124also supports user options which are prefixed with a 3125.Ql \&@ . 3126User options may have any name, so long as they are prefixed with 3127.Ql \&@ , 3128and be set to any string. 3129For example: 3130.Bd -literal -offset indent 3131$ tmux set -wq @foo "abc123" 3132$ tmux show -wv @foo 3133abc123 3134.Ed 3135.Pp 3136Commands which set options are as follows: 3137.Bl -tag -width Ds 3138.It Xo Ic set-option 3139.Op Fl aFgopqsuUw 3140.Op Fl t Ar target-pane 3141.Ar option Ar value 3142.Xc 3143.D1 (alias: Ic set ) 3144Set a pane option with 3145.Fl p , 3146a window option with 3147.Fl w , 3148a server option with 3149.Fl s , 3150otherwise a session option. 3151If the option is not a user option, 3152.Fl w 3153or 3154.Fl s 3155may be unnecessary - 3156.Nm 3157will infer the type from the option name, assuming 3158.Fl w 3159for pane options. 3160If 3161.Fl g 3162is given, the global session or window option is set. 3163.Pp 3164.Fl F 3165expands formats in the option value. 3166The 3167.Fl u 3168flag unsets an option, so a session inherits the option from the global 3169options (or with 3170.Fl g , 3171restores a global option to the default). 3172.Fl U 3173unsets an option (like 3174.Fl u ) 3175but if the option is a pane option also unsets the option on any panes in the 3176window. 3177.Ar value 3178depends on the option and may be a number, a string, or a flag (on, off, or 3179omitted to toggle). 3180.Pp 3181The 3182.Fl o 3183flag prevents setting an option that is already set and the 3184.Fl q 3185flag suppresses errors about unknown or ambiguous options. 3186.Pp 3187With 3188.Fl a , 3189and if the option expects a string or a style, 3190.Ar value 3191is appended to the existing setting. 3192For example: 3193.Bd -literal -offset indent 3194set -g status-left "foo" 3195set -ag status-left "bar" 3196.Ed 3197.Pp 3198Will result in 3199.Ql foobar . 3200And: 3201.Bd -literal -offset indent 3202set -g status-style "bg=red" 3203set -ag status-style "fg=blue" 3204.Ed 3205.Pp 3206Will result in a red background 3207.Em and 3208blue foreground. 3209Without 3210.Fl a , 3211the result would be the default background and a blue foreground. 3212.It Xo Ic show-options 3213.Op Fl AgHpqsvw 3214.Op Fl t Ar target-pane 3215.Op Ar option 3216.Xc 3217.D1 (alias: Ic show ) 3218Show the pane options (or a single option if 3219.Ar option 3220is provided) with 3221.Fl p , 3222the window options with 3223.Fl w , 3224the server options with 3225.Fl s , 3226otherwise the session options. 3227If the option is not a user option, 3228.Fl w 3229or 3230.Fl s 3231may be unnecessary - 3232.Nm 3233will infer the type from the option name, assuming 3234.Fl w 3235for pane options. 3236Global session or window options are listed if 3237.Fl g 3238is used. 3239.Fl v 3240shows only the option value, not the name. 3241If 3242.Fl q 3243is set, no error will be returned if 3244.Ar option 3245is unset. 3246.Fl H 3247includes hooks (omitted by default). 3248.Fl A 3249includes options inherited from a parent set of options, such options are 3250marked with an asterisk. 3251.El 3252.Pp 3253Available server options are: 3254.Bl -tag -width Ds 3255.It Ic backspace Ar key 3256Set the key sent by 3257.Nm 3258for backspace. 3259.It Ic buffer-limit Ar number 3260Set the number of buffers; as new buffers are added to the top of the stack, 3261old ones are removed from the bottom if necessary to maintain this maximum 3262length. 3263.It Xo Ic command-alias[] 3264.Ar name=value 3265.Xc 3266This is an array of custom aliases for commands. 3267If an unknown command matches 3268.Ar name , 3269it is replaced with 3270.Ar value . 3271For example, after: 3272.Pp 3273.Dl set -s command-alias[100] zoom='resize-pane -Z' 3274.Pp 3275Using: 3276.Pp 3277.Dl zoom -t:.1 3278.Pp 3279Is equivalent to: 3280.Pp 3281.Dl resize-pane -Z -t:.1 3282.Pp 3283Note that aliases are expanded when a command is parsed rather than when it is 3284executed, so binding an alias with 3285.Ic bind-key 3286will bind the expanded form. 3287.It Ic default-terminal Ar terminal 3288Set the default terminal for new windows created in this session - the 3289default value of the 3290.Ev TERM 3291environment variable. 3292For 3293.Nm 3294to work correctly, this 3295.Em must 3296be set to 3297.Ql screen , 3298.Ql tmux 3299or a derivative of them. 3300.It Ic copy-command Ar shell-command 3301Give the command to pipe to if the 3302.Ic copy-pipe 3303copy mode command is used without arguments. 3304.It Ic escape-time Ar time 3305Set the time in milliseconds for which 3306.Nm 3307waits after an escape is input to determine if it is part of a function or meta 3308key sequences. 3309The default is 500 milliseconds. 3310.It Ic editor Ar shell-command 3311Set the command used when 3312.Nm 3313runs an editor. 3314.It Xo Ic exit-empty 3315.Op Ic on | off 3316.Xc 3317If enabled (the default), the server will exit when there are no active 3318sessions. 3319.It Xo Ic exit-unattached 3320.Op Ic on | off 3321.Xc 3322If enabled, the server will exit when there are no attached clients. 3323.It Xo Ic extended-keys 3324.Op Ic on | off 3325.Xc 3326When enabled, extended keys are requested from the terminal and if supported 3327are recognised by 3328.Nm . 3329.It Xo Ic focus-events 3330.Op Ic on | off 3331.Xc 3332When enabled, focus events are requested from the terminal if supported and 3333passed through to applications running in 3334.Nm . 3335Attached clients should be detached and attached again after changing this 3336option. 3337.It Ic history-file Ar path 3338If not empty, a file to which 3339.Nm 3340will write command prompt history on exit and load it from on start. 3341.It Ic message-limit Ar number 3342Set the number of error or information messages to save in the message log for 3343each client. 3344The default is 100. 3345.It Xo Ic set-clipboard 3346.Op Ic on | external | off 3347.Xc 3348Attempt to set the terminal clipboard content using the 3349.Xr xterm 1 3350escape sequence, if there is an 3351.Em \&Ms 3352entry in the 3353.Xr terminfo 5 3354description (see the 3355.Sx TERMINFO EXTENSIONS 3356section). 3357.Pp 3358If set to 3359.Ic on , 3360.Nm 3361will both accept the escape sequence to create a buffer and attempt to set 3362the terminal clipboard. 3363If set to 3364.Ic external , 3365.Nm 3366will attempt to set the terminal clipboard but ignore attempts 3367by applications to set 3368.Nm 3369buffers. 3370If 3371.Ic off , 3372.Nm 3373will neither accept the clipboard escape sequence nor attempt to set the 3374clipboard. 3375.Pp 3376Note that this feature needs to be enabled in 3377.Xr xterm 1 3378by setting the resource: 3379.Bd -literal -offset indent 3380disallowedWindowOps: 20,21,SetXprop 3381.Ed 3382.Pp 3383Or changing this property from the 3384.Xr xterm 1 3385interactive menu when required. 3386.It Ic terminal-features[] Ar string 3387Set terminal features for terminal types read from 3388.Xr terminfo 5 . 3389.Nm 3390has a set of named terminal features. 3391Each will apply appropriate changes to the 3392.Xr terminfo 5 3393entry in use. 3394.Pp 3395.Nm 3396can detect features for a few common terminals; this option can be used to 3397easily tell tmux about features supported by terminals it cannot detect. 3398The 3399.Ic terminal-overrides 3400option allows individual 3401.Xr terminfo 5 3402capabilities to be set instead, 3403.Ic terminal-features 3404is intended for classes of functionality supported in a standard way but not 3405reported by 3406.Xr terminfo 5 . 3407Care must be taken only to configure this with features the terminal actually 3408support. 3409.Pp 3410This is an array option where each entry is a colon-separated string made up 3411of a terminal type pattern (matched using 3412.Xr fnmatch 3 ) 3413followed by a list of terminal features. 3414The available features are: 3415.Bl -tag -width Ds 3416.It 256 3417Supports 256 colours with the SGR escape sequences. 3418.It clipboard 3419Allows setting the system clipboard. 3420.It ccolour 3421Allows setting the cursor colour. 3422.It cstyle 3423Allows setting the cursor style. 3424.It extkeys 3425Supports extended keys. 3426.It focus 3427Supports focus reporting. 3428.It margins 3429Supports DECSLRM margins. 3430.It overline 3431Supports the overline SGR attribute. 3432.It rectfill 3433Supports the DECFRA rectangle fill escape sequence. 3434.It RGB 3435Supports RGB colour with the SGR escape sequences. 3436.It strikethrough 3437Supports the strikethrough SGR escape sequence. 3438.It sync 3439Supports synchronized updates. 3440.It title 3441Supports 3442.Xr xterm 1 3443title setting. 3444.It usstyle 3445Allows underscore style and colour to be set. 3446.It UTF-8 3447Is able to handle UTF-8 output. 3448.El 3449.It Ic terminal-overrides[] Ar string 3450Allow terminal descriptions read using 3451.Xr terminfo 5 3452to be overridden. 3453Each entry is a colon-separated string made up of a terminal type pattern 3454(matched using 3455.Xr fnmatch 3 ) 3456and a set of 3457.Em name=value 3458entries. 3459.Pp 3460For example, to set the 3461.Ql clear 3462.Xr terminfo 5 3463entry to 3464.Ql \ee[H\ee[2J 3465for all terminal types matching 3466.Ql rxvt* : 3467.Pp 3468.Dl "rxvt*:clear=\ee[H\ee[2J" 3469.Pp 3470The terminal entry value is passed through 3471.Xr strunvis 3 3472before interpretation. 3473.It Ic user-keys[] Ar key 3474Set list of user-defined key escape sequences. 3475Each item is associated with a key named 3476.Ql User0 , 3477.Ql User1 , 3478and so on. 3479.Pp 3480For example: 3481.Bd -literal -offset indent 3482set -s user-keys[0] "\ee[5;30012~" 3483bind User0 resize-pane -L 3 3484.Ed 3485.El 3486.Pp 3487Available session options are: 3488.Bl -tag -width Ds 3489.It Xo Ic activity-action 3490.Op Ic any | none | current | other 3491.Xc 3492Set action on window activity when 3493.Ic monitor-activity 3494is on. 3495.Ic any 3496means activity in any window linked to a session causes a bell or message 3497(depending on 3498.Ic visual-activity ) 3499in the current window of that session, 3500.Ic none 3501means all activity is ignored (equivalent to 3502.Ic monitor-activity 3503being off), 3504.Ic current 3505means only activity in windows other than the current window are ignored and 3506.Ic other 3507means activity in the current window is ignored but not those in other windows. 3508.It Ic assume-paste-time Ar milliseconds 3509If keys are entered faster than one in 3510.Ar milliseconds , 3511they are assumed to have been pasted rather than typed and 3512.Nm 3513key bindings are not processed. 3514The default is one millisecond and zero disables. 3515.It Ic base-index Ar index 3516Set the base index from which an unused index should be searched when a new 3517window is created. 3518The default is zero. 3519.It Xo Ic bell-action 3520.Op Ic any | none | current | other 3521.Xc 3522Set action on a bell in a window when 3523.Ic monitor-bell 3524is on. 3525The values are the same as those for 3526.Ic activity-action . 3527.It Ic default-command Ar shell-command 3528Set the command used for new windows (if not specified when the window is 3529created) to 3530.Ar shell-command , 3531which may be any 3532.Xr sh 1 3533command. 3534The default is an empty string, which instructs 3535.Nm 3536to create a login shell using the value of the 3537.Ic default-shell 3538option. 3539.It Ic default-shell Ar path 3540Specify the default shell. 3541This is used as the login shell for new windows when the 3542.Ic default-command 3543option is set to empty, and must be the full path of the executable. 3544When started 3545.Nm 3546tries to set a default value from the first suitable of the 3547.Ev SHELL 3548environment variable, the shell returned by 3549.Xr getpwuid 3 , 3550or 3551.Pa /bin/sh . 3552This option should be configured when 3553.Nm 3554is used as a login shell. 3555.It Ic default-size Ar XxY 3556Set the default size of new windows when the 3557.Ic window-size 3558option is set to manual or when a session is created with 3559.Ic new-session 3560.Fl d . 3561The value is the width and height separated by an 3562.Ql x 3563character. 3564The default is 80x24. 3565.It Xo Ic destroy-unattached 3566.Op Ic on | off 3567.Xc 3568If enabled and the session is no longer attached to any clients, it is 3569destroyed. 3570.It Xo Ic detach-on-destroy 3571.Op Ic on | off 3572.Xc 3573If on (the default), the client is detached when the session it is attached to 3574is destroyed. 3575If off, the client is switched to the most recently active of the remaining 3576sessions. 3577.It Ic display-panes-active-colour Ar colour 3578Set the colour used by the 3579.Ic display-panes 3580command to show the indicator for the active pane. 3581.It Ic display-panes-colour Ar colour 3582Set the colour used by the 3583.Ic display-panes 3584command to show the indicators for inactive panes. 3585.It Ic display-panes-time Ar time 3586Set the time in milliseconds for which the indicators shown by the 3587.Ic display-panes 3588command appear. 3589.It Ic display-time Ar time 3590Set the amount of time for which status line messages and other on-screen 3591indicators are displayed. 3592If set to 0, messages and indicators are displayed until a key is pressed. 3593.Ar time 3594is in milliseconds. 3595.It Ic history-limit Ar lines 3596Set the maximum number of lines held in window history. 3597This setting applies only to new windows - existing window histories are not 3598resized and retain the limit at the point they were created. 3599.It Ic key-table Ar key-table 3600Set the default key table to 3601.Ar key-table 3602instead of 3603.Em root . 3604.It Ic lock-after-time Ar number 3605Lock the session (like the 3606.Ic lock-session 3607command) after 3608.Ar number 3609seconds of inactivity. 3610The default is not to lock (set to 0). 3611.It Ic lock-command Ar shell-command 3612Command to run when locking each client. 3613The default is to run 3614.Xr lock 1 3615with 3616.Fl np . 3617.It Ic message-command-style Ar style 3618Set status line message command style. 3619This is used for the command prompt with 3620.Xr vi 1 3621keys when in command mode. 3622For how to specify 3623.Ar style , 3624see the 3625.Sx STYLES 3626section. 3627.It Ic message-style Ar style 3628Set status line message style. 3629This is used for messages and for the command prompt. 3630For how to specify 3631.Ar style , 3632see the 3633.Sx STYLES 3634section. 3635.It Xo Ic mouse 3636.Op Ic on | off 3637.Xc 3638If on, 3639.Nm 3640captures the mouse and allows mouse events to be bound as key bindings. 3641See the 3642.Sx MOUSE SUPPORT 3643section for details. 3644.It Ic prefix Ar key 3645Set the key accepted as a prefix key. 3646In addition to the standard keys described under 3647.Sx KEY BINDINGS , 3648.Ic prefix 3649can be set to the special key 3650.Ql None 3651to set no prefix. 3652.It Ic prefix2 Ar key 3653Set a secondary key accepted as a prefix key. 3654Like 3655.Ic prefix , 3656.Ic prefix2 3657can be set to 3658.Ql None . 3659.It Xo Ic renumber-windows 3660.Op Ic on | off 3661.Xc 3662If on, when a window is closed in a session, automatically renumber the other 3663windows in numerical order. 3664This respects the 3665.Ic base-index 3666option if it has been set. 3667If off, do not renumber the windows. 3668.It Ic repeat-time Ar time 3669Allow multiple commands to be entered without pressing the prefix-key again 3670in the specified 3671.Ar time 3672milliseconds (the default is 500). 3673Whether a key repeats may be set when it is bound using the 3674.Fl r 3675flag to 3676.Ic bind-key . 3677Repeat is enabled for the default keys bound to the 3678.Ic resize-pane 3679command. 3680.It Xo Ic set-titles 3681.Op Ic on | off 3682.Xc 3683Attempt to set the client terminal title using the 3684.Em tsl 3685and 3686.Em fsl 3687.Xr terminfo 5 3688entries if they exist. 3689.Nm 3690automatically sets these to the \ee]0;...\e007 sequence if 3691the terminal appears to be 3692.Xr xterm 1 . 3693This option is off by default. 3694.It Ic set-titles-string Ar string 3695String used to set the client terminal title if 3696.Ic set-titles 3697is on. 3698Formats are expanded, see the 3699.Sx FORMATS 3700section. 3701.It Xo Ic silence-action 3702.Op Ic any | none | current | other 3703.Xc 3704Set action on window silence when 3705.Ic monitor-silence 3706is on. 3707The values are the same as those for 3708.Ic activity-action . 3709.It Xo Ic status 3710.Op Ic off | on | 2 | 3 | 4 | 5 3711.Xc 3712Show or hide the status line or specify its size. 3713Using 3714.Ic on 3715gives a status line one row in height; 3716.Ic 2 , 3717.Ic 3 , 3718.Ic 4 3719or 3720.Ic 5 3721more rows. 3722.It Ic status-format[] Ar format 3723Specify the format to be used for each line of the status line. 3724The default builds the top status line from the various individual status 3725options below. 3726.It Ic status-interval Ar interval 3727Update the status line every 3728.Ar interval 3729seconds. 3730By default, updates will occur every 15 seconds. 3731A setting of zero disables redrawing at interval. 3732.It Xo Ic status-justify 3733.Op Ic left | centre | right 3734.Xc 3735Set the position of the window list component of the status line: left, centre 3736or right justified. 3737.It Xo Ic status-keys 3738.Op Ic vi | emacs 3739.Xc 3740Use vi or emacs-style 3741key bindings in the status line, for example at the command prompt. 3742The default is emacs, unless the 3743.Ev VISUAL 3744or 3745.Ev EDITOR 3746environment variables are set and contain the string 3747.Ql vi . 3748.It Ic status-left Ar string 3749Display 3750.Ar string 3751(by default the session name) to the left of the status line. 3752.Ar string 3753will be passed through 3754.Xr strftime 3 . 3755Also see the 3756.Sx FORMATS 3757and 3758.Sx STYLES 3759sections. 3760.Pp 3761For details on how the names and titles can be set see the 3762.Sx "NAMES AND TITLES" 3763section. 3764.Pp 3765Examples are: 3766.Bd -literal -offset indent 3767#(sysctl vm.loadavg) 3768#[fg=yellow,bold]#(apm -l)%%#[default] [#S] 3769.Ed 3770.Pp 3771The default is 3772.Ql "[#S] " . 3773.It Ic status-left-length Ar length 3774Set the maximum 3775.Ar length 3776of the left component of the status line. 3777The default is 10. 3778.It Ic status-left-style Ar style 3779Set the style of the left part of the status line. 3780For how to specify 3781.Ar style , 3782see the 3783.Sx STYLES 3784section. 3785.It Xo Ic status-position 3786.Op Ic top | bottom 3787.Xc 3788Set the position of the status line. 3789.It Ic status-right Ar string 3790Display 3791.Ar string 3792to the right of the status line. 3793By default, the current pane title in double quotes, the date and the time 3794are shown. 3795As with 3796.Ic status-left , 3797.Ar string 3798will be passed to 3799.Xr strftime 3 3800and character pairs are replaced. 3801.It Ic status-right-length Ar length 3802Set the maximum 3803.Ar length 3804of the right component of the status line. 3805The default is 40. 3806.It Ic status-right-style Ar style 3807Set the style of the right part of the status line. 3808For how to specify 3809.Ar style , 3810see the 3811.Sx STYLES 3812section. 3813.It Ic status-style Ar style 3814Set status line style. 3815For how to specify 3816.Ar style , 3817see the 3818.Sx STYLES 3819section. 3820.It Ic update-environment[] Ar variable 3821Set list of environment variables to be copied into the session environment 3822when a new session is created or an existing session is attached. 3823Any variables that do not exist in the source environment are set to be 3824removed from the session environment (as if 3825.Fl r 3826was given to the 3827.Ic set-environment 3828command). 3829.It Xo Ic visual-activity 3830.Op Ic on | off | both 3831.Xc 3832If on, display a message instead of sending a bell when activity occurs in a 3833window for which the 3834.Ic monitor-activity 3835window option is enabled. 3836If set to both, a bell and a message are produced. 3837.It Xo Ic visual-bell 3838.Op Ic on | off | both 3839.Xc 3840If on, a message is shown on a bell in a window for which the 3841.Ic monitor-bell 3842window option is enabled instead of it being passed through to the 3843terminal (which normally makes a sound). 3844If set to both, a bell and a message are produced. 3845Also see the 3846.Ic bell-action 3847option. 3848.It Xo Ic visual-silence 3849.Op Ic on | off | both 3850.Xc 3851If 3852.Ic monitor-silence 3853is enabled, prints a message after the interval has expired on a given window 3854instead of sending a bell. 3855If set to both, a bell and a message are produced. 3856.It Ic word-separators Ar string 3857Sets the session's conception of what characters are considered word 3858separators, for the purposes of the next and previous word commands in 3859copy mode. 3860The default is 3861.Ql \ -_@ . 3862.El 3863.Pp 3864Available window options are: 3865.Pp 3866.Bl -tag -width Ds -compact 3867.It Xo Ic aggressive-resize 3868.Op Ic on | off 3869.Xc 3870Aggressively resize the chosen window. 3871This means that 3872.Nm 3873will resize the window to the size of the smallest or largest session 3874(see the 3875.Ic window-size 3876option) for which it is the current window, rather than the session to 3877which it is attached. 3878The window may resize when the current window is changed on another 3879session; this option is good for full-screen programs which support 3880.Dv SIGWINCH 3881and poor for interactive programs such as shells. 3882.Pp 3883.It Xo Ic automatic-rename 3884.Op Ic on | off 3885.Xc 3886Control automatic window renaming. 3887When this setting is enabled, 3888.Nm 3889will rename the window automatically using the format specified by 3890.Ic automatic-rename-format . 3891This flag is automatically disabled for an individual window when a name 3892is specified at creation with 3893.Ic new-window 3894or 3895.Ic new-session , 3896or later with 3897.Ic rename-window , 3898or with a terminal escape sequence. 3899It may be switched off globally with: 3900.Bd -literal -offset indent 3901set-option -wg automatic-rename off 3902.Ed 3903.Pp 3904.It Ic automatic-rename-format Ar format 3905The format (see 3906.Sx FORMATS ) 3907used when the 3908.Ic automatic-rename 3909option is enabled. 3910.Pp 3911.It Ic clock-mode-colour Ar colour 3912Set clock colour. 3913.Pp 3914.It Xo Ic clock-mode-style 3915.Op Ic 12 | 24 3916.Xc 3917Set clock hour format. 3918.Pp 3919.It Ic main-pane-height Ar height 3920.It Ic main-pane-width Ar width 3921Set the width or height of the main (left or top) pane in the 3922.Ic main-horizontal 3923or 3924.Ic main-vertical 3925layouts. 3926If suffixed by 3927.Ql % , 3928this is a percentage of the window size. 3929.Pp 3930.It Ic copy-mode-match-style Ar style 3931Set the style of search matches in copy mode. 3932For how to specify 3933.Ar style , 3934see the 3935.Sx STYLES 3936section. 3937.Pp 3938.It Ic copy-mode-mark-style Ar style 3939Set the style of the line containing the mark in copy mode. 3940For how to specify 3941.Ar style , 3942see the 3943.Sx STYLES 3944section. 3945.Pp 3946.It Ic copy-mode-current-match-style Ar style 3947Set the style of the current search match in copy mode. 3948For how to specify 3949.Ar style , 3950see the 3951.Sx STYLES 3952section. 3953.Pp 3954.It Xo Ic mode-keys 3955.Op Ic vi | emacs 3956.Xc 3957Use vi or emacs-style key bindings in copy mode. 3958The default is emacs, unless 3959.Ev VISUAL 3960or 3961.Ev EDITOR 3962contains 3963.Ql vi . 3964.Pp 3965.It Ic mode-style Ar style 3966Set window modes style. 3967For how to specify 3968.Ar style , 3969see the 3970.Sx STYLES 3971section. 3972.Pp 3973.It Xo Ic monitor-activity 3974.Op Ic on | off 3975.Xc 3976Monitor for activity in the window. 3977Windows with activity are highlighted in the status line. 3978.Pp 3979.It Xo Ic monitor-bell 3980.Op Ic on | off 3981.Xc 3982Monitor for a bell in the window. 3983Windows with a bell are highlighted in the status line. 3984.Pp 3985.It Xo Ic monitor-silence 3986.Op Ic interval 3987.Xc 3988Monitor for silence (no activity) in the window within 3989.Ic interval 3990seconds. 3991Windows that have been silent for the interval are highlighted in the 3992status line. 3993An interval of zero disables the monitoring. 3994.Pp 3995.It Ic other-pane-height Ar height 3996Set the height of the other panes (not the main pane) in the 3997.Ic main-horizontal 3998layout. 3999If this option is set to 0 (the default), it will have no effect. 4000If both the 4001.Ic main-pane-height 4002and 4003.Ic other-pane-height 4004options are set, the main pane will grow taller to make the other panes the 4005specified height, but will never shrink to do so. 4006If suffixed by 4007.Ql % , 4008this is a percentage of the window size. 4009.Pp 4010.It Ic other-pane-width Ar width 4011Like 4012.Ic other-pane-height , 4013but set the width of other panes in the 4014.Ic main-vertical 4015layout. 4016.Pp 4017.It Ic pane-active-border-style Ar style 4018Set the pane border style for the currently active pane. 4019For how to specify 4020.Ar style , 4021see the 4022.Sx STYLES 4023section. 4024Attributes are ignored. 4025.Pp 4026.It Ic pane-base-index Ar index 4027Like 4028.Ic base-index , 4029but set the starting index for pane numbers. 4030.Pp 4031.It Ic pane-border-format Ar format 4032Set the text shown in pane border status lines. 4033.Pp 4034.It Ic pane-border-lines Ar type 4035Set the type of characters used for drawing pane borders. 4036.Ar type 4037may be one of: 4038.Bl -tag -width Ds 4039.It single 4040single lines using ACS or UTF-8 characters 4041.It double 4042double lines using UTF-8 characters 4043.It heavy 4044heavy lines using UTF-8 characters 4045.It simple 4046simple ASCII characters 4047.It number 4048the pane number 4049.El 4050.Pp 4051.Ql double 4052and 4053.Ql heavy 4054will fall back to standard ACS line drawing when UTF-8 is not supported. 4055.Pp 4056.It Xo Ic pane-border-status 4057.Op Ic off | top | bottom 4058.Xc 4059Turn pane border status lines off or set their position. 4060.Pp 4061.It Ic pane-border-style Ar style 4062Set the pane border style for panes aside from the active pane. 4063For how to specify 4064.Ar style , 4065see the 4066.Sx STYLES 4067section. 4068Attributes are ignored. 4069.Pp 4070.It Ic window-status-activity-style Ar style 4071Set status line style for windows with an activity alert. 4072For how to specify 4073.Ar style , 4074see the 4075.Sx STYLES 4076section. 4077.Pp 4078.It Ic window-status-bell-style Ar style 4079Set status line style for windows with a bell alert. 4080For how to specify 4081.Ar style , 4082see the 4083.Sx STYLES 4084section. 4085.Pp 4086.It Ic window-status-current-format Ar string 4087Like 4088.Ar window-status-format , 4089but is the format used when the window is the current window. 4090.Pp 4091.It Ic window-status-current-style Ar style 4092Set status line style for the currently active window. 4093For how to specify 4094.Ar style , 4095see the 4096.Sx STYLES 4097section. 4098.Pp 4099.It Ic window-status-format Ar string 4100Set the format in which the window is displayed in the status line window list. 4101See the 4102.Sx FORMATS 4103and 4104.Sx STYLES 4105sections. 4106.Pp 4107.It Ic window-status-last-style Ar style 4108Set status line style for the last active window. 4109For how to specify 4110.Ar style , 4111see the 4112.Sx STYLES 4113section. 4114.Pp 4115.It Ic window-status-separator Ar string 4116Sets the separator drawn between windows in the status line. 4117The default is a single space character. 4118.Pp 4119.It Ic window-status-style Ar style 4120Set status line style for a single window. 4121For how to specify 4122.Ar style , 4123see the 4124.Sx STYLES 4125section. 4126.Pp 4127.It Xo Ic window-size 4128.Ar largest | Ar smallest | Ar manual | Ar latest 4129.Xc 4130Configure how 4131.Nm 4132determines the window size. 4133If set to 4134.Ar largest , 4135the size of the largest attached session is used; if 4136.Ar smallest , 4137the size of the smallest. 4138If 4139.Ar manual , 4140the size of a new window is set from the 4141.Ic default-size 4142option and windows are resized automatically. 4143With 4144.Ar latest , 4145.Nm 4146uses the size of the client that had the most recent activity. 4147See also the 4148.Ic resize-window 4149command and the 4150.Ic aggressive-resize 4151option. 4152.Pp 4153.It Xo Ic wrap-search 4154.Op Ic on | off 4155.Xc 4156If this option is set, searches will wrap around the end of the pane contents. 4157The default is on. 4158.El 4159.Pp 4160Available pane options are: 4161.Pp 4162.Bl -tag -width Ds -compact 4163.It Xo Ic allow-rename 4164.Op Ic on | off 4165.Xc 4166Allow programs in the pane to change the window name using a terminal escape 4167sequence (\eek...\ee\e\e). 4168.Pp 4169.It Xo Ic alternate-screen 4170.Op Ic on | off 4171.Xc 4172This option configures whether programs running inside the pane may use the 4173terminal alternate screen feature, which allows the 4174.Em smcup 4175and 4176.Em rmcup 4177.Xr terminfo 5 4178capabilities. 4179The alternate screen feature preserves the contents of the window when an 4180interactive application starts and restores it on exit, so that any output 4181visible before the application starts reappears unchanged after it exits. 4182.Pp 4183.It Xo Ic remain-on-exit 4184.Op Ic on | off 4185.Xc 4186A pane with this flag set is not destroyed when the program running in it 4187exits. 4188The pane may be reactivated with the 4189.Ic respawn-pane 4190command. 4191.Pp 4192.It Xo Ic synchronize-panes 4193.Op Ic on | off 4194.Xc 4195Duplicate input to all other panes in the same window where this option is also 4196on (only for panes that are not in any mode). 4197.Pp 4198.It Ic window-active-style Ar style 4199Set the pane style when it is the active pane. 4200For how to specify 4201.Ar style , 4202see the 4203.Sx STYLES 4204section. 4205.Pp 4206.It Ic window-style Ar style 4207Set the pane style. 4208For how to specify 4209.Ar style , 4210see the 4211.Sx STYLES 4212section. 4213.El 4214.Sh HOOKS 4215.Nm 4216allows commands to run on various triggers, called 4217.Em hooks . 4218Most 4219.Nm 4220commands have an 4221.Em after 4222hook and there are a number of hooks not associated with commands. 4223.Pp 4224Hooks are stored as array options, members of the array are executed in 4225order when the hook is triggered. 4226Like options different hooks may be global or belong to a session, window or pane. 4227Hooks may be configured with the 4228.Ic set-hook 4229or 4230.Ic set-option 4231commands and displayed with 4232.Ic show-hooks 4233or 4234.Ic show-options 4235.Fl H . 4236The following two commands are equivalent: 4237.Bd -literal -offset indent. 4238set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red' 4239set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red' 4240.Ed 4241.Pp 4242Setting a hook without specifying an array index clears the hook and sets the 4243first member of the array. 4244.Pp 4245A command's after 4246hook is run after it completes, except when the command is run as part of a hook 4247itself. 4248They are named with an 4249.Ql after- 4250prefix. 4251For example, the following command adds a hook to select the even-vertical 4252layout after every 4253.Ic split-window : 4254.Bd -literal -offset indent 4255set-hook -g after-split-window "selectl even-vertical" 4256.Ed 4257.Pp 4258All the notifications listed in the 4259.Sx CONTROL MODE 4260section are hooks (without any arguments), except 4261.Ic %exit . 4262The following additional hooks are available: 4263.Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX" 4264.It alert-activity 4265Run when a window has activity. 4266See 4267.Ic monitor-activity . 4268.It alert-bell 4269Run when a window has received a bell. 4270See 4271.Ic monitor-bell . 4272.It alert-silence 4273Run when a window has been silent. 4274See 4275.Ic monitor-silence . 4276.It client-attached 4277Run when a client is attached. 4278.It client-detached 4279Run when a client is detached 4280.It client-resized 4281Run when a client is resized. 4282.It client-session-changed 4283Run when a client's attached session is changed. 4284.It pane-died 4285Run when the program running in a pane exits, but 4286.Ic remain-on-exit 4287is on so the pane has not closed. 4288.It pane-exited 4289Run when the program running in a pane exits. 4290.It pane-focus-in 4291Run when the focus enters a pane, if the 4292.Ic focus-events 4293option is on. 4294.It pane-focus-out 4295Run when the focus exits a pane, if the 4296.Ic focus-events 4297option is on. 4298.It pane-set-clipboard 4299Run when the terminal clipboard is set using the 4300.Xr xterm 1 4301escape sequence. 4302.It session-created 4303Run when a new session created. 4304.It session-closed 4305Run when a session closed. 4306.It session-renamed 4307Run when a session is renamed. 4308.It window-linked 4309Run when a window is linked into a session. 4310.It window-renamed 4311Run when a window is renamed. 4312.It window-unlinked 4313Run when a window is unlinked from a session. 4314.El 4315.Pp 4316Hooks are managed with these commands: 4317.Bl -tag -width Ds 4318.It Xo Ic set-hook 4319.Op Fl agpRuw 4320.Op Fl t Ar target-pane 4321.Ar hook-name 4322.Ar command 4323.Xc 4324Without 4325.Fl R , 4326sets (or with 4327.Fl u 4328unsets) hook 4329.Ar hook-name 4330to 4331.Ar command . 4332The flags are the same as for 4333.Ic set-option . 4334.Pp 4335With 4336.Fl R , 4337run 4338.Ar hook-name 4339immediately. 4340.It Xo Ic show-hooks 4341.Op Fl gpw 4342.Op Fl t Ar target-pane 4343.Xc 4344Shows hooks. 4345The flags are the same as for 4346.Ic show-options . 4347.El 4348.Sh MOUSE SUPPORT 4349If the 4350.Ic mouse 4351option is on (the default is off), 4352.Nm 4353allows mouse events to be bound as keys. 4354The name of each key is made up of a mouse event (such as 4355.Ql MouseUp1 ) 4356and a location suffix, one of the following: 4357.Bl -column "XXXXXXXXXXXXX" -offset indent 4358.It Li "Pane" Ta "the contents of a pane" 4359.It Li "Border" Ta "a pane border" 4360.It Li "Status" Ta "the status line window list" 4361.It Li "StatusLeft" Ta "the left part of the status line" 4362.It Li "StatusRight" Ta "the right part of the status line" 4363.It Li "StatusDefault" Ta "any other part of the status line" 4364.El 4365.Pp 4366The following mouse events are available: 4367.Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent 4368.It Li "WheelUp" Ta "WheelDown" Ta "" 4369.It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1" 4370.It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2" 4371.It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3" 4372.It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3" 4373.It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3" 4374.It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3" 4375.El 4376.Pp 4377The 4378.Ql SecondClick 4379events are fired for the second click of a double click, even if there may be a 4380third click which will fire 4381.Ql TripleClick 4382instead of 4383.Ql DoubleClick . 4384.Pp 4385Each should be suffixed with a location, for example 4386.Ql MouseDown1Status . 4387.Pp 4388The special token 4389.Ql {mouse} 4390or 4391.Ql = 4392may be used as 4393.Ar target-window 4394or 4395.Ar target-pane 4396in commands bound to mouse key bindings. 4397It resolves to the window or pane over which the mouse event took place 4398(for example, the window in the status line over which button 1 was released for a 4399.Ql MouseUp1Status 4400binding, or the pane over which the wheel was scrolled for a 4401.Ql WheelDownPane 4402binding). 4403.Pp 4404The 4405.Ic send-keys 4406.Fl M 4407flag may be used to forward a mouse event to a pane. 4408.Pp 4409The default key bindings allow the mouse to be used to select and resize panes, 4410to copy text and to change window using the status line. 4411These take effect if the 4412.Ic mouse 4413option is turned on. 4414.Sh FORMATS 4415Certain commands accept the 4416.Fl F 4417flag with a 4418.Ar format 4419argument. 4420This is a string which controls the output format of the command. 4421Format variables are enclosed in 4422.Ql #{ 4423and 4424.Ql } , 4425for example 4426.Ql #{session_name} . 4427The possible variables are listed in the table below, or the name of a 4428.Nm 4429option may be used for an option's value. 4430Some variables have a shorter alias such as 4431.Ql #S ; 4432.Ql ## 4433is replaced by a single 4434.Ql # , 4435.Ql #, 4436by a 4437.Ql \&, 4438and 4439.Ql #} 4440by a 4441.Ql } . 4442.Pp 4443Conditionals are available by prefixing with 4444.Ql \&? 4445and separating two alternatives with a comma; 4446if the specified variable exists and is not zero, the first alternative 4447is chosen, otherwise the second is used. 4448For example 4449.Ql #{?session_attached,attached,not attached} 4450will include the string 4451.Ql attached 4452if the session is attached and the string 4453.Ql not attached 4454if it is unattached, or 4455.Ql #{?automatic-rename,yes,no} 4456will include 4457.Ql yes 4458if 4459.Ic automatic-rename 4460is enabled, or 4461.Ql no 4462if not. 4463Conditionals can be nested arbitrarily. 4464Inside a conditional, 4465.Ql \&, 4466and 4467.Ql } 4468must be escaped as 4469.Ql #, 4470and 4471.Ql #} , 4472unless they are part of a 4473.Ql #{...} 4474replacement. 4475For example: 4476.Bd -literal -offset indent 4477#{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W . 4478.Ed 4479.Pp 4480String comparisons may be expressed by prefixing two comma-separated 4481alternatives by 4482.Ql == , 4483.Ql != , 4484.Ql < , 4485.Ql > , 4486.Ql <= 4487or 4488.Ql >= 4489and a colon. 4490For example 4491.Ql #{==:#{host},myhost} 4492will be replaced by 4493.Ql 1 4494if running on 4495.Ql myhost , 4496otherwise by 4497.Ql 0 . 4498.Ql || 4499and 4500.Ql && 4501evaluate to true if either or both of two comma-separated alternatives are 4502true, for example 4503.Ql #{||:#{pane_in_mode},#{alternate_on}} . 4504.Pp 4505An 4506.Ql m 4507specifies an 4508.Xr fnmatch 3 4509or regular expression comparison. 4510The first argument is the pattern and the second the string to compare. 4511An optional argument specifies flags: 4512.Ql r 4513means the pattern is a regular expression instead of the default 4514.Xr fnmatch 3 4515pattern, and 4516.Ql i 4517means to ignore case. 4518For example: 4519.Ql #{m:*foo*,#{host}} 4520or 4521.Ql #{m/ri:^A,MYVAR} . 4522A 4523.Ql C 4524performs a search for an 4525.Xr fnmatch 3 4526pattern or regular expression in the pane content and evaluates to zero if not 4527found, or a line number if found. 4528Like 4529.Ql m , 4530an 4531.Ql r 4532flag means search for a regular expression and 4533.Ql i 4534ignores case. 4535For example: 4536.Ql #{C/r:^Start} 4537.Pp 4538Numeric operators may be performed by prefixing two comma-separated alternatives with an 4539.Ql e 4540and an operator. 4541An optional 4542.Ql f 4543flag may be given after the operator to use floating point numbers, otherwise integers are used. 4544This may be followed by a number giving the number of decimal places to use for the result. 4545The available operators are: 4546addition 4547.Ql + , 4548subtraction 4549.Ql - , 4550multiplication 4551.Ql * , 4552division 4553.Ql / , 4554modulus 4555.Ql m 4556or 4557.Ql % 4558(note that 4559.Ql % 4560must be escaped as 4561.Ql %% 4562in formats which are also expanded by 4563.Xr strftime 3 ) 4564and numeric comparison operators 4565.Ql == , 4566.Ql != , 4567.Ql < , 4568.Ql <= , 4569.Ql > 4570and 4571.Ql >= . 4572For example, 4573.Ql #{e|*|f|4:5.5,3} 4574multiplies 5.5 by 3 for a result with four decimal places and 4575.Ql #{e|%%:7,3} 4576returns the modulus of 7 and 3. 4577.Pp 4578A limit may be placed on the length of the resultant string by prefixing it 4579by an 4580.Ql = , 4581a number and a colon. 4582Positive numbers count from the start of the string and negative from the end, 4583so 4584.Ql #{=5:pane_title} 4585will include at most the first five characters of the pane title, or 4586.Ql #{=-5:pane_title} 4587the last five characters. 4588A suffix or prefix may be given as a second argument - if provided then it is 4589appended or prepended to the string if the length has been trimmed, for example 4590.Ql #{=/5/...:pane_title} 4591will append 4592.Ql ... 4593if the pane title is more than five characters. 4594Similarly, 4595.Ql p 4596pads the string to a given width, for example 4597.Ql #{p10:pane_title} 4598will result in a width of at least 10 characters. 4599A positive width pads on the left, a negative on the right. 4600.Ql n 4601expands to the length of the variable and 4602.Ql w 4603to its width when displayed, for example 4604.Ql #{n:window_name} . 4605.Pp 4606Prefixing a time variable with 4607.Ql t:\& 4608will convert it to a string, so if 4609.Ql #{window_activity} 4610gives 4611.Ql 1445765102 , 4612.Ql #{t:window_activity} 4613gives 4614.Ql Sun Oct 25 09:25:02 2015 . 4615Adding 4616.Ql p ( 4617.Ql `t/p` ) 4618will use shorter but less accurate time format for times in the past. 4619A custom format may be given using an 4620.Ql f 4621suffix (note that 4622.Ql % 4623must be escaped as 4624.Ql %% 4625if the format is separately being passed through 4626.Xr strftime 3 , 4627for example in the 4628.Ic status-left 4629option): 4630.Ql #{t/f/%%H#:%%M:window_activity} , 4631see 4632.Xr strftime 3 . 4633.Pp 4634The 4635.Ql b:\& 4636and 4637.Ql d:\& 4638prefixes are 4639.Xr basename 3 4640and 4641.Xr dirname 3 4642of the variable respectively. 4643.Ql q:\& 4644will escape 4645.Xr sh 1 4646special characters or with an 4647.Ql e 4648suffix, escape hash characters (so 4649.Ql # 4650becomes 4651.Ql ## ) . 4652.Ql E:\& 4653will expand the format twice, for example 4654.Ql #{E:status-left} 4655is the result of expanding the content of the 4656.Ic status-left 4657option rather than the option itself. 4658.Ql T:\& 4659is like 4660.Ql E:\& 4661but also expands 4662.Xr strftime 3 4663specifiers. 4664.Ql S:\& , 4665.Ql W:\& 4666or 4667.Ql P:\& 4668will loop over each session, window or pane and insert the format once 4669for each. 4670For windows and panes, two comma-separated formats may be given: 4671the second is used for the current window or active pane. 4672For example, to get a list of windows formatted like the status line: 4673.Bd -literal -offset indent 4674#{W:#{E:window-status-format} ,#{E:window-status-current-format} } 4675.Ed 4676.Pp 4677A prefix of the form 4678.Ql s/foo/bar/:\& 4679will substitute 4680.Ql foo 4681with 4682.Ql bar 4683throughout. 4684The first argument may be an extended regular expression and a final argument may be 4685.Ql i 4686to ignore case, for example 4687.Ql s/a(.)/\e1x/i:\& 4688would change 4689.Ql abABab 4690into 4691.Ql bxBxbx . 4692.Pp 4693In addition, the last line of a shell command's output may be inserted using 4694.Ql #() . 4695For example, 4696.Ql #(uptime) 4697will insert the system's uptime. 4698When constructing formats, 4699.Nm 4700does not wait for 4701.Ql #() 4702commands to finish; instead, the previous result from running the same command is used, 4703or a placeholder if the command has not been run before. 4704If the command hasn't exited, the most recent line of output will be used, but the status 4705line will not be updated more than once a second. 4706Commands are executed with the 4707.Nm 4708global environment set (see the 4709.Sx GLOBAL AND SESSION ENVIRONMENT 4710section). 4711.Pp 4712An 4713.Ql l 4714specifies that a string should be interpreted literally and not expanded. 4715For example 4716.Ql #{l:#{?pane_in_mode,yes,no}} 4717will be replaced by 4718.Ql #{?pane_in_mode,yes,no} . 4719.Pp 4720The following variables are available, where appropriate: 4721.Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX" 4722.It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with" 4723.It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen" 4724.It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen" 4725.It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen" 4726.It Li "buffer_created" Ta "" Ta "Time buffer created" 4727.It Li "buffer_name" Ta "" Ta "Name of buffer" 4728.It Li "buffer_sample" Ta "" Ta "Sample of start of buffer" 4729.It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes" 4730.It Li "client_activity" Ta "" Ta "Time client last had activity" 4731.It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels" 4732.It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels" 4733.It Li "client_control_mode" Ta "" Ta "1 if client is in control mode" 4734.It Li "client_created" Ta "" Ta "Time client created" 4735.It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind" 4736.It Li "client_flags" Ta "" Ta "List of client flags" 4737.It Li "client_height" Ta "" Ta "Height of client" 4738.It Li "client_key_table" Ta "" Ta "Current key table" 4739.It Li "client_last_session" Ta "" Ta "Name of the client's last session" 4740.It Li "client_name" Ta "" Ta "Name of client" 4741.It Li "client_pid" Ta "" Ta "PID of client process" 4742.It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed" 4743.It Li "client_readonly" Ta "" Ta "1 if client is readonly" 4744.It Li "client_session" Ta "" Ta "Name of the client's session" 4745.It Li "client_termname" Ta "" Ta "Terminal name of client" 4746.It Li "client_termtype" Ta "" Ta "Terminal type of client, if available" 4747.It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any" 4748.It Li "client_tty" Ta "" Ta "Pseudo terminal of client" 4749.It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8" 4750.It Li "client_width" Ta "" Ta "Width of client" 4751.It Li "client_written" Ta "" Ta "Bytes written to client" 4752.It Li "command" Ta "" Ta "Name of command in use, if any" 4753.It Li "command_list_alias" Ta "" Ta "Command alias if listing commands" 4754.It Li "command_list_name" Ta "" Ta "Command name if listing commands" 4755.It Li "command_list_usage" Ta "" Ta "Command usage if listing commands" 4756.It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode" 4757.It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode" 4758.It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode" 4759.It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode" 4760.It Li "cursor_character" Ta "" Ta "Character at cursor in pane" 4761.It Li "cursor_flag" Ta "" Ta "Pane cursor flag" 4762.It Li "cursor_x" Ta "" Ta "Cursor X position in pane" 4763.It Li "cursor_y" Ta "" Ta "Cursor Y position in pane" 4764.It Li "history_bytes" Ta "" Ta "Number of bytes in window history" 4765.It Li "history_limit" Ta "" Ta "Maximum window history lines" 4766.It Li "history_size" Ta "" Ta "Size of history in lines" 4767.It Li "hook" Ta "" Ta "Name of running hook, if any" 4768.It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any" 4769.It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any" 4770.It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any" 4771.It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any" 4772.It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any" 4773.It Li "host" Ta "#H" Ta "Hostname of local host" 4774.It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)" 4775.It Li "insert_flag" Ta "" Ta "Pane insert flag" 4776.It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag" 4777.It Li "keypad_flag" Ta "" Ta "Pane keypad flag" 4778.It Li "line" Ta "" Ta "Line number in the list" 4779.It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag" 4780.It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag" 4781.It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag" 4782.It Li "mouse_line" Ta "" Ta "Line under mouse, if any" 4783.It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag" 4784.It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag" 4785.It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag" 4786.It Li "mouse_word" Ta "" Ta "Word under mouse, if any" 4787.It Li "mouse_x" Ta "" Ta "Mouse X position, if any" 4788.It Li "mouse_y" Ta "" Ta "Mouse Y position, if any" 4789.It Li "origin_flag" Ta "" Ta "Pane origin flag" 4790.It Li "pane_active" Ta "" Ta "1 if active pane" 4791.It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window" 4792.It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window" 4793.It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window" 4794.It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window" 4795.It Li "pane_bottom" Ta "" Ta "Bottom of pane" 4796.It Li "pane_current_command" Ta "" Ta "Current command if available" 4797.It Li "pane_current_path" Ta "" Ta "Current path if available" 4798.It Li "pane_dead" Ta "" Ta "1 if pane is dead" 4799.It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane" 4800.It Li "pane_format" Ta "" Ta "1 if format is for a pane" 4801.It Li "pane_height" Ta "" Ta "Height of pane" 4802.It Li "pane_id" Ta "#D" Ta "Unique pane ID" 4803.It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode" 4804.It Li "pane_index" Ta "#P" Ta "Index of pane" 4805.It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled" 4806.It Li "pane_last" Ta "" Ta "1 if last pane" 4807.It Li "pane_left" Ta "" Ta "Left of pane" 4808.It Li "pane_marked" Ta "" Ta "1 if this is the marked pane" 4809.It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set" 4810.It Li "pane_mode" Ta "" Ta "Name of pane mode, if any" 4811.It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)" 4812.It Li "pane_pid" Ta "" Ta "PID of first process in pane" 4813.It Li "pane_pipe" Ta "" Ta "1 if pane is being piped" 4814.It Li "pane_right" Ta "" Ta "Right of pane" 4815.It Li "pane_search_string" Ta "" Ta "Last search string in copy mode" 4816.It Li "pane_skipped" Ta "" Ta "Bytes skipped as not visible in pane" 4817.It Li "pane_start_command" Ta "" Ta "Command pane started with" 4818.It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized" 4819.It Li "pane_tabs" Ta "" Ta "Pane tab positions" 4820.It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)" 4821.It Li "pane_top" Ta "" Ta "Top of pane" 4822.It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane" 4823.It Li "pane_width" Ta "" Ta "Width of pane" 4824.It Li "pane_written" Ta "" Ta "Bytes written by pane (aside from redrawing)" 4825.It Li "pid" Ta "" Ta "Server PID" 4826.It Li "popup_key" Ta "" Ta "Key pressed in popup" 4827.It Li "popup_mouse_x" Ta "" Ta "Mouse X position in popup" 4828.It Li "popup_mouse_y" Ta "" Ta "Mouse Y position in popup" 4829.It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated" 4830.It Li "scroll_position" Ta "" Ta "Scroll position in copy mode" 4831.It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane" 4832.It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane" 4833.It Li "search_present" Ta "" Ta "1 if search started in copy mode" 4834.It Li "search_match" Ta "" Ta "Search match if any" 4835.It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode" 4836.It Li "selection_end_x" Ta "" Ta "X position of the end of the selection" 4837.It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection" 4838.It Li "selection_present" Ta "" Ta "1 if selection started in copy mode" 4839.It Li "selection_start_x" Ta "" Ta "X position of the start of the selection" 4840.It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection" 4841.It Li "session_activity" Ta "" Ta "Time of session last activity" 4842.It Li "session_alerts" Ta "" Ta "List of window indexes with alerts" 4843.It Li "session_attached" Ta "" Ta "Number of clients session is attached to" 4844.It Li "session_attached_list" Ta "" Ta "List of clients session is attached to" 4845.It Li "session_created" Ta "" Ta "Time session created" 4846.It Li "session_format" Ta "" Ta "1 if format is for a session" 4847.It Li "session_group" Ta "" Ta "Name of session group" 4848.It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to" 4849.It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to" 4850.It Li "session_group_list" Ta "" Ta "List of sessions in group" 4851.It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group" 4852.It Li "session_group_size" Ta "" Ta "Size of session group" 4853.It Li "session_grouped" Ta "" Ta "1 if session in a group" 4854.It Li "session_id" Ta "" Ta "Unique session ID" 4855.It Li "session_last_attached" Ta "" Ta "Time session last attached" 4856.It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached" 4857.It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane" 4858.It Li "session_name" Ta "#S" Ta "Name of session" 4859.It Li "session_path" Ta "" Ta "Working directory of session" 4860.It Li "session_stack" Ta "" Ta "Window indexes in most recent order" 4861.It Li "session_windows" Ta "" Ta "Number of windows in session" 4862.It Li "socket_path" Ta "" Ta "Server socket path" 4863.It Li "start_time" Ta "" Ta "Server start time" 4864.It Li "version" Ta "" Ta "Server version" 4865.It Li "window_active" Ta "" Ta "1 if window active" 4866.It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window" 4867.It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window" 4868.It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active" 4869.It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active" 4870.It Li "window_activity" Ta "" Ta "Time of window last activity" 4871.It Li "window_activity_flag" Ta "" Ta "1 if window has activity" 4872.It Li "window_bell_flag" Ta "" Ta "1 if window has bell" 4873.It Li "window_bigger" Ta "" Ta "1 if window is larger than client" 4874.It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels" 4875.It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels" 4876.It Li "window_end_flag" Ta "" Ta "1 if window has the highest index" 4877.It Li "window_flags" Ta "#F" Ta "Window flags" 4878.It Li "window_format" Ta "" Ta "1 if format is for a window" 4879.It Li "window_height" Ta "" Ta "Height of window" 4880.It Li "window_id" Ta "" Ta "Unique window ID" 4881.It Li "window_index" Ta "#I" Ta "Index of window" 4882.It Li "window_last_flag" Ta "" Ta "1 if window is the last used" 4883.It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes" 4884.It Li "window_linked" Ta "" Ta "1 if window is linked across sessions" 4885.It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to" 4886.It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to" 4887.It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane" 4888.It Li "window_name" Ta "#W" Ta "Name of window" 4889.It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client" 4890.It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client" 4891.It Li "window_panes" Ta "" Ta "Number of panes in window" 4892.It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert" 4893.It Li "window_stack_index" Ta "" Ta "Index in session most recent stack" 4894.It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index" 4895.It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes" 4896.It Li "window_width" Ta "" Ta "Width of window" 4897.It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed" 4898.It Li "wrap_flag" Ta "" Ta "Pane wrap flag" 4899.El 4900.Sh STYLES 4901.Nm 4902offers various options to specify the colour and attributes of aspects of the 4903interface, for example 4904.Ic status-style 4905for the status line. 4906In addition, embedded styles may be specified in format options, such as 4907.Ic status-left , 4908by enclosing them in 4909.Ql #[ 4910and 4911.Ql \&] . 4912.Pp 4913A style may be the single term 4914.Ql default 4915to specify the default style (which may come from an option, for example 4916.Ic status-style 4917in the status line) or a space 4918or comma separated list of the following: 4919.Bl -tag -width Ds 4920.It Ic fg=colour 4921Set the foreground colour. 4922The colour is one of: 4923.Ic black , 4924.Ic red , 4925.Ic green , 4926.Ic yellow , 4927.Ic blue , 4928.Ic magenta , 4929.Ic cyan , 4930.Ic white ; 4931if supported the bright variants 4932.Ic brightred , 4933.Ic brightgreen , 4934.Ic brightyellow ; 4935.Ic colour0 4936to 4937.Ic colour255 4938from the 256-colour set; 4939.Ic default 4940for the default colour; 4941.Ic terminal 4942for the terminal default colour; or a hexadecimal RGB string such as 4943.Ql #ffffff . 4944.It Ic bg=colour 4945Set the background colour. 4946.It Ic none 4947Set no attributes (turn off any active attributes). 4948.It Xo Ic acs , 4949.Ic bright 4950(or 4951.Ic bold ) , 4952.Ic dim , 4953.Ic underscore , 4954.Ic blink , 4955.Ic reverse , 4956.Ic hidden , 4957.Ic italics , 4958.Ic overline , 4959.Ic strikethrough , 4960.Ic double-underscore , 4961.Ic curly-underscore , 4962.Ic dotted-underscore , 4963.Ic dashed-underscore 4964.Xc 4965Set an attribute. 4966Any of the attributes may be prefixed with 4967.Ql no 4968to unset. 4969.Ic acs 4970is the terminal alternate character set. 4971.It Xo Ic align=left 4972(or 4973.Ic noalign ) , 4974.Ic align=centre , 4975.Ic align=right 4976.Xc 4977Align text to the left, centre or right of the available space if appropriate. 4978.It Ic fill=colour 4979Fill the available space with a background colour if appropriate. 4980.It Xo Ic list=on , 4981.Ic list=focus , 4982.Ic list=left-marker , 4983.Ic list=right-marker , 4984.Ic nolist 4985.Xc 4986Mark the position of the various window list components in the 4987.Ic status-format 4988option: 4989.Ic list=on 4990marks the start of the list; 4991.Ic list=focus 4992is the part of the list that should be kept in focus if the entire list won't fit 4993in the available space (typically the current window); 4994.Ic list=left-marker 4995and 4996.Ic list=right-marker 4997mark the text to be used to mark that text has been trimmed from the left or 4998right of the list if there is not enough space. 4999.It Xo Ic push-default , 5000.Ic pop-default 5001.Xc 5002Store the current colours and attributes as the default or reset to the previous 5003default. 5004A 5005.Ic push-default 5006affects any subsequent use of the 5007.Ic default 5008term until a 5009.Ic pop-default . 5010Only one default may be pushed (each 5011.Ic push-default 5012replaces the previous saved default). 5013.It Xo Ic range=left , 5014.Ic range=right , 5015.Ic range=window|X , 5016.Ic norange 5017.Xc 5018Mark a range in the 5019.Ic status-format 5020option. 5021.Ic range=left 5022and 5023.Ic range=right 5024are the text used for the 5025.Ql StatusLeft 5026and 5027.Ql StatusRight 5028mouse keys. 5029.Ic range=window|X 5030is the range for a window passed to the 5031.Ql Status 5032mouse key, where 5033.Ql X 5034is a window index. 5035.El 5036.Pp 5037Examples are: 5038.Bd -literal -offset indent 5039fg=yellow bold underscore blink 5040bg=black,fg=default,noreverse 5041.Ed 5042.Sh NAMES AND TITLES 5043.Nm 5044distinguishes between names and titles. 5045Windows and sessions have names, which may be used to specify them in targets 5046and are displayed in the status line and various lists: the name is the 5047.Nm 5048identifier for a window or session. 5049Only panes have titles. 5050A pane's title is typically set by the program running inside the pane using 5051an escape sequence (like it would set the 5052.Xr xterm 1 5053window title in 5054.Xr X 7 ) . 5055Windows themselves do not have titles - a window's title is the title of its 5056active pane. 5057.Nm 5058itself may set the title of the terminal in which the client is running, see 5059the 5060.Ic set-titles 5061option. 5062.Pp 5063A session's name is set with the 5064.Ic new-session 5065and 5066.Ic rename-session 5067commands. 5068A window's name is set with one of: 5069.Bl -enum -width Ds 5070.It 5071A command argument (such as 5072.Fl n 5073for 5074.Ic new-window 5075or 5076.Ic new-session ) . 5077.It 5078An escape sequence (if the 5079.Ic allow-rename 5080option is turned on): 5081.Bd -literal -offset indent 5082$ printf '\e033kWINDOW_NAME\e033\e\e' 5083.Ed 5084.It 5085Automatic renaming, which sets the name to the active command in the window's 5086active pane. 5087See the 5088.Ic automatic-rename 5089option. 5090.El 5091.Pp 5092When a pane is first created, its title is the hostname. 5093A pane's title can be set via the title setting escape sequence, for example: 5094.Bd -literal -offset indent 5095$ printf '\e033]2;My Title\e033\e\e' 5096.Ed 5097.Pp 5098It can also be modified with the 5099.Ic select-pane 5100.Fl T 5101command. 5102.Sh GLOBAL AND SESSION ENVIRONMENT 5103When the server is started, 5104.Nm 5105copies the environment into the 5106.Em global environment ; 5107in addition, each session has a 5108.Em session environment . 5109When a window is created, the session and global environments are merged. 5110If a variable exists in both, the value from the session environment is used. 5111The result is the initial environment passed to the new process. 5112.Pp 5113The 5114.Ic update-environment 5115session option may be used to update the session environment from the client 5116when a new session is created or an old reattached. 5117.Nm 5118also initialises the 5119.Ev TMUX 5120variable with some internal information to allow commands to be executed 5121from inside, and the 5122.Ev TERM 5123variable with the correct terminal setting of 5124.Ql screen . 5125.Pp 5126Variables in both session and global environments may be marked as hidden. 5127Hidden variables are not passed into the environment of new processes and 5128instead can only be used by tmux itself (for example in formats, see the 5129.Sx FORMATS 5130section). 5131.Pp 5132Commands to alter and view the environment are: 5133.Bl -tag -width Ds 5134.It Xo Ic set-environment 5135.Op Fl Fhgru 5136.Op Fl t Ar target-session 5137.Ar name Op Ar value 5138.Xc 5139.D1 (alias: Ic setenv ) 5140Set or unset an environment variable. 5141If 5142.Fl g 5143is used, the change is made in the global environment; otherwise, it is applied 5144to the session environment for 5145.Ar target-session . 5146If 5147.Fl F 5148is present, then 5149.Ar value 5150is expanded as a format. 5151The 5152.Fl u 5153flag unsets a variable. 5154.Fl r 5155indicates the variable is to be removed from the environment before starting a 5156new process. 5157.Fl h 5158marks the variable as hidden. 5159.It Xo Ic show-environment 5160.Op Fl hgs 5161.Op Fl t Ar target-session 5162.Op Ar variable 5163.Xc 5164.D1 (alias: Ic showenv ) 5165Display the environment for 5166.Ar target-session 5167or the global environment with 5168.Fl g . 5169If 5170.Ar variable 5171is omitted, all variables are shown. 5172Variables removed from the environment are prefixed with 5173.Ql - . 5174If 5175.Fl s 5176is used, the output is formatted as a set of Bourne shell commands. 5177.Fl h 5178shows hidden variables (omitted by default). 5179.El 5180.Sh STATUS LINE 5181.Nm 5182includes an optional status line which is displayed in the bottom line of each 5183terminal. 5184.Pp 5185By default, the status line is enabled and one line in height (it may be 5186disabled or made multiple lines with the 5187.Ic status 5188session option) and contains, from left-to-right: the name of the current 5189session in square brackets; the window list; the title of the active pane 5190in double quotes; and the time and date. 5191.Pp 5192Each line of the status line is configured with the 5193.Ic status-format 5194option. 5195The default is made of three parts: configurable left and right sections (which 5196may contain dynamic content such as the time or output from a shell command, 5197see the 5198.Ic status-left , 5199.Ic status-left-length , 5200.Ic status-right , 5201and 5202.Ic status-right-length 5203options below), and a central window list. 5204By default, the window list shows the index, name and (if any) flag of the 5205windows present in the current session in ascending numerical order. 5206It may be customised with the 5207.Ar window-status-format 5208and 5209.Ar window-status-current-format 5210options. 5211The flag is one of the following symbols appended to the window name: 5212.Bl -column "Symbol" "Meaning" -offset indent 5213.It Sy "Symbol" Ta Sy "Meaning" 5214.It Li "*" Ta "Denotes the current window." 5215.It Li "-" Ta "Marks the last window (previously selected)." 5216.It Li "#" Ta "Window activity is monitored and activity has been detected." 5217.It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window." 5218.It Li "~" Ta "The window has been silent for the monitor-silence interval." 5219.It Li "M" Ta "The window contains the marked pane." 5220.It Li "Z" Ta "The window's active pane is zoomed." 5221.El 5222.Pp 5223The # symbol relates to the 5224.Ic monitor-activity 5225window option. 5226The window name is printed in inverted colours if an alert (bell, activity or 5227silence) is present. 5228.Pp 5229The colour and attributes of the status line may be configured, the entire 5230status line using the 5231.Ic status-style 5232session option and individual windows using the 5233.Ic window-status-style 5234window option. 5235.Pp 5236The status line is automatically refreshed at interval if it has changed, the 5237interval may be controlled with the 5238.Ic status-interval 5239session option. 5240.Pp 5241Commands related to the status line are as follows: 5242.Bl -tag -width Ds 5243.It Xo Ic command-prompt 5244.Op Fl 1ikNTW 5245.Op Fl I Ar inputs 5246.Op Fl p Ar prompts 5247.Op Fl t Ar target-client 5248.Op Ar template 5249.Xc 5250Open the command prompt in a client. 5251This may be used from inside 5252.Nm 5253to execute commands interactively. 5254.Pp 5255If 5256.Ar template 5257is specified, it is used as the command. 5258If present, 5259.Fl I 5260is a comma-separated list of the initial text for each prompt. 5261If 5262.Fl p 5263is given, 5264.Ar prompts 5265is a comma-separated list of prompts which are displayed in order; otherwise 5266a single prompt is displayed, constructed from 5267.Ar template 5268if it is present, or 5269.Ql \&: 5270if not. 5271.Pp 5272Before the command is executed, the first occurrence of the string 5273.Ql %% 5274and all occurrences of 5275.Ql %1 5276are replaced by the response to the first prompt, all 5277.Ql %2 5278are replaced with the response to the second prompt, and so on for further 5279prompts. 5280Up to nine prompt responses may be replaced 5281.Po 5282.Ql %1 5283to 5284.Ql %9 5285.Pc . 5286.Ql %%% 5287is like 5288.Ql %% 5289but any quotation marks are escaped. 5290.Pp 5291.Fl 1 5292makes the prompt only accept one key press, in this case the resulting input 5293is a single character. 5294.Fl k 5295is like 5296.Fl 1 5297but the key press is translated to a key name. 5298.Fl N 5299makes the prompt only accept numeric key presses. 5300.Fl i 5301executes the command every time the prompt input changes instead of when the 5302user exits the command prompt. 5303.Fl T 5304tells 5305.Nm 5306that the prompt is for a target which affects what completions are offered when 5307.Em Tab 5308is pressed; 5309.Fl W 5310is similar but indicates the prompt is for a window. 5311.Pp 5312The following keys have a special meaning in the command prompt, depending 5313on the value of the 5314.Ic status-keys 5315option: 5316.Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent 5317.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" 5318.It Li "Cancel command prompt" Ta "q" Ta "Escape" 5319.It Li "Delete from cursor to start of word" Ta "" Ta "C-w" 5320.It Li "Delete entire command" Ta "d" Ta "C-u" 5321.It Li "Delete from cursor to end" Ta "D" Ta "C-k" 5322.It Li "Execute command" Ta "Enter" Ta "Enter" 5323.It Li "Get next command from history" Ta "" Ta "Down" 5324.It Li "Get previous command from history" Ta "" Ta "Up" 5325.It Li "Insert top paste buffer" Ta "p" Ta "C-y" 5326.It Li "Look for completions" Ta "Tab" Ta "Tab" 5327.It Li "Move cursor left" Ta "h" Ta "Left" 5328.It Li "Move cursor right" Ta "l" Ta "Right" 5329.It Li "Move cursor to end" Ta "$" Ta "C-e" 5330.It Li "Move cursor to next word" Ta "w" Ta "M-f" 5331.It Li "Move cursor to previous word" Ta "b" Ta "M-b" 5332.It Li "Move cursor to start" Ta "0" Ta "C-a" 5333.It Li "Transpose characters" Ta "" Ta "C-t" 5334.El 5335.It Xo Ic confirm-before 5336.Op Fl p Ar prompt 5337.Op Fl t Ar target-client 5338.Ar command 5339.Xc 5340.D1 (alias: Ic confirm ) 5341Ask for confirmation before executing 5342.Ar command . 5343If 5344.Fl p 5345is given, 5346.Ar prompt 5347is the prompt to display; otherwise a prompt is constructed from 5348.Ar command . 5349It may contain the special character sequences supported by the 5350.Ic status-left 5351option. 5352.Pp 5353This command works only from inside 5354.Nm . 5355.It Xo Ic display-menu 5356.Op Fl O 5357.Op Fl c Ar target-client 5358.Op Fl t Ar target-pane 5359.Op Fl T Ar title 5360.Op Fl x Ar position 5361.Op Fl y Ar position 5362.Ar name 5363.Ar key 5364.Ar command 5365.Ar ... 5366.Xc 5367.D1 (alias: Ic menu ) 5368Display a menu on 5369.Ar target-client . 5370.Ar target-pane 5371gives the target for any commands run from the menu. 5372.Pp 5373A menu is passed as a series of arguments: first the menu item name, 5374second the key shortcut (or empty for none) and third the command 5375to run when the menu item is chosen. 5376The name and command are formats, see the 5377.Sx FORMATS 5378and 5379.Sx STYLES 5380sections. 5381If the name begins with a hyphen (-), then the item is disabled (shown dim) and 5382may not be chosen. 5383The name may be empty for a separator line, in which case both the key and 5384command should be omitted. 5385.Pp 5386.Fl T 5387is a format for the menu title (see 5388.Sx FORMATS ) . 5389.Pp 5390.Fl x 5391and 5392.Fl y 5393give the position of the menu. 5394Both may be a row or column number, or one of the following special values: 5395.Bl -column "XXXXX" "XXXX" -offset indent 5396.It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning" 5397.It Li "C" Ta "Both" Ta "The centre of the terminal" 5398.It Li "R" Ta Fl x Ta "The right side of the terminal" 5399.It Li "P" Ta "Both" Ta "The bottom left of the pane" 5400.It Li "M" Ta "Both" Ta "The mouse position" 5401.It Li "W" Ta "Both" Ta "The window position on the status line" 5402.It Li "S" Ta Fl y Ta "The line above or below the status line" 5403.El 5404.Pp 5405Or a format, which is expanded including the following additional variables: 5406.Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent 5407.It Sy "Variable name" Ta Sy "Replaced with" 5408.It Li "popup_centre_x" Ta "Centered in the client" 5409.It Li "popup_centre_y" Ta "Centered in the client" 5410.It Li "popup_height" Ta "Height of menu or popup" 5411.It Li "popup_mouse_bottom" Ta "Bottom of at the mouse" 5412.It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse" 5413.It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse" 5414.It Li "popup_mouse_top" Ta "Top at the mouse" 5415.It Li "popup_mouse_x" Ta "Mouse X position" 5416.It Li "popup_mouse_y" Ta "Mouse Y position" 5417.It Li "popup_pane_bottom" Ta "Bottom of the pane" 5418.It Li "popup_pane_left" Ta "Left of the pane" 5419.It Li "popup_pane_right" Ta "Right of the pane" 5420.It Li "popup_pane_top" Ta "Top of the pane" 5421.It Li "popup_status_line_y" Ta "Above or below the status line" 5422.It Li "popup_width" Ta "Width of menu or popup" 5423.It Li "popup_window_status_line_x" Ta "At the window position in status line" 5424.It Li "popup_window_status_line_y" Ta "At the status line showing the window" 5425.El 5426.Pp 5427Each menu consists of items followed by a key shortcut shown in brackets. 5428If the menu is too large to fit on the terminal, it is not displayed. 5429Pressing the key shortcut chooses the corresponding item. 5430If the mouse is enabled and the menu is opened from a mouse key binding, 5431releasing the mouse button with an item selected chooses that item and 5432releasing the mouse button without an item selected closes the menu. 5433.Fl O 5434changes this behaviour so that the menu does not close when the mouse button is 5435released without an item selected the menu is not closed and a mouse button 5436must be clicked to choose an item. 5437.Pp 5438The following keys are also available: 5439.Bl -column "Key" "Function" -offset indent 5440.It Sy "Key" Ta Sy "Function" 5441.It Li "Enter" Ta "Choose selected item" 5442.It Li "Up" Ta "Select previous item" 5443.It Li "Down" Ta "Select next item" 5444.It Li "q" Ta "Exit menu" 5445.El 5446.It Xo Ic display-message 5447.Op Fl aIpv 5448.Op Fl c Ar target-client 5449.Op Fl d Ar delay 5450.Op Fl t Ar target-pane 5451.Op Ar message 5452.Xc 5453.D1 (alias: Ic display ) 5454Display a message. 5455If 5456.Fl p 5457is given, the output is printed to stdout, otherwise it is displayed in the 5458.Ar target-client 5459status line for up to 5460.Ar delay 5461milliseconds. 5462If 5463.Ar delay 5464is not given, the 5465.Ic message-time 5466option is used; a delay of zero waits for a key press. 5467The format of 5468.Ar message 5469is described in the 5470.Sx FORMATS 5471section; information is taken from 5472.Ar target-pane 5473if 5474.Fl t 5475is given, otherwise the active pane. 5476.Pp 5477.Fl v 5478prints verbose logging as the format is parsed and 5479.Fl a 5480lists the format variables and their values. 5481.Pp 5482.Fl I 5483forwards any input read from stdin to the empty pane given by 5484.Ar target-pane . 5485.It Xo Ic display-popup 5486.Op Fl CEK 5487.Op Fl c Ar target-client 5488.Op Fl d Ar start-directory 5489.Op Fl h Ar height 5490.Op Fl R Ar shell-command 5491.Op Fl t Ar target-pane 5492.Op Fl w Ar width 5493.Op Fl x Ar position 5494.Op Fl y Ar position 5495.Op Ar command Ar line Ar ... 5496.Xc 5497.D1 (alias: Ic popup ) 5498Display a popup on 5499.Ar target-client . 5500A popup is a rectangular box drawn over the top of any panes. 5501Panes are not updated while a popup is present. 5502The popup content may be given in two ways: 5503.Bl -enum -offset Ds 5504.It 5505A set of lines as arguments. 5506Each line is a format which is expanded using 5507.Ar target-pane 5508as the target. 5509If a line contains newlines it is split into multiple lines. 5510Lines may use styles, see the 5511.Sx STYLES 5512section. 5513.It 5514A shell command given by 5515.Fl R 5516which is run and any output shown in the pane. 5517.El 5518.Pp 5519The first argument, 5520.Ar command , 5521is a 5522.Nm 5523command which is run when a key is pressed. 5524The key is available in the 5525.Ql popup_key 5526format. 5527After 5528.Ar command 5529is run, the popup is closed. 5530It may be empty to discard any key presses. 5531If 5532.Fl K 5533is given together with 5534.Fl R , 5535key presses are instead passed to the 5536.Fl R 5537shell command. 5538.Fl E 5539closes the popup automatically when 5540.Ar shell-command 5541exits. 5542Two 5543.Fl E 5544closes the popup only if 5545.Ar shell-command 5546exited with success. 5547With 5548.Fl K , 5549.Ql Escape 5550and 5551.Ql C-c 5552close the popup unless 5553.Fl E 5554is also given. 5555.Pp 5556.Fl x 5557and 5558.Fl y 5559give the position of the popup, they have the same meaning as for the 5560.Ic display-menu 5561command. 5562.Fl w 5563and 5564.Fl h 5565give the width and height - both may be a percentage (followed by 5566.Ql % ) . 5567If omitted, without 5568.Fl R 5569they are calculated from the given lines and with 5570.Fl R 5571they use half the terminal size. 5572.Pp 5573The 5574.Fl C 5575flag closes any popup on the client. 5576.El 5577.Sh BUFFERS 5578.Nm 5579maintains a set of named 5580.Em paste buffers . 5581Each buffer may be either explicitly or automatically named. 5582Explicitly named buffers are named when created with the 5583.Ic set-buffer 5584or 5585.Ic load-buffer 5586commands, or by renaming an automatically named buffer with 5587.Ic set-buffer 5588.Fl n . 5589Automatically named buffers are given a name such as 5590.Ql buffer0001 , 5591.Ql buffer0002 5592and so on. 5593When the 5594.Ic buffer-limit 5595option is reached, the oldest automatically named buffer is deleted. 5596Explicitly named buffers are not subject to 5597.Ic buffer-limit 5598and may be deleted with the 5599.Ic delete-buffer 5600command. 5601.Pp 5602Buffers may be added using 5603.Ic copy-mode 5604or the 5605.Ic set-buffer 5606and 5607.Ic load-buffer 5608commands, and pasted into a window using the 5609.Ic paste-buffer 5610command. 5611If a buffer command is used and no buffer is specified, the most 5612recently added automatically named buffer is assumed. 5613.Pp 5614A configurable history buffer is also maintained for each window. 5615By default, up to 2000 lines are kept; this can be altered with the 5616.Ic history-limit 5617option (see the 5618.Ic set-option 5619command above). 5620.Pp 5621The buffer commands are as follows: 5622.Bl -tag -width Ds 5623.It Xo 5624.Ic choose-buffer 5625.Op Fl NZr 5626.Op Fl F Ar format 5627.Op Fl f Ar filter 5628.Op Fl O Ar sort-order 5629.Op Fl t Ar target-pane 5630.Op Ar template 5631.Xc 5632Put a pane into buffer mode, where a buffer may be chosen interactively from 5633a list. 5634.Fl Z 5635zooms the pane. 5636The following keys may be used in buffer mode: 5637.Bl -column "Key" "Function" -offset indent 5638.It Sy "Key" Ta Sy "Function" 5639.It Li "Enter" Ta "Paste selected buffer" 5640.It Li "Up" Ta "Select previous buffer" 5641.It Li "Down" Ta "Select next buffer" 5642.It Li "C-s" Ta "Search by name or content" 5643.It Li "n" Ta "Repeat last search" 5644.It Li "t" Ta "Toggle if buffer is tagged" 5645.It Li "T" Ta "Tag no buffers" 5646.It Li "C-t" Ta "Tag all buffers" 5647.It Li "p" Ta "Paste selected buffer" 5648.It Li "P" Ta "Paste tagged buffers" 5649.It Li "d" Ta "Delete selected buffer" 5650.It Li "D" Ta "Delete tagged buffers" 5651.It Li "e" Ta "Open the buffer in an editor" 5652.It Li "f" Ta "Enter a format to filter items" 5653.It Li "O" Ta "Change sort field" 5654.It Li "r" Ta "Reverse sort order" 5655.It Li "v" Ta "Toggle preview" 5656.It Li "q" Ta "Exit mode" 5657.El 5658.Pp 5659After a buffer is chosen, 5660.Ql %% 5661is replaced by the buffer name in 5662.Ar template 5663and the result executed as a command. 5664If 5665.Ar template 5666is not given, "paste-buffer -b '%%'" is used. 5667.Pp 5668.Fl O 5669specifies the initial sort field: one of 5670.Ql time , 5671.Ql name 5672or 5673.Ql size . 5674.Fl r 5675reverses the sort order. 5676.Fl f 5677specifies an initial filter: the filter is a format - if it evaluates to zero, 5678the item in the list is not shown, otherwise it is shown. 5679If a filter would lead to an empty list, it is ignored. 5680.Fl F 5681specifies the format for each item in the list. 5682.Fl N 5683starts without the preview. 5684This command works only if at least one client is attached. 5685.It Ic clear-history Op Fl t Ar target-pane 5686.D1 (alias: Ic clearhist ) 5687Remove and free the history for the specified pane. 5688.It Ic delete-buffer Op Fl b Ar buffer-name 5689.D1 (alias: Ic deleteb ) 5690Delete the buffer named 5691.Ar buffer-name , 5692or the most recently added automatically named buffer if not specified. 5693.It Xo Ic list-buffers 5694.Op Fl F Ar format 5695.Op Fl f Ar filter 5696.Xc 5697.D1 (alias: Ic lsb ) 5698List the global buffers. 5699.Fl F 5700specifies the format of each line and 5701.Fl f 5702a filter. 5703Only buffers for which the filter is true are shown. 5704See the 5705.Sx FORMATS 5706section. 5707.It Xo Ic load-buffer 5708.Op Fl w 5709.Op Fl b Ar buffer-name 5710.Op Fl t Ar target-client 5711.Ar path 5712.Xc 5713.D1 (alias: Ic loadb ) 5714Load the contents of the specified paste buffer from 5715.Ar path . 5716If 5717.Fl w 5718is given, the buffer is also sent to the clipboard for 5719.Ar target-client 5720using the 5721.Xr xterm 1 5722escape sequence, if possible. 5723.It Xo Ic paste-buffer 5724.Op Fl dpr 5725.Op Fl b Ar buffer-name 5726.Op Fl s Ar separator 5727.Op Fl t Ar target-pane 5728.Xc 5729.D1 (alias: Ic pasteb ) 5730Insert the contents of a paste buffer into the specified pane. 5731If not specified, paste into the current one. 5732With 5733.Fl d , 5734also delete the paste buffer. 5735When output, any linefeed (LF) characters in the paste buffer are replaced with 5736a separator, by default carriage return (CR). 5737A custom separator may be specified using the 5738.Fl s 5739flag. 5740The 5741.Fl r 5742flag means to do no replacement (equivalent to a separator of LF). 5743If 5744.Fl p 5745is specified, paste bracket control codes are inserted around the 5746buffer if the application has requested bracketed paste mode. 5747.It Xo Ic save-buffer 5748.Op Fl a 5749.Op Fl b Ar buffer-name 5750.Ar path 5751.Xc 5752.D1 (alias: Ic saveb ) 5753Save the contents of the specified paste buffer to 5754.Ar path . 5755The 5756.Fl a 5757option appends to rather than overwriting the file. 5758.It Xo Ic set-buffer 5759.Op Fl aw 5760.Op Fl b Ar buffer-name 5761.Op Fl t Ar target-client 5762.Op Fl n Ar new-buffer-name 5763.Ar data 5764.Xc 5765.D1 (alias: Ic setb ) 5766Set the contents of the specified buffer to 5767.Ar data . 5768If 5769.Fl w 5770is given, the buffer is also sent to the clipboard for 5771.Ar target-client 5772using the 5773.Xr xterm 1 5774escape sequence, if possible. 5775The 5776.Fl a 5777option appends to rather than overwriting the buffer. 5778The 5779.Fl n 5780option renames the buffer to 5781.Ar new-buffer-name . 5782.It Xo Ic show-buffer 5783.Op Fl b Ar buffer-name 5784.Xc 5785.D1 (alias: Ic showb ) 5786Display the contents of the specified buffer. 5787.El 5788.Sh MISCELLANEOUS 5789Miscellaneous commands are as follows: 5790.Bl -tag -width Ds 5791.It Ic clock-mode Op Fl t Ar target-pane 5792Display a large clock. 5793.It Xo Ic if-shell 5794.Op Fl bF 5795.Op Fl t Ar target-pane 5796.Ar shell-command command 5797.Op Ar command 5798.Xc 5799.D1 (alias: Ic if ) 5800Execute the first 5801.Ar command 5802if 5803.Ar shell-command 5804returns success or the second 5805.Ar command 5806otherwise. 5807Before being executed, 5808.Ar shell-command 5809is expanded using the rules specified in the 5810.Sx FORMATS 5811section, including those relevant to 5812.Ar target-pane . 5813With 5814.Fl b , 5815.Ar shell-command 5816is run in the background. 5817.Pp 5818If 5819.Fl F 5820is given, 5821.Ar shell-command 5822is not executed but considered success if neither empty nor zero (after formats 5823are expanded). 5824.It Ic lock-server 5825.D1 (alias: Ic lock ) 5826Lock each client individually by running the command specified by the 5827.Ic lock-command 5828option. 5829.It Xo Ic run-shell 5830.Op Fl bC 5831.Op Fl d Ar delay 5832.Op Fl t Ar target-pane 5833.Op Ar shell-command 5834.Xc 5835.D1 (alias: Ic run ) 5836Execute 5837.Ar shell-command 5838or (with 5839.Fl C ) 5840a 5841.Nm 5842command in the background without creating a window. 5843Before being executed, 5844.Ar shell-command 5845is expanded using the rules specified in the 5846.Sx FORMATS 5847section. 5848With 5849.Fl b , 5850the command is run in the background. 5851.Fl d 5852waits for 5853.Ar delay 5854seconds before starting the command. 5855If 5856.Fl C 5857is not given, any output to stdout is displayed in view mode (in the pane 5858specified by 5859.Fl t 5860or the current pane if omitted) after the command finishes. 5861If the command fails, the exit status is also displayed. 5862.It Xo Ic wait-for 5863.Op Fl L | S | U 5864.Ar channel 5865.Xc 5866.D1 (alias: Ic wait ) 5867When used without options, prevents the client from exiting until woken using 5868.Ic wait-for 5869.Fl S 5870with the same channel. 5871When 5872.Fl L 5873is used, the channel is locked and any clients that try to lock the same 5874channel are made to wait until the channel is unlocked with 5875.Ic wait-for 5876.Fl U . 5877.El 5878.Sh EXIT MESSAGES 5879When a 5880.Nm 5881client detaches, it prints a message. 5882This may be one of: 5883.Bl -tag -width Ds 5884.It detached (from session ...) 5885The client was detached normally. 5886.It detached and SIGHUP 5887The client was detached and its parent sent the 5888.Dv SIGHUP 5889signal (for example with 5890.Ic detach-client 5891.Fl P ) . 5892.It lost tty 5893The client's 5894.Xr tty 4 5895or 5896.Xr pty 4 5897was unexpectedly destroyed. 5898.It terminated 5899The client was killed with 5900.Dv SIGTERM . 5901.It too far behind 5902The client is in control mode and became unable to keep up with the data from 5903.Nm . 5904.It exited 5905The server exited when it had no sessions. 5906.It server exited 5907The server exited when it received 5908.Dv SIGTERM . 5909.It server exited unexpectedly 5910The server crashed or otherwise exited without telling the client the reason. 5911.El 5912.Sh TERMINFO EXTENSIONS 5913.Nm 5914understands some unofficial extensions to 5915.Xr terminfo 5 . 5916It is not normally necessary to set these manually, instead the 5917.Ic terminal-features 5918option should be used. 5919.Bl -tag -width Ds 5920.It Em \&AX 5921An existing extension that tells 5922.Nm 5923the terminal supports default colours. 5924.It Em \&Cs , Cr 5925Set the cursor colour. 5926The first takes a single string argument and is used to set the colour; 5927the second takes no arguments and restores the default cursor colour. 5928If set, a sequence such as this may be used 5929to change the cursor colour from inside 5930.Nm : 5931.Bd -literal -offset indent 5932$ printf '\e033]12;red\e033\e\e' 5933.Ed 5934.It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg 5935Set, clear, disable or enable DECSLRM margins. 5936These are set automatically if the terminal reports it is 5937.Em VT420 5938compatible. 5939.It Em \&Dsbp , \&Enbp 5940Disable and enable bracketed paste. 5941These are set automatically if the 5942.Em XT 5943capability is present. 5944.It Em \&Dseks , \&Eneks 5945Disable and enable extended keys. 5946.It Em \&Dsfcs , \&Enfcs 5947Disable and enable focus reporting. 5948These are set automatically if the 5949.Em XT 5950capability is present. 5951.It Em \&Smol 5952Enable the overline attribute. 5953.It Em \&Smulx 5954Set a styled underscore. 5955The single parameter is one of: 0 for no underscore, 1 for normal 5956underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted 5957underscore and 5 for dashed underscore. 5958.It Em \&Setulc , \&ol 5959Set the underscore colour or reset to the default. 5960The argument is (red * 65536) + (green * 256) + blue where each is between 0 5961and 255. 5962.It Em \&Ss , Se 5963Set or reset the cursor style. 5964If set, a sequence such as this may be used 5965to change the cursor to an underline: 5966.Bd -literal -offset indent 5967$ printf '\e033[4 q' 5968.Ed 5969.Pp 5970If 5971.Em Se 5972is not set, \&Ss with argument 0 will be used to reset the cursor style instead. 5973.It Em \&Sync 5974Start (parameter is 1) or end (parameter is 2) a synchronized update. 5975.It Em \&Tc 5976Indicate that the terminal supports the 5977.Ql direct colour 5978RGB escape sequence (for example, \ee[38;2;255;255;255m). 5979.Pp 5980If supported, this is used for the initialize colour escape sequence (which 5981may be enabled by adding the 5982.Ql initc 5983and 5984.Ql ccc 5985capabilities to the 5986.Nm 5987.Xr terminfo 5 5988entry). 5989.Pp 5990This is equivalent to the 5991.Em RGB 5992.Xr terminfo 5 5993capability. 5994.It Em \&Ms 5995Store the current buffer in the host terminal's selection (clipboard). 5996See the 5997.Em set-clipboard 5998option above and the 5999.Xr xterm 1 6000man page. 6001.It Em \&XT 6002This is an existing extension capability that tmux uses to mean that the 6003terminal supports the 6004.Xr xterm 1 6005title set sequences and to automatically set some of the capabilities above. 6006.El 6007.Sh CONTROL MODE 6008.Nm 6009offers a textual interface called 6010.Em control mode . 6011This allows applications to communicate with 6012.Nm 6013using a simple text-only protocol. 6014.Pp 6015In control mode, a client sends 6016.Nm 6017commands or command sequences terminated by newlines on standard input. 6018Each command will produce one block of output on standard output. 6019An output block consists of a 6020.Em %begin 6021line followed by the output (which may be empty). 6022The output block ends with a 6023.Em %end 6024or 6025.Em %error . 6026.Em %begin 6027and matching 6028.Em %end 6029or 6030.Em %error 6031have two arguments: an integer time (as seconds from epoch) and command number. 6032For example: 6033.Bd -literal -offset indent 6034%begin 1363006971 2 60350: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) 6036%end 1363006971 2 6037.Ed 6038.Pp 6039The 6040.Ic refresh-client 6041.Fl C 6042command may be used to set the size of a client in control mode. 6043.Pp 6044In control mode, 6045.Nm 6046outputs notifications. 6047A notification will never occur inside an output block. 6048.Pp 6049The following notifications are defined: 6050.Bl -tag -width Ds 6051.It Ic %client-session-changed Ar client session-id name 6052The client is now attached to the session with ID 6053.Ar session-id , 6054which is named 6055.Ar name . 6056.It Ic %continue Ar pane-id 6057The pane has been continued after being paused (if the 6058.Ar pause-after 6059flag is set, see 6060.Ic refresh-client 6061.Fl A ) . 6062.It Ic %exit Op Ar reason 6063The 6064.Nm 6065client is exiting immediately, either because it is not attached to any session 6066or an error occurred. 6067If present, 6068.Ar reason 6069describes why the client exited. 6070.It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value 6071New form of 6072.Ic %output 6073sent when the 6074.Ar pause-after 6075flag is set. 6076.Ar age 6077is the time in milliseconds for which tmux had buffered the output before it was sent. 6078Any subsequent arguments up until a single 6079.Ql \&: 6080are for future use and should be ignored. 6081.It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags 6082The layout of a window with ID 6083.Ar window-id 6084changed. 6085The new layout is 6086.Ar window-layout . 6087The window's visible layout is 6088.Ar window-visible-layout 6089and the window flags are 6090.Ar window-flags . 6091.It Ic %output Ar pane-id Ar value 6092A window pane produced output. 6093.Ar value 6094escapes non-printable characters and backslash as octal \\xxx. 6095.It Ic %pane-mode-changed Ar pane-id 6096The pane with ID 6097.Ar pane-id 6098has changed mode. 6099.It Ic %pause Ar pane-id 6100The pane has been paused (if the 6101.Ar pause-after 6102flag is set). 6103.It Ic %session-changed Ar session-id Ar name 6104The client is now attached to the session with ID 6105.Ar session-id , 6106which is named 6107.Ar name . 6108.It Ic %session-renamed Ar name 6109The current session was renamed to 6110.Ar name . 6111.It Ic %session-window-changed Ar session-id Ar window-id 6112The session with ID 6113.Ar session-id 6114changed its active window to the window with ID 6115.Ar window-id . 6116.It Ic %sessions-changed 6117A session was created or destroyed. 6118.It Xo Ic %subscription-changed 6119.Ar name 6120.Ar session-id 6121.Ar window-id 6122.Ar window-index 6123.Ar pane-id ... \& : 6124.Ar value 6125.Xc 6126The value of the format associated with subscription 6127.Ar name 6128has changed to 6129.Ar value . 6130See 6131.Ic refresh-client 6132.Fl B . 6133Any arguments after 6134.Ar pane-id 6135up until a single 6136.Ql \&: 6137are for future use and should be ignored. 6138.It Ic %unlinked-window-add Ar window-id 6139The window with ID 6140.Ar window-id 6141was created but is not linked to the current session. 6142.It Ic %window-add Ar window-id 6143The window with ID 6144.Ar window-id 6145was linked to the current session. 6146.It Ic %window-close Ar window-id 6147The window with ID 6148.Ar window-id 6149closed. 6150.It Ic %window-pane-changed Ar window-id Ar pane-id 6151The active pane in the window with ID 6152.Ar window-id 6153changed to the pane with ID 6154.Ar pane-id . 6155.It Ic %window-renamed Ar window-id Ar name 6156The window with ID 6157.Ar window-id 6158was renamed to 6159.Ar name . 6160.El 6161.Sh ENVIRONMENT 6162When 6163.Nm 6164is started, it inspects the following environment variables: 6165.Bl -tag -width LC_CTYPE 6166.It Ev EDITOR 6167If the command specified in this variable contains the string 6168.Ql vi 6169and 6170.Ev VISUAL 6171is unset, use vi-style key bindings. 6172Overridden by the 6173.Ic mode-keys 6174and 6175.Ic status-keys 6176options. 6177.It Ev HOME 6178The user's login directory. 6179If unset, the 6180.Xr passwd 5 6181database is consulted. 6182.It Ev LC_CTYPE 6183The character encoding 6184.Xr locale 1 . 6185It is used for two separate purposes. 6186For output to the terminal, UTF-8 is used if the 6187.Fl u 6188option is given or if 6189.Ev LC_CTYPE 6190contains 6191.Qq UTF-8 6192or 6193.Qq UTF8 . 6194Otherwise, only ASCII characters are written and non-ASCII characters 6195are replaced with underscores 6196.Pq Ql _ . 6197For input, 6198.Nm 6199always runs with a UTF-8 locale. 6200If en_US.UTF-8 is provided by the operating system it is used and 6201.Ev LC_CTYPE 6202is ignored for input. 6203Otherwise, 6204.Ev LC_CTYPE 6205tells 6206.Nm 6207what the UTF-8 locale is called on the current system. 6208If the locale specified by 6209.Ev LC_CTYPE 6210is not available or is not a UTF-8 locale, 6211.Nm 6212exits with an error message. 6213.It Ev LC_TIME 6214The date and time format 6215.Xr locale 1 . 6216It is used for locale-dependent 6217.Xr strftime 3 6218format specifiers. 6219.It Ev PWD 6220The current working directory to be set in the global environment. 6221This may be useful if it contains symbolic links. 6222If the value of the variable does not match the current working 6223directory, the variable is ignored and the result of 6224.Xr getcwd 3 6225is used instead. 6226.It Ev SHELL 6227The absolute path to the default shell for new windows. 6228See the 6229.Ic default-shell 6230option for details. 6231.It Ev TMUX_TMPDIR 6232The parent directory of the directory containing the server sockets. 6233See the 6234.Fl L 6235option for details. 6236.It Ev VISUAL 6237If the command specified in this variable contains the string 6238.Ql vi , 6239use vi-style key bindings. 6240Overridden by the 6241.Ic mode-keys 6242and 6243.Ic status-keys 6244options. 6245.El 6246.Sh FILES 6247.Bl -tag -width "/etc/tmux.confXXX" -compact 6248.It Pa ~/.tmux.conf 6249Default 6250.Nm 6251configuration file. 6252.It Pa /etc/tmux.conf 6253System-wide configuration file. 6254.El 6255.Sh EXAMPLES 6256To create a new 6257.Nm 6258session running 6259.Xr vi 1 : 6260.Pp 6261.Dl $ tmux new-session vi 6262.Pp 6263Most commands have a shorter form, known as an alias. 6264For new-session, this is 6265.Ic new : 6266.Pp 6267.Dl $ tmux new vi 6268.Pp 6269Alternatively, the shortest unambiguous form of a command is accepted. 6270If there are several options, they are listed: 6271.Bd -literal -offset indent 6272$ tmux n 6273ambiguous command: n, could be: new-session, new-window, next-window 6274.Ed 6275.Pp 6276Within an active session, a new window may be created by typing 6277.Ql C-b c 6278(Ctrl 6279followed by the 6280.Ql b 6281key 6282followed by the 6283.Ql c 6284key). 6285.Pp 6286Windows may be navigated with: 6287.Ql C-b 0 6288(to select window 0), 6289.Ql C-b 1 6290(to select window 1), and so on; 6291.Ql C-b n 6292to select the next window; and 6293.Ql C-b p 6294to select the previous window. 6295.Pp 6296A session may be detached using 6297.Ql C-b d 6298(or by an external event such as 6299.Xr ssh 1 6300disconnection) and reattached with: 6301.Pp 6302.Dl $ tmux attach-session 6303.Pp 6304Typing 6305.Ql C-b \&? 6306lists the current key bindings in the current window; up and down may be used 6307to navigate the list or 6308.Ql q 6309to exit from it. 6310.Pp 6311Commands to be run when the 6312.Nm 6313server is started may be placed in the 6314.Pa ~/.tmux.conf 6315configuration file. 6316Common examples include: 6317.Pp 6318Changing the default prefix key: 6319.Bd -literal -offset indent 6320set-option -g prefix C-a 6321unbind-key C-b 6322bind-key C-a send-prefix 6323.Ed 6324.Pp 6325Turning the status line off, or changing its colour: 6326.Bd -literal -offset indent 6327set-option -g status off 6328set-option -g status-style bg=blue 6329.Ed 6330.Pp 6331Setting other options, such as the default command, 6332or locking after 30 minutes of inactivity: 6333.Bd -literal -offset indent 6334set-option -g default-command "exec /bin/ksh" 6335set-option -g lock-after-time 1800 6336.Ed 6337.Pp 6338Creating new key bindings: 6339.Bd -literal -offset indent 6340bind-key b set-option status 6341bind-key / command-prompt "split-window 'exec man %%'" 6342bind-key S command-prompt "new-window -n %1 'ssh %1'" 6343.Ed 6344.Sh SEE ALSO 6345.Xr pty 4 6346.Sh AUTHORS 6347.An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com 6348