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