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