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