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