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