1.\" $OpenBSD: tmux.1,v 1.920 2023/05/19 07:46:34 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: May 19 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 -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent 1746.It Sy "Command" Ta Sy "vi" Ta Sy "emacs" 1747.It Li "append-selection" Ta "" Ta "" 1748.It Li "append-selection-and-cancel" Ta "A" Ta "" 1749.It Li "back-to-indentation" Ta "^" Ta "M-m" 1750.It Li "begin-selection" Ta "Space" Ta "C-Space" 1751.It Li "bottom-line" Ta "L" Ta "" 1752.It Li "cancel" Ta "q" Ta "Escape" 1753.It Li "clear-selection" Ta "Escape" Ta "C-g" 1754.It Li "copy-end-of-line [<prefix>]" Ta "" Ta "" 1755.It Li "copy-end-of-line-and-cancel [<prefix>]" Ta "" Ta "" 1756.It Li "copy-pipe-end-of-line [<command>] [<prefix>]" Ta "" Ta "" 1757.It Li "copy-pipe-end-of-line-and-cancel [<command>] [<prefix>]" Ta "D" Ta "C-k" 1758.It Li "copy-line [<prefix>]" Ta "" Ta "" 1759.It Li "copy-line-and-cancel [<prefix>]" Ta "" Ta "" 1760.It Li "copy-pipe-line [<command>] [<prefix>]" Ta "" Ta "" 1761.It Li "copy-pipe-line-and-cancel [<command>] [<prefix>]" Ta "" Ta "" 1762.It Li "copy-pipe [<command>] [<prefix>]" Ta "" Ta "" 1763.It Li "copy-pipe-no-clear [<command>] [<prefix>]" Ta "" Ta "" 1764.It Li "copy-pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta "" 1765.It Li "copy-selection [<prefix>]" Ta "" Ta "" 1766.It Li "copy-selection-no-clear [<prefix>]" Ta "" Ta "" 1767.It Li "copy-selection-and-cancel [<prefix>]" Ta "Enter" Ta "M-w" 1768.It Li "cursor-down" Ta "j" Ta "Down" 1769.It Li "cursor-down-and-cancel" Ta "" Ta "" 1770.It Li "cursor-left" Ta "h" Ta "Left" 1771.It Li "cursor-right" Ta "l" Ta "Right" 1772.It Li "cursor-up" Ta "k" Ta "Up" 1773.It Li "end-of-line" Ta "$" Ta "C-e" 1774.It Li "goto-line <line>" Ta ":" Ta "g" 1775.It Li "halfpage-down" Ta "C-d" Ta "M-Down" 1776.It Li "halfpage-down-and-cancel" Ta "" Ta "" 1777.It Li "halfpage-up" Ta "C-u" Ta "M-Up" 1778.It Li "history-bottom" Ta "G" Ta "M->" 1779.It Li "history-top" Ta "g" Ta "M-<" 1780.It Li "jump-again" Ta ";" Ta ";" 1781.It Li "jump-backward <to>" Ta "F" Ta "F" 1782.It Li "jump-forward <to>" Ta "f" Ta "f" 1783.It Li "jump-reverse" Ta "," Ta "," 1784.It Li "jump-to-backward <to>" Ta "T" Ta "" 1785.It Li "jump-to-forward <to>" Ta "t" Ta "" 1786.It Li "jump-to-mark" Ta "M-x" Ta "M-x" 1787.It Li "middle-line" Ta "M" Ta "M-r" 1788.It Li "next-matching-bracket" Ta "%" Ta "M-C-f" 1789.It Li "next-paragraph" Ta "}" Ta "M-}" 1790.It Li "next-space" Ta "W" Ta "" 1791.It Li "next-space-end" Ta "E" Ta "" 1792.It Li "next-word" Ta "w" Ta "" 1793.It Li "next-word-end" Ta "e" Ta "M-f" 1794.It Li "other-end" Ta "o" Ta "" 1795.It Li "page-down" Ta "C-f" Ta "PageDown" 1796.It Li "page-down-and-cancel" Ta "" Ta "" 1797.It Li "page-up" Ta "C-b" Ta "PageUp" 1798.It Li "pipe [<command>] [<prefix>]" Ta "" Ta "" 1799.It Li "pipe-no-clear [<command>] [<prefix>]" Ta "" Ta "" 1800.It Li "pipe-and-cancel [<command>] [<prefix>]" Ta "" Ta "" 1801.It Li "previous-matching-bracket" Ta "" Ta "M-C-b" 1802.It Li "previous-paragraph" Ta "{" Ta "M-{" 1803.It Li "previous-space" Ta "B" Ta "" 1804.It Li "previous-word" Ta "b" Ta "M-b" 1805.It Li "rectangle-on" Ta "" Ta "" 1806.It Li "rectangle-off" Ta "" Ta "" 1807.It Li "rectangle-toggle" Ta "v" Ta "R" 1808.It Li "refresh-from-pane" Ta "r" Ta "r" 1809.It Li "scroll-down" Ta "C-e" Ta "C-Down" 1810.It Li "scroll-down-and-cancel" Ta "" Ta "" 1811.It Li "scroll-up" Ta "C-y" Ta "C-Up" 1812.It Li "search-again" Ta "n" Ta "n" 1813.It Li "search-backward <for>" Ta "?" Ta "" 1814.It Li "search-backward-incremental <for>" Ta "" Ta "C-r" 1815.It Li "search-backward-text <for>" Ta "" Ta "" 1816.It Li "search-forward <for>" Ta "/" Ta "" 1817.It Li "search-forward-incremental <for>" Ta "" Ta "C-s" 1818.It Li "search-forward-text <for>" Ta "" Ta "" 1819.It Li "scroll-bottom" Ta "" Ta "" 1820.It Li "scroll-middle" Ta "z" Ta "" 1821.It Li "scroll-top" Ta "" Ta "" 1822.It Li "search-reverse" Ta "N" Ta "N" 1823.It Li "select-line" Ta "V" Ta "" 1824.It Li "select-word" Ta "" Ta "" 1825.It Li "set-mark" Ta "X" Ta "X" 1826.It Li "start-of-line" Ta "0" Ta "C-a" 1827.It Li "stop-selection" Ta "" Ta "" 1828.It Li "toggle-position" Ta "P" Ta "P" 1829.It Li "top-line" Ta "H" Ta "M-R" 1830.El 1831.Pp 1832The search commands come in several varieties: 1833.Ql search-forward 1834and 1835.Ql search-backward 1836search for a regular expression; 1837the 1838.Ql -text 1839variants search for a plain text string rather than a regular expression; 1840.Ql -incremental 1841perform an incremental search and expect to be used with the 1842.Fl i 1843flag to the 1844.Ic command-prompt 1845command. 1846.Ql search-again 1847repeats the last search and 1848.Ql search-reverse 1849does the same but reverses the direction (forward becomes backward and backward 1850becomes forward). 1851.Pp 1852Copy commands may take an optional buffer prefix argument which is used 1853to generate the buffer name (the default is 1854.Ql buffer 1855so buffers are named 1856.Ql buffer0 , 1857.Ql buffer1 1858and so on). 1859Pipe commands take a command argument which is the command to which the 1860selected text is piped. 1861.Ql copy-pipe 1862variants also copy the selection. 1863The 1864.Ql -and-cancel 1865variants of some commands exit copy mode after they have completed (for copy 1866commands) or when the cursor reaches the bottom (for scrolling commands). 1867.Ql -no-clear 1868variants do not clear the selection. 1869.Pp 1870The next and previous word keys skip over whitespace and treat consecutive 1871runs of either word separators or other letters as words. 1872Word separators can be customized with the 1873.Em word-separators 1874session option. 1875Next word moves to the start of the next word, next word end to the end of the 1876next word and previous word to the start of the previous word. 1877The three next and previous space keys work similarly but use a space alone as 1878the word separator. 1879Setting 1880.Em word-separators 1881to the empty string makes next/previous word equivalent to next/previous space. 1882.Pp 1883The jump commands enable quick movement within a line. 1884For instance, typing 1885.Ql f 1886followed by 1887.Ql / 1888will move the cursor to the next 1889.Ql / 1890character on the current line. 1891A 1892.Ql \&; 1893will then jump to the next occurrence. 1894.Pp 1895Commands in copy mode may be prefaced by an optional repeat count. 1896With vi key bindings, a prefix is entered using the number keys; with 1897emacs, the Alt (meta) key and a number begins prefix entry. 1898.Pp 1899The synopsis for the 1900.Ic copy-mode 1901command is: 1902.Bl -tag -width Ds 1903.It Xo Ic copy-mode 1904.Op Fl eHMqu 1905.Op Fl s Ar src-pane 1906.Op Fl t Ar target-pane 1907.Xc 1908Enter copy mode. 1909The 1910.Fl u 1911option scrolls one page up. 1912.Fl M 1913begins a mouse drag (only valid if bound to a mouse key binding, see 1914.Sx MOUSE SUPPORT ) . 1915.Fl H 1916hides the position indicator in the top right. 1917.Fl q 1918cancels copy mode and any other modes. 1919.Fl s 1920copies from 1921.Ar src-pane 1922instead of 1923.Ar target-pane . 1924.Pp 1925.Fl e 1926specifies that scrolling to the bottom of the history (to the visible screen) 1927should exit copy mode. 1928While in copy mode, pressing a key other than those used for scrolling will 1929disable this behaviour. 1930This is intended to allow fast scrolling through a pane's history, for 1931example with: 1932.Bd -literal -offset indent 1933bind PageUp copy-mode -eu 1934.Ed 1935.El 1936.Pp 1937A number of preset arrangements of panes are available, these are called 1938layouts. 1939These may be selected with the 1940.Ic select-layout 1941command or cycled with 1942.Ic next-layout 1943(bound to 1944.Ql Space 1945by default); once a layout is chosen, panes within it may be moved and resized 1946as normal. 1947.Pp 1948The following layouts are supported: 1949.Bl -tag -width Ds 1950.It Ic even-horizontal 1951Panes are spread out evenly from left to right across the window. 1952.It Ic even-vertical 1953Panes are spread evenly from top to bottom. 1954.It Ic main-horizontal 1955A large (main) pane is shown at the top of the window and the remaining panes 1956are spread from left to right in the leftover space at the bottom. 1957Use the 1958.Em main-pane-height 1959window option to specify the height of the top pane. 1960.It Ic main-vertical 1961Similar to 1962.Ic main-horizontal 1963but the large pane is placed on the left and the others spread from top to 1964bottom along the right. 1965See the 1966.Em main-pane-width 1967window option. 1968.It Ic tiled 1969Panes are spread out as evenly as possible over the window in both rows and 1970columns. 1971.El 1972.Pp 1973In addition, 1974.Ic select-layout 1975may be used to apply a previously used layout - the 1976.Ic list-windows 1977command displays the layout of each window in a form suitable for use with 1978.Ic select-layout . 1979For example: 1980.Bd -literal -offset indent 1981$ tmux list-windows 19820: ksh [159x48] 1983 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} 1984$ tmux select-layout 'bb62,159x48,0,0{79x48,0,0,79x48,80,0}' 1985.Ed 1986.Pp 1987.Nm 1988automatically adjusts the size of the layout for the current window size. 1989Note that a layout cannot be applied to a window with more panes than that 1990from which the layout was originally defined. 1991.Pp 1992Commands related to windows and panes are as follows: 1993.Bl -tag -width Ds 1994.Tg breakp 1995.It Xo Ic break-pane 1996.Op Fl abdP 1997.Op Fl F Ar format 1998.Op Fl n Ar window-name 1999.Op Fl s Ar src-pane 2000.Op Fl t Ar dst-window 2001.Xc 2002.D1 Pq alias: Ic breakp 2003Break 2004.Ar src-pane 2005off from its containing window to make it the only pane in 2006.Ar dst-window . 2007With 2008.Fl a 2009or 2010.Fl b , 2011the window is moved to the next index after or before (existing windows are 2012moved if necessary). 2013If 2014.Fl d 2015is given, the new window does not become the current window. 2016The 2017.Fl P 2018option prints information about the new window after it has been created. 2019By default, it uses the format 2020.Ql #{session_name}:#{window_index}.#{pane_index} 2021but a different format may be specified with 2022.Fl F . 2023.Tg capturep 2024.It Xo Ic capture-pane 2025.Op Fl aAepPqCJN 2026.Op Fl b Ar buffer-name 2027.Op Fl E Ar end-line 2028.Op Fl S Ar start-line 2029.Op Fl t Ar target-pane 2030.Xc 2031.D1 Pq alias: Ic capturep 2032Capture the contents of a pane. 2033If 2034.Fl p 2035is given, the output goes to stdout, otherwise to the buffer specified with 2036.Fl b 2037or a new buffer if omitted. 2038If 2039.Fl a 2040is given, the alternate screen is used, and the history is not accessible. 2041If no alternate screen exists, an error will be returned unless 2042.Fl q 2043is given. 2044If 2045.Fl e 2046is given, the output includes escape sequences for text and background 2047attributes. 2048.Fl C 2049also escapes non-printable characters as octal \exxx. 2050.Fl T 2051ignores trailing positions that do not contain a character. 2052.Fl N 2053preserves trailing spaces at each line's end and 2054.Fl J 2055preserves trailing spaces and joins any wrapped lines; 2056.Fl J 2057implies 2058.Fl T . 2059.Fl P 2060captures only any output that the pane has received that is the beginning of an 2061as-yet incomplete escape sequence. 2062.Pp 2063.Fl S 2064and 2065.Fl E 2066specify the starting and ending line numbers, zero is the first line of the 2067visible pane and negative numbers are lines in the history. 2068.Ql - 2069to 2070.Fl S 2071is the start of the history and to 2072.Fl E 2073the end of the visible pane. 2074The default is to capture only the visible contents of the pane. 2075.It Xo 2076.Ic choose-client 2077.Op Fl NrZ 2078.Op Fl F Ar format 2079.Op Fl f Ar filter 2080.Op Fl K Ar key-format 2081.Op Fl O Ar sort-order 2082.Op Fl t Ar target-pane 2083.Op Ar template 2084.Xc 2085Put a pane into client mode, allowing a client to be selected interactively from 2086a list. 2087Each client is shown on one line. 2088A shortcut key is shown on the left in brackets allowing for immediate choice, 2089or the list may be navigated and an item chosen or otherwise manipulated using 2090the keys below. 2091.Fl Z 2092zooms the pane. 2093The following keys may be used in client mode: 2094.Bl -column "Key" "Function" -offset indent 2095.It Sy "Key" Ta Sy "Function" 2096.It Li "Enter" Ta "Choose selected client" 2097.It Li "Up" Ta "Select previous client" 2098.It Li "Down" Ta "Select next client" 2099.It Li "C-s" Ta "Search by name" 2100.It Li "n" Ta "Repeat last search" 2101.It Li "t" Ta "Toggle if client is tagged" 2102.It Li "T" Ta "Tag no clients" 2103.It Li "C-t" Ta "Tag all clients" 2104.It Li "d" Ta "Detach selected client" 2105.It Li "D" Ta "Detach tagged clients" 2106.It Li "x" Ta "Detach and HUP selected client" 2107.It Li "X" Ta "Detach and HUP tagged clients" 2108.It Li "z" Ta "Suspend selected client" 2109.It Li "Z" Ta "Suspend tagged clients" 2110.It Li "f" Ta "Enter a format to filter items" 2111.It Li "O" Ta "Change sort field" 2112.It Li "r" Ta "Reverse sort order" 2113.It Li "v" Ta "Toggle preview" 2114.It Li "q" Ta "Exit mode" 2115.El 2116.Pp 2117After a client is chosen, 2118.Ql %% 2119is replaced by the client name in 2120.Ar template 2121and the result executed as a command. 2122If 2123.Ar template 2124is not given, "detach-client -t '%%'" is used. 2125.Pp 2126.Fl O 2127specifies the initial sort field: one of 2128.Ql name , 2129.Ql size , 2130.Ql creation 2131(time), 2132or 2133.Ql activity 2134(time). 2135.Fl r 2136reverses the sort order. 2137.Fl f 2138specifies an initial filter: the filter is a format - if it evaluates to zero, 2139the item in the list is not shown, otherwise it is shown. 2140If a filter would lead to an empty list, it is ignored. 2141.Fl F 2142specifies the format for each item in the list and 2143.Fl K 2144a format for each shortcut key; both are evaluated once for each line. 2145.Fl N 2146starts without the preview. 2147This command works only if at least one client is attached. 2148.It Xo 2149.Ic choose-tree 2150.Op Fl GNrswZ 2151.Op Fl F Ar format 2152.Op Fl f Ar filter 2153.Op Fl K Ar key-format 2154.Op Fl O Ar sort-order 2155.Op Fl t Ar target-pane 2156.Op Ar template 2157.Xc 2158Put a pane into tree mode, where a session, window or pane may be chosen 2159interactively from a tree. 2160Each session, window or pane is shown on one line. 2161A shortcut key is shown on the left in brackets allowing for immediate choice, 2162or the tree may be navigated and an item chosen or otherwise manipulated using 2163the keys below. 2164.Fl s 2165starts with sessions collapsed and 2166.Fl w 2167with windows collapsed. 2168.Fl Z 2169zooms the pane. 2170The following keys may be used in tree mode: 2171.Bl -column "Key" "Function" -offset indent 2172.It Sy "Key" Ta Sy "Function" 2173.It Li "Enter" Ta "Choose selected item" 2174.It Li "Up" Ta "Select previous item" 2175.It Li "Down" Ta "Select next item" 2176.It Li "+" Ta "Expand selected item" 2177.It Li "-" Ta "Collapse selected item" 2178.It Li "M-+" Ta "Expand all items" 2179.It Li "M--" Ta "Collapse all items" 2180.It Li "x" Ta "Kill selected item" 2181.It Li "X" Ta "Kill tagged items" 2182.It Li "<" Ta "Scroll list of previews left" 2183.It Li ">" Ta "Scroll list of previews right" 2184.It Li "C-s" Ta "Search by name" 2185.It Li "m" Ta "Set the marked pane" 2186.It Li "M" Ta "Clear the marked pane" 2187.It Li "n" Ta "Repeat last search" 2188.It Li "t" Ta "Toggle if item is tagged" 2189.It Li "T" Ta "Tag no items" 2190.It Li "C-t" Ta "Tag all items" 2191.It Li "\&:" Ta "Run a command for each tagged item" 2192.It Li "f" Ta "Enter a format to filter items" 2193.It Li "H" Ta "Jump to the starting pane" 2194.It Li "O" Ta "Change sort field" 2195.It Li "r" Ta "Reverse sort order" 2196.It Li "v" Ta "Toggle preview" 2197.It Li "q" Ta "Exit mode" 2198.El 2199.Pp 2200After a session, window or pane is chosen, the first instance of 2201.Ql %% 2202and all instances of 2203.Ql %1 2204are replaced by the target in 2205.Ar template 2206and the result executed as a command. 2207If 2208.Ar template 2209is not given, "switch-client -t '%%'" is used. 2210.Pp 2211.Fl O 2212specifies the initial sort field: one of 2213.Ql index , 2214.Ql name , 2215or 2216.Ql time 2217(activity). 2218.Fl r 2219reverses the sort order. 2220.Fl f 2221specifies an initial filter: the filter is a format - if it evaluates to zero, 2222the item in the list is not shown, otherwise it is shown. 2223If a filter would lead to an empty list, it is ignored. 2224.Fl F 2225specifies the format for each item in the tree and 2226.Fl K 2227a format for each shortcut key; both are evaluated once for each line. 2228.Fl N 2229starts without the preview. 2230.Fl G 2231includes all sessions in any session groups in the tree rather than only the 2232first. 2233This command works only if at least one client is attached. 2234.It Xo 2235.Ic customize-mode 2236.Op Fl NZ 2237.Op Fl F Ar format 2238.Op Fl f Ar filter 2239.Op Fl t Ar target-pane 2240.Op Ar template 2241.Xc 2242Put a pane into customize mode, where options and key bindings may be browsed 2243and modified from a list. 2244Option values in the list are shown for the active pane in the current window. 2245.Fl Z 2246zooms the pane. 2247The following keys may be used in customize mode: 2248.Bl -column "Key" "Function" -offset indent 2249.It Sy "Key" Ta Sy "Function" 2250.It Li "Enter" Ta "Set pane, window, session or global option value" 2251.It Li "Up" Ta "Select previous item" 2252.It Li "Down" Ta "Select next item" 2253.It Li "+" Ta "Expand selected item" 2254.It Li "-" Ta "Collapse selected item" 2255.It Li "M-+" Ta "Expand all items" 2256.It Li "M--" Ta "Collapse all items" 2257.It Li "s" Ta "Set option value or key attribute" 2258.It Li "S" Ta "Set global option value" 2259.It Li "w" Ta "Set window option value, if option is for pane and window" 2260.It Li "d" Ta "Set an option or key to the default" 2261.It Li "D" Ta "Set tagged options and tagged keys to the default" 2262.It Li "u" Ta "Unset an option (set to default value if global) or unbind a key" 2263.It Li "U" Ta "Unset tagged options and unbind tagged keys" 2264.It Li "C-s" Ta "Search by name" 2265.It Li "n" Ta "Repeat last search" 2266.It Li "t" Ta "Toggle if item is tagged" 2267.It Li "T" Ta "Tag no items" 2268.It Li "C-t" Ta "Tag all items" 2269.It Li "f" Ta "Enter a format to filter items" 2270.It Li "v" Ta "Toggle option information" 2271.It Li "q" Ta "Exit mode" 2272.El 2273.Pp 2274.Fl f 2275specifies an initial filter: the filter is a format - if it evaluates to zero, 2276the item in the list is not shown, otherwise it is shown. 2277If a filter would lead to an empty list, it is ignored. 2278.Fl F 2279specifies the format for each item in the tree. 2280.Fl N 2281starts without the option information. 2282This command works only if at least one client is attached. 2283.It Xo 2284.Tg displayp 2285.Ic display-panes 2286.Op Fl bN 2287.Op Fl d Ar duration 2288.Op Fl t Ar target-client 2289.Op Ar template 2290.Xc 2291.D1 Pq alias: Ic displayp 2292Display a visible indicator of each pane shown by 2293.Ar target-client . 2294See the 2295.Ic display-panes-colour 2296and 2297.Ic display-panes-active-colour 2298session options. 2299The indicator is closed when a key is pressed (unless 2300.Fl N 2301is given) or 2302.Ar duration 2303milliseconds have passed. 2304If 2305.Fl d 2306is not given, 2307.Ic display-panes-time 2308is used. 2309A duration of zero means the indicator stays until a key is pressed. 2310While the indicator is on screen, a pane may be chosen with the 2311.Ql 0 2312to 2313.Ql 9 2314keys, which will cause 2315.Ar template 2316to be executed as a command with 2317.Ql %% 2318substituted by the pane ID. 2319The default 2320.Ar template 2321is "select-pane -t '%%'". 2322With 2323.Fl b , 2324other commands are not blocked from running until the indicator is closed. 2325.Tg findw 2326.It Xo Ic find-window 2327.Op Fl iCNrTZ 2328.Op Fl t Ar target-pane 2329.Ar match-string 2330.Xc 2331.D1 Pq alias: Ic findw 2332Search for a 2333.Xr fnmatch 3 2334pattern or, with 2335.Fl r , 2336regular expression 2337.Ar match-string 2338in window names, titles, and visible content (but not history). 2339The flags control matching behavior: 2340.Fl C 2341matches only visible window contents, 2342.Fl N 2343matches only the window name and 2344.Fl T 2345matches only the window title. 2346.Fl i 2347makes the search ignore case. 2348The default is 2349.Fl CNT . 2350.Fl Z 2351zooms the pane. 2352.Pp 2353This command works only if at least one client is attached. 2354.Tg joinp 2355.It Xo Ic join-pane 2356.Op Fl bdfhv 2357.Op Fl l Ar size 2358.Op Fl s Ar src-pane 2359.Op Fl t Ar dst-pane 2360.Xc 2361.D1 Pq alias: Ic joinp 2362Like 2363.Ic split-window , 2364but instead of splitting 2365.Ar dst-pane 2366and creating a new pane, split it and move 2367.Ar src-pane 2368into the space. 2369This can be used to reverse 2370.Ic break-pane . 2371The 2372.Fl b 2373option causes 2374.Ar src-pane 2375to be joined to left of or above 2376.Ar dst-pane . 2377.Pp 2378If 2379.Fl s 2380is omitted and a marked pane is present (see 2381.Ic select-pane 2382.Fl m ) , 2383the marked pane is used rather than the current pane. 2384.Tg killp 2385.It Xo Ic kill-pane 2386.Op Fl a 2387.Op Fl t Ar target-pane 2388.Xc 2389.D1 Pq alias: Ic killp 2390Destroy the given pane. 2391If no panes remain in the containing window, it is also destroyed. 2392The 2393.Fl a 2394option kills all but the pane given with 2395.Fl t . 2396.Tg killw 2397.It Xo Ic kill-window 2398.Op Fl a 2399.Op Fl t Ar target-window 2400.Xc 2401.D1 Pq alias: Ic killw 2402Kill the current window or the window at 2403.Ar target-window , 2404removing it from any sessions to which it is linked. 2405The 2406.Fl a 2407option kills all but the window given with 2408.Fl t . 2409.Tg lastp 2410.It Xo Ic last-pane 2411.Op Fl deZ 2412.Op Fl t Ar target-window 2413.Xc 2414.D1 Pq alias: Ic lastp 2415Select the last (previously selected) pane. 2416.Fl Z 2417keeps the window zoomed if it was zoomed. 2418.Fl e 2419enables or 2420.Fl d 2421disables input to the pane. 2422.Tg last 2423.It Ic last-window Op Fl t Ar target-session 2424.D1 Pq alias: Ic last 2425Select the last (previously selected) window. 2426If no 2427.Ar target-session 2428is specified, select the last window of the current session. 2429.Tg link 2430.It Xo Ic link-window 2431.Op Fl abdk 2432.Op Fl s Ar src-window 2433.Op Fl t Ar dst-window 2434.Xc 2435.D1 Pq alias: Ic linkw 2436Link the window at 2437.Ar src-window 2438to the specified 2439.Ar dst-window . 2440If 2441.Ar dst-window 2442is specified and no such window exists, the 2443.Ar src-window 2444is linked there. 2445With 2446.Fl a 2447or 2448.Fl b 2449the window is moved to the next index after or before 2450.Ar dst-window 2451(existing windows are moved if necessary). 2452If 2453.Fl k 2454is given and 2455.Ar dst-window 2456exists, it is killed, otherwise an error is generated. 2457If 2458.Fl d 2459is given, the newly linked window is not selected. 2460.Tg lsp 2461.It Xo Ic list-panes 2462.Op Fl as 2463.Op Fl F Ar format 2464.Op Fl f Ar filter 2465.Op Fl t Ar target 2466.Xc 2467.D1 Pq alias: Ic lsp 2468If 2469.Fl a 2470is given, 2471.Ar target 2472is ignored and all panes on the server are listed. 2473If 2474.Fl s 2475is given, 2476.Ar target 2477is a session (or the current session). 2478If neither is given, 2479.Ar target 2480is a window (or the current window). 2481.Fl F 2482specifies the format of each line and 2483.Fl f 2484a filter. 2485Only panes for which the filter is true are shown. 2486See the 2487.Sx FORMATS 2488section. 2489.Tg lsw 2490.It Xo Ic list-windows 2491.Op Fl a 2492.Op Fl F Ar format 2493.Op Fl f Ar filter 2494.Op Fl t Ar target-session 2495.Xc 2496.D1 Pq alias: Ic lsw 2497If 2498.Fl a 2499is given, list all windows on the server. 2500Otherwise, list windows in the current session or in 2501.Ar target-session . 2502.Fl F 2503specifies the format of each line and 2504.Fl f 2505a filter. 2506Only windows for which the filter is true are shown. 2507See the 2508.Sx FORMATS 2509section. 2510.Tg movep 2511.It Xo Ic move-pane 2512.Op Fl bdfhv 2513.Op Fl l Ar size 2514.Op Fl s Ar src-pane 2515.Op Fl t Ar dst-pane 2516.Xc 2517.D1 Pq alias: Ic movep 2518Does the same as 2519.Ic join-pane . 2520.Tg movew 2521.It Xo Ic move-window 2522.Op Fl abrdk 2523.Op Fl s Ar src-window 2524.Op Fl t Ar dst-window 2525.Xc 2526.D1 Pq alias: Ic movew 2527This is similar to 2528.Ic link-window , 2529except the window at 2530.Ar src-window 2531is moved to 2532.Ar dst-window . 2533With 2534.Fl r , 2535all windows in the session are renumbered in sequential order, respecting 2536the 2537.Ic base-index 2538option. 2539.Tg neww 2540.It Xo Ic new-window 2541.Op Fl abdkPS 2542.Op Fl c Ar start-directory 2543.Op Fl e Ar environment 2544.Op Fl F Ar format 2545.Op Fl n Ar window-name 2546.Op Fl t Ar target-window 2547.Op Ar shell-command 2548.Xc 2549.D1 Pq alias: Ic neww 2550Create a new window. 2551With 2552.Fl a 2553or 2554.Fl b , 2555the new window is inserted at the next index after or before the specified 2556.Ar target-window , 2557moving windows up if necessary; 2558otherwise 2559.Ar target-window 2560is the new window location. 2561.Pp 2562If 2563.Fl d 2564is given, the session does not make the new window the current window. 2565.Ar target-window 2566represents the window to be created; if the target already exists an error is 2567shown, unless the 2568.Fl k 2569flag is used, in which case it is destroyed. 2570If 2571.Fl S 2572is given and a window named 2573.Ar window-name 2574already exists, it is selected (unless 2575.Fl d 2576is also given in which case the command does nothing). 2577.Pp 2578.Ar shell-command 2579is the command to execute. 2580If 2581.Ar shell-command 2582is not specified, the value of the 2583.Ic default-command 2584option is used. 2585.Fl c 2586specifies the working directory in which the new window is created. 2587.Pp 2588When the shell command completes, the window closes. 2589See the 2590.Ic remain-on-exit 2591option to change this behaviour. 2592.Pp 2593.Fl e 2594takes the form 2595.Ql VARIABLE=value 2596and sets an environment variable for the newly created window; it may be 2597specified multiple times. 2598.Pp 2599The 2600.Ev TERM 2601environment variable must be set to 2602.Ql screen 2603or 2604.Ql tmux 2605for all programs running 2606.Em inside 2607.Nm . 2608New windows will automatically have 2609.Ql TERM=screen 2610added to their environment, but care must be taken not to reset this in shell 2611start-up files or by the 2612.Fl e 2613option. 2614.Pp 2615The 2616.Fl P 2617option prints information about the new window after it has been created. 2618By default, it uses the format 2619.Ql #{session_name}:#{window_index} 2620but a different format may be specified with 2621.Fl F . 2622.Tg nextl 2623.It Ic next-layout Op Fl t Ar target-window 2624.D1 Pq alias: Ic nextl 2625Move a window to the next layout and rearrange the panes to fit. 2626.Tg next 2627.It Xo Ic next-window 2628.Op Fl a 2629.Op Fl t Ar target-session 2630.Xc 2631.D1 Pq alias: Ic next 2632Move to the next window in the session. 2633If 2634.Fl a 2635is used, move to the next window with an alert. 2636.Tg pipep 2637.It Xo Ic pipe-pane 2638.Op Fl IOo 2639.Op Fl t Ar target-pane 2640.Op Ar shell-command 2641.Xc 2642.D1 Pq alias: Ic pipep 2643Pipe output sent by the program in 2644.Ar target-pane 2645to a shell command or vice versa. 2646A pane may only be connected to one command at a time, any existing pipe is 2647closed before 2648.Ar shell-command 2649is executed. 2650The 2651.Ar shell-command 2652string may contain the special character sequences supported by the 2653.Ic status-left 2654option. 2655If no 2656.Ar shell-command 2657is given, the current pipe (if any) is closed. 2658.Pp 2659.Fl I 2660and 2661.Fl O 2662specify which of the 2663.Ar shell-command 2664output streams are connected to the pane: 2665with 2666.Fl I 2667stdout is connected (so anything 2668.Ar shell-command 2669prints is written to the pane as if it were typed); 2670with 2671.Fl O 2672stdin is connected (so any output in the pane is piped to 2673.Ar shell-command ) . 2674Both may be used together and if neither are specified, 2675.Fl O 2676is used. 2677.Pp 2678The 2679.Fl o 2680option only opens a new pipe if no previous pipe exists, allowing a pipe to 2681be toggled with a single key, for example: 2682.Bd -literal -offset indent 2683bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' 2684.Ed 2685.Tg prevl 2686.It Xo Ic previous-layout 2687.Op Fl t Ar target-window 2688.Xc 2689.D1 Pq alias: Ic prevl 2690Move to the previous layout in the session. 2691.Tg prev 2692.It Xo Ic previous-window 2693.Op Fl a 2694.Op Fl t Ar target-session 2695.Xc 2696.D1 Pq alias: Ic prev 2697Move to the previous window in the session. 2698With 2699.Fl a , 2700move to the previous window with an alert. 2701.Tg renamew 2702.It Xo Ic rename-window 2703.Op Fl t Ar target-window 2704.Ar new-name 2705.Xc 2706.D1 Pq alias: Ic renamew 2707Rename the current window, or the window at 2708.Ar target-window 2709if specified, to 2710.Ar new-name . 2711.Tg resizep 2712.It Xo Ic resize-pane 2713.Op Fl DLMRTUZ 2714.Op Fl t Ar target-pane 2715.Op Fl x Ar width 2716.Op Fl y Ar height 2717.Op Ar adjustment 2718.Xc 2719.D1 Pq alias: Ic resizep 2720Resize a pane, up, down, left or right by 2721.Ar adjustment 2722with 2723.Fl U , 2724.Fl D , 2725.Fl L 2726or 2727.Fl R , 2728or 2729to an absolute size 2730with 2731.Fl x 2732or 2733.Fl y . 2734The 2735.Ar adjustment 2736is given in lines or columns (the default is 1); 2737.Fl x 2738and 2739.Fl y 2740may be a given as a number of lines or columns or followed by 2741.Ql % 2742for a percentage of the window size (for example 2743.Ql -x 10% ) . 2744With 2745.Fl Z , 2746the active pane is toggled between zoomed (occupying the whole of the window) 2747and unzoomed (its normal position in the layout). 2748.Pp 2749.Fl M 2750begins mouse resizing (only valid if bound to a mouse key binding, see 2751.Sx MOUSE SUPPORT ) . 2752.Pp 2753.Fl T 2754trims all lines below the current cursor position and moves lines out of the 2755history to replace them. 2756.Tg resizew 2757.It Xo Ic resize-window 2758.Op Fl aADLRU 2759.Op Fl t Ar target-window 2760.Op Fl x Ar width 2761.Op Fl y Ar height 2762.Op Ar adjustment 2763.Xc 2764.D1 Pq alias: Ic resizew 2765Resize a window, up, down, left or right by 2766.Ar adjustment 2767with 2768.Fl U , 2769.Fl D , 2770.Fl L 2771or 2772.Fl R , 2773or 2774to an absolute size 2775with 2776.Fl x 2777or 2778.Fl y . 2779The 2780.Ar adjustment 2781is given in lines or cells (the default is 1). 2782.Fl A 2783sets the size of the largest session containing the window; 2784.Fl a 2785the size of the smallest. 2786This command will automatically set 2787.Ic window-size 2788to manual in the window options. 2789.Tg respawnp 2790.It Xo Ic respawn-pane 2791.Op Fl k 2792.Op Fl c Ar start-directory 2793.Op Fl e Ar environment 2794.Op Fl t Ar target-pane 2795.Op Ar shell-command 2796.Xc 2797.D1 Pq alias: Ic respawnp 2798Reactivate a pane in which the command has exited (see the 2799.Ic remain-on-exit 2800window option). 2801If 2802.Ar shell-command 2803is not given, the command used when the pane was created or last respawned is 2804executed. 2805The pane must be already inactive, unless 2806.Fl k 2807is given, in which case any existing command is killed. 2808.Fl c 2809specifies a new working directory for the pane. 2810The 2811.Fl e 2812option has the same meaning as for the 2813.Ic new-window 2814command. 2815.Tg respawnw 2816.It Xo Ic respawn-window 2817.Op Fl k 2818.Op Fl c Ar start-directory 2819.Op Fl e Ar environment 2820.Op Fl t Ar target-window 2821.Op Ar shell-command 2822.Xc 2823.D1 Pq alias: Ic respawnw 2824Reactivate a window in which the command has exited (see the 2825.Ic remain-on-exit 2826window option). 2827If 2828.Ar shell-command 2829is not given, the command used when the window was created or last respawned is 2830executed. 2831The window must be already inactive, unless 2832.Fl k 2833is given, in which case any existing command is killed. 2834.Fl c 2835specifies a new working directory for the window. 2836The 2837.Fl e 2838option has the same meaning as for the 2839.Ic new-window 2840command. 2841.Tg rotatew 2842.It Xo Ic rotate-window 2843.Op Fl DUZ 2844.Op Fl t Ar target-window 2845.Xc 2846.D1 Pq alias: Ic rotatew 2847Rotate the positions of the panes within a window, either upward (numerically 2848lower) with 2849.Fl U 2850or downward (numerically higher). 2851.Fl Z 2852keeps the window zoomed if it was zoomed. 2853.Tg selectl 2854.It Xo Ic select-layout 2855.Op Fl Enop 2856.Op Fl t Ar target-pane 2857.Op Ar layout-name 2858.Xc 2859.D1 Pq alias: Ic selectl 2860Choose a specific layout for a window. 2861If 2862.Ar layout-name 2863is not given, the last preset layout used (if any) is reapplied. 2864.Fl n 2865and 2866.Fl p 2867are equivalent to the 2868.Ic next-layout 2869and 2870.Ic previous-layout 2871commands. 2872.Fl o 2873applies the last set layout if possible (undoes the most recent layout change). 2874.Fl E 2875spreads the current pane and any panes next to it out evenly. 2876.Tg selectp 2877.It Xo Ic select-pane 2878.Op Fl DdeLlMmRUZ 2879.Op Fl T Ar title 2880.Op Fl t Ar target-pane 2881.Xc 2882.D1 Pq alias: Ic selectp 2883Make pane 2884.Ar target-pane 2885the active pane in its window. 2886If one of 2887.Fl D , 2888.Fl L , 2889.Fl R , 2890or 2891.Fl U 2892is used, respectively the pane below, to the left, to the right, or above the 2893target pane is used. 2894.Fl Z 2895keeps the window zoomed if it was zoomed. 2896.Fl l 2897is the same as using the 2898.Ic last-pane 2899command. 2900.Fl e 2901enables or 2902.Fl d 2903disables input to the pane. 2904.Fl T 2905sets the pane title. 2906.Pp 2907.Fl m 2908and 2909.Fl M 2910are used to set and clear the 2911.Em marked pane . 2912There is one marked pane at a time, setting a new marked pane clears the last. 2913The marked pane is the default target for 2914.Fl s 2915to 2916.Ic join-pane , 2917.Ic move-pane , 2918.Ic swap-pane 2919and 2920.Ic swap-window . 2921.Tg selectw 2922.It Xo Ic select-window 2923.Op Fl lnpT 2924.Op Fl t Ar target-window 2925.Xc 2926.D1 Pq alias: Ic selectw 2927Select the window at 2928.Ar target-window . 2929.Fl l , 2930.Fl n 2931and 2932.Fl p 2933are equivalent to the 2934.Ic last-window , 2935.Ic next-window 2936and 2937.Ic previous-window 2938commands. 2939If 2940.Fl T 2941is given and the selected window is already the current window, 2942the command behaves like 2943.Ic last-window . 2944.Tg splitw 2945.It Xo Ic split-window 2946.Op Fl bdfhIvPZ 2947.Op Fl c Ar start-directory 2948.Op Fl e Ar environment 2949.Op Fl l Ar size 2950.Op Fl t Ar target-pane 2951.Op Ar shell-command 2952.Op Fl F Ar format 2953.Xc 2954.D1 Pq alias: Ic splitw 2955Create a new pane by splitting 2956.Ar target-pane : 2957.Fl h 2958does a horizontal split and 2959.Fl v 2960a vertical split; if neither is specified, 2961.Fl v 2962is assumed. 2963The 2964.Fl l 2965option specifies the size of the new pane in lines (for vertical split) or in 2966columns (for horizontal split); 2967.Ar size 2968may be followed by 2969.Ql % 2970to specify a percentage of the available space. 2971The 2972.Fl b 2973option causes the new pane to be created to the left of or above 2974.Ar target-pane . 2975The 2976.Fl f 2977option creates a new pane spanning the full window height (with 2978.Fl h ) 2979or full window width (with 2980.Fl v ) , 2981instead of splitting the active pane. 2982.Fl Z 2983zooms if the window is not zoomed, or keeps it zoomed if already zoomed. 2984.Pp 2985An empty 2986.Ar shell-command 2987('') will create a pane with no command running in it. 2988Output can be sent to such a pane with the 2989.Ic display-message 2990command. 2991The 2992.Fl I 2993flag (if 2994.Ar shell-command 2995is not specified or empty) 2996will create an empty pane and forward any output from stdin to it. 2997For example: 2998.Bd -literal -offset indent 2999$ make 2>&1|tmux splitw -dI & 3000.Ed 3001.Pp 3002All other options have the same meaning as for the 3003.Ic new-window 3004command. 3005.Tg swapp 3006.It Xo Ic swap-pane 3007.Op Fl dDUZ 3008.Op Fl s Ar src-pane 3009.Op Fl t Ar dst-pane 3010.Xc 3011.D1 Pq alias: Ic swapp 3012Swap two panes. 3013If 3014.Fl U 3015is used and no source pane is specified with 3016.Fl s , 3017.Ar dst-pane 3018is swapped with the previous pane (before it numerically); 3019.Fl D 3020swaps with the next pane (after it numerically). 3021.Fl d 3022instructs 3023.Nm 3024not to change the active pane and 3025.Fl Z 3026keeps the window zoomed if it was zoomed. 3027.Pp 3028If 3029.Fl s 3030is omitted and a marked pane is present (see 3031.Ic select-pane 3032.Fl m ) , 3033the marked pane is used rather than the current pane. 3034.Tg swapw 3035.It Xo Ic swap-window 3036.Op Fl d 3037.Op Fl s Ar src-window 3038.Op Fl t Ar dst-window 3039.Xc 3040.D1 Pq alias: Ic swapw 3041This is similar to 3042.Ic link-window , 3043except the source and destination windows are swapped. 3044It is an error if no window exists at 3045.Ar src-window . 3046If 3047.Fl d 3048is given, the new window does not become the current window. 3049.Pp 3050If 3051.Fl s 3052is omitted and a marked pane is present (see 3053.Ic select-pane 3054.Fl m ) , 3055the window containing the marked pane is used rather than the current window. 3056.Tg unlinkw 3057.It Xo Ic unlink-window 3058.Op Fl k 3059.Op Fl t Ar target-window 3060.Xc 3061.D1 Pq alias: Ic unlinkw 3062Unlink 3063.Ar target-window . 3064Unless 3065.Fl k 3066is given, a window may be unlinked only if it is linked to multiple sessions - 3067windows may not be linked to no sessions; 3068if 3069.Fl k 3070is specified and the window is linked to only one session, it is unlinked and 3071destroyed. 3072.El 3073.Sh KEY BINDINGS 3074.Nm 3075allows a command to be bound to most keys, with or without a prefix key. 3076When specifying keys, most represent themselves (for example 3077.Ql A 3078to 3079.Ql Z ) . 3080Ctrl keys may be prefixed with 3081.Ql C- 3082or 3083.Ql ^ , 3084Shift keys with 3085.Ql S- 3086and Alt (meta) with 3087.Ql M- . 3088In addition, the following special key names are accepted: 3089.Em Up , 3090.Em Down , 3091.Em Left , 3092.Em Right , 3093.Em BSpace , 3094.Em BTab , 3095.Em DC 3096(Delete), 3097.Em End , 3098.Em Enter , 3099.Em Escape , 3100.Em F1 3101to 3102.Em F12 , 3103.Em Home , 3104.Em IC 3105(Insert), 3106.Em NPage/PageDown/PgDn , 3107.Em PPage/PageUp/PgUp , 3108.Em Space , 3109and 3110.Em Tab . 3111Note that to bind the 3112.Ql \&" 3113or 3114.Ql ' 3115keys, quotation marks are necessary, for example: 3116.Bd -literal -offset indent 3117bind-key '"' split-window 3118bind-key "'" new-window 3119.Ed 3120.Pp 3121A command bound to the 3122.Em Any 3123key will execute for all keys which do not have a more specific binding. 3124.Pp 3125Commands related to key bindings are as follows: 3126.Bl -tag -width Ds 3127.Tg bind 3128.It Xo Ic bind-key 3129.Op Fl nr 3130.Op Fl N Ar note 3131.Op Fl T Ar key-table 3132.Ar key command Op Ar argument ... 3133.Xc 3134.D1 Pq alias: Ic bind 3135Bind key 3136.Ar key 3137to 3138.Ar command . 3139Keys are bound in a key table. 3140By default (without -T), the key is bound in 3141the 3142.Em prefix 3143key table. 3144This table is used for keys pressed after the prefix key (for example, 3145by default 3146.Ql c 3147is bound to 3148.Ic new-window 3149in the 3150.Em prefix 3151table, so 3152.Ql C-b c 3153creates a new window). 3154The 3155.Em root 3156table is used for keys pressed without the prefix key: binding 3157.Ql c 3158to 3159.Ic new-window 3160in the 3161.Em root 3162table (not recommended) means a plain 3163.Ql c 3164will create a new window. 3165.Fl n 3166is an alias 3167for 3168.Fl T Ar root . 3169Keys may also be bound in custom key tables and the 3170.Ic switch-client 3171.Fl T 3172command used to switch to them from a key binding. 3173The 3174.Fl r 3175flag indicates this key may repeat, see the 3176.Ic repeat-time 3177option. 3178.Fl N 3179attaches a note to the key (shown with 3180.Ic list-keys 3181.Fl N ) . 3182.Pp 3183To view the default bindings and possible commands, see the 3184.Ic list-keys 3185command. 3186.Tg lsk 3187.It Xo Ic list-keys 3188.Op Fl 1aN 3189.Op Fl P Ar prefix-string Fl T Ar key-table 3190.Op Ar key 3191.Xc 3192.D1 Pq alias: Ic lsk 3193List key bindings. 3194There are two forms: the default lists keys as 3195.Ic bind-key 3196commands; 3197.Fl N 3198lists only keys with attached notes and shows only the key and note for each 3199key. 3200.Pp 3201With the default form, all key tables are listed by default. 3202.Fl T 3203lists only keys in 3204.Ar key-table . 3205.Pp 3206With the 3207.Fl N 3208form, only keys in the 3209.Em root 3210and 3211.Em prefix 3212key tables are listed by default; 3213.Fl T 3214also lists only keys in 3215.Ar key-table . 3216.Fl P 3217specifies a prefix to print before each key and 3218.Fl 1 3219lists only the first matching key. 3220.Fl a 3221lists the command for keys that do not have a note rather than skipping them. 3222.Tg send 3223.It Xo Ic send-keys 3224.Op Fl FHKlMRX 3225.Op Fl c Ar target-client 3226.Op Fl N Ar repeat-count 3227.Op Fl t Ar target-pane 3228.Ar key ... 3229.Xc 3230.D1 Pq alias: Ic send 3231Send a key or keys to a window or client. 3232Each argument 3233.Ar key 3234is the name of the key (such as 3235.Ql C-a 3236or 3237.Ql NPage ) 3238to send; if the string is not recognised as a key, it is sent as a series of 3239characters. 3240If 3241.Fl K 3242is given, keys are sent to 3243.Ar target-client , 3244so they are looked up in the client's key table, rather than to 3245.Ar target-pane . 3246All arguments are sent sequentially from first to last. 3247If no keys are given and the command is bound to a key, then that key is used. 3248.Pp 3249The 3250.Fl l 3251flag disables key name lookup and processes the keys as literal UTF-8 3252characters. 3253The 3254.Fl H 3255flag expects each key to be a hexadecimal number for an ASCII character. 3256.Pp 3257The 3258.Fl R 3259flag causes the terminal state to be reset. 3260.Pp 3261.Fl M 3262passes through a mouse event (only valid if bound to a mouse key binding, see 3263.Sx MOUSE SUPPORT ) . 3264.Pp 3265.Fl X 3266is used to send a command into copy mode - see 3267the 3268.Sx WINDOWS AND PANES 3269section. 3270.Fl N 3271specifies a repeat count and 3272.Fl F 3273expands formats in arguments where appropriate. 3274.It Xo Ic send-prefix 3275.Op Fl 2 3276.Op Fl t Ar target-pane 3277.Xc 3278Send the prefix key, or with 3279.Fl 2 3280the secondary prefix key, to a window as if it was pressed. 3281.Tg unbind 3282.It Xo Ic unbind-key 3283.Op Fl anq 3284.Op Fl T Ar key-table 3285.Ar key 3286.Xc 3287.D1 Pq alias: Ic unbind 3288Unbind the command bound to 3289.Ar key . 3290.Fl n 3291and 3292.Fl T 3293are the same as for 3294.Ic bind-key . 3295If 3296.Fl a 3297is present, all key bindings are removed. 3298The 3299.Fl q 3300option prevents errors being returned. 3301.El 3302.Sh OPTIONS 3303The appearance and behaviour of 3304.Nm 3305may be modified by changing the value of various options. 3306There are four types of option: 3307.Em server options , 3308.Em session options , 3309.Em window options , 3310and 3311.Em pane options . 3312.Pp 3313The 3314.Nm 3315server has a set of global server options which do not apply to any particular 3316window or session or pane. 3317These are altered with the 3318.Ic set-option 3319.Fl s 3320command, or displayed with the 3321.Ic show-options 3322.Fl s 3323command. 3324.Pp 3325In addition, each individual session may have a set of session options, and 3326there is a separate set of global session options. 3327Sessions which do not have a particular option configured inherit the value 3328from the global session options. 3329Session options are set or unset with the 3330.Ic set-option 3331command and may be listed with the 3332.Ic show-options 3333command. 3334The available server and session options are listed under the 3335.Ic set-option 3336command. 3337.Pp 3338Similarly, a set of window options is attached to each window and a set of pane 3339options to each pane. 3340Pane options inherit from window options. 3341This means any pane option may be set as a window option to apply the option to 3342all panes in the window without the option set, for example these commands will 3343set the background colour to red for all panes except pane 0: 3344.Bd -literal -offset indent 3345set -w window-style bg=red 3346set -pt:.0 window-style bg=blue 3347.Ed 3348.Pp 3349There is also a set of global window options from which any unset window or 3350pane options are inherited. 3351Window and pane options are altered with 3352.Ic set-option 3353.Fl w 3354and 3355.Fl p 3356commands and displayed with 3357.Ic show-option 3358.Fl w 3359and 3360.Fl p . 3361.Pp 3362.Nm 3363also supports user options which are prefixed with a 3364.Ql \&@ . 3365User options may have any name, so long as they are prefixed with 3366.Ql \&@ , 3367and be set to any string. 3368For example: 3369.Bd -literal -offset indent 3370$ tmux set -wq @foo "abc123" 3371$ tmux show -wv @foo 3372abc123 3373.Ed 3374.Pp 3375Commands which set options are as follows: 3376.Bl -tag -width Ds 3377.Tg set 3378.It Xo Ic set-option 3379.Op Fl aFgopqsuUw 3380.Op Fl t Ar target-pane 3381.Ar option Ar value 3382.Xc 3383.D1 Pq alias: Ic set 3384Set a pane option with 3385.Fl p , 3386a window option with 3387.Fl w , 3388a server option with 3389.Fl s , 3390otherwise a session option. 3391If the option is not a user option, 3392.Fl w 3393or 3394.Fl s 3395may be unnecessary - 3396.Nm 3397will infer the type from the option name, assuming 3398.Fl w 3399for pane options. 3400If 3401.Fl g 3402is given, the global session or window option is set. 3403.Pp 3404.Fl F 3405expands formats in the option value. 3406The 3407.Fl u 3408flag unsets an option, so a session inherits the option from the global 3409options (or with 3410.Fl g , 3411restores a global option to the default). 3412.Fl U 3413unsets an option (like 3414.Fl u ) 3415but if the option is a pane option also unsets the option on any panes in the 3416window. 3417.Ar value 3418depends on the option and may be a number, a string, or a flag (on, off, or 3419omitted to toggle). 3420.Pp 3421The 3422.Fl o 3423flag prevents setting an option that is already set and the 3424.Fl q 3425flag suppresses errors about unknown or ambiguous options. 3426.Pp 3427With 3428.Fl a , 3429and if the option expects a string or a style, 3430.Ar value 3431is appended to the existing setting. 3432For example: 3433.Bd -literal -offset indent 3434set -g status-left "foo" 3435set -ag status-left "bar" 3436.Ed 3437.Pp 3438Will result in 3439.Ql foobar . 3440And: 3441.Bd -literal -offset indent 3442set -g status-style "bg=red" 3443set -ag status-style "fg=blue" 3444.Ed 3445.Pp 3446Will result in a red background 3447.Em and 3448blue foreground. 3449Without 3450.Fl a , 3451the result would be the default background and a blue foreground. 3452.Tg show 3453.It Xo Ic show-options 3454.Op Fl AgHpqsvw 3455.Op Fl t Ar target-pane 3456.Op Ar option 3457.Xc 3458.D1 Pq alias: Ic show 3459Show the pane options (or a single option if 3460.Ar option 3461is provided) with 3462.Fl p , 3463the window options with 3464.Fl w , 3465the server options with 3466.Fl s , 3467otherwise the session options. 3468If the option is not a user option, 3469.Fl w 3470or 3471.Fl s 3472may be unnecessary - 3473.Nm 3474will infer the type from the option name, assuming 3475.Fl w 3476for pane options. 3477Global session or window options are listed if 3478.Fl g 3479is used. 3480.Fl v 3481shows only the option value, not the name. 3482If 3483.Fl q 3484is set, no error will be returned if 3485.Ar option 3486is unset. 3487.Fl H 3488includes hooks (omitted by default). 3489.Fl A 3490includes options inherited from a parent set of options, such options are 3491marked with an asterisk. 3492.El 3493.Pp 3494Available server options are: 3495.Bl -tag -width Ds 3496.It Ic backspace Ar key 3497Set the key sent by 3498.Nm 3499for backspace. 3500.It Ic buffer-limit Ar number 3501Set the number of buffers; as new buffers are added to the top of the stack, 3502old ones are removed from the bottom if necessary to maintain this maximum 3503length. 3504.It Xo Ic command-alias[] 3505.Ar name=value 3506.Xc 3507This is an array of custom aliases for commands. 3508If an unknown command matches 3509.Ar name , 3510it is replaced with 3511.Ar value . 3512For example, after: 3513.Pp 3514.Dl set -s command-alias[100] zoom='resize-pane -Z' 3515.Pp 3516Using: 3517.Pp 3518.Dl zoom -t:.1 3519.Pp 3520Is equivalent to: 3521.Pp 3522.Dl resize-pane -Z -t:.1 3523.Pp 3524Note that aliases are expanded when a command is parsed rather than when it is 3525executed, so binding an alias with 3526.Ic bind-key 3527will bind the expanded form. 3528.It Ic default-terminal Ar terminal 3529Set the default terminal for new windows created in this session - the 3530default value of the 3531.Ev TERM 3532environment variable. 3533For 3534.Nm 3535to work correctly, this 3536.Em must 3537be set to 3538.Ql screen , 3539.Ql tmux 3540or a derivative of them. 3541.It Ic copy-command Ar shell-command 3542Give the command to pipe to if the 3543.Ic copy-pipe 3544copy mode command is used without arguments. 3545.It Ic escape-time Ar time 3546Set the time in milliseconds for which 3547.Nm 3548waits after an escape is input to determine if it is part of a function or meta 3549key sequences. 3550The default is 500 milliseconds. 3551.It Ic editor Ar shell-command 3552Set the command used when 3553.Nm 3554runs an editor. 3555.It Xo Ic exit-empty 3556.Op Ic on | off 3557.Xc 3558If enabled (the default), the server will exit when there are no active 3559sessions. 3560.It Xo Ic exit-unattached 3561.Op Ic on | off 3562.Xc 3563If enabled, the server will exit when there are no attached clients. 3564.It Xo Ic extended-keys 3565.Op Ic on | off | always 3566.Xc 3567When 3568.Ic on 3569or 3570.Ic always , 3571the escape sequence to enable extended keys is sent to the terminal, if 3572.Nm 3573knows that it is supported. 3574.Nm 3575always recognises extended keys itself. 3576If this option is 3577.Ic on , 3578.Nm 3579will only forward extended keys to applications when they request them; if 3580.Ic always , 3581.Nm 3582will always forward the keys. 3583.It Xo Ic focus-events 3584.Op Ic on | off 3585.Xc 3586When enabled, focus events are requested from the terminal if supported and 3587passed through to applications running in 3588.Nm . 3589Attached clients should be detached and attached again after changing this 3590option. 3591.It Ic history-file Ar path 3592If not empty, a file to which 3593.Nm 3594will write command prompt history on exit and load it from on start. 3595.It Ic message-limit Ar number 3596Set the number of error or information messages to save in the message log for 3597each client. 3598.It Ic prompt-history-limit Ar number 3599Set the number of history items to save in the history file for each type of 3600command prompt. 3601.It Xo Ic set-clipboard 3602.Op Ic on | external | off 3603.Xc 3604Attempt to set the terminal clipboard content using the 3605.Xr xterm 1 3606escape sequence, if there is an 3607.Em \&Ms 3608entry in the 3609.Xr terminfo 5 3610description (see the 3611.Sx TERMINFO EXTENSIONS 3612section). 3613.Pp 3614If set to 3615.Ic on , 3616.Nm 3617will both accept the escape sequence to create a buffer and attempt to set 3618the terminal clipboard. 3619If set to 3620.Ic external , 3621.Nm 3622will attempt to set the terminal clipboard but ignore attempts 3623by applications to set 3624.Nm 3625buffers. 3626If 3627.Ic off , 3628.Nm 3629will neither accept the clipboard escape sequence nor attempt to set the 3630clipboard. 3631.Pp 3632Note that this feature needs to be enabled in 3633.Xr xterm 1 3634by setting the resource: 3635.Bd -literal -offset indent 3636disallowedWindowOps: 20,21,SetXprop 3637.Ed 3638.Pp 3639Or changing this property from the 3640.Xr xterm 1 3641interactive menu when required. 3642.It Ic terminal-features[] Ar string 3643Set terminal features for terminal types read from 3644.Xr terminfo 5 . 3645.Nm 3646has a set of named terminal features. 3647Each will apply appropriate changes to the 3648.Xr terminfo 5 3649entry in use. 3650.Pp 3651.Nm 3652can detect features for a few common terminals; this option can be used to 3653easily tell tmux about features supported by terminals it cannot detect. 3654The 3655.Ic terminal-overrides 3656option allows individual 3657.Xr terminfo 5 3658capabilities to be set instead, 3659.Ic terminal-features 3660is intended for classes of functionality supported in a standard way but not 3661reported by 3662.Xr terminfo 5 . 3663Care must be taken to configure this only with features the terminal actually 3664supports. 3665.Pp 3666This is an array option where each entry is a colon-separated string made up 3667of a terminal type pattern (matched using 3668.Xr fnmatch 3 ) 3669followed by a list of terminal features. 3670The available features are: 3671.Bl -tag -width Ds 3672.It 256 3673Supports 256 colours with the SGR escape sequences. 3674.It clipboard 3675Allows setting the system clipboard. 3676.It ccolour 3677Allows setting the cursor colour. 3678.It cstyle 3679Allows setting the cursor style. 3680.It extkeys 3681Supports extended keys. 3682.It focus 3683Supports focus reporting. 3684.It hyperlinks 3685Supports OSC 8 hyperlinks. 3686.It ignorefkeys 3687Ignore function keys from 3688.Xr terminfo 5 3689and use the 3690.Nm 3691internal set only. 3692.It margins 3693Supports DECSLRM margins. 3694.It mouse 3695Supports 3696.Xr xterm 1 3697mouse sequences. 3698.It osc7 3699Supports the OSC 7 working directory extension. 3700.It overline 3701Supports the overline SGR attribute. 3702.It rectfill 3703Supports the DECFRA rectangle fill escape sequence. 3704.It RGB 3705Supports RGB colour with the SGR escape sequences. 3706.It sixel 3707Supports SIXEL graphics. 3708.It strikethrough 3709Supports the strikethrough SGR escape sequence. 3710.It sync 3711Supports synchronized updates. 3712.It title 3713Supports 3714.Xr xterm 1 3715title setting. 3716.It usstyle 3717Allows underscore style and colour to be set. 3718.El 3719.It Ic terminal-overrides[] Ar string 3720Allow terminal descriptions read using 3721.Xr terminfo 5 3722to be overridden. 3723Each entry is a colon-separated string made up of a terminal type pattern 3724(matched using 3725.Xr fnmatch 3 ) 3726and a set of 3727.Em name=value 3728entries. 3729.Pp 3730For example, to set the 3731.Ql clear 3732.Xr terminfo 5 3733entry to 3734.Ql \ee[H\ee[2J 3735for all terminal types matching 3736.Ql rxvt* : 3737.Pp 3738.Dl "rxvt*:clear=\ee[H\ee[2J" 3739.Pp 3740The terminal entry value is passed through 3741.Xr strunvis 3 3742before interpretation. 3743.It Ic user-keys[] Ar key 3744Set list of user-defined key escape sequences. 3745Each item is associated with a key named 3746.Ql User0 , 3747.Ql User1 , 3748and so on. 3749.Pp 3750For example: 3751.Bd -literal -offset indent 3752set -s user-keys[0] "\ee[5;30012~" 3753bind User0 resize-pane -L 3 3754.Ed 3755.El 3756.Pp 3757Available session options are: 3758.Bl -tag -width Ds 3759.It Xo Ic activity-action 3760.Op Ic any | none | current | other 3761.Xc 3762Set action on window activity when 3763.Ic monitor-activity 3764is on. 3765.Ic any 3766means activity in any window linked to a session causes a bell or message 3767(depending on 3768.Ic visual-activity ) 3769in the current window of that session, 3770.Ic none 3771means all activity is ignored (equivalent to 3772.Ic monitor-activity 3773being off), 3774.Ic current 3775means only activity in windows other than the current window are ignored and 3776.Ic other 3777means activity in the current window is ignored but not those in other windows. 3778.It Ic assume-paste-time Ar milliseconds 3779If keys are entered faster than one in 3780.Ar milliseconds , 3781they are assumed to have been pasted rather than typed and 3782.Nm 3783key bindings are not processed. 3784The default is one millisecond and zero disables. 3785.It Ic base-index Ar index 3786Set the base index from which an unused index should be searched when a new 3787window is created. 3788The default is zero. 3789.It Xo Ic bell-action 3790.Op Ic any | none | current | other 3791.Xc 3792Set action on a bell in a window when 3793.Ic monitor-bell 3794is on. 3795The values are the same as those for 3796.Ic activity-action . 3797.It Ic default-command Ar shell-command 3798Set the command used for new windows (if not specified when the window is 3799created) to 3800.Ar shell-command , 3801which may be any 3802.Xr sh 1 3803command. 3804The default is an empty string, which instructs 3805.Nm 3806to create a login shell using the value of the 3807.Ic default-shell 3808option. 3809.It Ic default-shell Ar path 3810Specify the default shell. 3811This is used as the login shell for new windows when the 3812.Ic default-command 3813option is set to empty, and must be the full path of the executable. 3814When started 3815.Nm 3816tries to set a default value from the first suitable of the 3817.Ev SHELL 3818environment variable, the shell returned by 3819.Xr getpwuid 3 , 3820or 3821.Pa /bin/sh . 3822This option should be configured when 3823.Nm 3824is used as a login shell. 3825.It Ic default-size Ar XxY 3826Set the default size of new windows when the 3827.Ic window-size 3828option is set to manual or when a session is created with 3829.Ic new-session 3830.Fl d . 3831The value is the width and height separated by an 3832.Ql x 3833character. 3834The default is 80x24. 3835.It Xo Ic destroy-unattached 3836.Op Ic on | off 3837.Xc 3838If enabled and the session is no longer attached to any clients, it is 3839destroyed. 3840.It Xo Ic detach-on-destroy 3841.Op Ic off | on | no-detached 3842.Xc 3843If on (the default), the client is detached when the session it is attached to 3844is destroyed. 3845If off, the client is switched to the most recently active of the remaining 3846sessions. 3847If 3848.Ic no-detached , 3849the client is detached only if there are no detached sessions; if detached 3850sessions exist, the client is switched to the most recently active. 3851.It Ic display-panes-active-colour Ar colour 3852Set the colour used by the 3853.Ic display-panes 3854command to show the indicator for the active pane. 3855.It Ic display-panes-colour Ar colour 3856Set the colour used by the 3857.Ic display-panes 3858command to show the indicators for inactive panes. 3859.It Ic display-panes-time Ar time 3860Set the time in milliseconds for which the indicators shown by the 3861.Ic display-panes 3862command appear. 3863.It Ic display-time Ar time 3864Set the amount of time for which status line messages and other on-screen 3865indicators are displayed. 3866If set to 0, messages and indicators are displayed until a key is pressed. 3867.Ar time 3868is in milliseconds. 3869.It Ic history-limit Ar lines 3870Set the maximum number of lines held in window history. 3871This setting applies only to new windows - existing window histories are not 3872resized and retain the limit at the point they were created. 3873.It Ic key-table Ar key-table 3874Set the default key table to 3875.Ar key-table 3876instead of 3877.Em root . 3878.It Ic lock-after-time Ar number 3879Lock the session (like the 3880.Ic lock-session 3881command) after 3882.Ar number 3883seconds of inactivity. 3884The default is not to lock (set to 0). 3885.It Ic lock-command Ar shell-command 3886Command to run when locking each client. 3887The default is to run 3888.Xr lock 1 3889with 3890.Fl np . 3891.It Ic message-command-style Ar style 3892Set status line message command style. 3893This is used for the command prompt with 3894.Xr vi 1 3895keys when in command mode. 3896For how to specify 3897.Ar style , 3898see the 3899.Sx STYLES 3900section. 3901.It Xo Ic message-line 3902.Op Ic 0 | 1 | 2 | 3 | 4 3903.Xc 3904Set line on which status line messages and the command prompt are shown. 3905.It Ic message-style Ar style 3906Set status line message style. 3907This is used for messages and for the command prompt. 3908For how to specify 3909.Ar style , 3910see the 3911.Sx STYLES 3912section. 3913.It Xo Ic mouse 3914.Op Ic on | off 3915.Xc 3916If on, 3917.Nm 3918captures the mouse and allows mouse events to be bound as key bindings. 3919See the 3920.Sx MOUSE SUPPORT 3921section for details. 3922.It Ic prefix Ar key 3923Set the key accepted as a prefix key. 3924In addition to the standard keys described under 3925.Sx KEY BINDINGS , 3926.Ic prefix 3927can be set to the special key 3928.Ql None 3929to set no prefix. 3930.It Ic prefix2 Ar key 3931Set a secondary key accepted as a prefix key. 3932Like 3933.Ic prefix , 3934.Ic prefix2 3935can be set to 3936.Ql None . 3937.It Xo Ic renumber-windows 3938.Op Ic on | off 3939.Xc 3940If on, when a window is closed in a session, automatically renumber the other 3941windows in numerical order. 3942This respects the 3943.Ic base-index 3944option if it has been set. 3945If off, do not renumber the windows. 3946.It Ic repeat-time Ar time 3947Allow multiple commands to be entered without pressing the prefix-key again 3948in the specified 3949.Ar time 3950milliseconds (the default is 500). 3951Whether a key repeats may be set when it is bound using the 3952.Fl r 3953flag to 3954.Ic bind-key . 3955Repeat is enabled for the default keys bound to the 3956.Ic resize-pane 3957command. 3958.It Xo Ic set-titles 3959.Op Ic on | off 3960.Xc 3961Attempt to set the client terminal title using the 3962.Em tsl 3963and 3964.Em fsl 3965.Xr terminfo 5 3966entries if they exist. 3967.Nm 3968automatically sets these to the \ee]0;...\e007 sequence if 3969the terminal appears to be 3970.Xr xterm 1 . 3971This option is off by default. 3972.It Ic set-titles-string Ar string 3973String used to set the client terminal title if 3974.Ic set-titles 3975is on. 3976Formats are expanded, see the 3977.Sx FORMATS 3978section. 3979.It Xo Ic silence-action 3980.Op Ic any | none | current | other 3981.Xc 3982Set action on window silence when 3983.Ic monitor-silence 3984is on. 3985The values are the same as those for 3986.Ic activity-action . 3987.It Xo Ic status 3988.Op Ic off | on | 2 | 3 | 4 | 5 3989.Xc 3990Show or hide the status line or specify its size. 3991Using 3992.Ic on 3993gives a status line one row in height; 3994.Ic 2 , 3995.Ic 3 , 3996.Ic 4 3997or 3998.Ic 5 3999more rows. 4000.It Ic status-format[] Ar format 4001Specify the format to be used for each line of the status line. 4002The default builds the top status line from the various individual status 4003options below. 4004.It Ic status-interval Ar interval 4005Update the status line every 4006.Ar interval 4007seconds. 4008By default, updates will occur every 15 seconds. 4009A setting of zero disables redrawing at interval. 4010.It Xo Ic status-justify 4011.Op Ic left | centre | right | absolute-centre 4012.Xc 4013Set the position of the window list in the status line: left, centre or right. 4014centre puts the window list in the relative centre of the available free space; 4015absolute-centre uses the centre of the entire horizontal space. 4016.It Xo Ic status-keys 4017.Op Ic vi | emacs 4018.Xc 4019Use vi or emacs-style 4020key bindings in the status line, for example at the command prompt. 4021The default is emacs, unless the 4022.Ev VISUAL 4023or 4024.Ev EDITOR 4025environment variables are set and contain the string 4026.Ql vi . 4027.It Ic status-left Ar string 4028Display 4029.Ar string 4030(by default the session name) to the left of the status line. 4031.Ar string 4032will be passed through 4033.Xr strftime 3 . 4034Also see the 4035.Sx FORMATS 4036and 4037.Sx STYLES 4038sections. 4039.Pp 4040For details on how the names and titles can be set see the 4041.Sx "NAMES AND TITLES" 4042section. 4043.Pp 4044Examples are: 4045.Bd -literal -offset indent 4046#(sysctl vm.loadavg) 4047#[fg=yellow,bold]#(apm -l)%%#[default] [#S] 4048.Ed 4049.Pp 4050The default is 4051.Ql "[#S] " . 4052.It Ic status-left-length Ar length 4053Set the maximum 4054.Ar length 4055of the left component of the status line. 4056The default is 10. 4057.It Ic status-left-style Ar style 4058Set the style of the left part of the status line. 4059For how to specify 4060.Ar style , 4061see the 4062.Sx STYLES 4063section. 4064.It Xo Ic status-position 4065.Op Ic top | bottom 4066.Xc 4067Set the position of the status line. 4068.It Ic status-right Ar string 4069Display 4070.Ar string 4071to the right of the status line. 4072By default, the current pane title in double quotes, the date and the time 4073are shown. 4074As with 4075.Ic status-left , 4076.Ar string 4077will be passed to 4078.Xr strftime 3 4079and character pairs are replaced. 4080.It Ic status-right-length Ar length 4081Set the maximum 4082.Ar length 4083of the right component of the status line. 4084The default is 40. 4085.It Ic status-right-style Ar style 4086Set the style of the right part of the status line. 4087For how to specify 4088.Ar style , 4089see the 4090.Sx STYLES 4091section. 4092.It Ic status-style Ar style 4093Set status line style. 4094For how to specify 4095.Ar style , 4096see the 4097.Sx STYLES 4098section. 4099.It Ic update-environment[] Ar variable 4100Set list of environment variables to be copied into the session environment 4101when a new session is created or an existing session is attached. 4102Any variables that do not exist in the source environment are set to be 4103removed from the session environment (as if 4104.Fl r 4105was given to the 4106.Ic set-environment 4107command). 4108.It Xo Ic visual-activity 4109.Op Ic on | off | both 4110.Xc 4111If on, display a message instead of sending a bell when activity occurs in a 4112window for which the 4113.Ic monitor-activity 4114window option is enabled. 4115If set to both, a bell and a message are produced. 4116.It Xo Ic visual-bell 4117.Op Ic on | off | both 4118.Xc 4119If on, a message is shown on a bell in a window for which the 4120.Ic monitor-bell 4121window option is enabled instead of it being passed through to the 4122terminal (which normally makes a sound). 4123If set to both, a bell and a message are produced. 4124Also see the 4125.Ic bell-action 4126option. 4127.It Xo Ic visual-silence 4128.Op Ic on | off | both 4129.Xc 4130If 4131.Ic monitor-silence 4132is enabled, prints a message after the interval has expired on a given window 4133instead of sending a bell. 4134If set to both, a bell and a message are produced. 4135.It Ic word-separators Ar string 4136Sets the session's conception of what characters are considered word 4137separators, for the purposes of the next and previous word commands in 4138copy mode. 4139.El 4140.Pp 4141Available window options are: 4142.Pp 4143.Bl -tag -width Ds -compact 4144.It Xo Ic aggressive-resize 4145.Op Ic on | off 4146.Xc 4147Aggressively resize the chosen window. 4148This means that 4149.Nm 4150will resize the window to the size of the smallest or largest session 4151(see the 4152.Ic window-size 4153option) for which it is the current window, rather than the session to 4154which it is attached. 4155The window may resize when the current window is changed on another 4156session; this option is good for full-screen programs which support 4157.Dv SIGWINCH 4158and poor for interactive programs such as shells. 4159.Pp 4160.It Xo Ic automatic-rename 4161.Op Ic on | off 4162.Xc 4163Control automatic window renaming. 4164When this setting is enabled, 4165.Nm 4166will rename the window automatically using the format specified by 4167.Ic automatic-rename-format . 4168This flag is automatically disabled for an individual window when a name 4169is specified at creation with 4170.Ic new-window 4171or 4172.Ic new-session , 4173or later with 4174.Ic rename-window , 4175or with a terminal escape sequence. 4176It may be switched off globally with: 4177.Bd -literal -offset indent 4178set-option -wg automatic-rename off 4179.Ed 4180.Pp 4181.It Ic automatic-rename-format Ar format 4182The format (see 4183.Sx FORMATS ) 4184used when the 4185.Ic automatic-rename 4186option is enabled. 4187.Pp 4188.It Ic clock-mode-colour Ar colour 4189Set clock colour. 4190.Pp 4191.It Xo Ic clock-mode-style 4192.Op Ic 12 | 24 4193.Xc 4194Set clock hour format. 4195.Pp 4196.It Ic fill-character Ar character 4197Set the character used to fill areas of the terminal unused by a window. 4198.Pp 4199.It Ic main-pane-height Ar height 4200.It Ic main-pane-width Ar width 4201Set the width or height of the main (left or top) pane in the 4202.Ic main-horizontal 4203or 4204.Ic main-vertical 4205layouts. 4206If suffixed by 4207.Ql % , 4208this is a percentage of the window size. 4209.Pp 4210.It Ic copy-mode-match-style Ar style 4211Set the style of search matches in copy mode. 4212For how to specify 4213.Ar style , 4214see the 4215.Sx STYLES 4216section. 4217.Pp 4218.It Ic copy-mode-mark-style Ar style 4219Set the style of the line containing the mark in copy mode. 4220For how to specify 4221.Ar style , 4222see the 4223.Sx STYLES 4224section. 4225.Pp 4226.It Ic copy-mode-current-match-style Ar style 4227Set the style of the current search match in copy mode. 4228For how to specify 4229.Ar style , 4230see the 4231.Sx STYLES 4232section. 4233.Pp 4234.It Xo Ic mode-keys 4235.Op Ic vi | emacs 4236.Xc 4237Use vi or emacs-style key bindings in copy mode. 4238The default is emacs, unless 4239.Ev VISUAL 4240or 4241.Ev EDITOR 4242contains 4243.Ql vi . 4244.Pp 4245.It Ic mode-style Ar style 4246Set window modes style. 4247For how to specify 4248.Ar style , 4249see the 4250.Sx STYLES 4251section. 4252.Pp 4253.It Xo Ic monitor-activity 4254.Op Ic on | off 4255.Xc 4256Monitor for activity in the window. 4257Windows with activity are highlighted in the status line. 4258.Pp 4259.It Xo Ic monitor-bell 4260.Op Ic on | off 4261.Xc 4262Monitor for a bell in the window. 4263Windows with a bell are highlighted in the status line. 4264.Pp 4265.It Xo Ic monitor-silence 4266.Op Ic interval 4267.Xc 4268Monitor for silence (no activity) in the window within 4269.Ic interval 4270seconds. 4271Windows that have been silent for the interval are highlighted in the 4272status line. 4273An interval of zero disables the monitoring. 4274.Pp 4275.It Ic other-pane-height Ar height 4276Set the height of the other panes (not the main pane) in the 4277.Ic main-horizontal 4278layout. 4279If this option is set to 0 (the default), it will have no effect. 4280If both the 4281.Ic main-pane-height 4282and 4283.Ic other-pane-height 4284options are set, the main pane will grow taller to make the other panes the 4285specified height, but will never shrink to do so. 4286If suffixed by 4287.Ql % , 4288this is a percentage of the window size. 4289.Pp 4290.It Ic other-pane-width Ar width 4291Like 4292.Ic other-pane-height , 4293but set the width of other panes in the 4294.Ic main-vertical 4295layout. 4296.Pp 4297.It Ic pane-active-border-style Ar style 4298Set the pane border style for the currently active pane. 4299For how to specify 4300.Ar style , 4301see the 4302.Sx STYLES 4303section. 4304Attributes are ignored. 4305.Pp 4306.It Ic pane-base-index Ar index 4307Like 4308.Ic base-index , 4309but set the starting index for pane numbers. 4310.Pp 4311.It Ic pane-border-format Ar format 4312Set the text shown in pane border status lines. 4313.Pp 4314.It Xo Ic pane-border-indicators 4315.Op Ic off | colour | arrows | both 4316.Xc 4317Indicate active pane by colouring only half of the border in windows with 4318exactly two panes, by displaying arrow markers, by drawing both or neither. 4319.Pp 4320.It Ic pane-border-lines Ar type 4321Set the type of characters used for drawing pane borders. 4322.Ar type 4323may be one of: 4324.Bl -tag -width Ds 4325.It single 4326single lines using ACS or UTF-8 characters 4327.It double 4328double lines using UTF-8 characters 4329.It heavy 4330heavy lines using UTF-8 characters 4331.It simple 4332simple ASCII characters 4333.It number 4334the pane number 4335.El 4336.Pp 4337.Ql double 4338and 4339.Ql heavy 4340will fall back to standard ACS line drawing when UTF-8 is not supported. 4341.Pp 4342.It Xo Ic pane-border-status 4343.Op Ic off | top | bottom 4344.Xc 4345Turn pane border status lines off or set their position. 4346.Pp 4347.It Ic pane-border-style Ar style 4348Set the pane border style for panes aside from the active pane. 4349For how to specify 4350.Ar style , 4351see the 4352.Sx STYLES 4353section. 4354Attributes are ignored. 4355.Pp 4356.It Ic popup-style Ar style 4357Set the popup style. 4358For how to specify 4359.Ar style , 4360see the 4361.Sx STYLES 4362section. 4363Attributes are ignored. 4364.Pp 4365.It Ic popup-border-style Ar style 4366Set the popup border style. 4367For how to specify 4368.Ar style , 4369see the 4370.Sx STYLES 4371section. 4372Attributes are ignored. 4373.Pp 4374.It Ic popup-border-lines Ar type 4375Set the type of characters used for drawing popup borders. 4376.Ar type 4377may be one of: 4378.Bl -tag -width Ds 4379.It single 4380single lines using ACS or UTF-8 characters (default) 4381.It rounded 4382variation of single with rounded corners using UTF-8 characters 4383.It double 4384double lines using UTF-8 characters 4385.It heavy 4386heavy lines using UTF-8 characters 4387.It simple 4388simple ASCII characters 4389.It padded 4390simple ASCII space character 4391.It none 4392no border 4393.El 4394.Pp 4395.Ql double 4396and 4397.Ql heavy 4398will fall back to standard ACS line drawing when UTF-8 is not supported. 4399.Pp 4400.It Ic window-status-activity-style Ar style 4401Set status line style for windows with an activity alert. 4402For how to specify 4403.Ar style , 4404see the 4405.Sx STYLES 4406section. 4407.Pp 4408.It Ic window-status-bell-style Ar style 4409Set status line style for windows with a bell alert. 4410For how to specify 4411.Ar style , 4412see the 4413.Sx STYLES 4414section. 4415.Pp 4416.It Ic window-status-current-format Ar string 4417Like 4418.Ar window-status-format , 4419but is the format used when the window is the current window. 4420.Pp 4421.It Ic window-status-current-style Ar style 4422Set status line style for the currently active window. 4423For how to specify 4424.Ar style , 4425see the 4426.Sx STYLES 4427section. 4428.Pp 4429.It Ic window-status-format Ar string 4430Set the format in which the window is displayed in the status line window list. 4431See the 4432.Sx FORMATS 4433and 4434.Sx STYLES 4435sections. 4436.Pp 4437.It Ic window-status-last-style Ar style 4438Set status line style for the last active window. 4439For how to specify 4440.Ar style , 4441see the 4442.Sx STYLES 4443section. 4444.Pp 4445.It Ic window-status-separator Ar string 4446Sets the separator drawn between windows in the status line. 4447The default is a single space character. 4448.Pp 4449.It Ic window-status-style Ar style 4450Set status line style for a single window. 4451For how to specify 4452.Ar style , 4453see the 4454.Sx STYLES 4455section. 4456.Pp 4457.It Xo Ic window-size 4458.Ar largest | Ar smallest | Ar manual | Ar latest 4459.Xc 4460Configure how 4461.Nm 4462determines the window size. 4463If set to 4464.Ar largest , 4465the size of the largest attached session is used; if 4466.Ar smallest , 4467the size of the smallest. 4468If 4469.Ar manual , 4470the size of a new window is set from the 4471.Ic default-size 4472option and windows are resized automatically. 4473With 4474.Ar latest , 4475.Nm 4476uses the size of the client that had the most recent activity. 4477See also the 4478.Ic resize-window 4479command and the 4480.Ic aggressive-resize 4481option. 4482.Pp 4483.It Xo Ic wrap-search 4484.Op Ic on | off 4485.Xc 4486If this option is set, searches will wrap around the end of the pane contents. 4487The default is on. 4488.El 4489.Pp 4490Available pane options are: 4491.Pp 4492.Bl -tag -width Ds -compact 4493.It Xo Ic allow-passthrough 4494.Op Ic on | off | all 4495.Xc 4496Allow programs in the pane to bypass 4497.Nm 4498using a terminal escape sequence (\eePtmux;...\ee\e\e). 4499If set to 4500.Ic on , 4501passthrough sequences will be allowed only if the pane is visible. 4502If set to 4503.Ic all , 4504they will be allowed even if the pane is invisible. 4505.Pp 4506.It Xo Ic allow-rename 4507.Op Ic on | off 4508.Xc 4509Allow programs in the pane to change the window name using a terminal escape 4510sequence (\eek...\ee\e\e). 4511.Pp 4512.It Xo Ic alternate-screen 4513.Op Ic on | off 4514.Xc 4515This option configures whether programs running inside the pane may use the 4516terminal alternate screen feature, which allows the 4517.Em smcup 4518and 4519.Em rmcup 4520.Xr terminfo 5 4521capabilities. 4522The alternate screen feature preserves the contents of the window when an 4523interactive application starts and restores it on exit, so that any output 4524visible before the application starts reappears unchanged after it exits. 4525.Pp 4526.It Ic cursor-colour Ar colour 4527Set the colour of the cursor. 4528.Pp 4529.It Ic pane-colours[] Ar colour 4530The default colour palette. 4531Each entry in the array defines the colour 4532.Nm 4533uses when the colour with that index is requested. 4534The index may be from zero to 255. 4535.Pp 4536.It Ic cursor-style Ar style 4537Set the style of the cursor. 4538Available styles are: 4539.Ic default , 4540.Ic blinking-block , 4541.Ic block , 4542.Ic blinking-underline , 4543.Ic underline , 4544.Ic blinking-bar , 4545.Ic bar . 4546.Pp 4547.It Xo Ic remain-on-exit 4548.Op Ic on | off | failed 4549.Xc 4550A pane with this flag set is not destroyed when the program running in it 4551exits. 4552If set to 4553.Ic failed , 4554then only when the program exit status is not zero. 4555The pane may be reactivated with the 4556.Ic respawn-pane 4557command. 4558.Pp 4559.It Ic remain-on-exit-format Ar string 4560Set the text shown at the bottom of exited panes when 4561.Ic remain-on-exit 4562is enabled. 4563.Pp 4564.It Xo Ic scroll-on-clear 4565.Op Ic on | off 4566.Xc 4567When the entire screen is cleared and this option is on, scroll the contents of 4568the screen into history before clearing it. 4569.Pp 4570.It Xo Ic synchronize-panes 4571.Op Ic on | off 4572.Xc 4573Duplicate input to all other panes in the same window where this option is also 4574on (only for panes that are not in any mode). 4575.Pp 4576.It Ic window-active-style Ar style 4577Set the pane style when it is the active pane. 4578For how to specify 4579.Ar style , 4580see the 4581.Sx STYLES 4582section. 4583.Pp 4584.It Ic window-style Ar style 4585Set the pane style. 4586For how to specify 4587.Ar style , 4588see the 4589.Sx STYLES 4590section. 4591.El 4592.Sh HOOKS 4593.Nm 4594allows commands to run on various triggers, called 4595.Em hooks . 4596Most 4597.Nm 4598commands have an 4599.Em after 4600hook and there are a number of hooks not associated with commands. 4601.Pp 4602Hooks are stored as array options, members of the array are executed in 4603order when the hook is triggered. 4604Like options different hooks may be global or belong to a session, window or 4605pane. 4606Hooks may be configured with the 4607.Ic set-hook 4608or 4609.Ic set-option 4610commands and displayed with 4611.Ic show-hooks 4612or 4613.Ic show-options 4614.Fl H . 4615The following two commands are equivalent: 4616.Bd -literal -offset indent. 4617set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red' 4618set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red' 4619.Ed 4620.Pp 4621Setting a hook without specifying an array index clears the hook and sets the 4622first member of the array. 4623.Pp 4624A command's after 4625hook is run after it completes, except when the command is run as part of a hook 4626itself. 4627They are named with an 4628.Ql after- 4629prefix. 4630For example, the following command adds a hook to select the even-vertical 4631layout after every 4632.Ic split-window : 4633.Bd -literal -offset indent 4634set-hook -g after-split-window "selectl even-vertical" 4635.Ed 4636.Pp 4637All the notifications listed in the 4638.Sx CONTROL MODE 4639section are hooks (without any arguments), except 4640.Ic %exit . 4641The following additional hooks are available: 4642.Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX" 4643.It alert-activity 4644Run when a window has activity. 4645See 4646.Ic monitor-activity . 4647.It alert-bell 4648Run when a window has received a bell. 4649See 4650.Ic monitor-bell . 4651.It alert-silence 4652Run when a window has been silent. 4653See 4654.Ic monitor-silence . 4655.It client-active 4656Run when a client becomes the latest active client of its session. 4657.It client-attached 4658Run when a client is attached. 4659.It client-detached 4660Run when a client is detached 4661.It client-focus-in 4662Run when focus enters a client 4663.It client-focus-out 4664Run when focus exits a client 4665.It client-resized 4666Run when a client is resized. 4667.It client-session-changed 4668Run when a client's attached session is changed. 4669.It pane-died 4670Run when the program running in a pane exits, but 4671.Ic remain-on-exit 4672is on so the pane has not closed. 4673.It pane-exited 4674Run when the program running in a pane exits. 4675.It pane-focus-in 4676Run when the focus enters a pane, if the 4677.Ic focus-events 4678option is on. 4679.It pane-focus-out 4680Run when the focus exits a pane, if the 4681.Ic focus-events 4682option is on. 4683.It pane-set-clipboard 4684Run when the terminal clipboard is set using the 4685.Xr xterm 1 4686escape sequence. 4687.It session-created 4688Run when a new session created. 4689.It session-closed 4690Run when a session closed. 4691.It session-renamed 4692Run when a session is renamed. 4693.It window-linked 4694Run when a window is linked into a session. 4695.It window-renamed 4696Run when a window is renamed. 4697.It window-resized 4698Run when a window is resized. 4699This may be after the 4700.Ar client-resized 4701hook is run. 4702.It window-unlinked 4703Run when a window is unlinked from a session. 4704.El 4705.Pp 4706Hooks are managed with these commands: 4707.Bl -tag -width Ds 4708.It Xo Ic set-hook 4709.Op Fl agpRuw 4710.Op Fl t Ar target-pane 4711.Ar hook-name 4712.Ar command 4713.Xc 4714Without 4715.Fl R , 4716sets (or with 4717.Fl u 4718unsets) hook 4719.Ar hook-name 4720to 4721.Ar command . 4722The flags are the same as for 4723.Ic set-option . 4724.Pp 4725With 4726.Fl R , 4727run 4728.Ar hook-name 4729immediately. 4730.It Xo Ic show-hooks 4731.Op Fl gpw 4732.Op Fl t Ar target-pane 4733.Xc 4734Shows hooks. 4735The flags are the same as for 4736.Ic show-options . 4737.El 4738.Sh MOUSE SUPPORT 4739If the 4740.Ic mouse 4741option is on (the default is off), 4742.Nm 4743allows mouse events to be bound as keys. 4744The name of each key is made up of a mouse event (such as 4745.Ql MouseUp1 ) 4746and a location suffix, one of the following: 4747.Bl -column "XXXXXXXXXXXXX" -offset indent 4748.It Li "Pane" Ta "the contents of a pane" 4749.It Li "Border" Ta "a pane border" 4750.It Li "Status" Ta "the status line window list" 4751.It Li "StatusLeft" Ta "the left part of the status line" 4752.It Li "StatusRight" Ta "the right part of the status line" 4753.It Li "StatusDefault" Ta "any other part of the status line" 4754.El 4755.Pp 4756The following mouse events are available: 4757.Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent 4758.It Li "WheelUp" Ta "WheelDown" Ta "" 4759.It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1" 4760.It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2" 4761.It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3" 4762.It Li "SecondClick1" Ta "SecondClick2" Ta "SecondClick3" 4763.It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3" 4764.It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3" 4765.El 4766.Pp 4767The 4768.Ql SecondClick 4769events are fired for the second click of a double click, even if there may be a 4770third click which will fire 4771.Ql TripleClick 4772instead of 4773.Ql DoubleClick . 4774.Pp 4775Each should be suffixed with a location, for example 4776.Ql MouseDown1Status . 4777.Pp 4778The special token 4779.Ql {mouse} 4780or 4781.Ql = 4782may be used as 4783.Ar target-window 4784or 4785.Ar target-pane 4786in commands bound to mouse key bindings. 4787It resolves to the window or pane over which the mouse event took place 4788(for example, the window in the status line over which button 1 was released 4789for a 4790.Ql MouseUp1Status 4791binding, or the pane over which the wheel was scrolled for a 4792.Ql WheelDownPane 4793binding). 4794.Pp 4795The 4796.Ic send-keys 4797.Fl M 4798flag may be used to forward a mouse event to a pane. 4799.Pp 4800The default key bindings allow the mouse to be used to select and resize panes, 4801to copy text and to change window using the status line. 4802These take effect if the 4803.Ic mouse 4804option is turned on. 4805.Sh FORMATS 4806Certain commands accept the 4807.Fl F 4808flag with a 4809.Ar format 4810argument. 4811This is a string which controls the output format of the command. 4812Format variables are enclosed in 4813.Ql #{ 4814and 4815.Ql } , 4816for example 4817.Ql #{session_name} . 4818The possible variables are listed in the table below, or the name of a 4819.Nm 4820option may be used for an option's value. 4821Some variables have a shorter alias such as 4822.Ql #S ; 4823.Ql ## 4824is replaced by a single 4825.Ql # , 4826.Ql #, 4827by a 4828.Ql \&, 4829and 4830.Ql #} 4831by a 4832.Ql } . 4833.Pp 4834Conditionals are available by prefixing with 4835.Ql \&? 4836and separating two alternatives with a comma; 4837if the specified variable exists and is not zero, the first alternative 4838is chosen, otherwise the second is used. 4839For example 4840.Ql #{?session_attached,attached,not attached} 4841will include the string 4842.Ql attached 4843if the session is attached and the string 4844.Ql not attached 4845if it is unattached, or 4846.Ql #{?automatic-rename,yes,no} 4847will include 4848.Ql yes 4849if 4850.Ic automatic-rename 4851is enabled, or 4852.Ql no 4853if not. 4854Conditionals can be nested arbitrarily. 4855Inside a conditional, 4856.Ql \&, 4857and 4858.Ql } 4859must be escaped as 4860.Ql #, 4861and 4862.Ql #} , 4863unless they are part of a 4864.Ql #{...} 4865replacement. 4866For example: 4867.Bd -literal -offset indent 4868#{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W . 4869.Ed 4870.Pp 4871String comparisons may be expressed by prefixing two comma-separated 4872alternatives by 4873.Ql == , 4874.Ql != , 4875.Ql < , 4876.Ql > , 4877.Ql <= 4878or 4879.Ql >= 4880and a colon. 4881For example 4882.Ql #{==:#{host},myhost} 4883will be replaced by 4884.Ql 1 4885if running on 4886.Ql myhost , 4887otherwise by 4888.Ql 0 . 4889.Ql || 4890and 4891.Ql && 4892evaluate to true if either or both of two comma-separated alternatives are 4893true, for example 4894.Ql #{||:#{pane_in_mode},#{alternate_on}} . 4895.Pp 4896An 4897.Ql m 4898specifies an 4899.Xr fnmatch 3 4900or regular expression comparison. 4901The first argument is the pattern and the second the string to compare. 4902An optional argument specifies flags: 4903.Ql r 4904means the pattern is a regular expression instead of the default 4905.Xr fnmatch 3 4906pattern, and 4907.Ql i 4908means to ignore case. 4909For example: 4910.Ql #{m:*foo*,#{host}} 4911or 4912.Ql #{m/ri:^A,MYVAR} . 4913A 4914.Ql C 4915performs a search for an 4916.Xr fnmatch 3 4917pattern or regular expression in the pane content and evaluates to zero if not 4918found, or a line number if found. 4919Like 4920.Ql m , 4921an 4922.Ql r 4923flag means search for a regular expression and 4924.Ql i 4925ignores case. 4926For example: 4927.Ql #{C/r:^Start} 4928.Pp 4929Numeric operators may be performed by prefixing two comma-separated alternatives 4930with an 4931.Ql e 4932and an operator. 4933An optional 4934.Ql f 4935flag may be given after the operator to use floating point numbers, otherwise 4936integers are used. 4937This may be followed by a number giving the number of decimal places to use for 4938the result. 4939The available operators are: 4940addition 4941.Ql + , 4942subtraction 4943.Ql - , 4944multiplication 4945.Ql * , 4946division 4947.Ql / , 4948modulus 4949.Ql m 4950or 4951.Ql % 4952(note that 4953.Ql % 4954must be escaped as 4955.Ql %% 4956in formats which are also expanded by 4957.Xr strftime 3 ) 4958and numeric comparison operators 4959.Ql == , 4960.Ql != , 4961.Ql < , 4962.Ql <= , 4963.Ql > 4964and 4965.Ql >= . 4966For example, 4967.Ql #{e|*|f|4:5.5,3} 4968multiplies 5.5 by 3 for a result with four decimal places and 4969.Ql #{e|%%:7,3} 4970returns the modulus of 7 and 3. 4971.Ql a 4972replaces a numeric argument by its ASCII equivalent, so 4973.Ql #{a:98} 4974results in 4975.Ql b . 4976.Ql c 4977replaces a 4978.Nm 4979colour by its six-digit hexadecimal RGB value. 4980.Pp 4981A limit may be placed on the length of the resultant string by prefixing it 4982by an 4983.Ql = , 4984a number and a colon. 4985Positive numbers count from the start of the string and negative from the end, 4986so 4987.Ql #{=5:pane_title} 4988will include at most the first five characters of the pane title, or 4989.Ql #{=-5:pane_title} 4990the last five characters. 4991A suffix or prefix may be given as a second argument - if provided then it is 4992appended or prepended to the string if the length has been trimmed, for example 4993.Ql #{=/5/...:pane_title} 4994will append 4995.Ql ... 4996if the pane title is more than five characters. 4997Similarly, 4998.Ql p 4999pads the string to a given width, for example 5000.Ql #{p10:pane_title} 5001will result in a width of at least 10 characters. 5002A positive width pads on the left, a negative on the right. 5003.Ql n 5004expands to the length of the variable and 5005.Ql w 5006to its width when displayed, for example 5007.Ql #{n:window_name} . 5008.Pp 5009Prefixing a time variable with 5010.Ql t:\& 5011will convert it to a string, so if 5012.Ql #{window_activity} 5013gives 5014.Ql 1445765102 , 5015.Ql #{t:window_activity} 5016gives 5017.Ql Sun Oct 25 09:25:02 2015 . 5018Adding 5019.Ql p ( 5020.Ql `t/p` ) 5021will use shorter but less accurate time format for times in the past. 5022A custom format may be given using an 5023.Ql f 5024suffix (note that 5025.Ql % 5026must be escaped as 5027.Ql %% 5028if the format is separately being passed through 5029.Xr strftime 3 , 5030for example in the 5031.Ic status-left 5032option): 5033.Ql #{t/f/%%H#:%%M:window_activity} , 5034see 5035.Xr strftime 3 . 5036.Pp 5037The 5038.Ql b:\& 5039and 5040.Ql d:\& 5041prefixes are 5042.Xr basename 3 5043and 5044.Xr dirname 3 5045of the variable respectively. 5046.Ql q:\& 5047will escape 5048.Xr sh 1 5049special characters or with a 5050.Ql h 5051suffix, escape hash characters (so 5052.Ql # 5053becomes 5054.Ql ## ) . 5055.Ql E:\& 5056will expand the format twice, for example 5057.Ql #{E:status-left} 5058is the result of expanding the content of the 5059.Ic status-left 5060option rather than the option itself. 5061.Ql T:\& 5062is like 5063.Ql E:\& 5064but also expands 5065.Xr strftime 3 5066specifiers. 5067.Ql S:\& , 5068.Ql W:\& , 5069.Ql P:\& 5070or 5071.Ql L:\& 5072will loop over each session, window, pane or client and insert the format once 5073for each. 5074For windows and panes, two comma-separated formats may be given: 5075the second is used for the current window or active pane. 5076For example, to get a list of windows formatted like the status line: 5077.Bd -literal -offset indent 5078#{W:#{E:window-status-format} ,#{E:window-status-current-format} } 5079.Ed 5080.Pp 5081.Ql N:\& 5082checks if a window (without any suffix or with the 5083.Ql w 5084suffix) or a session (with the 5085.Ql s 5086suffix) name exists, for example 5087.Ql `N/w:foo` 5088is replaced with 1 if a window named 5089.Ql foo 5090exists. 5091.Pp 5092A prefix of the form 5093.Ql s/foo/bar/:\& 5094will substitute 5095.Ql foo 5096with 5097.Ql bar 5098throughout. 5099The first argument may be an extended regular expression and a final argument 5100may be 5101.Ql i 5102to ignore case, for example 5103.Ql s/a(.)/\e1x/i:\& 5104would change 5105.Ql abABab 5106into 5107.Ql bxBxbx . 5108A different delimiter character may also be used, to avoid collisions with 5109literal slashes in the pattern. 5110For example, 5111.Ql s|foo/|bar/|:\& 5112will substitute 5113.Ql foo/ 5114with 5115.Ql bar/ 5116throughout. 5117.Pp 5118In addition, the last line of a shell command's output may be inserted using 5119.Ql #() . 5120For example, 5121.Ql #(uptime) 5122will insert the system's uptime. 5123When constructing formats, 5124.Nm 5125does not wait for 5126.Ql #() 5127commands to finish; instead, the previous result from running the same command 5128is used, or a placeholder if the command has not been run before. 5129If the command hasn't exited, the most recent line of output will be used, but 5130the status line will not be updated more than once a second. 5131Commands are executed using 5132.Pa /bin/sh 5133and with the 5134.Nm 5135global environment set (see the 5136.Sx GLOBAL AND SESSION ENVIRONMENT 5137section). 5138.Pp 5139An 5140.Ql l 5141specifies that a string should be interpreted literally and not expanded. 5142For example 5143.Ql #{l:#{?pane_in_mode,yes,no}} 5144will be replaced by 5145.Ql #{?pane_in_mode,yes,no} . 5146.Pp 5147The following variables are available, where appropriate: 5148.Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX" 5149.It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with" 5150.It Li "active_window_index" Ta "" Ta "Index of active window in session" 5151.It Li "alternate_on" Ta "" Ta "1 if pane is in alternate screen" 5152.It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen" 5153.It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen" 5154.It Li "buffer_created" Ta "" Ta "Time buffer created" 5155.It Li "buffer_name" Ta "" Ta "Name of buffer" 5156.It Li "buffer_sample" Ta "" Ta "Sample of start of buffer" 5157.It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes" 5158.It Li "client_activity" Ta "" Ta "Time client last had activity" 5159.It Li "client_cell_height" Ta "" Ta "Height of each client cell in pixels" 5160.It Li "client_cell_width" Ta "" Ta "Width of each client cell in pixels" 5161.It Li "client_control_mode" Ta "" Ta "1 if client is in control mode" 5162.It Li "client_created" Ta "" Ta "Time client created" 5163.It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind" 5164.It Li "client_flags" Ta "" Ta "List of client flags" 5165.It Li "client_height" Ta "" Ta "Height of client" 5166.It Li "client_key_table" Ta "" Ta "Current key table" 5167.It Li "client_last_session" Ta "" Ta "Name of the client's last session" 5168.It Li "client_name" Ta "" Ta "Name of client" 5169.It Li "client_pid" Ta "" Ta "PID of client process" 5170.It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed" 5171.It Li "client_readonly" Ta "" Ta "1 if client is read-only" 5172.It Li "client_session" Ta "" Ta "Name of the client's session" 5173.It Li "client_termfeatures" Ta "" Ta "Terminal features of client, if any" 5174.It Li "client_termname" Ta "" Ta "Terminal name of client" 5175.It Li "client_termtype" Ta "" Ta "Terminal type of client, if available" 5176.It Li "client_tty" Ta "" Ta "Pseudo terminal of client" 5177.It Li "client_uid" Ta "" Ta "UID of client process" 5178.It Li "client_user" Ta "" Ta "User of client process" 5179.It Li "client_utf8" Ta "" Ta "1 if client supports UTF-8" 5180.It Li "client_width" Ta "" Ta "Width of client" 5181.It Li "client_written" Ta "" Ta "Bytes written to client" 5182.It Li "command" Ta "" Ta "Name of command in use, if any" 5183.It Li "command_list_alias" Ta "" Ta "Command alias if listing commands" 5184.It Li "command_list_name" Ta "" Ta "Command name if listing commands" 5185.It Li "command_list_usage" Ta "" Ta "Command usage if listing commands" 5186.It Li "config_files" Ta "" Ta "List of configuration files loaded" 5187.It Li "copy_cursor_line" Ta "" Ta "Line the cursor is on in copy mode" 5188.It Li "copy_cursor_word" Ta "" Ta "Word under cursor in copy mode" 5189.It Li "copy_cursor_x" Ta "" Ta "Cursor X position in copy mode" 5190.It Li "copy_cursor_y" Ta "" Ta "Cursor Y position in copy mode" 5191.It Li "current_file" Ta "" Ta "Current configuration file" 5192.It Li "cursor_character" Ta "" Ta "Character at cursor in pane" 5193.It Li "cursor_flag" Ta "" Ta "Pane cursor flag" 5194.It Li "cursor_x" Ta "" Ta "Cursor X position in pane" 5195.It Li "cursor_y" Ta "" Ta "Cursor Y position in pane" 5196.It Li "history_bytes" Ta "" Ta "Number of bytes in window history" 5197.It Li "history_limit" Ta "" Ta "Maximum window history lines" 5198.It Li "history_size" Ta "" Ta "Size of history in lines" 5199.It Li "hook" Ta "" Ta "Name of running hook, if any" 5200.It Li "hook_client" Ta "" Ta "Name of client where hook was run, if any" 5201.It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any" 5202.It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any" 5203.It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any" 5204.It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any" 5205.It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any" 5206.It Li "host" Ta "#H" Ta "Hostname of local host" 5207.It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)" 5208.It Li "insert_flag" Ta "" Ta "Pane insert flag" 5209.It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag" 5210.It Li "keypad_flag" Ta "" Ta "Pane keypad flag" 5211.It Li "last_window_index" Ta "" Ta "Index of last window in session" 5212.It Li "line" Ta "" Ta "Line number in the list" 5213.It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag" 5214.It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag" 5215.It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag" 5216.It Li "mouse_hyperlink" Ta "" Ta "Hyperlink under mouse, if any" 5217.It Li "mouse_line" Ta "" Ta "Line under mouse, if any" 5218.It Li "mouse_sgr_flag" Ta "" Ta "Pane mouse SGR flag" 5219.It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag" 5220.It Li "mouse_utf8_flag" Ta "" Ta "Pane mouse UTF-8 flag" 5221.It Li "mouse_word" Ta "" Ta "Word under mouse, if any" 5222.It Li "mouse_x" Ta "" Ta "Mouse X position, if any" 5223.It Li "mouse_y" Ta "" Ta "Mouse Y position, if any" 5224.It Li "next_session_id" Ta "" Ta "Unique session ID for next new session" 5225.It Li "origin_flag" Ta "" Ta "Pane origin flag" 5226.It Li "pane_active" Ta "" Ta "1 if active pane" 5227.It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window" 5228.It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window" 5229.It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window" 5230.It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window" 5231.It Li "pane_bg" Ta "" Ta "Pane background colour" 5232.It Li "pane_bottom" Ta "" Ta "Bottom of pane" 5233.It Li "pane_current_command" Ta "" Ta "Current command if available" 5234.It Li "pane_current_path" Ta "" Ta "Current path if available" 5235.It Li "pane_dead" Ta "" Ta "1 if pane is dead" 5236.It Li "pane_dead_signal" Ta "" Ta "Exit signal of process in dead pane" 5237.It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane" 5238.It Li "pane_dead_time" Ta "" Ta "Exit time of process in dead pane" 5239.It Li "pane_fg" Ta "" Ta "Pane foreground colour" 5240.It Li "pane_format" Ta "" Ta "1 if format is for a pane" 5241.It Li "pane_height" Ta "" Ta "Height of pane" 5242.It Li "pane_id" Ta "#D" Ta "Unique pane ID" 5243.It Li "pane_in_mode" Ta "" Ta "1 if pane is in a mode" 5244.It Li "pane_index" Ta "#P" Ta "Index of pane" 5245.It Li "pane_input_off" Ta "" Ta "1 if input to pane is disabled" 5246.It Li "pane_last" Ta "" Ta "1 if last pane" 5247.It Li "pane_left" Ta "" Ta "Left of pane" 5248.It Li "pane_marked" Ta "" Ta "1 if this is the marked pane" 5249.It Li "pane_marked_set" Ta "" Ta "1 if a marked pane is set" 5250.It Li "pane_mode" Ta "" Ta "Name of pane mode, if any" 5251.It Li "pane_path" Ta "" Ta "Path of pane (can be set by application)" 5252.It Li "pane_pid" Ta "" Ta "PID of first process in pane" 5253.It Li "pane_pipe" Ta "" Ta "1 if pane is being piped" 5254.It Li "pane_right" Ta "" Ta "Right of pane" 5255.It Li "pane_search_string" Ta "" Ta "Last search string in copy mode" 5256.It Li "pane_start_command" Ta "" Ta "Command pane started with" 5257.It Li "pane_start_path" Ta "" Ta "Path pane started with" 5258.It Li "pane_synchronized" Ta "" Ta "1 if pane is synchronized" 5259.It Li "pane_tabs" Ta "" Ta "Pane tab positions" 5260.It Li "pane_title" Ta "#T" Ta "Title of pane (can be set by application)" 5261.It Li "pane_top" Ta "" Ta "Top of pane" 5262.It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane" 5263.It Li "pane_unseen_changes" Ta "" Ta "1 if there were changes in pane while in mode" 5264.It Li "pane_width" Ta "" Ta "Width of pane" 5265.It Li "pid" Ta "" Ta "Server PID" 5266.It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated" 5267.It Li "scroll_position" Ta "" Ta "Scroll position in copy mode" 5268.It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane" 5269.It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane" 5270.It Li "search_match" Ta "" Ta "Search match if any" 5271.It Li "search_present" Ta "" Ta "1 if search started in copy mode" 5272.It Li "selection_active" Ta "" Ta "1 if selection started and changes with the cursor in copy mode" 5273.It Li "selection_end_x" Ta "" Ta "X position of the end of the selection" 5274.It Li "selection_end_y" Ta "" Ta "Y position of the end of the selection" 5275.It Li "selection_present" Ta "" Ta "1 if selection started in copy mode" 5276.It Li "selection_start_x" Ta "" Ta "X position of the start of the selection" 5277.It Li "selection_start_y" Ta "" Ta "Y position of the start of the selection" 5278.It Li "server_sessions" Ta "" Ta "Number of sessions" 5279.It Li "session_activity" Ta "" Ta "Time of session last activity" 5280.It Li "session_alerts" Ta "" Ta "List of window indexes with alerts" 5281.It Li "session_attached" Ta "" Ta "Number of clients session is attached to" 5282.It Li "session_attached_list" Ta "" Ta "List of clients session is attached to" 5283.It Li "session_created" Ta "" Ta "Time session created" 5284.It Li "session_format" Ta "" Ta "1 if format is for a session" 5285.It Li "session_group" Ta "" Ta "Name of session group" 5286.It Li "session_group_attached" Ta "" Ta "Number of clients sessions in group are attached to" 5287.It Li "session_group_attached_list" Ta "" Ta "List of clients sessions in group are attached to" 5288.It Li "session_group_list" Ta "" Ta "List of sessions in group" 5289.It Li "session_group_many_attached" Ta "" Ta "1 if multiple clients attached to sessions in group" 5290.It Li "session_group_size" Ta "" Ta "Size of session group" 5291.It Li "session_grouped" Ta "" Ta "1 if session in a group" 5292.It Li "session_id" Ta "" Ta "Unique session ID" 5293.It Li "session_last_attached" Ta "" Ta "Time session last attached" 5294.It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached" 5295.It Li "session_marked" Ta "" Ta "1 if this session contains the marked pane" 5296.It Li "session_name" Ta "#S" Ta "Name of session" 5297.It Li "session_path" Ta "" Ta "Working directory of session" 5298.It Li "session_stack" Ta "" Ta "Window indexes in most recent order" 5299.It Li "session_windows" Ta "" Ta "Number of windows in session" 5300.It Li "socket_path" Ta "" Ta "Server socket path" 5301.It Li "start_time" Ta "" Ta "Server start time" 5302.It Li "uid" Ta "" Ta "Server UID" 5303.It Li "user" Ta "" Ta "Server user" 5304.It Li "version" Ta "" Ta "Server version" 5305.It Li "window_active" Ta "" Ta "1 if window active" 5306.It Li "window_active_clients" Ta "" Ta "Number of clients viewing this window" 5307.It Li "window_active_clients_list" Ta "" Ta "List of clients viewing this window" 5308.It Li "window_active_sessions" Ta "" Ta "Number of sessions on which this window is active" 5309.It Li "window_active_sessions_list" Ta "" Ta "List of sessions on which this window is active" 5310.It Li "window_activity" Ta "" Ta "Time of window last activity" 5311.It Li "window_activity_flag" Ta "" Ta "1 if window has activity" 5312.It Li "window_bell_flag" Ta "" Ta "1 if window has bell" 5313.It Li "window_bigger" Ta "" Ta "1 if window is larger than client" 5314.It Li "window_cell_height" Ta "" Ta "Height of each cell in pixels" 5315.It Li "window_cell_width" Ta "" Ta "Width of each cell in pixels" 5316.It Li "window_end_flag" Ta "" Ta "1 if window has the highest index" 5317.It Li "window_flags" Ta "#F" Ta "Window flags with # escaped as ##" 5318.It Li "window_format" Ta "" Ta "1 if format is for a window" 5319.It Li "window_height" Ta "" Ta "Height of window" 5320.It Li "window_id" Ta "" Ta "Unique window ID" 5321.It Li "window_index" Ta "#I" Ta "Index of window" 5322.It Li "window_last_flag" Ta "" Ta "1 if window is the last used" 5323.It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes" 5324.It Li "window_linked" Ta "" Ta "1 if window is linked across sessions" 5325.It Li "window_linked_sessions" Ta "" Ta "Number of sessions this window is linked to" 5326.It Li "window_linked_sessions_list" Ta "" Ta "List of sessions this window is linked to" 5327.It Li "window_marked_flag" Ta "" Ta "1 if window contains the marked pane" 5328.It Li "window_name" Ta "#W" Ta "Name of window" 5329.It Li "window_offset_x" Ta "" Ta "X offset into window if larger than client" 5330.It Li "window_offset_y" Ta "" Ta "Y offset into window if larger than client" 5331.It Li "window_panes" Ta "" Ta "Number of panes in window" 5332.It Li "window_raw_flags" Ta "" Ta "Window flags with nothing escaped" 5333.It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert" 5334.It Li "window_stack_index" Ta "" Ta "Index in session most recent stack" 5335.It Li "window_start_flag" Ta "" Ta "1 if window has the lowest index" 5336.It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes" 5337.It Li "window_width" Ta "" Ta "Width of window" 5338.It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed" 5339.It Li "wrap_flag" Ta "" Ta "Pane wrap flag" 5340.El 5341.Sh STYLES 5342.Nm 5343offers various options to specify the colour and attributes of aspects of the 5344interface, for example 5345.Ic status-style 5346for the status line. 5347In addition, embedded styles may be specified in format options, such as 5348.Ic status-left , 5349by enclosing them in 5350.Ql #[ 5351and 5352.Ql \&] . 5353.Pp 5354A style may be the single term 5355.Ql default 5356to specify the default style (which may come from an option, for example 5357.Ic status-style 5358in the status line) or a space 5359or comma separated list of the following: 5360.Bl -tag -width Ds 5361.It Ic fg=colour 5362Set the foreground colour. 5363The colour is one of: 5364.Ic black , 5365.Ic red , 5366.Ic green , 5367.Ic yellow , 5368.Ic blue , 5369.Ic magenta , 5370.Ic cyan , 5371.Ic white ; 5372if supported the bright variants 5373.Ic brightred , 5374.Ic brightgreen , 5375.Ic brightyellow ; 5376.Ic colour0 5377to 5378.Ic colour255 5379from the 256-colour set; 5380.Ic default 5381for the default colour; 5382.Ic terminal 5383for the terminal default colour; or a hexadecimal RGB string such as 5384.Ql #ffffff . 5385.It Ic bg=colour 5386Set the background colour. 5387.It Ic none 5388Set no attributes (turn off any active attributes). 5389.It Xo Ic acs , 5390.Ic bright 5391(or 5392.Ic bold ) , 5393.Ic dim , 5394.Ic underscore , 5395.Ic blink , 5396.Ic reverse , 5397.Ic hidden , 5398.Ic italics , 5399.Ic overline , 5400.Ic strikethrough , 5401.Ic double-underscore , 5402.Ic curly-underscore , 5403.Ic dotted-underscore , 5404.Ic dashed-underscore 5405.Xc 5406Set an attribute. 5407Any of the attributes may be prefixed with 5408.Ql no 5409to unset. 5410.Ic acs 5411is the terminal alternate character set. 5412.It Xo Ic align=left 5413(or 5414.Ic noalign ) , 5415.Ic align=centre , 5416.Ic align=right 5417.Xc 5418Align text to the left, centre or right of the available space if appropriate. 5419.It Ic fill=colour 5420Fill the available space with a background colour if appropriate. 5421.It Xo Ic list=on , 5422.Ic list=focus , 5423.Ic list=left-marker , 5424.Ic list=right-marker , 5425.Ic nolist 5426.Xc 5427Mark the position of the various window list components in the 5428.Ic status-format 5429option: 5430.Ic list=on 5431marks the start of the list; 5432.Ic list=focus 5433is the part of the list that should be kept in focus if the entire list won't 5434fit in the available space (typically the current window); 5435.Ic list=left-marker 5436and 5437.Ic list=right-marker 5438mark the text to be used to mark that text has been trimmed from the left or 5439right of the list if there is not enough space. 5440.It Xo Ic push-default , 5441.Ic pop-default 5442.Xc 5443Store the current colours and attributes as the default or reset to the previous 5444default. 5445A 5446.Ic push-default 5447affects any subsequent use of the 5448.Ic default 5449term until a 5450.Ic pop-default . 5451Only one default may be pushed (each 5452.Ic push-default 5453replaces the previous saved default). 5454.It Xo Ic range=left , 5455.Ic range=right , 5456.Ic range=window|X , 5457.Ic norange 5458.Xc 5459Mark a range in the 5460.Ic status-format 5461option. 5462.Ic range=left 5463and 5464.Ic range=right 5465are the text used for the 5466.Ql StatusLeft 5467and 5468.Ql StatusRight 5469mouse keys. 5470.Ic range=window|X 5471is the range for a window passed to the 5472.Ql Status 5473mouse key, where 5474.Ql X 5475is a window index. 5476.El 5477.Pp 5478Examples are: 5479.Bd -literal -offset indent 5480fg=yellow bold underscore blink 5481bg=black,fg=default,noreverse 5482.Ed 5483.Sh NAMES AND TITLES 5484.Nm 5485distinguishes between names and titles. 5486Windows and sessions have names, which may be used to specify them in targets 5487and are displayed in the status line and various lists: the name is the 5488.Nm 5489identifier for a window or session. 5490Only panes have titles. 5491A pane's title is typically set by the program running inside the pane using 5492an escape sequence (like it would set the 5493.Xr xterm 1 5494window title in 5495.Xr X 7 ) . 5496Windows themselves do not have titles - a window's title is the title of its 5497active pane. 5498.Nm 5499itself may set the title of the terminal in which the client is running, see 5500the 5501.Ic set-titles 5502option. 5503.Pp 5504A session's name is set with the 5505.Ic new-session 5506and 5507.Ic rename-session 5508commands. 5509A window's name is set with one of: 5510.Bl -enum -width Ds 5511.It 5512A command argument (such as 5513.Fl n 5514for 5515.Ic new-window 5516or 5517.Ic new-session ) . 5518.It 5519An escape sequence (if the 5520.Ic allow-rename 5521option is turned on): 5522.Bd -literal -offset indent 5523$ printf '\e033kWINDOW_NAME\e033\e\e' 5524.Ed 5525.It 5526Automatic renaming, which sets the name to the active command in the window's 5527active pane. 5528See the 5529.Ic automatic-rename 5530option. 5531.El 5532.Pp 5533When a pane is first created, its title is the hostname. 5534A pane's title can be set via the title setting escape sequence, for example: 5535.Bd -literal -offset indent 5536$ printf '\e033]2;My Title\e033\e\e' 5537.Ed 5538.Pp 5539It can also be modified with the 5540.Ic select-pane 5541.Fl T 5542command. 5543.Sh GLOBAL AND SESSION ENVIRONMENT 5544When the server is started, 5545.Nm 5546copies the environment into the 5547.Em global environment ; 5548in addition, each session has a 5549.Em session environment . 5550When a window is created, the session and global environments are merged. 5551If a variable exists in both, the value from the session environment is used. 5552The result is the initial environment passed to the new process. 5553.Pp 5554The 5555.Ic update-environment 5556session option may be used to update the session environment from the client 5557when a new session is created or an old reattached. 5558.Nm 5559also initialises the 5560.Ev TMUX 5561variable with some internal information to allow commands to be executed 5562from inside, and the 5563.Ev TERM 5564variable with the correct terminal setting of 5565.Ql screen . 5566.Pp 5567Variables in both session and global environments may be marked as hidden. 5568Hidden variables are not passed into the environment of new processes and 5569instead can only be used by tmux itself (for example in formats, see the 5570.Sx FORMATS 5571section). 5572.Pp 5573Commands to alter and view the environment are: 5574.Bl -tag -width Ds 5575.Tg setenv 5576.It Xo Ic set-environment 5577.Op Fl Fhgru 5578.Op Fl t Ar target-session 5579.Ar name Op Ar value 5580.Xc 5581.D1 Pq alias: Ic setenv 5582Set or unset an environment variable. 5583If 5584.Fl g 5585is used, the change is made in the global environment; otherwise, it is applied 5586to the session environment for 5587.Ar target-session . 5588If 5589.Fl F 5590is present, then 5591.Ar value 5592is expanded as a format. 5593The 5594.Fl u 5595flag unsets a variable. 5596.Fl r 5597indicates the variable is to be removed from the environment before starting a 5598new process. 5599.Fl h 5600marks the variable as hidden. 5601.Tg showenv 5602.It Xo Ic show-environment 5603.Op Fl hgs 5604.Op Fl t Ar target-session 5605.Op Ar variable 5606.Xc 5607.D1 Pq alias: Ic showenv 5608Display the environment for 5609.Ar target-session 5610or the global environment with 5611.Fl g . 5612If 5613.Ar variable 5614is omitted, all variables are shown. 5615Variables removed from the environment are prefixed with 5616.Ql - . 5617If 5618.Fl s 5619is used, the output is formatted as a set of Bourne shell commands. 5620.Fl h 5621shows hidden variables (omitted by default). 5622.El 5623.Sh STATUS LINE 5624.Nm 5625includes an optional status line which is displayed in the bottom line of each 5626terminal. 5627.Pp 5628By default, the status line is enabled and one line in height (it may be 5629disabled or made multiple lines with the 5630.Ic status 5631session option) and contains, from left-to-right: the name of the current 5632session in square brackets; the window list; the title of the active pane 5633in double quotes; and the time and date. 5634.Pp 5635Each line of the status line is configured with the 5636.Ic status-format 5637option. 5638The default is made of three parts: configurable left and right sections (which 5639may contain dynamic content such as the time or output from a shell command, 5640see the 5641.Ic status-left , 5642.Ic status-left-length , 5643.Ic status-right , 5644and 5645.Ic status-right-length 5646options below), and a central window list. 5647By default, the window list shows the index, name and (if any) flag of the 5648windows present in the current session in ascending numerical order. 5649It may be customised with the 5650.Ar window-status-format 5651and 5652.Ar window-status-current-format 5653options. 5654The flag is one of the following symbols appended to the window name: 5655.Bl -column "Symbol" "Meaning" -offset indent 5656.It Sy "Symbol" Ta Sy "Meaning" 5657.It Li "*" Ta "Denotes the current window." 5658.It Li "-" Ta "Marks the last window (previously selected)." 5659.It Li "#" Ta "Window activity is monitored and activity has been detected." 5660.It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window." 5661.It Li "~" Ta "The window has been silent for the monitor-silence interval." 5662.It Li "M" Ta "The window contains the marked pane." 5663.It Li "Z" Ta "The window's active pane is zoomed." 5664.El 5665.Pp 5666The # symbol relates to the 5667.Ic monitor-activity 5668window option. 5669The window name is printed in inverted colours if an alert (bell, activity or 5670silence) is present. 5671.Pp 5672The colour and attributes of the status line may be configured, the entire 5673status line using the 5674.Ic status-style 5675session option and individual windows using the 5676.Ic window-status-style 5677window option. 5678.Pp 5679The status line is automatically refreshed at interval if it has changed, the 5680interval may be controlled with the 5681.Ic status-interval 5682session option. 5683.Pp 5684Commands related to the status line are as follows: 5685.Bl -tag -width Ds 5686.Tg clearphist 5687.It Xo Ic clear-prompt-history 5688.Op Fl T Ar prompt-type 5689.Xc 5690.D1 Pq alias: Ic clearphist 5691Clear status prompt history for prompt type 5692.Ar prompt-type . 5693If 5694.Fl T 5695is omitted, then clear history for all types. 5696See 5697.Ic command-prompt 5698for possible values for 5699.Ar prompt-type . 5700.It Xo Ic command-prompt 5701.Op Fl 1bFikN 5702.Op Fl I Ar inputs 5703.Op Fl p Ar prompts 5704.Op Fl t Ar target-client 5705.Op Fl T Ar prompt-type 5706.Op Ar template 5707.Xc 5708Open the command prompt in a client. 5709This may be used from inside 5710.Nm 5711to execute commands interactively. 5712.Pp 5713If 5714.Ar template 5715is specified, it is used as the command. 5716With 5717.Fl F , 5718.Ar template 5719is expanded as a format. 5720.Pp 5721If present, 5722.Fl I 5723is a comma-separated list of the initial text for each prompt. 5724If 5725.Fl p 5726is given, 5727.Ar prompts 5728is a comma-separated list of prompts which are displayed in order; otherwise 5729a single prompt is displayed, constructed from 5730.Ar template 5731if it is present, or 5732.Ql \&: 5733if not. 5734.Pp 5735Before the command is executed, the first occurrence of the string 5736.Ql %% 5737and all occurrences of 5738.Ql %1 5739are replaced by the response to the first prompt, all 5740.Ql %2 5741are replaced with the response to the second prompt, and so on for further 5742prompts. 5743Up to nine prompt responses may be replaced 5744.Po 5745.Ql %1 5746to 5747.Ql %9 5748.Pc . 5749.Ql %%% 5750is like 5751.Ql %% 5752but any quotation marks are escaped. 5753.Pp 5754.Fl 1 5755makes the prompt only accept one key press, in this case the resulting input 5756is a single character. 5757.Fl k 5758is like 5759.Fl 1 5760but the key press is translated to a key name. 5761.Fl N 5762makes the prompt only accept numeric key presses. 5763.Fl i 5764executes the command every time the prompt input changes instead of when the 5765user exits the command prompt. 5766.Pp 5767.Fl T 5768tells 5769.Nm 5770the prompt type. 5771This affects what completions are offered when 5772.Em Tab 5773is pressed. 5774Available types are: 5775.Ql command , 5776.Ql search , 5777.Ql target 5778and 5779.Ql window-target . 5780.Pp 5781The following keys have a special meaning in the command prompt, depending 5782on the value of the 5783.Ic status-keys 5784option: 5785.Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent 5786.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" 5787.It Li "Cancel command prompt" Ta "q" Ta "Escape" 5788.It Li "Delete from cursor to start of word" Ta "" Ta "C-w" 5789.It Li "Delete entire command" Ta "d" Ta "C-u" 5790.It Li "Delete from cursor to end" Ta "D" Ta "C-k" 5791.It Li "Execute command" Ta "Enter" Ta "Enter" 5792.It Li "Get next command from history" Ta "" Ta "Down" 5793.It Li "Get previous command from history" Ta "" Ta "Up" 5794.It Li "Insert top paste buffer" Ta "p" Ta "C-y" 5795.It Li "Look for completions" Ta "Tab" Ta "Tab" 5796.It Li "Move cursor left" Ta "h" Ta "Left" 5797.It Li "Move cursor right" Ta "l" Ta "Right" 5798.It Li "Move cursor to end" Ta "$" Ta "C-e" 5799.It Li "Move cursor to next word" Ta "w" Ta "M-f" 5800.It Li "Move cursor to previous word" Ta "b" Ta "M-b" 5801.It Li "Move cursor to start" Ta "0" Ta "C-a" 5802.It Li "Transpose characters" Ta "" Ta "C-t" 5803.El 5804.Pp 5805With 5806.Fl b , 5807the prompt is shown in the background and the invoking client does not exit 5808until it is dismissed. 5809.Tg confirm 5810.It Xo Ic confirm-before 5811.Op Fl by 5812.Op Fl c Ar confirm-key 5813.Op Fl p Ar prompt 5814.Op Fl t Ar target-client 5815.Ar command 5816.Xc 5817.D1 Pq alias: Ic confirm 5818Ask for confirmation before executing 5819.Ar command . 5820If 5821.Fl p 5822is given, 5823.Ar prompt 5824is the prompt to display; otherwise a prompt is constructed from 5825.Ar command . 5826It may contain the special character sequences supported by the 5827.Ic status-left 5828option. 5829With 5830.Fl b , 5831the prompt is shown in the background and the invoking client does not exit 5832until it is dismissed. 5833.Fl y 5834changes the default behaviour (if Enter alone is pressed) of the prompt to 5835run the command. 5836.Fl c 5837changes the confirmation key to 5838.Ar confirm-key ; 5839the default is 5840.Ql y . 5841.Tg menu 5842.It Xo Ic display-menu 5843.Op Fl O 5844.Op Fl c Ar target-client 5845.Op Fl t Ar target-pane 5846.Op Fl S Ar starting-choice 5847.Op Fl T Ar title 5848.Op Fl x Ar position 5849.Op Fl y Ar position 5850.Ar name 5851.Ar key 5852.Ar command Op Ar argument ... 5853.Xc 5854.D1 Pq alias: Ic menu 5855Display a menu on 5856.Ar target-client . 5857.Ar target-pane 5858gives the target for any commands run from the menu. 5859.Pp 5860A menu is passed as a series of arguments: first the menu item name, 5861second the key shortcut (or empty for none) and third the command 5862to run when the menu item is chosen. 5863The name and command are formats, see the 5864.Sx FORMATS 5865and 5866.Sx STYLES 5867sections. 5868If the name begins with a hyphen (-), then the item is disabled (shown dim) and 5869may not be chosen. 5870The name may be empty for a separator line, in which case both the key and 5871command should be omitted. 5872.Pp 5873.Fl T 5874is a format for the menu title (see 5875.Sx FORMATS ) . 5876.Fl S 5877sets the menu item selected by default, if the menu is not bound to a mouse key 5878binding. 5879.Pp 5880.Fl x 5881and 5882.Fl y 5883give the position of the menu. 5884Both may be a row or column number, or one of the following special values: 5885.Bl -column "XXXXX" "XXXX" -offset indent 5886.It Sy "Value" Ta Sy "Flag" Ta Sy "Meaning" 5887.It Li "C" Ta "Both" Ta "The centre of the terminal" 5888.It Li "R" Ta Fl x Ta "The right side of the terminal" 5889.It Li "P" Ta "Both" Ta "The bottom left of the pane" 5890.It Li "M" Ta "Both" Ta "The mouse position" 5891.It Li "W" Ta "Both" Ta "The window position on the status line" 5892.It Li "S" Ta Fl y Ta "The line above or below the status line" 5893.El 5894.Pp 5895Or a format, which is expanded including the following additional variables: 5896.Bl -column "XXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent 5897.It Sy "Variable name" Ta Sy "Replaced with" 5898.It Li "popup_centre_x" Ta "Centered in the client" 5899.It Li "popup_centre_y" Ta "Centered in the client" 5900.It Li "popup_height" Ta "Height of menu or popup" 5901.It Li "popup_mouse_bottom" Ta "Bottom of at the mouse" 5902.It Li "popup_mouse_centre_x" Ta "Horizontal centre at the mouse" 5903.It Li "popup_mouse_centre_y" Ta "Vertical centre at the mouse" 5904.It Li "popup_mouse_top" Ta "Top at the mouse" 5905.It Li "popup_mouse_x" Ta "Mouse X position" 5906.It Li "popup_mouse_y" Ta "Mouse Y position" 5907.It Li "popup_pane_bottom" Ta "Bottom of the pane" 5908.It Li "popup_pane_left" Ta "Left of the pane" 5909.It Li "popup_pane_right" Ta "Right of the pane" 5910.It Li "popup_pane_top" Ta "Top of the pane" 5911.It Li "popup_status_line_y" Ta "Above or below the status line" 5912.It Li "popup_width" Ta "Width of menu or popup" 5913.It Li "popup_window_status_line_x" Ta "At the window position in status line" 5914.It Li "popup_window_status_line_y" Ta "At the status line showing the window" 5915.El 5916.Pp 5917Each menu consists of items followed by a key shortcut shown in brackets. 5918If the menu is too large to fit on the terminal, it is not displayed. 5919Pressing the key shortcut chooses the corresponding item. 5920If the mouse is enabled and the menu is opened from a mouse key binding, 5921releasing the mouse button with an item selected chooses that item and 5922releasing the mouse button without an item selected closes the menu. 5923.Fl O 5924changes this behaviour so that the menu does not close when the mouse button is 5925released without an item selected the menu is not closed and a mouse button 5926must be clicked to choose an item. 5927.Pp 5928The following keys are also available: 5929.Bl -column "Key" "Function" -offset indent 5930.It Sy "Key" Ta Sy "Function" 5931.It Li "Enter" Ta "Choose selected item" 5932.It Li "Up" Ta "Select previous item" 5933.It Li "Down" Ta "Select next item" 5934.It Li "q" Ta "Exit menu" 5935.El 5936.Tg display 5937.It Xo Ic display-message 5938.Op Fl aIlNpv 5939.Op Fl c Ar target-client 5940.Op Fl d Ar delay 5941.Op Fl t Ar target-pane 5942.Op Ar message 5943.Xc 5944.D1 Pq alias: Ic display 5945Display a message. 5946If 5947.Fl p 5948is given, the output is printed to stdout, otherwise it is displayed in the 5949.Ar target-client 5950status line for up to 5951.Ar delay 5952milliseconds. 5953If 5954.Ar delay 5955is not given, the 5956.Ic display-time 5957option is used; a delay of zero waits for a key press. 5958.Ql N 5959ignores key presses and closes only after the delay expires. 5960If 5961.Fl l 5962is given, 5963.Ar message 5964is printed unchanged. 5965Otherwise, the format of 5966.Ar message 5967is described in the 5968.Sx FORMATS 5969section; information is taken from 5970.Ar target-pane 5971if 5972.Fl t 5973is given, otherwise the active pane. 5974.Pp 5975.Fl v 5976prints verbose logging as the format is parsed and 5977.Fl a 5978lists the format variables and their values. 5979.Pp 5980.Fl I 5981forwards any input read from stdin to the empty pane given by 5982.Ar target-pane . 5983.Tg popup 5984.It Xo Ic display-popup 5985.Op Fl BCE 5986.Op Fl b Ar border-lines 5987.Op Fl c Ar target-client 5988.Op Fl d Ar start-directory 5989.Op Fl e Ar environment 5990.Op Fl h Ar height 5991.Op Fl s Ar style 5992.Op Fl S Ar border-style 5993.Op Fl t Ar target-pane 5994.Op Fl T Ar title 5995.Op Fl w Ar width 5996.Op Fl x Ar position 5997.Op Fl y Ar position 5998.Op Ar shell-command 5999.Xc 6000.D1 Pq alias: Ic popup 6001Display a popup running 6002.Ar shell-command 6003on 6004.Ar target-client . 6005A popup is a rectangular box drawn over the top of any panes. 6006Panes are not updated while a popup is present. 6007.Pp 6008.Fl E 6009closes the popup automatically when 6010.Ar shell-command 6011exits. 6012Two 6013.Fl E 6014closes the popup only if 6015.Ar shell-command 6016exited with success. 6017.Pp 6018.Fl x 6019and 6020.Fl y 6021give the position of the popup, they have the same meaning as for the 6022.Ic display-menu 6023command. 6024.Fl w 6025and 6026.Fl h 6027give the width and height - both may be a percentage (followed by 6028.Ql % ) . 6029If omitted, half of the terminal size is used. 6030.Pp 6031.Fl B 6032does not surround the popup by a border. 6033.Pp 6034.Fl b 6035sets the type of border line for the popup. 6036When 6037.Fl B 6038is specified, the 6039.Fl b 6040option is ignored. 6041See 6042.Ic popup-border-lines 6043for possible values for 6044.Ar border-lines . 6045.Pp 6046.Fl s 6047sets the style for the popup and 6048.Fl S 6049sets the style for the popup border. 6050For how to specify 6051.Ar style , 6052see the 6053.Sx STYLES 6054section. 6055.Pp 6056.Fl e 6057takes the form 6058.Ql VARIABLE=value 6059and sets an environment variable for the popup; it may be specified multiple 6060times. 6061.Pp 6062.Fl T 6063is a format for the popup title (see 6064.Sx FORMATS ) . 6065.Pp 6066The 6067.Fl C 6068flag closes any popup on the client. 6069.Tg showphist 6070.It Xo Ic show-prompt-history 6071.Op Fl T Ar prompt-type 6072.Xc 6073.D1 Pq alias: Ic showphist 6074Display status prompt history for prompt type 6075.Ar prompt-type . 6076If 6077.Fl T 6078is omitted, then show history for all types. 6079See 6080.Ic command-prompt 6081for possible values for 6082.Ar prompt-type . 6083.El 6084.Sh BUFFERS 6085.Nm 6086maintains a set of named 6087.Em paste buffers . 6088Each buffer may be either explicitly or automatically named. 6089Explicitly named buffers are named when created with the 6090.Ic set-buffer 6091or 6092.Ic load-buffer 6093commands, or by renaming an automatically named buffer with 6094.Ic set-buffer 6095.Fl n . 6096Automatically named buffers are given a name such as 6097.Ql buffer0001 , 6098.Ql buffer0002 6099and so on. 6100When the 6101.Ic buffer-limit 6102option is reached, the oldest automatically named buffer is deleted. 6103Explicitly named buffers are not subject to 6104.Ic buffer-limit 6105and may be deleted with the 6106.Ic delete-buffer 6107command. 6108.Pp 6109Buffers may be added using 6110.Ic copy-mode 6111or the 6112.Ic set-buffer 6113and 6114.Ic load-buffer 6115commands, and pasted into a window using the 6116.Ic paste-buffer 6117command. 6118If a buffer command is used and no buffer is specified, the most 6119recently added automatically named buffer is assumed. 6120.Pp 6121A configurable history buffer is also maintained for each window. 6122By default, up to 2000 lines are kept; this can be altered with the 6123.Ic history-limit 6124option (see the 6125.Ic set-option 6126command above). 6127.Pp 6128The buffer commands are as follows: 6129.Bl -tag -width Ds 6130.It Xo 6131.Ic choose-buffer 6132.Op Fl NZr 6133.Op Fl F Ar format 6134.Op Fl f Ar filter 6135.Op Fl K Ar key-format 6136.Op Fl O Ar sort-order 6137.Op Fl t Ar target-pane 6138.Op Ar template 6139.Xc 6140Put a pane into buffer mode, where a buffer may be chosen interactively from 6141a list. 6142Each buffer is shown on one line. 6143A shortcut key is shown on the left in brackets allowing for immediate choice, 6144or the list may be navigated and an item chosen or otherwise manipulated using 6145the keys below. 6146.Fl Z 6147zooms the pane. 6148The following keys may be used in buffer mode: 6149.Bl -column "Key" "Function" -offset indent 6150.It Sy "Key" Ta Sy "Function" 6151.It Li "Enter" Ta "Paste selected buffer" 6152.It Li "Up" Ta "Select previous buffer" 6153.It Li "Down" Ta "Select next buffer" 6154.It Li "C-s" Ta "Search by name or content" 6155.It Li "n" Ta "Repeat last search" 6156.It Li "t" Ta "Toggle if buffer is tagged" 6157.It Li "T" Ta "Tag no buffers" 6158.It Li "C-t" Ta "Tag all buffers" 6159.It Li "p" Ta "Paste selected buffer" 6160.It Li "P" Ta "Paste tagged buffers" 6161.It Li "d" Ta "Delete selected buffer" 6162.It Li "D" Ta "Delete tagged buffers" 6163.It Li "e" Ta "Open the buffer in an editor" 6164.It Li "f" Ta "Enter a format to filter items" 6165.It Li "O" Ta "Change sort field" 6166.It Li "r" Ta "Reverse sort order" 6167.It Li "v" Ta "Toggle preview" 6168.It Li "q" Ta "Exit mode" 6169.El 6170.Pp 6171After a buffer is chosen, 6172.Ql %% 6173is replaced by the buffer name in 6174.Ar template 6175and the result executed as a command. 6176If 6177.Ar template 6178is not given, "paste-buffer -b '%%'" is used. 6179.Pp 6180.Fl O 6181specifies the initial sort field: one of 6182.Ql time 6183(creation), 6184.Ql name 6185or 6186.Ql size . 6187.Fl r 6188reverses the sort order. 6189.Fl f 6190specifies an initial filter: the filter is a format - if it evaluates to zero, 6191the item in the list is not shown, otherwise it is shown. 6192If a filter would lead to an empty list, it is ignored. 6193.Fl F 6194specifies the format for each item in the list and 6195.Fl K 6196a format for each shortcut key; both are evaluated once for each line. 6197.Fl N 6198starts without the preview. 6199This command works only if at least one client is attached. 6200.Tg clearhist 6201.It Xo Ic clear-history 6202.Op Fl H 6203.Op Fl t Ar target-pane 6204.Xc 6205.D1 Pq alias: Ic clearhist 6206Remove and free the history for the specified pane. 6207.Fl H 6208also removes all hyperlinks. 6209.Tg deleteb 6210.It Ic delete-buffer Op Fl b Ar buffer-name 6211.D1 Pq alias: Ic deleteb 6212Delete the buffer named 6213.Ar buffer-name , 6214or the most recently added automatically named buffer if not specified. 6215.Tg lsb 6216.It Xo Ic list-buffers 6217.Op Fl F Ar format 6218.Op Fl f Ar filter 6219.Xc 6220.D1 Pq alias: Ic lsb 6221List the global buffers. 6222.Fl F 6223specifies the format of each line and 6224.Fl f 6225a filter. 6226Only buffers for which the filter is true are shown. 6227See the 6228.Sx FORMATS 6229section. 6230.It Xo Ic load-buffer 6231.Op Fl w 6232.Op Fl b Ar buffer-name 6233.Op Fl t Ar target-client 6234.Ar path 6235.Xc 6236.Tg loadb 6237.D1 Pq alias: Ic loadb 6238Load the contents of the specified paste buffer from 6239.Ar path . 6240If 6241.Fl w 6242is given, the buffer is also sent to the clipboard for 6243.Ar target-client 6244using the 6245.Xr xterm 1 6246escape sequence, if possible. 6247.Tg pasteb 6248.It Xo Ic paste-buffer 6249.Op Fl dpr 6250.Op Fl b Ar buffer-name 6251.Op Fl s Ar separator 6252.Op Fl t Ar target-pane 6253.Xc 6254.D1 Pq alias: Ic pasteb 6255Insert the contents of a paste buffer into the specified pane. 6256If not specified, paste into the current one. 6257With 6258.Fl d , 6259also delete the paste buffer. 6260When output, any linefeed (LF) characters in the paste buffer are replaced with 6261a separator, by default carriage return (CR). 6262A custom separator may be specified using the 6263.Fl s 6264flag. 6265The 6266.Fl r 6267flag means to do no replacement (equivalent to a separator of LF). 6268If 6269.Fl p 6270is specified, paste bracket control codes are inserted around the 6271buffer if the application has requested bracketed paste mode. 6272.Tg saveb 6273.It Xo Ic save-buffer 6274.Op Fl a 6275.Op Fl b Ar buffer-name 6276.Ar path 6277.Xc 6278.D1 Pq alias: Ic saveb 6279Save the contents of the specified paste buffer to 6280.Ar path . 6281The 6282.Fl a 6283option appends to rather than overwriting the file. 6284.It Xo Ic set-buffer 6285.Op Fl aw 6286.Op Fl b Ar buffer-name 6287.Op Fl t Ar target-client 6288.Tg setb 6289.Op Fl n Ar new-buffer-name 6290.Ar data 6291.Xc 6292.D1 Pq alias: Ic setb 6293Set the contents of the specified buffer to 6294.Ar data . 6295If 6296.Fl w 6297is given, the buffer is also sent to the clipboard for 6298.Ar target-client 6299using the 6300.Xr xterm 1 6301escape sequence, if possible. 6302The 6303.Fl a 6304option appends to rather than overwriting the buffer. 6305The 6306.Fl n 6307option renames the buffer to 6308.Ar new-buffer-name . 6309.Tg showb 6310.It Xo Ic show-buffer 6311.Op Fl b Ar buffer-name 6312.Xc 6313.D1 Pq alias: Ic showb 6314Display the contents of the specified buffer. 6315.El 6316.Sh MISCELLANEOUS 6317Miscellaneous commands are as follows: 6318.Bl -tag -width Ds 6319.It Ic clock-mode Op Fl t Ar target-pane 6320Display a large clock. 6321.Tg if 6322.It Xo Ic if-shell 6323.Op Fl bF 6324.Op Fl t Ar target-pane 6325.Ar shell-command command 6326.Op Ar command 6327.Xc 6328.D1 Pq alias: Ic if 6329Execute the first 6330.Ar command 6331if 6332.Ar shell-command 6333(run with 6334.Pa /bin/sh ) 6335returns success or the second 6336.Ar command 6337otherwise. 6338Before being executed, 6339.Ar shell-command 6340is expanded using the rules specified in the 6341.Sx FORMATS 6342section, including those relevant to 6343.Ar target-pane . 6344With 6345.Fl b , 6346.Ar shell-command 6347is run in the background. 6348.Pp 6349If 6350.Fl F 6351is given, 6352.Ar shell-command 6353is not executed but considered success if neither empty nor zero (after formats 6354are expanded). 6355.Tg lock 6356.It Ic lock-server 6357.D1 Pq alias: Ic lock 6358Lock each client individually by running the command specified by the 6359.Ic lock-command 6360option. 6361.Tg run 6362.It Xo Ic run-shell 6363.Op Fl bC 6364.Op Fl d Ar delay 6365.Op Fl t Ar target-pane 6366.Op Ar shell-command 6367.Xc 6368.D1 Pq alias: Ic run 6369Execute 6370.Ar shell-command 6371using 6372.Pa /bin/sh 6373or (with 6374.Fl C ) 6375a 6376.Nm 6377command in the background without creating a window. 6378Before being executed, 6379.Ar shell-command 6380is expanded using the rules specified in the 6381.Sx FORMATS 6382section. 6383With 6384.Fl b , 6385the command is run in the background. 6386.Fl d 6387waits for 6388.Ar delay 6389seconds before starting the command. 6390If 6391.Fl C 6392is not given, any output to stdout is displayed in view mode (in the pane 6393specified by 6394.Fl t 6395or the current pane if omitted) after the command finishes. 6396If the command fails, the exit status is also displayed. 6397.Tg wait 6398.It Xo Ic wait-for 6399.Op Fl L | S | U 6400.Ar channel 6401.Xc 6402.D1 Pq alias: Ic wait 6403When used without options, prevents the client from exiting until woken using 6404.Ic wait-for 6405.Fl S 6406with the same channel. 6407When 6408.Fl L 6409is used, the channel is locked and any clients that try to lock the same 6410channel are made to wait until the channel is unlocked with 6411.Ic wait-for 6412.Fl U . 6413.El 6414.Sh EXIT MESSAGES 6415When a 6416.Nm 6417client detaches, it prints a message. 6418This may be one of: 6419.Bl -tag -width Ds 6420.It detached (from session ...) 6421The client was detached normally. 6422.It detached and SIGHUP 6423The client was detached and its parent sent the 6424.Dv SIGHUP 6425signal (for example with 6426.Ic detach-client 6427.Fl P ) . 6428.It lost tty 6429The client's 6430.Xr tty 4 6431or 6432.Xr pty 4 6433was unexpectedly destroyed. 6434.It terminated 6435The client was killed with 6436.Dv SIGTERM . 6437.It too far behind 6438The client is in control mode and became unable to keep up with the data from 6439.Nm . 6440.It exited 6441The server exited when it had no sessions. 6442.It server exited 6443The server exited when it received 6444.Dv SIGTERM . 6445.It server exited unexpectedly 6446The server crashed or otherwise exited without telling the client the reason. 6447.El 6448.Sh TERMINFO EXTENSIONS 6449.Nm 6450understands some unofficial extensions to 6451.Xr terminfo 5 . 6452It is not normally necessary to set these manually, instead the 6453.Ic terminal-features 6454option should be used. 6455.Bl -tag -width Ds 6456.It Em \&AX 6457An existing extension that tells 6458.Nm 6459the terminal supports default colours. 6460.It Em \&Bidi 6461Tell 6462.Nm 6463that the terminal supports the VTE bidirectional text extensions. 6464.It Em \&Cs , Cr 6465Set the cursor colour. 6466The first takes a single string argument and is used to set the colour; 6467the second takes no arguments and restores the default cursor colour. 6468If set, a sequence such as this may be used 6469to change the cursor colour from inside 6470.Nm : 6471.Bd -literal -offset indent 6472$ printf '\e033]12;red\e033\e\e' 6473.Ed 6474.Pp 6475The colour is an 6476.Xr X 7 6477colour, see 6478.Xr XParseColor 3 . 6479.It Em \&Cmg, \&Clmg, \&Dsmg , \&Enmg 6480Set, clear, disable or enable DECSLRM margins. 6481These are set automatically if the terminal reports it is 6482.Em VT420 6483compatible. 6484.It Em \&Dsbp , \&Enbp 6485Disable and enable bracketed paste. 6486These are set automatically if the 6487.Em XT 6488capability is present. 6489.It Em \&Dseks , \&Eneks 6490Disable and enable extended keys. 6491.It Em \&Dsfcs , \&Enfcs 6492Disable and enable focus reporting. 6493These are set automatically if the 6494.Em XT 6495capability is present. 6496.It Em \&Hls 6497Set or clear a hyperlink annotation. 6498.It Em \&Nobr 6499Tell 6500.Nm 6501that the terminal does not use bright colors for bold display. 6502.It Em \&Rect 6503Tell 6504.Nm 6505that the terminal supports rectangle operations. 6506.It Em \&Smol 6507Enable the overline attribute. 6508.It Em \&Smulx 6509Set a styled underscore. 6510The single parameter is one of: 0 for no underscore, 1 for normal 6511underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted 6512underscore and 5 for dashed underscore. 6513.It Em \&Setulc , \&ol 6514Set the underscore colour or reset to the default. 6515The argument is (red * 65536) + (green * 256) + blue where each is between 0 6516and 255. 6517.It Em \&Ss , Se 6518Set or reset the cursor style. 6519If set, a sequence such as this may be used 6520to change the cursor to an underline: 6521.Bd -literal -offset indent 6522$ printf '\e033[4 q' 6523.Ed 6524.Pp 6525If 6526.Em Se 6527is not set, \&Ss with argument 0 will be used to reset the cursor style instead. 6528.It Em \&Swd 6529Set the opening sequence for the working directory notification. 6530The sequence is terminated using the standard 6531.Em fsl 6532capability. 6533.It Em \&Sxl 6534Indicates that the terminal supports SIXEL. 6535.It Em \&Sync 6536Start (parameter is 1) or end (parameter is 2) a synchronized update. 6537.It Em \&Tc 6538Indicate that the terminal supports the 6539.Ql direct colour 6540RGB escape sequence (for example, \ee[38;2;255;255;255m). 6541.Pp 6542If supported, this is used for the initialize colour escape sequence (which 6543may be enabled by adding the 6544.Ql initc 6545and 6546.Ql ccc 6547capabilities to the 6548.Nm 6549.Xr terminfo 5 6550entry). 6551.Pp 6552This is equivalent to the 6553.Em RGB 6554.Xr terminfo 5 6555capability. 6556.It Em \&Ms 6557Store the current buffer in the host terminal's selection (clipboard). 6558See the 6559.Em set-clipboard 6560option above and the 6561.Xr xterm 1 6562man page. 6563.It Em \&XT 6564This is an existing extension capability that tmux uses to mean that the 6565terminal supports the 6566.Xr xterm 1 6567title set sequences and to automatically set some of the capabilities above. 6568.El 6569.Sh CONTROL MODE 6570.Nm 6571offers a textual interface called 6572.Em control mode . 6573This allows applications to communicate with 6574.Nm 6575using a simple text-only protocol. 6576.Pp 6577In control mode, a client sends 6578.Nm 6579commands or command sequences terminated by newlines on standard input. 6580Each command will produce one block of output on standard output. 6581An output block consists of a 6582.Em %begin 6583line followed by the output (which may be empty). 6584The output block ends with a 6585.Em %end 6586or 6587.Em %error . 6588.Em %begin 6589and matching 6590.Em %end 6591or 6592.Em %error 6593have three arguments: an integer time (as seconds from epoch), command number 6594and flags (currently not used). 6595For example: 6596.Bd -literal -offset indent 6597%begin 1363006971 2 1 65980: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) 6599%end 1363006971 2 1 6600.Ed 6601.Pp 6602The 6603.Ic refresh-client 6604.Fl C 6605command may be used to set the size of a client in control mode. 6606.Pp 6607In control mode, 6608.Nm 6609outputs notifications. 6610A notification will never occur inside an output block. 6611.Pp 6612The following notifications are defined: 6613.Bl -tag -width Ds 6614.It Ic %client-detached Ar client 6615The client has detached. 6616.It Ic %client-session-changed Ar client session-id name 6617The client is now attached to the session with ID 6618.Ar session-id , 6619which is named 6620.Ar name . 6621.It Ic %config-error Ar error 6622An error has happened in a configuration file. 6623.It Ic %continue Ar pane-id 6624The pane has been continued after being paused (if the 6625.Ar pause-after 6626flag is set, see 6627.Ic refresh-client 6628.Fl A ) . 6629.It Ic %exit Op Ar reason 6630The 6631.Nm 6632client is exiting immediately, either because it is not attached to any session 6633or an error occurred. 6634If present, 6635.Ar reason 6636describes why the client exited. 6637.It Ic %extended-output Ar pane-id Ar age Ar ... \& : Ar value 6638New form of 6639.Ic %output 6640sent when the 6641.Ar pause-after 6642flag is set. 6643.Ar age 6644is the time in milliseconds for which tmux had buffered the output before it 6645was sent. 6646Any subsequent arguments up until a single 6647.Ql \&: 6648are for future use and should be ignored. 6649.It Xo Ic %layout-change 6650.Ar window-id 6651.Ar window-layout 6652.Ar window-visible-layout 6653.Ar window-flags 6654.Xc 6655The layout of a window with ID 6656.Ar window-id 6657changed. 6658The new layout is 6659.Ar window-layout . 6660The window's visible layout is 6661.Ar window-visible-layout 6662and the window flags are 6663.Ar window-flags . 6664.It Ic %message Ar message 6665A message sent with the 6666.Ic display-message 6667command. 6668.It Ic %output Ar pane-id Ar value 6669A window pane produced output. 6670.Ar value 6671escapes non-printable characters and backslash as octal \\xxx. 6672.It Ic %pane-mode-changed Ar pane-id 6673The pane with ID 6674.Ar pane-id 6675has changed mode. 6676.It Ic %paste-buffer-changed Ar name 6677Paste buffer 6678.Ar name 6679has been changed. 6680.It Ic %paste-buffer-deleted Ar name 6681Paste buffer 6682.Ar name 6683has been deleted. 6684.It Ic %pause Ar pane-id 6685The pane has been paused (if the 6686.Ar pause-after 6687flag is set). 6688.It Ic %session-changed Ar session-id Ar name 6689The client is now attached to the session with ID 6690.Ar session-id , 6691which is named 6692.Ar name . 6693.It Ic %session-renamed Ar name 6694The current session was renamed to 6695.Ar name . 6696.It Ic %session-window-changed Ar session-id Ar window-id 6697The session with ID 6698.Ar session-id 6699changed its active window to the window with ID 6700.Ar window-id . 6701.It Ic %sessions-changed 6702A session was created or destroyed. 6703.It Xo Ic %subscription-changed 6704.Ar name 6705.Ar session-id 6706.Ar window-id 6707.Ar window-index 6708.Ar pane-id ... \& : 6709.Ar value 6710.Xc 6711The value of the format associated with subscription 6712.Ar name 6713has changed to 6714.Ar value . 6715See 6716.Ic refresh-client 6717.Fl B . 6718Any arguments after 6719.Ar pane-id 6720up until a single 6721.Ql \&: 6722are for future use and should be ignored. 6723.It Ic %unlinked-window-add Ar window-id 6724The window with ID 6725.Ar window-id 6726was created but is not linked to the current session. 6727.It Ic %unlinked-window-close Ar window-id 6728The window with ID 6729.Ar window-id , 6730which is not linked to the current session, was closed. 6731.It Ic %unlinked-window-renamed Ar window-id 6732The window with ID 6733.Ar window-id , 6734which is not linked to the current session, was renamed. 6735.It Ic %window-add Ar window-id 6736The window with ID 6737.Ar window-id 6738was linked to the current session. 6739.It Ic %window-close Ar window-id 6740The window with ID 6741.Ar window-id 6742closed. 6743.It Ic %window-pane-changed Ar window-id Ar pane-id 6744The active pane in the window with ID 6745.Ar window-id 6746changed to the pane with ID 6747.Ar pane-id . 6748.It Ic %window-renamed Ar window-id Ar name 6749The window with ID 6750.Ar window-id 6751was renamed to 6752.Ar name . 6753.El 6754.Sh ENVIRONMENT 6755When 6756.Nm 6757is started, it inspects the following environment variables: 6758.Bl -tag -width LC_CTYPE 6759.It Ev EDITOR 6760If the command specified in this variable contains the string 6761.Ql vi 6762and 6763.Ev VISUAL 6764is unset, use vi-style key bindings. 6765Overridden by the 6766.Ic mode-keys 6767and 6768.Ic status-keys 6769options. 6770.It Ev HOME 6771The user's login directory. 6772If unset, the 6773.Xr passwd 5 6774database is consulted. 6775.It Ev LC_CTYPE 6776The character encoding 6777.Xr locale 1 . 6778It is used for two separate purposes. 6779For output to the terminal, UTF-8 is used if the 6780.Fl u 6781option is given or if 6782.Ev LC_CTYPE 6783contains 6784.Qq UTF-8 6785or 6786.Qq UTF8 . 6787Otherwise, only ASCII characters are written and non-ASCII characters 6788are replaced with underscores 6789.Pq Ql _ . 6790For input, 6791.Nm 6792always runs with a UTF-8 locale. 6793If en_US.UTF-8 is provided by the operating system, it is used and 6794.Ev LC_CTYPE 6795is ignored for input. 6796Otherwise, 6797.Ev LC_CTYPE 6798tells 6799.Nm 6800what the UTF-8 locale is called on the current system. 6801If the locale specified by 6802.Ev LC_CTYPE 6803is not available or is not a UTF-8 locale, 6804.Nm 6805exits with an error message. 6806.It Ev LC_TIME 6807The date and time format 6808.Xr locale 1 . 6809It is used for locale-dependent 6810.Xr strftime 3 6811format specifiers. 6812.It Ev PWD 6813The current working directory to be set in the global environment. 6814This may be useful if it contains symbolic links. 6815If the value of the variable does not match the current working 6816directory, the variable is ignored and the result of 6817.Xr getcwd 3 6818is used instead. 6819.It Ev SHELL 6820The absolute path to the default shell for new windows. 6821See the 6822.Ic default-shell 6823option for details. 6824.It Ev TMUX_TMPDIR 6825The parent directory of the directory containing the server sockets. 6826See the 6827.Fl L 6828option for details. 6829.It Ev VISUAL 6830If the command specified in this variable contains the string 6831.Ql vi , 6832use vi-style key bindings. 6833Overridden by the 6834.Ic mode-keys 6835and 6836.Ic status-keys 6837options. 6838.El 6839.Sh FILES 6840.Bl -tag -width "/etc/tmux.confXXX" -compact 6841.It Pa ~/.tmux.conf 6842Default 6843.Nm 6844configuration file. 6845.It Pa /etc/tmux.conf 6846System-wide configuration file. 6847.El 6848.Sh EXAMPLES 6849To create a new 6850.Nm 6851session running 6852.Xr vi 1 : 6853.Pp 6854.Dl $ tmux new-session vi 6855.Pp 6856Most commands have a shorter form, known as an alias. 6857For new-session, this is 6858.Ic new : 6859.Pp 6860.Dl $ tmux new vi 6861.Pp 6862Alternatively, the shortest unambiguous form of a command is accepted. 6863If there are several options, they are listed: 6864.Bd -literal -offset indent 6865$ tmux n 6866ambiguous command: n, could be: new-session, new-window, next-window 6867.Ed 6868.Pp 6869Within an active session, a new window may be created by typing 6870.Ql C-b c 6871(Ctrl 6872followed by the 6873.Ql b 6874key 6875followed by the 6876.Ql c 6877key). 6878.Pp 6879Windows may be navigated with: 6880.Ql C-b 0 6881(to select window 0), 6882.Ql C-b 1 6883(to select window 1), and so on; 6884.Ql C-b n 6885to select the next window; and 6886.Ql C-b p 6887to select the previous window. 6888.Pp 6889A session may be detached using 6890.Ql C-b d 6891(or by an external event such as 6892.Xr ssh 1 6893disconnection) and reattached with: 6894.Pp 6895.Dl $ tmux attach-session 6896.Pp 6897Typing 6898.Ql C-b \&? 6899lists the current key bindings in the current window; up and down may be used 6900to navigate the list or 6901.Ql q 6902to exit from it. 6903.Pp 6904Commands to be run when the 6905.Nm 6906server is started may be placed in the 6907.Pa ~/.tmux.conf 6908configuration file. 6909Common examples include: 6910.Pp 6911Changing the default prefix key: 6912.Bd -literal -offset indent 6913set-option -g prefix C-a 6914unbind-key C-b 6915bind-key C-a send-prefix 6916.Ed 6917.Pp 6918Turning the status line off, or changing its colour: 6919.Bd -literal -offset indent 6920set-option -g status off 6921set-option -g status-style bg=blue 6922.Ed 6923.Pp 6924Setting other options, such as the default command, 6925or locking after 30 minutes of inactivity: 6926.Bd -literal -offset indent 6927set-option -g default-command "exec /bin/ksh" 6928set-option -g lock-after-time 1800 6929.Ed 6930.Pp 6931Creating new key bindings: 6932.Bd -literal -offset indent 6933bind-key b set-option status 6934bind-key / command-prompt "split-window 'exec man %%'" 6935bind-key S command-prompt "new-window -n %1 'ssh %1'" 6936.Ed 6937.Sh SEE ALSO 6938.Xr pty 4 6939.Sh AUTHORS 6940.An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com 6941