1.\" $OpenBSD: tmux.1,v 1.810 2021/01/04 08:43:16 nicm Exp $ 2.\" 3.\" Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER 14.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING 15.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 4 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 | failed 4185.Xc 4186A pane with this flag set is not destroyed when the program running in it 4187exits. 4188If set to 4189.Ic failed , 4190then only when the program exit status is not zero. 4191The pane may be reactivated with the 4192.Ic respawn-pane 4193command. 4194.Pp 4195.It Xo Ic synchronize-panes 4196.Op Ic on | off 4197.Xc 4198Duplicate input to all other panes in the same window where this option is also 4199on (only for panes that are not in any mode). 4200.Pp 4201.It Ic window-active-style Ar style 4202Set the pane style when it is the active pane. 4203For how to specify 4204.Ar style , 4205see the 4206.Sx STYLES 4207section. 4208.Pp 4209.It Ic window-style Ar style 4210Set the pane style. 4211For how to specify 4212.Ar style , 4213see the 4214.Sx STYLES 4215section. 4216.El 4217.Sh HOOKS 4218.Nm 4219allows commands to run on various triggers, called 4220.Em hooks . 4221Most 4222.Nm 4223commands have an 4224.Em after 4225hook and there are a number of hooks not associated with commands. 4226.Pp 4227Hooks are stored as array options, members of the array are executed in 4228order when the hook is triggered. 4229Like options different hooks may be global or belong to a session, window or pane. 4230Hooks may be configured with the 4231.Ic set-hook 4232or 4233.Ic set-option 4234commands and displayed with 4235.Ic show-hooks 4236or 4237.Ic show-options 4238.Fl H . 4239The following two commands are equivalent: 4240.Bd -literal -offset indent. 4241set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red' 4242set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red' 4243.Ed 4244.Pp 4245Setting a hook without specifying an array index clears the hook and sets the 4246first member of the array. 4247.Pp 4248A command's after 4249hook is run after it completes, except when the command is run as part of a hook 4250itself. 4251They are named with an 4252.Ql after- 4253prefix. 4254For example, the following command adds a hook to select the even-vertical 4255layout after every 4256.Ic split-window : 4257.Bd -literal -offset indent 4258set-hook -g after-split-window "selectl even-vertical" 4259.Ed 4260.Pp 4261All the notifications listed in the 4262.Sx CONTROL MODE 4263section are hooks (without any arguments), except 4264.Ic %exit . 4265The following additional hooks are available: 4266.Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX" 4267.It alert-activity 4268Run when a window has activity. 4269See 4270.Ic monitor-activity . 4271.It alert-bell 4272Run when a window has received a bell. 4273See 4274.Ic monitor-bell . 4275.It alert-silence 4276Run when a window has been silent. 4277See 4278.Ic monitor-silence . 4279.It client-attached 4280Run when a client is attached. 4281.It client-detached 4282Run when a client is detached 4283.It client-resized 4284Run when a client is resized. 4285.It client-session-changed 4286Run when a client's attached session is changed. 4287.It pane-died 4288Run when the program running in a pane exits, but 4289.Ic remain-on-exit 4290is on so the pane has not closed. 4291.It pane-exited 4292Run when the program running in a pane exits. 4293.It pane-focus-in 4294Run when the focus enters a pane, if the 4295.Ic focus-events 4296option is on. 4297.It pane-focus-out 4298Run when the focus exits a pane, if the 4299.Ic focus-events 4300option is on. 4301.It pane-set-clipboard 4302Run when the terminal clipboard is set using the 4303.Xr xterm 1 4304escape sequence. 4305.It session-created 4306Run when a new session created. 4307.It session-closed 4308Run when a session closed. 4309.It session-renamed 4310Run when a session is renamed. 4311.It window-linked 4312Run when a window is linked into a session. 4313.It window-renamed 4314Run when a window is renamed. 4315.It window-unlinked 4316Run when a window is unlinked from a session. 4317.El 4318.Pp 4319Hooks are managed with these commands: 4320.Bl -tag -width Ds 4321.It Xo Ic set-hook 4322.Op Fl agpRuw 4323.Op Fl t Ar target-pane 4324.Ar hook-name 4325.Ar command 4326.Xc 4327Without 4328.Fl R , 4329sets (or with 4330.Fl u 4331unsets) hook 4332.Ar hook-name 4333to 4334.Ar command . 4335The flags are the same as for 4336.Ic set-option . 4337.Pp 4338With 4339.Fl R , 4340run 4341.Ar hook-name 4342immediately. 4343.It Xo Ic show-hooks 4344.Op Fl gpw 4345.Op Fl t Ar target-pane 4346.Xc 4347Shows hooks. 4348The flags are the same as for 4349.Ic show-options . 4350.El 4351.Sh MOUSE SUPPORT 4352If the 4353.Ic mouse 4354option is on (the default is off), 4355.Nm 4356allows mouse events to be bound as keys. 4357The name of each key is made up of a mouse event (such as 4358.Ql MouseUp1 ) 4359and a location suffix, one of the following: 4360.Bl -column "XXXXXXXXXXXXX" -offset indent 4361.It Li "Pane" Ta "the contents of a pane" 4362.It Li "Border" Ta "a pane border" 4363.It Li "Status" Ta "the status line window list" 4364.It Li "StatusLeft" Ta "the left part of the status line" 4365.It Li "StatusRight" Ta "the right part of the status line" 4366.It Li "StatusDefault" Ta "any other part of the status line" 4367.El 4368.Pp 4369The following mouse events are available: 4370.Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent 4371.It Li "WheelUp" Ta "WheelDown" Ta "" 4372.It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1" 4373.It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2" 4374.It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3" 4375.It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3" 4376.It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3" 4377.It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3" 4378.El 4379.Pp 4380The 4381.Ql SecondClick 4382events are fired for the second click of a double click, even if there may be a 4383third click which will fire 4384.Ql TripleClick 4385instead of 4386.Ql DoubleClick . 4387.Pp 4388Each should be suffixed with a location, for example 4389.Ql MouseDown1Status . 4390.Pp 4391The special token 4392.Ql {mouse} 4393or 4394.Ql = 4395may be used as 4396.Ar target-window 4397or 4398.Ar target-pane 4399in commands bound to mouse key bindings. 4400It resolves to the window or pane over which the mouse event took place 4401(for example, the window in the status line over which button 1 was released for a 4402.Ql MouseUp1Status 4403binding, or the pane over which the wheel was scrolled for a 4404.Ql WheelDownPane 4405binding). 4406.Pp 4407The 4408.Ic send-keys 4409.Fl M 4410flag may be used to forward a mouse event to a pane. 4411.Pp 4412The default key bindings allow the mouse to be used to select and resize panes, 4413to copy text and to change window using the status line. 4414These take effect if the 4415.Ic mouse 4416option is turned on. 4417.Sh FORMATS 4418Certain commands accept the 4419.Fl F 4420flag with a 4421.Ar format 4422argument. 4423This is a string which controls the output format of the command. 4424Format variables are enclosed in 4425.Ql #{ 4426and 4427.Ql } , 4428for example 4429.Ql #{session_name} . 4430The possible variables are listed in the table below, or the name of a 4431.Nm 4432option may be used for an option's value. 4433Some variables have a shorter alias such as 4434.Ql #S ; 4435.Ql ## 4436is replaced by a single 4437.Ql # , 4438.Ql #, 4439by a 4440.Ql \&, 4441and 4442.Ql #} 4443by a 4444.Ql } . 4445.Pp 4446Conditionals are available by prefixing with 4447.Ql \&? 4448and separating two alternatives with a comma; 4449if the specified variable exists and is not zero, the first alternative 4450is chosen, otherwise the second is used. 4451For example 4452.Ql #{?session_attached,attached,not attached} 4453will include the string 4454.Ql attached 4455if the session is attached and the string 4456.Ql not attached 4457if it is unattached, or 4458.Ql #{?automatic-rename,yes,no} 4459will include 4460.Ql yes 4461if 4462.Ic automatic-rename 4463is enabled, or 4464.Ql no 4465if not. 4466Conditionals can be nested arbitrarily. 4467Inside a conditional, 4468.Ql \&, 4469and 4470.Ql } 4471must be escaped as 4472.Ql #, 4473and 4474.Ql #} , 4475unless they are part of a 4476.Ql #{...} 4477replacement. 4478For example: 4479.Bd -literal -offset indent 4480#{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W . 4481.Ed 4482.Pp 4483String comparisons may be expressed by prefixing two comma-separated 4484alternatives by 4485.Ql == , 4486.Ql != , 4487.Ql < , 4488.Ql > , 4489.Ql <= 4490or 4491.Ql >= 4492and a colon. 4493For example 4494.Ql #{==:#{host},myhost} 4495will be replaced by 4496.Ql 1 4497if running on 4498.Ql myhost , 4499otherwise by 4500.Ql 0 . 4501.Ql || 4502and 4503.Ql && 4504evaluate to true if either or both of two comma-separated alternatives are 4505true, for example 4506.Ql #{||:#{pane_in_mode},#{alternate_on}} . 4507.Pp 4508An 4509.Ql m 4510specifies an 4511.Xr fnmatch 3 4512or regular expression comparison. 4513The first argument is the pattern and the second the string to compare. 4514An optional argument specifies flags: 4515.Ql r 4516means the pattern is a regular expression instead of the default 4517.Xr fnmatch 3 4518pattern, and 4519.Ql i 4520means to ignore case. 4521For example: 4522.Ql #{m:*foo*,#{host}} 4523or 4524.Ql #{m/ri:^A,MYVAR} . 4525A 4526.Ql C 4527performs a search for an 4528.Xr fnmatch 3 4529pattern or regular expression in the pane content and evaluates to zero if not 4530found, or a line number if found. 4531Like 4532.Ql m , 4533an 4534.Ql r 4535flag means search for a regular expression and 4536.Ql i 4537ignores case. 4538For example: 4539.Ql #{C/r:^Start} 4540.Pp 4541Numeric operators may be performed by prefixing two comma-separated alternatives with an 4542.Ql e 4543and an operator. 4544An optional 4545.Ql f 4546flag may be given after the operator to use floating point numbers, otherwise integers are used. 4547This may be followed by a number giving the number of decimal places to use for the result. 4548The available operators are: 4549addition 4550.Ql + , 4551subtraction 4552.Ql - , 4553multiplication 4554.Ql * , 4555division 4556.Ql / , 4557modulus 4558.Ql m 4559or 4560.Ql % 4561(note that 4562.Ql % 4563must be escaped as 4564.Ql %% 4565in formats which are also expanded by 4566.Xr strftime 3 ) 4567and numeric comparison operators 4568.Ql == , 4569.Ql != , 4570.Ql < , 4571.Ql <= , 4572.Ql > 4573and 4574.Ql >= . 4575For example, 4576.Ql #{e|*|f|4:5.5,3} 4577multiplies 5.5 by 3 for a result with four decimal places and 4578.Ql #{e|%%:7,3} 4579returns the modulus of 7 and 3. 4580.Pp 4581A limit may be placed on the length of the resultant string by prefixing it 4582by an 4583.Ql = , 4584a number and a colon. 4585Positive numbers count from the start of the string and negative from the end, 4586so 4587.Ql #{=5:pane_title} 4588will include at most the first five characters of the pane title, or 4589.Ql #{=-5:pane_title} 4590the last five characters. 4591A suffix or prefix may be given as a second argument - if provided then it is 4592appended or prepended to the string if the length has been trimmed, for example 4593.Ql #{=/5/...:pane_title} 4594will append 4595.Ql ... 4596if the pane title is more than five characters. 4597Similarly, 4598.Ql p 4599pads the string to a given width, for example 4600.Ql #{p10:pane_title} 4601will result in a width of at least 10 characters. 4602A positive width pads on the left, a negative on the right. 4603.Ql n 4604expands to the length of the variable and 4605.Ql w 4606to its width when displayed, for example 4607.Ql #{n:window_name} . 4608.Pp 4609Prefixing a time variable with 4610.Ql t:\& 4611will convert it to a string, so if 4612.Ql #{window_activity} 4613gives 4614.Ql 1445765102 , 4615.Ql #{t:window_activity} 4616gives 4617.Ql Sun Oct 25 09:25:02 2015 . 4618Adding 4619.Ql p ( 4620.Ql `t/p` ) 4621will use shorter but less accurate time format for times in the past. 4622A custom format may be given using an 4623.Ql f 4624suffix (note that 4625.Ql % 4626must be escaped as 4627.Ql %% 4628if the format is separately being passed through 4629.Xr strftime 3 , 4630for example in the 4631.Ic status-left 4632option): 4633.Ql #{t/f/%%H#:%%M:window_activity} , 4634see 4635.Xr strftime 3 . 4636.Pp 4637The 4638.Ql b:\& 4639and 4640.Ql d:\& 4641prefixes are 4642.Xr basename 3 4643and 4644.Xr dirname 3 4645of the variable respectively. 4646.Ql q:\& 4647will escape 4648.Xr sh 1 4649special characters or with an 4650.Ql e 4651suffix, escape hash characters (so 4652.Ql # 4653becomes 4654.Ql ## ) . 4655.Ql E:\& 4656will expand the format twice, for example 4657.Ql #{E:status-left} 4658is the result of expanding the content of the 4659.Ic status-left 4660option rather than the option itself. 4661.Ql T:\& 4662is like 4663.Ql E:\& 4664but also expands 4665.Xr strftime 3 4666specifiers. 4667.Ql S:\& , 4668.Ql W:\& 4669or 4670.Ql P:\& 4671will loop over each session, window or pane and insert the format once 4672for each. 4673For windows and panes, two comma-separated formats may be given: 4674the second is used for the current window or active pane. 4675For example, to get a list of windows formatted like the status line: 4676.Bd -literal -offset indent 4677#{W:#{E:window-status-format} ,#{E:window-status-current-format} } 4678.Ed 4679.Pp 4680A prefix of the form 4681.Ql s/foo/bar/:\& 4682will substitute 4683.Ql foo 4684with 4685.Ql bar 4686throughout. 4687The first argument may be an extended regular expression and a final argument may be 4688.Ql i 4689to ignore case, for example 4690.Ql s/a(.)/\e1x/i:\& 4691would change 4692.Ql abABab 4693into 4694.Ql bxBxbx . 4695.Pp 4696In addition, the last line of a shell command's output may be inserted using 4697.Ql #() . 4698For example, 4699.Ql #(uptime) 4700will insert the system's uptime. 4701When constructing formats, 4702.Nm 4703does not wait for 4704.Ql #() 4705commands to finish; instead, the previous result from running the same command is used, 4706or a placeholder if the command has not been run before. 4707If the command hasn't exited, the most recent line of output will be used, but the status 4708line will not be updated more than once a second. 4709Commands are executed with the 4710.Nm 4711global environment set (see the 4712.Sx GLOBAL AND SESSION ENVIRONMENT 4713section). 4714.Pp 4715An 4716.Ql l 4717specifies that a string should be interpreted literally and not expanded. 4718For example 4719.Ql #{l:#{?pane_in_mode,yes,no}} 4720will be replaced by 4721.Ql #{?pane_in_mode,yes,no} . 4722.Pp 4723The following variables are available, where appropriate: 4724.Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX" 4725.It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with" 4726.It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen" 4727.It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen" 4728.It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen" 4729.It Li "buffer_created" Ta "" Ta "Time buffer created" 4730.It Li "buffer_name" Ta "" Ta "Name of buffer" 4731.It Li "buffer_sample" Ta "" Ta "Sample of start of buffer" 4732.It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes" 4733.It Li "client_activity" Ta "" Ta "Time client last had activity" 4734.It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels" 4735.It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels" 4736.It Li "client_control_mode" Ta "" Ta "1 if client is in control mode" 4737.It Li "client_created" Ta "" Ta "Time client created" 4738.It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind" 4739.It Li "client_flags" Ta "" Ta "List of client flags" 4740.It Li "client_height" Ta "" Ta "Height of client" 4741.It Li "client_key_table" Ta "" Ta "Current key table" 4742.It Li "client_last_session" Ta "" Ta "Name of the client's last session" 4743.It Li "client_name" Ta "" Ta "Name of client" 4744.It Li "client_pid" Ta "" Ta "PID of client process" 4745.It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed" 4746.It Li "client_readonly" Ta "" Ta "1 if client is readonly" 4747.It Li "client_session" Ta "" Ta "Name of the client's session" 4748.It Li "client_termname" Ta "" Ta "Terminal name of client" 4749.It Li "client_termtype" Ta "" Ta "Terminal type of client, if available" 4750.It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any" 4751.It Li "client_tty" Ta "" Ta "Pseudo terminal of client" 4752.It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8" 4753.It Li "client_width" Ta "" Ta "Width of client" 4754.It Li "client_written" Ta "" Ta "Bytes written to client" 4755.It Li "command" Ta "" Ta "Name of command in use, if any" 4756.It Li "command_list_alias" Ta "" Ta "Command alias if listing commands" 4757.It Li "command_list_name" Ta "" Ta "Command name if listing commands" 4758.It Li "command_list_usage" Ta "" Ta "Command usage if listing commands" 4759.It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode" 4760.It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode" 4761.It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode" 4762.It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode" 4763.It Li "cursor_character" Ta "" Ta "Character at cursor in pane" 4764.It Li "cursor_flag" Ta "" Ta "Pane cursor flag" 4765.It Li "cursor_x" Ta "" Ta "Cursor X position in pane" 4766.It Li "cursor_y" Ta "" Ta "Cursor Y position in pane" 4767.It Li "history_bytes" Ta "" Ta "Number of bytes in window history" 4768.It Li "history_limit" Ta "" Ta "Maximum window history lines" 4769.It Li "history_size" Ta "" Ta "Size of history in lines" 4770.It Li "hook" Ta "" Ta "Name of running hook, if any" 4771.It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any" 4772.It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any" 4773.It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any" 4774.It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any" 4775.It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any" 4776.It Li "host" Ta "#H" Ta "Hostname of local host" 4777.It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)" 4778.It Li "insert_flag" Ta "" Ta "Pane insert flag" 4779.It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag" 4780.It Li "keypad_flag" Ta "" Ta "Pane keypad flag" 4781.It Li "line" Ta "" Ta "Line number in the list" 4782.It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag" 4783.It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag" 4784.It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag" 4785.It Li "mouse_line" Ta "" Ta "Line under mouse, if any" 4786.It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag" 4787.It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag" 4788.It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag" 4789.It Li "mouse_word" Ta "" Ta "Word under mouse, if any" 4790.It Li "mouse_x" Ta "" Ta "Mouse X position, if any" 4791.It Li "mouse_y" Ta "" Ta "Mouse Y position, if any" 4792.It Li "origin_flag" Ta "" Ta "Pane origin flag" 4793.It Li "pane_active" Ta "" Ta "1 if active pane" 4794.It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window" 4795.It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window" 4796.It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window" 4797.It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window" 4798.It Li "pane_bottom" Ta "" Ta "Bottom of pane" 4799.It Li "pane_current_command" Ta "" Ta "Current command if available" 4800.It Li "pane_current_path" Ta "" Ta "Current path if available" 4801.It Li "pane_dead" Ta "" Ta "1 if pane is dead" 4802.It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane" 4803.It Li "pane_format" Ta "" Ta "1 if format is for a pane" 4804.It Li "pane_height" Ta "" Ta "Height of pane" 4805.It Li "pane_id" Ta "#D" Ta "Unique pane ID" 4806.It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode" 4807.It Li "pane_index" Ta "#P" Ta "Index of pane" 4808.It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled" 4809.It Li "pane_last" Ta "" Ta "1 if last pane" 4810.It Li "pane_left" Ta "" Ta "Left of pane" 4811.It Li "pane_marked" Ta "" Ta "1 if this is the marked pane" 4812.It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set" 4813.It Li "pane_mode" Ta "" Ta "Name of pane mode, if any" 4814.It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)" 4815.It Li "pane_pid" Ta "" Ta "PID of first process in pane" 4816.It Li "pane_pipe" Ta "" Ta "1 if pane is being piped" 4817.It Li "pane_right" Ta "" Ta "Right of pane" 4818.It Li "pane_search_string" Ta "" Ta "Last search string in copy mode" 4819.It Li "pane_skipped" Ta "" Ta "Bytes skipped as not visible in pane" 4820.It Li "pane_start_command" Ta "" Ta "Command pane started with" 4821.It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized" 4822.It Li "pane_tabs" Ta "" Ta "Pane tab positions" 4823.It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)" 4824.It Li "pane_top" Ta "" Ta "Top of pane" 4825.It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane" 4826.It Li "pane_width" Ta "" Ta "Width of pane" 4827.It Li "pane_written" Ta "" Ta "Bytes written by pane (aside from redrawing)" 4828.It Li "pid" Ta "" Ta "Server PID" 4829.It Li "popup_key" Ta "" Ta "Key pressed in popup" 4830.It Li "popup_mouse_x" Ta "" Ta "Mouse X position in popup" 4831.It Li "popup_mouse_y" Ta "" Ta "Mouse Y position in popup" 4832.It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated" 4833.It Li "scroll_position" Ta "" Ta "Scroll position in copy mode" 4834.It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane" 4835.It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane" 4836.It Li "search_present" Ta "" Ta "1 if search started in copy mode" 4837.It Li "search_match" Ta "" Ta "Search match if any" 4838.It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode" 4839.It Li "selection_end_x" Ta "" Ta "X position of the end of the selection" 4840.It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection" 4841.It Li "selection_present" Ta "" Ta "1 if selection started in copy mode" 4842.It Li "selection_start_x" Ta "" Ta "X position of the start of the selection" 4843.It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection" 4844.It Li "session_activity" Ta "" Ta "Time of session last activity" 4845.It Li "session_alerts" Ta "" Ta "List of window indexes with alerts" 4846.It Li "session_attached" Ta "" Ta "Number of clients session is attached to" 4847.It Li "session_attached_list" Ta "" Ta "List of clients session is attached to" 4848.It Li "session_created" Ta "" Ta "Time session created" 4849.It Li "session_format" Ta "" Ta "1 if format is for a session" 4850.It Li "session_group" Ta "" Ta "Name of session group" 4851.It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to" 4852.It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to" 4853.It Li "session_group_list" Ta "" Ta "List of sessions in group" 4854.It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group" 4855.It Li "session_group_size" Ta "" Ta "Size of session group" 4856.It Li "session_grouped" Ta "" Ta "1 if session in a group" 4857.It Li "session_id" Ta "" Ta "Unique session ID" 4858.It Li "session_last_attached" Ta "" Ta "Time session last attached" 4859.It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached" 4860.It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane" 4861.It Li "session_name" Ta "#S" Ta "Name of session" 4862.It Li "session_path" Ta "" Ta "Working directory of session" 4863.It Li "session_stack" Ta "" Ta "Window indexes in most recent order" 4864.It Li "session_windows" Ta "" Ta "Number of windows in session" 4865.It Li "socket_path" Ta "" Ta "Server socket path" 4866.It Li "start_time" Ta "" Ta "Server start time" 4867.It Li "version" Ta "" Ta "Server version" 4868.It Li "window_active" Ta "" Ta "1 if window active" 4869.It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window" 4870.It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window" 4871.It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active" 4872.It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active" 4873.It Li "window_activity" Ta "" Ta "Time of window last activity" 4874.It Li "window_activity_flag" Ta "" Ta "1 if window has activity" 4875.It Li "window_bell_flag" Ta "" Ta "1 if window has bell" 4876.It Li "window_bigger" Ta "" Ta "1 if window is larger than client" 4877.It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels" 4878.It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels" 4879.It Li "window_end_flag" Ta "" Ta "1 if window has the highest index" 4880.It Li "window_flags" Ta "#F" Ta "Window flags" 4881.It Li "window_format" Ta "" Ta "1 if format is for a window" 4882.It Li "window_height" Ta "" Ta "Height of window" 4883.It Li "window_id" Ta "" Ta "Unique window ID" 4884.It Li "window_index" Ta "#I" Ta "Index of window" 4885.It Li "window_last_flag" Ta "" Ta "1 if window is the last used" 4886.It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes" 4887.It Li "window_linked" Ta "" Ta "1 if window is linked across sessions" 4888.It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to" 4889.It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to" 4890.It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane" 4891.It Li "window_name" Ta "#W" Ta "Name of window" 4892.It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client" 4893.It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client" 4894.It Li "window_panes" Ta "" Ta "Number of panes in window" 4895.It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert" 4896.It Li "window_stack_index" Ta "" Ta "Index in session most recent stack" 4897.It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index" 4898.It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes" 4899.It Li "window_width" Ta "" Ta "Width of window" 4900.It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed" 4901.It Li "wrap_flag" Ta "" Ta "Pane wrap flag" 4902.El 4903.Sh STYLES 4904.Nm 4905offers various options to specify the colour and attributes of aspects of the 4906interface, for example 4907.Ic status-style 4908for the status line. 4909In addition, embedded styles may be specified in format options, such as 4910.Ic status-left , 4911by enclosing them in 4912.Ql #[ 4913and 4914.Ql \&] . 4915.Pp 4916A style may be the single term 4917.Ql default 4918to specify the default style (which may come from an option, for example 4919.Ic status-style 4920in the status line) or a space 4921or comma separated list of the following: 4922.Bl -tag -width Ds 4923.It Ic fg=colour 4924Set the foreground colour. 4925The colour is one of: 4926.Ic black , 4927.Ic red , 4928.Ic green , 4929.Ic yellow , 4930.Ic blue , 4931.Ic magenta , 4932.Ic cyan , 4933.Ic white ; 4934if supported the bright variants 4935.Ic brightred , 4936.Ic brightgreen , 4937.Ic brightyellow ; 4938.Ic colour0 4939to 4940.Ic colour255 4941from the 256-colour set; 4942.Ic default 4943for the default colour; 4944.Ic terminal 4945for the terminal default colour; or a hexadecimal RGB string such as 4946.Ql #ffffff . 4947.It Ic bg=colour 4948Set the background colour. 4949.It Ic none 4950Set no attributes (turn off any active attributes). 4951.It Xo Ic acs , 4952.Ic bright 4953(or 4954.Ic bold ) , 4955.Ic dim , 4956.Ic underscore , 4957.Ic blink , 4958.Ic reverse , 4959.Ic hidden , 4960.Ic italics , 4961.Ic overline , 4962.Ic strikethrough , 4963.Ic double-underscore , 4964.Ic curly-underscore , 4965.Ic dotted-underscore , 4966.Ic dashed-underscore 4967.Xc 4968Set an attribute. 4969Any of the attributes may be prefixed with 4970.Ql no 4971to unset. 4972.Ic acs 4973is the terminal alternate character set. 4974.It Xo Ic align=left 4975(or 4976.Ic noalign ) , 4977.Ic align=centre , 4978.Ic align=right 4979.Xc 4980Align text to the left, centre or right of the available space if appropriate. 4981.It Ic fill=colour 4982Fill the available space with a background colour if appropriate. 4983.It Xo Ic list=on , 4984.Ic list=focus , 4985.Ic list=left-marker , 4986.Ic list=right-marker , 4987.Ic nolist 4988.Xc 4989Mark the position of the various window list components in the 4990.Ic status-format 4991option: 4992.Ic list=on 4993marks the start of the list; 4994.Ic list=focus 4995is the part of the list that should be kept in focus if the entire list won't fit 4996in the available space (typically the current window); 4997.Ic list=left-marker 4998and 4999.Ic list=right-marker 5000mark the text to be used to mark that text has been trimmed from the left or 5001right of the list if there is not enough space. 5002.It Xo Ic push-default , 5003.Ic pop-default 5004.Xc 5005Store the current colours and attributes as the default or reset to the previous 5006default. 5007A 5008.Ic push-default 5009affects any subsequent use of the 5010.Ic default 5011term until a 5012.Ic pop-default . 5013Only one default may be pushed (each 5014.Ic push-default 5015replaces the previous saved default). 5016.It Xo Ic range=left , 5017.Ic range=right , 5018.Ic range=window|X , 5019.Ic norange 5020.Xc 5021Mark a range in the 5022.Ic status-format 5023option. 5024.Ic range=left 5025and 5026.Ic range=right 5027are the text used for the 5028.Ql StatusLeft 5029and 5030.Ql StatusRight 5031mouse keys. 5032.Ic range=window|X 5033is the range for a window passed to the 5034.Ql Status 5035mouse key, where 5036.Ql X 5037is a window index. 5038.El 5039.Pp 5040Examples are: 5041.Bd -literal -offset indent 5042fg=yellow bold underscore blink 5043bg=black,fg=default,noreverse 5044.Ed 5045.Sh NAMES AND TITLES 5046.Nm 5047distinguishes between names and titles. 5048Windows and sessions have names, which may be used to specify them in targets 5049and are displayed in the status line and various lists: the name is the 5050.Nm 5051identifier for a window or session. 5052Only panes have titles. 5053A pane's title is typically set by the program running inside the pane using 5054an escape sequence (like it would set the 5055.Xr xterm 1 5056window title in 5057.Xr X 7 ) . 5058Windows themselves do not have titles - a window's title is the title of its 5059active pane. 5060.Nm 5061itself may set the title of the terminal in which the client is running, see 5062the 5063.Ic set-titles 5064option. 5065.Pp 5066A session's name is set with the 5067.Ic new-session 5068and 5069.Ic rename-session 5070commands. 5071A window's name is set with one of: 5072.Bl -enum -width Ds 5073.It 5074A command argument (such as 5075.Fl n 5076for 5077.Ic new-window 5078or 5079.Ic new-session ) . 5080.It 5081An escape sequence (if the 5082.Ic allow-rename 5083option is turned on): 5084.Bd -literal -offset indent 5085$ printf '\e033kWINDOW_NAME\e033\e\e' 5086.Ed 5087.It 5088Automatic renaming, which sets the name to the active command in the window's 5089active pane. 5090See the 5091.Ic automatic-rename 5092option. 5093.El 5094.Pp 5095When a pane is first created, its title is the hostname. 5096A pane's title can be set via the title setting escape sequence, for example: 5097.Bd -literal -offset indent 5098$ printf '\e033]2;My Title\e033\e\e' 5099.Ed 5100.Pp 5101It can also be modified with the 5102.Ic select-pane 5103.Fl T 5104command. 5105.Sh GLOBAL AND SESSION ENVIRONMENT 5106When the server is started, 5107.Nm 5108copies the environment into the 5109.Em global environment ; 5110in addition, each session has a 5111.Em session environment . 5112When a window is created, the session and global environments are merged. 5113If a variable exists in both, the value from the session environment is used. 5114The result is the initial environment passed to the new process. 5115.Pp 5116The 5117.Ic update-environment 5118session option may be used to update the session environment from the client 5119when a new session is created or an old reattached. 5120.Nm 5121also initialises the 5122.Ev TMUX 5123variable with some internal information to allow commands to be executed 5124from inside, and the 5125.Ev TERM 5126variable with the correct terminal setting of 5127.Ql screen . 5128.Pp 5129Variables in both session and global environments may be marked as hidden. 5130Hidden variables are not passed into the environment of new processes and 5131instead can only be used by tmux itself (for example in formats, see the 5132.Sx FORMATS 5133section). 5134.Pp 5135Commands to alter and view the environment are: 5136.Bl -tag -width Ds 5137.It Xo Ic set-environment 5138.Op Fl Fhgru 5139.Op Fl t Ar target-session 5140.Ar name Op Ar value 5141.Xc 5142.D1 (alias: Ic setenv ) 5143Set or unset an environment variable. 5144If 5145.Fl g 5146is used, the change is made in the global environment; otherwise, it is applied 5147to the session environment for 5148.Ar target-session . 5149If 5150.Fl F 5151is present, then 5152.Ar value 5153is expanded as a format. 5154The 5155.Fl u 5156flag unsets a variable. 5157.Fl r 5158indicates the variable is to be removed from the environment before starting a 5159new process. 5160.Fl h 5161marks the variable as hidden. 5162.It Xo Ic show-environment 5163.Op Fl hgs 5164.Op Fl t Ar target-session 5165.Op Ar variable 5166.Xc 5167.D1 (alias: Ic showenv ) 5168Display the environment for 5169.Ar target-session 5170or the global environment with 5171.Fl g . 5172If 5173.Ar variable 5174is omitted, all variables are shown. 5175Variables removed from the environment are prefixed with 5176.Ql - . 5177If 5178.Fl s 5179is used, the output is formatted as a set of Bourne shell commands. 5180.Fl h 5181shows hidden variables (omitted by default). 5182.El 5183.Sh STATUS LINE 5184.Nm 5185includes an optional status line which is displayed in the bottom line of each 5186terminal. 5187.Pp 5188By default, the status line is enabled and one line in height (it may be 5189disabled or made multiple lines with the 5190.Ic status 5191session option) and contains, from left-to-right: the name of the current 5192session in square brackets; the window list; the title of the active pane 5193in double quotes; and the time and date. 5194.Pp 5195Each line of the status line is configured with the 5196.Ic status-format 5197option. 5198The default is made of three parts: configurable left and right sections (which 5199may contain dynamic content such as the time or output from a shell command, 5200see the 5201.Ic status-left , 5202.Ic status-left-length , 5203.Ic status-right , 5204and 5205.Ic status-right-length 5206options below), and a central window list. 5207By default, the window list shows the index, name and (if any) flag of the 5208windows present in the current session in ascending numerical order. 5209It may be customised with the 5210.Ar window-status-format 5211and 5212.Ar window-status-current-format 5213options. 5214The flag is one of the following symbols appended to the window name: 5215.Bl -column "Symbol" "Meaning" -offset indent 5216.It Sy "Symbol" Ta Sy "Meaning" 5217.It Li "*" Ta "Denotes the current window." 5218.It Li "-" Ta "Marks the last window (previously selected)." 5219.It Li "#" Ta "Window activity is monitored and activity has been detected." 5220.It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window." 5221.It Li "~" Ta "The window has been silent for the monitor-silence interval." 5222.It Li "M" Ta "The window contains the marked pane." 5223.It Li "Z" Ta "The window's active pane is zoomed." 5224.El 5225.Pp 5226The # symbol relates to the 5227.Ic monitor-activity 5228window option. 5229The window name is printed in inverted colours if an alert (bell, activity or 5230silence) is present. 5231.Pp 5232The colour and attributes of the status line may be configured, the entire 5233status line using the 5234.Ic status-style 5235session option and individual windows using the 5236.Ic window-status-style 5237window option. 5238.Pp 5239The status line is automatically refreshed at interval if it has changed, the 5240interval may be controlled with the 5241.Ic status-interval 5242session option. 5243.Pp 5244Commands related to the status line are as follows: 5245.Bl -tag -width Ds 5246.It Xo Ic command-prompt 5247.Op Fl 1ikNTW 5248.Op Fl I Ar inputs 5249.Op Fl p Ar prompts 5250.Op Fl t Ar target-client 5251.Op Ar template 5252.Xc 5253Open the command prompt in a client. 5254This may be used from inside 5255.Nm 5256to execute commands interactively. 5257.Pp 5258If 5259.Ar template 5260is specified, it is used as the command. 5261If present, 5262.Fl I 5263is a comma-separated list of the initial text for each prompt. 5264If 5265.Fl p 5266is given, 5267.Ar prompts 5268is a comma-separated list of prompts which are displayed in order; otherwise 5269a single prompt is displayed, constructed from 5270.Ar template 5271if it is present, or 5272.Ql \&: 5273if not. 5274.Pp 5275Before the command is executed, the first occurrence of the string 5276.Ql %% 5277and all occurrences of 5278.Ql %1 5279are replaced by the response to the first prompt, all 5280.Ql %2 5281are replaced with the response to the second prompt, and so on for further 5282prompts. 5283Up to nine prompt responses may be replaced 5284.Po 5285.Ql %1 5286to 5287.Ql %9 5288.Pc . 5289.Ql %%% 5290is like 5291.Ql %% 5292but any quotation marks are escaped. 5293.Pp 5294.Fl 1 5295makes the prompt only accept one key press, in this case the resulting input 5296is a single character. 5297.Fl k 5298is like 5299.Fl 1 5300but the key press is translated to a key name. 5301.Fl N 5302makes the prompt only accept numeric key presses. 5303.Fl i 5304executes the command every time the prompt input changes instead of when the 5305user exits the command prompt. 5306.Fl T 5307tells 5308.Nm 5309that the prompt is for a target which affects what completions are offered when 5310.Em Tab 5311is pressed; 5312.Fl W 5313is similar but indicates the prompt is for a window. 5314.Pp 5315The following keys have a special meaning in the command prompt, depending 5316on the value of the 5317.Ic status-keys 5318option: 5319.Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent 5320.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" 5321.It Li "Cancel command prompt" Ta "q" Ta "Escape" 5322.It Li "Delete from cursor to start of word" Ta "" Ta "C-w" 5323.It Li "Delete entire command" Ta "d" Ta "C-u" 5324.It Li "Delete from cursor to end" Ta "D" Ta "C-k" 5325.It Li "Execute command" Ta "Enter" Ta "Enter" 5326.It Li "Get next command from history" Ta "" Ta "Down" 5327.It Li "Get previous command from history" Ta "" Ta "Up" 5328.It Li "Insert top paste buffer" Ta "p" Ta "C-y" 5329.It Li "Look for completions" Ta "Tab" Ta "Tab" 5330.It Li "Move cursor left" Ta "h" Ta "Left" 5331.It Li "Move cursor right" Ta "l" Ta "Right" 5332.It Li "Move cursor to end" Ta "$" Ta "C-e" 5333.It Li "Move cursor to next word" Ta "w" Ta "M-f" 5334.It Li "Move cursor to previous word" Ta "b" Ta "M-b" 5335.It Li "Move cursor to start" Ta "0" Ta "C-a" 5336.It Li "Transpose characters" Ta "" Ta "C-t" 5337.El 5338.It Xo Ic confirm-before 5339.Op Fl p Ar prompt 5340.Op Fl t Ar target-client 5341.Ar command 5342.Xc 5343.D1 (alias: Ic confirm ) 5344Ask for confirmation before executing 5345.Ar command . 5346If 5347.Fl p 5348is given, 5349.Ar prompt 5350is the prompt to display; otherwise a prompt is constructed from 5351.Ar command . 5352It may contain the special character sequences supported by the 5353.Ic status-left 5354option. 5355.Pp 5356This command works only from inside 5357.Nm . 5358.It Xo Ic display-menu 5359.Op Fl O 5360.Op Fl c Ar target-client 5361.Op Fl t Ar target-pane 5362.Op Fl T Ar title 5363.Op Fl x Ar position 5364.Op Fl y Ar position 5365.Ar name 5366.Ar key 5367.Ar command 5368.Ar ... 5369.Xc 5370.D1 (alias: Ic menu ) 5371Display a menu on 5372.Ar target-client . 5373.Ar target-pane 5374gives the target for any commands run from the menu. 5375.Pp 5376A menu is passed as a series of arguments: first the menu item name, 5377second the key shortcut (or empty for none) and third the command 5378to run when the menu item is chosen. 5379The name and command are formats, see the 5380.Sx FORMATS 5381and 5382.Sx STYLES 5383sections. 5384If the name begins with a hyphen (-), then the item is disabled (shown dim) and 5385may not be chosen. 5386The name may be empty for a separator line, in which case both the key and 5387command should be omitted. 5388.Pp 5389.Fl T 5390is a format for the menu title (see 5391.Sx FORMATS ) . 5392.Pp 5393.Fl x 5394and 5395.Fl y 5396give the position of the menu. 5397Both may be a row or column number, or one of the following special values: 5398.Bl -column "XXXXX" "XXXX" -offset indent 5399.It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning" 5400.It Li "C" Ta "Both" Ta "The centre of the terminal" 5401.It Li "R" Ta Fl x Ta "The right side of the terminal" 5402.It Li "P" Ta "Both" Ta "The bottom left of the pane" 5403.It Li "M" Ta "Both" Ta "The mouse position" 5404.It Li "W" Ta "Both" Ta "The window position on the status line" 5405.It Li "S" Ta Fl y Ta "The line above or below the status line" 5406.El 5407.Pp 5408Or a format, which is expanded including the following additional variables: 5409.Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent 5410.It Sy "Variable name" Ta Sy "Replaced with" 5411.It Li "popup_centre_x" Ta "Centered in the client" 5412.It Li "popup_centre_y" Ta "Centered in the client" 5413.It Li "popup_height" Ta "Height of menu or popup" 5414.It Li "popup_mouse_bottom" Ta "Bottom of at the mouse" 5415.It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse" 5416.It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse" 5417.It Li "popup_mouse_top" Ta "Top at the mouse" 5418.It Li "popup_mouse_x" Ta "Mouse X position" 5419.It Li "popup_mouse_y" Ta "Mouse Y position" 5420.It Li "popup_pane_bottom" Ta "Bottom of the pane" 5421.It Li "popup_pane_left" Ta "Left of the pane" 5422.It Li "popup_pane_right" Ta "Right of the pane" 5423.It Li "popup_pane_top" Ta "Top of the pane" 5424.It Li "popup_status_line_y" Ta "Above or below the status line" 5425.It Li "popup_width" Ta "Width of menu or popup" 5426.It Li "popup_window_status_line_x" Ta "At the window position in status line" 5427.It Li "popup_window_status_line_y" Ta "At the status line showing the window" 5428.El 5429.Pp 5430Each menu consists of items followed by a key shortcut shown in brackets. 5431If the menu is too large to fit on the terminal, it is not displayed. 5432Pressing the key shortcut chooses the corresponding item. 5433If the mouse is enabled and the menu is opened from a mouse key binding, 5434releasing the mouse button with an item selected chooses that item and 5435releasing the mouse button without an item selected closes the menu. 5436.Fl O 5437changes this behaviour so that the menu does not close when the mouse button is 5438released without an item selected the menu is not closed and a mouse button 5439must be clicked to choose an item. 5440.Pp 5441The following keys are also available: 5442.Bl -column "Key" "Function" -offset indent 5443.It Sy "Key" Ta Sy "Function" 5444.It Li "Enter" Ta "Choose selected item" 5445.It Li "Up" Ta "Select previous item" 5446.It Li "Down" Ta "Select next item" 5447.It Li "q" Ta "Exit menu" 5448.El 5449.It Xo Ic display-message 5450.Op Fl aIpv 5451.Op Fl c Ar target-client 5452.Op Fl d Ar delay 5453.Op Fl t Ar target-pane 5454.Op Ar message 5455.Xc 5456.D1 (alias: Ic display ) 5457Display a message. 5458If 5459.Fl p 5460is given, the output is printed to stdout, otherwise it is displayed in the 5461.Ar target-client 5462status line for up to 5463.Ar delay 5464milliseconds. 5465If 5466.Ar delay 5467is not given, the 5468.Ic message-time 5469option is used; a delay of zero waits for a key press. 5470The format of 5471.Ar message 5472is described in the 5473.Sx FORMATS 5474section; information is taken from 5475.Ar target-pane 5476if 5477.Fl t 5478is given, otherwise the active pane. 5479.Pp 5480.Fl v 5481prints verbose logging as the format is parsed and 5482.Fl a 5483lists the format variables and their values. 5484.Pp 5485.Fl I 5486forwards any input read from stdin to the empty pane given by 5487.Ar target-pane . 5488.It Xo Ic display-popup 5489.Op Fl CEK 5490.Op Fl c Ar target-client 5491.Op Fl d Ar start-directory 5492.Op Fl h Ar height 5493.Op Fl R Ar shell-command 5494.Op Fl t Ar target-pane 5495.Op Fl w Ar width 5496.Op Fl x Ar position 5497.Op Fl y Ar position 5498.Op Ar command Ar line Ar ... 5499.Xc 5500.D1 (alias: Ic popup ) 5501Display a popup on 5502.Ar target-client . 5503A popup is a rectangular box drawn over the top of any panes. 5504Panes are not updated while a popup is present. 5505The popup content may be given in two ways: 5506.Bl -enum -offset Ds 5507.It 5508A set of lines as arguments. 5509Each line is a format which is expanded using 5510.Ar target-pane 5511as the target. 5512If a line contains newlines it is split into multiple lines. 5513Lines may use styles, see the 5514.Sx STYLES 5515section. 5516.It 5517A shell command given by 5518.Fl R 5519which is run and any output shown in the pane. 5520.El 5521.Pp 5522The first argument, 5523.Ar command , 5524is a 5525.Nm 5526command which is run when a key is pressed. 5527The key is available in the 5528.Ql popup_key 5529format. 5530After 5531.Ar command 5532is run, the popup is closed. 5533It may be empty to discard any key presses. 5534If 5535.Fl K 5536is given together with 5537.Fl R , 5538key presses are instead passed to the 5539.Fl R 5540shell command. 5541.Fl E 5542closes the popup automatically when 5543.Ar shell-command 5544exits. 5545Two 5546.Fl E 5547closes the popup only if 5548.Ar shell-command 5549exited with success. 5550With 5551.Fl K , 5552.Ql Escape 5553and 5554.Ql C-c 5555close the popup unless 5556.Fl E 5557is also given. 5558.Pp 5559.Fl x 5560and 5561.Fl y 5562give the position of the popup, they have the same meaning as for the 5563.Ic display-menu 5564command. 5565.Fl w 5566and 5567.Fl h 5568give the width and height - both may be a percentage (followed by 5569.Ql % ) . 5570If omitted, without 5571.Fl R 5572they are calculated from the given lines and with 5573.Fl R 5574they use half the terminal size. 5575.Pp 5576The 5577.Fl C 5578flag closes any popup on the client. 5579.El 5580.Sh BUFFERS 5581.Nm 5582maintains a set of named 5583.Em paste buffers . 5584Each buffer may be either explicitly or automatically named. 5585Explicitly named buffers are named when created with the 5586.Ic set-buffer 5587or 5588.Ic load-buffer 5589commands, or by renaming an automatically named buffer with 5590.Ic set-buffer 5591.Fl n . 5592Automatically named buffers are given a name such as 5593.Ql buffer0001 , 5594.Ql buffer0002 5595and so on. 5596When the 5597.Ic buffer-limit 5598option is reached, the oldest automatically named buffer is deleted. 5599Explicitly named buffers are not subject to 5600.Ic buffer-limit 5601and may be deleted with the 5602.Ic delete-buffer 5603command. 5604.Pp 5605Buffers may be added using 5606.Ic copy-mode 5607or the 5608.Ic set-buffer 5609and 5610.Ic load-buffer 5611commands, and pasted into a window using the 5612.Ic paste-buffer 5613command. 5614If a buffer command is used and no buffer is specified, the most 5615recently added automatically named buffer is assumed. 5616.Pp 5617A configurable history buffer is also maintained for each window. 5618By default, up to 2000 lines are kept; this can be altered with the 5619.Ic history-limit 5620option (see the 5621.Ic set-option 5622command above). 5623.Pp 5624The buffer commands are as follows: 5625.Bl -tag -width Ds 5626.It Xo 5627.Ic choose-buffer 5628.Op Fl NZr 5629.Op Fl F Ar format 5630.Op Fl f Ar filter 5631.Op Fl O Ar sort-order 5632.Op Fl t Ar target-pane 5633.Op Ar template 5634.Xc 5635Put a pane into buffer mode, where a buffer may be chosen interactively from 5636a list. 5637.Fl Z 5638zooms the pane. 5639The following keys may be used in buffer mode: 5640.Bl -column "Key" "Function" -offset indent 5641.It Sy "Key" Ta Sy "Function" 5642.It Li "Enter" Ta "Paste selected buffer" 5643.It Li "Up" Ta "Select previous buffer" 5644.It Li "Down" Ta "Select next buffer" 5645.It Li "C-s" Ta "Search by name or content" 5646.It Li "n" Ta "Repeat last search" 5647.It Li "t" Ta "Toggle if buffer is tagged" 5648.It Li "T" Ta "Tag no buffers" 5649.It Li "C-t" Ta "Tag all buffers" 5650.It Li "p" Ta "Paste selected buffer" 5651.It Li "P" Ta "Paste tagged buffers" 5652.It Li "d" Ta "Delete selected buffer" 5653.It Li "D" Ta "Delete tagged buffers" 5654.It Li "e" Ta "Open the buffer in an editor" 5655.It Li "f" Ta "Enter a format to filter items" 5656.It Li "O" Ta "Change sort field" 5657.It Li "r" Ta "Reverse sort order" 5658.It Li "v" Ta "Toggle preview" 5659.It Li "q" Ta "Exit mode" 5660.El 5661.Pp 5662After a buffer is chosen, 5663.Ql %% 5664is replaced by the buffer name in 5665.Ar template 5666and the result executed as a command. 5667If 5668.Ar template 5669is not given, "paste-buffer -b '%%'" is used. 5670.Pp 5671.Fl O 5672specifies the initial sort field: one of 5673.Ql time , 5674.Ql name 5675or 5676.Ql size . 5677.Fl r 5678reverses the sort order. 5679.Fl f 5680specifies an initial filter: the filter is a format - if it evaluates to zero, 5681the item in the list is not shown, otherwise it is shown. 5682If a filter would lead to an empty list, it is ignored. 5683.Fl F 5684specifies the format for each item in the list. 5685.Fl N 5686starts without the preview. 5687This command works only if at least one client is attached. 5688.It Ic clear-history Op Fl t Ar target-pane 5689.D1 (alias: Ic clearhist ) 5690Remove and free the history for the specified pane. 5691.It Ic delete-buffer Op Fl b Ar buffer-name 5692.D1 (alias: Ic deleteb ) 5693Delete the buffer named 5694.Ar buffer-name , 5695or the most recently added automatically named buffer if not specified. 5696.It Xo Ic list-buffers 5697.Op Fl F Ar format 5698.Op Fl f Ar filter 5699.Xc 5700.D1 (alias: Ic lsb ) 5701List the global buffers. 5702.Fl F 5703specifies the format of each line and 5704.Fl f 5705a filter. 5706Only buffers for which the filter is true are shown. 5707See the 5708.Sx FORMATS 5709section. 5710.It Xo Ic load-buffer 5711.Op Fl w 5712.Op Fl b Ar buffer-name 5713.Op Fl t Ar target-client 5714.Ar path 5715.Xc 5716.D1 (alias: Ic loadb ) 5717Load the contents of the specified paste buffer from 5718.Ar path . 5719If 5720.Fl w 5721is given, the buffer is also sent to the clipboard for 5722.Ar target-client 5723using the 5724.Xr xterm 1 5725escape sequence, if possible. 5726.It Xo Ic paste-buffer 5727.Op Fl dpr 5728.Op Fl b Ar buffer-name 5729.Op Fl s Ar separator 5730.Op Fl t Ar target-pane 5731.Xc 5732.D1 (alias: Ic pasteb ) 5733Insert the contents of a paste buffer into the specified pane. 5734If not specified, paste into the current one. 5735With 5736.Fl d , 5737also delete the paste buffer. 5738When output, any linefeed (LF) characters in the paste buffer are replaced with 5739a separator, by default carriage return (CR). 5740A custom separator may be specified using the 5741.Fl s 5742flag. 5743The 5744.Fl r 5745flag means to do no replacement (equivalent to a separator of LF). 5746If 5747.Fl p 5748is specified, paste bracket control codes are inserted around the 5749buffer if the application has requested bracketed paste mode. 5750.It Xo Ic save-buffer 5751.Op Fl a 5752.Op Fl b Ar buffer-name 5753.Ar path 5754.Xc 5755.D1 (alias: Ic saveb ) 5756Save the contents of the specified paste buffer to 5757.Ar path . 5758The 5759.Fl a 5760option appends to rather than overwriting the file. 5761.It Xo Ic set-buffer 5762.Op Fl aw 5763.Op Fl b Ar buffer-name 5764.Op Fl t Ar target-client 5765.Op Fl n Ar new-buffer-name 5766.Ar data 5767.Xc 5768.D1 (alias: Ic setb ) 5769Set the contents of the specified buffer to 5770.Ar data . 5771If 5772.Fl w 5773is given, the buffer is also sent to the clipboard for 5774.Ar target-client 5775using the 5776.Xr xterm 1 5777escape sequence, if possible. 5778The 5779.Fl a 5780option appends to rather than overwriting the buffer. 5781The 5782.Fl n 5783option renames the buffer to 5784.Ar new-buffer-name . 5785.It Xo Ic show-buffer 5786.Op Fl b Ar buffer-name 5787.Xc 5788.D1 (alias: Ic showb ) 5789Display the contents of the specified buffer. 5790.El 5791.Sh MISCELLANEOUS 5792Miscellaneous commands are as follows: 5793.Bl -tag -width Ds 5794.It Ic clock-mode Op Fl t Ar target-pane 5795Display a large clock. 5796.It Xo Ic if-shell 5797.Op Fl bF 5798.Op Fl t Ar target-pane 5799.Ar shell-command command 5800.Op Ar command 5801.Xc 5802.D1 (alias: Ic if ) 5803Execute the first 5804.Ar command 5805if 5806.Ar shell-command 5807returns success or the second 5808.Ar command 5809otherwise. 5810Before being executed, 5811.Ar shell-command 5812is expanded using the rules specified in the 5813.Sx FORMATS 5814section, including those relevant to 5815.Ar target-pane . 5816With 5817.Fl b , 5818.Ar shell-command 5819is run in the background. 5820.Pp 5821If 5822.Fl F 5823is given, 5824.Ar shell-command 5825is not executed but considered success if neither empty nor zero (after formats 5826are expanded). 5827.It Ic lock-server 5828.D1 (alias: Ic lock ) 5829Lock each client individually by running the command specified by the 5830.Ic lock-command 5831option. 5832.It Xo Ic run-shell 5833.Op Fl bC 5834.Op Fl d Ar delay 5835.Op Fl t Ar target-pane 5836.Op Ar shell-command 5837.Xc 5838.D1 (alias: Ic run ) 5839Execute 5840.Ar shell-command 5841or (with 5842.Fl C ) 5843a 5844.Nm 5845command in the background without creating a window. 5846Before being executed, 5847.Ar shell-command 5848is expanded using the rules specified in the 5849.Sx FORMATS 5850section. 5851With 5852.Fl b , 5853the command is run in the background. 5854.Fl d 5855waits for 5856.Ar delay 5857seconds before starting the command. 5858If 5859.Fl C 5860is not given, any output to stdout is displayed in view mode (in the pane 5861specified by 5862.Fl t 5863or the current pane if omitted) after the command finishes. 5864If the command fails, the exit status is also displayed. 5865.It Xo Ic wait-for 5866.Op Fl L | S | U 5867.Ar channel 5868.Xc 5869.D1 (alias: Ic wait ) 5870When used without options, prevents the client from exiting until woken using 5871.Ic wait-for 5872.Fl S 5873with the same channel. 5874When 5875.Fl L 5876is used, the channel is locked and any clients that try to lock the same 5877channel are made to wait until the channel is unlocked with 5878.Ic wait-for 5879.Fl U . 5880.El 5881.Sh EXIT MESSAGES 5882When a 5883.Nm 5884client detaches, it prints a message. 5885This may be one of: 5886.Bl -tag -width Ds 5887.It detached (from session ...) 5888The client was detached normally. 5889.It detached and SIGHUP 5890The client was detached and its parent sent the 5891.Dv SIGHUP 5892signal (for example with 5893.Ic detach-client 5894.Fl P ) . 5895.It lost tty 5896The client's 5897.Xr tty 4 5898or 5899.Xr pty 4 5900was unexpectedly destroyed. 5901.It terminated 5902The client was killed with 5903.Dv SIGTERM . 5904.It too far behind 5905The client is in control mode and became unable to keep up with the data from 5906.Nm . 5907.It exited 5908The server exited when it had no sessions. 5909.It server exited 5910The server exited when it received 5911.Dv SIGTERM . 5912.It server exited unexpectedly 5913The server crashed or otherwise exited without telling the client the reason. 5914.El 5915.Sh TERMINFO EXTENSIONS 5916.Nm 5917understands some unofficial extensions to 5918.Xr terminfo 5 . 5919It is not normally necessary to set these manually, instead the 5920.Ic terminal-features 5921option should be used. 5922.Bl -tag -width Ds 5923.It Em \&AX 5924An existing extension that tells 5925.Nm 5926the terminal supports default colours. 5927.It Em \&Cs , Cr 5928Set the cursor colour. 5929The first takes a single string argument and is used to set the colour; 5930the second takes no arguments and restores the default cursor colour. 5931If set, a sequence such as this may be used 5932to change the cursor colour from inside 5933.Nm : 5934.Bd -literal -offset indent 5935$ printf '\e033]12;red\e033\e\e' 5936.Ed 5937.It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg 5938Set, clear, disable or enable DECSLRM margins. 5939These are set automatically if the terminal reports it is 5940.Em VT420 5941compatible. 5942.It Em \&Dsbp , \&Enbp 5943Disable and enable bracketed paste. 5944These are set automatically if the 5945.Em XT 5946capability is present. 5947.It Em \&Dseks , \&Eneks 5948Disable and enable extended keys. 5949.It Em \&Dsfcs , \&Enfcs 5950Disable and enable focus reporting. 5951These are set automatically if the 5952.Em XT 5953capability is present. 5954.It Em \&Smol 5955Enable the overline attribute. 5956.It Em \&Smulx 5957Set a styled underscore. 5958The single parameter is one of: 0 for no underscore, 1 for normal 5959underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted 5960underscore and 5 for dashed underscore. 5961.It Em \&Setulc , \&ol 5962Set the underscore colour or reset to the default. 5963The argument is (red * 65536) + (green * 256) + blue where each is between 0 5964and 255. 5965.It Em \&Ss , Se 5966Set or reset the cursor style. 5967If set, a sequence such as this may be used 5968to change the cursor to an underline: 5969.Bd -literal -offset indent 5970$ printf '\e033[4 q' 5971.Ed 5972.Pp 5973If 5974.Em Se 5975is not set, \&Ss with argument 0 will be used to reset the cursor style instead. 5976.It Em \&Sync 5977Start (parameter is 1) or end (parameter is 2) a synchronized update. 5978.It Em \&Tc 5979Indicate that the terminal supports the 5980.Ql direct colour 5981RGB escape sequence (for example, \ee[38;2;255;255;255m). 5982.Pp 5983If supported, this is used for the initialize colour escape sequence (which 5984may be enabled by adding the 5985.Ql initc 5986and 5987.Ql ccc 5988capabilities to the 5989.Nm 5990.Xr terminfo 5 5991entry). 5992.Pp 5993This is equivalent to the 5994.Em RGB 5995.Xr terminfo 5 5996capability. 5997.It Em \&Ms 5998Store the current buffer in the host terminal's selection (clipboard). 5999See the 6000.Em set-clipboard 6001option above and the 6002.Xr xterm 1 6003man page. 6004.It Em \&XT 6005This is an existing extension capability that tmux uses to mean that the 6006terminal supports the 6007.Xr xterm 1 6008title set sequences and to automatically set some of the capabilities above. 6009.El 6010.Sh CONTROL MODE 6011.Nm 6012offers a textual interface called 6013.Em control mode . 6014This allows applications to communicate with 6015.Nm 6016using a simple text-only protocol. 6017.Pp 6018In control mode, a client sends 6019.Nm 6020commands or command sequences terminated by newlines on standard input. 6021Each command will produce one block of output on standard output. 6022An output block consists of a 6023.Em %begin 6024line followed by the output (which may be empty). 6025The output block ends with a 6026.Em %end 6027or 6028.Em %error . 6029.Em %begin 6030and matching 6031.Em %end 6032or 6033.Em %error 6034have two arguments: an integer time (as seconds from epoch) and command number. 6035For example: 6036.Bd -literal -offset indent 6037%begin 1363006971 2 60380: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) 6039%end 1363006971 2 6040.Ed 6041.Pp 6042The 6043.Ic refresh-client 6044.Fl C 6045command may be used to set the size of a client in control mode. 6046.Pp 6047In control mode, 6048.Nm 6049outputs notifications. 6050A notification will never occur inside an output block. 6051.Pp 6052The following notifications are defined: 6053.Bl -tag -width Ds 6054.It Ic %client-session-changed Ar client session-id name 6055The client is now attached to the session with ID 6056.Ar session-id , 6057which is named 6058.Ar name . 6059.It Ic %continue Ar pane-id 6060The pane has been continued after being paused (if the 6061.Ar pause-after 6062flag is set, see 6063.Ic refresh-client 6064.Fl A ) . 6065.It Ic %exit Op Ar reason 6066The 6067.Nm 6068client is exiting immediately, either because it is not attached to any session 6069or an error occurred. 6070If present, 6071.Ar reason 6072describes why the client exited. 6073.It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value 6074New form of 6075.Ic %output 6076sent when the 6077.Ar pause-after 6078flag is set. 6079.Ar age 6080is the time in milliseconds for which tmux had buffered the output before it was sent. 6081Any subsequent arguments up until a single 6082.Ql \&: 6083are for future use and should be ignored. 6084.It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags 6085The layout of a window with ID 6086.Ar window-id 6087changed. 6088The new layout is 6089.Ar window-layout . 6090The window's visible layout is 6091.Ar window-visible-layout 6092and the window flags are 6093.Ar window-flags . 6094.It Ic %output Ar pane-id Ar value 6095A window pane produced output. 6096.Ar value 6097escapes non-printable characters and backslash as octal \\xxx. 6098.It Ic %pane-mode-changed Ar pane-id 6099The pane with ID 6100.Ar pane-id 6101has changed mode. 6102.It Ic %pause Ar pane-id 6103The pane has been paused (if the 6104.Ar pause-after 6105flag is set). 6106.It Ic %session-changed Ar session-id Ar name 6107The client is now attached to the session with ID 6108.Ar session-id , 6109which is named 6110.Ar name . 6111.It Ic %session-renamed Ar name 6112The current session was renamed to 6113.Ar name . 6114.It Ic %session-window-changed Ar session-id Ar window-id 6115The session with ID 6116.Ar session-id 6117changed its active window to the window with ID 6118.Ar window-id . 6119.It Ic %sessions-changed 6120A session was created or destroyed. 6121.It Xo Ic %subscription-changed 6122.Ar name 6123.Ar session-id 6124.Ar window-id 6125.Ar window-index 6126.Ar pane-id ... \& : 6127.Ar value 6128.Xc 6129The value of the format associated with subscription 6130.Ar name 6131has changed to 6132.Ar value . 6133See 6134.Ic refresh-client 6135.Fl B . 6136Any arguments after 6137.Ar pane-id 6138up until a single 6139.Ql \&: 6140are for future use and should be ignored. 6141.It Ic %unlinked-window-add Ar window-id 6142The window with ID 6143.Ar window-id 6144was created but is not linked to the current session. 6145.It Ic %window-add Ar window-id 6146The window with ID 6147.Ar window-id 6148was linked to the current session. 6149.It Ic %window-close Ar window-id 6150The window with ID 6151.Ar window-id 6152closed. 6153.It Ic %window-pane-changed Ar window-id Ar pane-id 6154The active pane in the window with ID 6155.Ar window-id 6156changed to the pane with ID 6157.Ar pane-id . 6158.It Ic %window-renamed Ar window-id Ar name 6159The window with ID 6160.Ar window-id 6161was renamed to 6162.Ar name . 6163.El 6164.Sh ENVIRONMENT 6165When 6166.Nm 6167is started, it inspects the following environment variables: 6168.Bl -tag -width LC_CTYPE 6169.It Ev EDITOR 6170If the command specified in this variable contains the string 6171.Ql vi 6172and 6173.Ev VISUAL 6174is unset, use vi-style key bindings. 6175Overridden by the 6176.Ic mode-keys 6177and 6178.Ic status-keys 6179options. 6180.It Ev HOME 6181The user's login directory. 6182If unset, the 6183.Xr passwd 5 6184database is consulted. 6185.It Ev LC_CTYPE 6186The character encoding 6187.Xr locale 1 . 6188It is used for two separate purposes. 6189For output to the terminal, UTF-8 is used if the 6190.Fl u 6191option is given or if 6192.Ev LC_CTYPE 6193contains 6194.Qq UTF-8 6195or 6196.Qq UTF8 . 6197Otherwise, only ASCII characters are written and non-ASCII characters 6198are replaced with underscores 6199.Pq Ql _ . 6200For input, 6201.Nm 6202always runs with a UTF-8 locale. 6203If en_US.UTF-8 is provided by the operating system it is used and 6204.Ev LC_CTYPE 6205is ignored for input. 6206Otherwise, 6207.Ev LC_CTYPE 6208tells 6209.Nm 6210what the UTF-8 locale is called on the current system. 6211If the locale specified by 6212.Ev LC_CTYPE 6213is not available or is not a UTF-8 locale, 6214.Nm 6215exits with an error message. 6216.It Ev LC_TIME 6217The date and time format 6218.Xr locale 1 . 6219It is used for locale-dependent 6220.Xr strftime 3 6221format specifiers. 6222.It Ev PWD 6223The current working directory to be set in the global environment. 6224This may be useful if it contains symbolic links. 6225If the value of the variable does not match the current working 6226directory, the variable is ignored and the result of 6227.Xr getcwd 3 6228is used instead. 6229.It Ev SHELL 6230The absolute path to the default shell for new windows. 6231See the 6232.Ic default-shell 6233option for details. 6234.It Ev TMUX_TMPDIR 6235The parent directory of the directory containing the server sockets. 6236See the 6237.Fl L 6238option for details. 6239.It Ev VISUAL 6240If the command specified in this variable contains the string 6241.Ql vi , 6242use vi-style key bindings. 6243Overridden by the 6244.Ic mode-keys 6245and 6246.Ic status-keys 6247options. 6248.El 6249.Sh FILES 6250.Bl -tag -width "/etc/tmux.confXXX" -compact 6251.It Pa ~/.tmux.conf 6252Default 6253.Nm 6254configuration file. 6255.It Pa /etc/tmux.conf 6256System-wide configuration file. 6257.El 6258.Sh EXAMPLES 6259To create a new 6260.Nm 6261session running 6262.Xr vi 1 : 6263.Pp 6264.Dl $ tmux new-session vi 6265.Pp 6266Most commands have a shorter form, known as an alias. 6267For new-session, this is 6268.Ic new : 6269.Pp 6270.Dl $ tmux new vi 6271.Pp 6272Alternatively, the shortest unambiguous form of a command is accepted. 6273If there are several options, they are listed: 6274.Bd -literal -offset indent 6275$ tmux n 6276ambiguous command: n, could be: new-session, new-window, next-window 6277.Ed 6278.Pp 6279Within an active session, a new window may be created by typing 6280.Ql C-b c 6281(Ctrl 6282followed by the 6283.Ql b 6284key 6285followed by the 6286.Ql c 6287key). 6288.Pp 6289Windows may be navigated with: 6290.Ql C-b 0 6291(to select window 0), 6292.Ql C-b 1 6293(to select window 1), and so on; 6294.Ql C-b n 6295to select the next window; and 6296.Ql C-b p 6297to select the previous window. 6298.Pp 6299A session may be detached using 6300.Ql C-b d 6301(or by an external event such as 6302.Xr ssh 1 6303disconnection) and reattached with: 6304.Pp 6305.Dl $ tmux attach-session 6306.Pp 6307Typing 6308.Ql C-b \&? 6309lists the current key bindings in the current window; up and down may be used 6310to navigate the list or 6311.Ql q 6312to exit from it. 6313.Pp 6314Commands to be run when the 6315.Nm 6316server is started may be placed in the 6317.Pa ~/.tmux.conf 6318configuration file. 6319Common examples include: 6320.Pp 6321Changing the default prefix key: 6322.Bd -literal -offset indent 6323set-option -g prefix C-a 6324unbind-key C-b 6325bind-key C-a send-prefix 6326.Ed 6327.Pp 6328Turning the status line off, or changing its colour: 6329.Bd -literal -offset indent 6330set-option -g status off 6331set-option -g status-style bg=blue 6332.Ed 6333.Pp 6334Setting other options, such as the default command, 6335or locking after 30 minutes of inactivity: 6336.Bd -literal -offset indent 6337set-option -g default-command "exec /bin/ksh" 6338set-option -g lock-after-time 1800 6339.Ed 6340.Pp 6341Creating new key bindings: 6342.Bd -literal -offset indent 6343bind-key b set-option status 6344bind-key / command-prompt "split-window 'exec man %%'" 6345bind-key S command-prompt "new-window -n %1 'ssh %1'" 6346.Ed 6347.Sh SEE ALSO 6348.Xr pty 4 6349.Sh AUTHORS 6350.An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com 6351