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