From c24b58e2ee8691870736959deb252c225b205b4d Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Tue, 16 Apr 2013 11:33:53 +0100 Subject: Generate tmux.1 using mdoc2man.awk on Solaris, issue brought up and changes tested by Dagobert Michelsen. --- .gitignore | 1 + Makefile.am | 14 +- configure.ac | 5 + mdoc2man.awk | 370 ++++++ tmux.1 | 3808 ---------------------------------------------------------- tmux.1.in | 3808 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 4196 insertions(+), 3810 deletions(-) create mode 100644 mdoc2man.awk delete mode 100644 tmux.1 create mode 100644 tmux.1.in diff --git a/.gitignore b/.gitignore index c3906ada..3b400861 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ tmux Makefile Makefile.in configure +tmux.1 diff --git a/Makefile.am b/Makefile.am index 2ce54b1a..b85eae0c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,12 +2,14 @@ # Obvious program stuff. bin_PROGRAMS = tmux -dist_man1_MANS = tmux.1 +nodist_man1_MANS = tmux.1 +CLEANFILES = tmux.1 # Distribution tarball options. EXTRA_DIST = \ CHANGES FAQ README TODO examples compat \ - array.h compat.h tmux.h osdep-*.c + array.h compat.h tmux.h osdep-*.c mdoc2man.awk \ + tmux.1.in dist-hook: grep "^#found_debug=" configure find $(distdir) -name .svn -type d|xargs rm -Rf @@ -232,6 +234,14 @@ if NO_B64_NTOP nodist_tmux_SOURCES += compat/b64_ntop.c endif +# Build tmux.1 in the right format. +tmux.1: tmux.1.in + if test x@MANFORMAT@ = xmdoc; then \ + cp tmux.1.in tmux.1; \ + else \ + $(AWK) -fmdoc2man.awk tmux.1.in >tmux.1; \ + fi + # Update SF web site. upload-index.html: update-index.html scp www/index.html www/main.css www/images/*.png \ diff --git a/configure.ac b/configure.ac index f00937f0..b4f76f5f 100644 --- a/configure.ac +++ b/configure.ac @@ -416,6 +416,10 @@ else AC_MSG_RESULT(no) fi +# Man page defaults to mdoc. +MANFORMAT=mdoc +AC_SUBST(MANFORMAT) + # Figure out the platform for osdep-*.c and forkpty-*.c. AC_MSG_CHECKING(platform) case "$host_os" in @@ -455,6 +459,7 @@ case "$host_os" in *solaris*) AC_MSG_RESULT(sunos) PLATFORM=sunos + MANFORMAT=man ;; *hpux*) AC_MSG_RESULT(hpux) diff --git a/mdoc2man.awk b/mdoc2man.awk new file mode 100644 index 00000000..80e8d5ff --- /dev/null +++ b/mdoc2man.awk @@ -0,0 +1,370 @@ +#!/usr/bin/awk +# +# $Id: mdoc2man.awk,v 1.9 2009/10/24 00:52:42 dtucker Exp $ +# +# Version history: +# v4+ Adapted for OpenSSH Portable (see cvs Id and history) +# v3, I put the program under a proper license +# Dan Nelson added .An, .Aq and fixed a typo +# v2, fixed to work on GNU awk --posix and MacOS X +# v1, first attempt, didn't work on MacOS X +# +# Copyright (c) 2003 Peter Stuge +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + +BEGIN { + optlist=0 + oldoptlist=0 + nospace=0 + synopsis=0 + reference=0 + block=0 + ext=0 + extopt=0 + literal=0 + prenl=0 + breakw=0 + line="" +} + +function wtail() { + retval="" + while(w0;i--) { + add(refauthors[i]) + if(i>1) + add(", ") + } + if(nrefauthors>1) + add(" and ") + if(nrefauthors>0) + add(refauthors[0] ", ") + add("\\fI" reftitle "\\fP") + if(length(refissue)) + add(", " refissue) + if(length(refreport)) { + add(", " refreport) + } + if(length(refdate)) + add(", " refdate) + if(length(refopt)) + add(", " refopt) + add(".") + reference=0 + } else if(reference) { + if(match(words[w],"^%A$")) { refauthors[nrefauthors++]=wtail() } + if(match(words[w],"^%T$")) { + reftitle=wtail() + sub("^\"","",reftitle) + sub("\"$","",reftitle) + } + if(match(words[w],"^%N$")) { refissue=wtail() } + if(match(words[w],"^%D$")) { refdate=wtail() } + if(match(words[w],"^%O$")) { refopt=wtail() } + if(match(words[w],"^%R$")) { refreport=wtail() } + } else if(match(words[w],"^Nm$")) { + if(synopsis) { + add(".br") + prenl++ + } + n=words[++w] + if(!length(name)) + name=n + if(!length(n)) + n=name + add("\\fB" n "\\fP") + if(!nospace&&match(words[w+1],"^[\\.,]")) + nospace=1 + } else if(match(words[w],"^Nd$")) { + add("\\- " wtail()) + } else if(match(words[w],"^Fl$")) { + add("\\fB\\-" words[++w] "\\fP") + if(!nospace&&match(words[w+1],"^[\\.,]")) + nospace=1 + } else if(match(words[w],"^Ar$")) { + add("\\fI") + if(w==nwords) + add("file ...\\fP") + else { + add(words[++w] "\\fP") + while(match(words[w+1],"^\\|$")) + add(OFS words[++w] " \\fI" words[++w] "\\fP") + } + if(!nospace&&match(words[w+1],"^[\\.,]")) + nospace=1 + } else if(match(words[w],"^Cm$")) { + add("\\fB" words[++w] "\\fP") + while(w") + if(option) + add("]") + if(ext&&!extopt&&!match(line," $")) + add(OFS) + if(!ext&&!extopt&&length(line)) { + print line + prenl=0 + line="" + } +} diff --git a/tmux.1 b/tmux.1 deleted file mode 100644 index 98bf9574..00000000 --- a/tmux.1 +++ /dev/null @@ -1,3808 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright (c) 2007 Nicholas Marriott -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER -.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING -.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: March 25 2013 $ -.Dt TMUX 1 -.Os -.Sh NAME -.Nm tmux -.Nd terminal multiplexer -.Sh SYNOPSIS -.Nm tmux -.Bk -words -.Op Fl 28lCquvV -.Op Fl c Ar shell-command -.Op Fl f Ar file -.Op Fl L Ar socket-name -.Op Fl S Ar socket-path -.Op Ar command Op Ar flags -.Ek -.Sh DESCRIPTION -.Nm -is a terminal multiplexer: -it enables a number of terminals to be created, accessed, and -controlled from a single screen. -.Nm -may be detached from a screen -and continue running in the background, -then later reattached. -.Pp -When -.Nm -is started it creates a new -.Em session -with a single -.Em window -and displays it on screen. -A status line at the bottom of the screen -shows information on the current session -and is used to enter interactive commands. -.Pp -A session is a single collection of -.Em pseudo terminals -under the management of -.Nm . -Each session has one or more -windows linked to it. -A window occupies the entire screen -and may be split into rectangular panes, -each of which is a separate pseudo terminal -(the -.Xr pty 4 -manual page documents the technical details of pseudo terminals). -Any number of -.Nm -instances may connect to the same session, -and any number of windows may be present in the same session. -Once all sessions are killed, -.Nm -exits. -.Pp -Each session is persistent and will survive accidental disconnection -(such as -.Xr ssh 1 -connection timeout) or intentional detaching (with the -.Ql C-b d -key strokes). -.Nm -may be reattached using: -.Pp -.Dl $ tmux attach -.Pp -In -.Nm , -a session is displayed on screen by a -.Em client -and all sessions are managed by a single -.Em server . -The server and each client are separate processes which communicate through a -socket in -.Pa /tmp . -.Pp -The options are as follows: -.Bl -tag -width "XXXXXXXXXXXX" -.It Fl 2 -Force -.Nm -to assume the terminal supports 256 colours. -.It Fl C -Start in control mode. -Given twice -.Xo ( Fl CC ) Xc -disables echo. -.It Fl c Ar shell-command -Execute -.Ar shell-command -using the default shell. -If necessary, the -.Nm -server will be started to retrieve the -.Ic default-shell -option. -This option is for compatibility with -.Xr sh 1 -when -.Nm -is used as a login shell. -.It Fl f Ar file -Specify an alternative configuration file. -By default, -.Nm -loads the system configuration file from -.Pa /etc/tmux.conf , -if present, then looks for a user configuration file at -.Pa ~/.tmux.conf . -.Pp -The configuration file is a set of -.Nm -commands which are executed in sequence when the server is first started. -.Nm -loads configuration files once when the server process has started. -The -.Ic source-file -command may be used to load a file later. -.Pp -.Nm -shows any error messages from commands in configuration files in the first -session created, and continues to process the rest of the configuration file. -.It Fl L Ar socket-name -.Nm -stores the server socket in a directory under -.Ev TMUX_TMPDIR , -.Ev TMPDIR -if it is unset, or -.Pa /tmp -if both are unset. -The default socket is named -.Em default . -This option allows a different socket name to be specified, allowing several -independent -.Nm -servers to be run. -Unlike -.Fl S -a full path is not necessary: the sockets are all created in the same -directory. -.Pp -If the socket is accidentally removed, the -.Dv SIGUSR1 -signal may be sent to the -.Nm -server process to recreate it. -.It Fl l -Behave as a login shell. -This flag currently has no effect and is for compatibility with other shells -when using tmux as a login shell. -.It Fl q -Set the -.Ic quiet -server option to prevent the server sending various informational messages. -.It Fl S Ar socket-path -Specify a full alternative path to the server socket. -If -.Fl S -is specified, the default socket directory is not used and any -.Fl L -flag is ignored. -.It Fl u -.Nm -attempts to guess if the terminal is likely to support UTF-8 by checking the -first of the -.Ev LC_ALL , -.Ev LC_CTYPE -and -.Ev LANG -environment variables to be set for the string "UTF-8". -This is not always correct: the -.Fl u -flag explicitly informs -.Nm -that UTF-8 is supported. -.Pp -If the server is started from a client passed -.Fl u -or where UTF-8 is detected, the -.Ic utf8 -and -.Ic status-utf8 -options are enabled in the global window and session options respectively. -.It Fl v -Request verbose logging. -This option may be specified multiple times for increasing verbosity. -Log messages will be saved into -.Pa tmux-client-PID.log -and -.Pa tmux-server-PID.log -files in the current directory, where -.Em PID -is the PID of the server or client process. -.It Fl V -Report the -.Nm -version. -.It Ar command Op Ar flags -This specifies one of a set of commands used to control -.Nm , -as described in the following sections. -If no commands are specified, the -.Ic new-session -command is assumed. -.El -.Sh KEY BINDINGS -.Nm -may be controlled from an attached client by using a key combination of a -prefix key, -.Ql C-b -(Ctrl-b) by default, followed by a command key. -.Pp -The default command key bindings are: -.Pp -.Bl -tag -width "XXXXXXXXXX" -offset indent -compact -.It C-b -Send the prefix key (C-b) through to the application. -.It C-o -Rotate the panes in the current window forwards. -.It C-z -Suspend the -.Nm -client. -.It ! -Break the current pane out of the window. -.It \&" -Split the current pane into two, top and bottom. -.It # -List all paste buffers. -.It $ -Rename the current session. -.It % -Split the current pane into two, left and right. -.It & -Kill the current window. -.It ' -Prompt for a window index to select. -.It , -Rename the current window. -.It - -Delete the most recently copied buffer of text. -.It . -Prompt for an index to move the current window. -.It 0 to 9 -Select windows 0 to 9. -.It : -Enter the -.Nm -command prompt. -.It ; -Move to the previously active pane. -.It = -Choose which buffer to paste interactively from a list. -.It \&? -List all key bindings. -.It D -Choose a client to detach. -.It \&[ -Enter copy mode to copy text or view the history. -.It \&] -Paste the most recently copied buffer of text. -.It c -Create a new window. -.It d -Detach the current client. -.It f -Prompt to search for text in open windows. -.It i -Display some information about the current window. -.It l -Move to the previously selected window. -.It n -Change to the next window. -.It o -Select the next pane in the current window. -.It p -Change to the previous window. -.It q -Briefly display pane indexes. -.It r -Force redraw of the attached client. -.It s -Select a new session for the attached client interactively. -.It L -Switch the attached client back to the last session. -.It t -Show the time. -.It w -Choose the current window interactively. -.It x -Kill the current pane. -.It { -Swap the current pane with the previous pane. -.It } -Swap the current pane with the next pane. -.It ~ -Show previous messages from -.Nm , -if any. -.It Page Up -Enter copy mode and scroll one page up. -.It Up, Down -.It Left, Right -Change to the pane above, below, to the left, or to the right of the current -pane. -.It M-1 to M-5 -Arrange panes in one of the five preset layouts: even-horizontal, -even-vertical, main-horizontal, main-vertical, or tiled. -.It M-n -Move to the next window with a bell or activity marker. -.It M-o -Rotate the panes in the current window backwards. -.It M-p -Move to the previous window with a bell or activity marker. -.It C-Up, C-Down -.It C-Left, C-Right -Resize the current pane in steps of one cell. -.It M-Up, M-Down -.It M-Left, M-Right -Resize the current pane in steps of five cells. -.El -.Pp -Key bindings may be changed with the -.Ic bind-key -and -.Ic unbind-key -commands. -.Sh COMMANDS -This section contains a list of the commands supported by -.Nm . -Most commands accept the optional -.Fl t -argument with one of -.Ar target-client , -.Ar target-session -.Ar target-window , -or -.Ar target-pane . -These specify the client, session, window or pane which a command should affect. -.Ar target-client -is the name of the -.Xr pty 4 -file to which the client is connected, for example either of -.Pa /dev/ttyp1 -or -.Pa ttyp1 -for the client attached to -.Pa /dev/ttyp1 . -If no client is specified, the current client is chosen, if possible, or an -error is reported. -Clients may be listed with the -.Ic list-clients -command. -.Pp -.Ar target-session -is the session id prefixed with a $, the name of a session (as listed by the -.Ic list-sessions -command), or the name of a client with the same syntax as -.Ar target-client , -in which case the session attached to the client is used. -When looking for the session name, -.Nm -initially searches for an exact match; if none is found, the session names -are checked for any for which -.Ar target-session -is a prefix or for which it matches as an -.Xr fnmatch 3 -pattern. -If a single match is found, it is used as the target session; multiple matches -produce an error. -If a session is omitted, the current session is used if available; if no -current session is available, the most recently used is chosen. -.Pp -.Ar target-window -specifies a window in the form -.Em session Ns \&: Ns Em window . -.Em session -follows the same rules as for -.Ar target-session , -and -.Em window -is looked for in order: as a window index, for example mysession:1; -as a window ID, such as @1; -as an exact window name, such as mysession:mywindow; then as an -.Xr fnmatch 3 -pattern or the start of a window name, such as mysession:mywin* or -mysession:mywin. -An empty window name specifies the next unused index if appropriate (for -example the -.Ic new-window -and -.Ic link-window -commands) -otherwise the current window in -.Em session -is chosen. -The special character -.Ql \&! -uses the last (previously current) window, -.Ql ^ -selects the highest numbered window, -.Ql $ -selects the lowest numbered window, and -.Ql + -and -.Ql - -select the next window or the previous window by number. -When the argument does not contain a colon, -.Nm -first attempts to parse it as window; if that fails, an attempt is made to -match a session. -.Pp -.Ar target-pane -takes a similar form to -.Ar target-window -but with the optional addition of a period followed by a pane index, for -example: mysession:mywindow.1. -If the pane index is omitted, the currently active pane in the specified -window is used. -If neither a colon nor period appears, -.Nm -first attempts to use the argument as a pane index; if that fails, it is looked -up as for -.Ar target-window . -A -.Ql + -or -.Ql - -indicate the next or previous pane index, respectively. -One of the strings -.Em top , -.Em bottom , -.Em left , -.Em right , -.Em top-left , -.Em top-right , -.Em bottom-left -or -.Em bottom-right -may be used instead of a pane index. -.Pp -The special characters -.Ql + -and -.Ql - -may be followed by an offset, for example: -.Bd -literal -offset indent -select-window -t:+2 -.Ed -.Pp -When dealing with a session that doesn't contain sequential window indexes, -they will be correctly skipped. -.Pp -.Nm -also gives each pane created in a server an identifier consisting of a -.Ql % -and a number, starting from zero. -A pane's identifier is unique for the life of the -.Nm -server and is passed to the child process of the pane in the -.Ev TMUX_PANE -environment variable. -It may be used alone to target a pane or the window containing it. -.Pp -.Ar shell-command -arguments are -.Xr sh 1 -commands. -These must be passed as a single item, which typically means quoting them, for -example: -.Bd -literal -offset indent -new-window 'vi /etc/passwd' -.Ed -.Pp -.Ar command -.Op Ar arguments -refers to a -.Nm -command, passed with the command and arguments separately, for example: -.Bd -literal -offset indent -bind-key F1 set-window-option force-width 81 -.Ed -.Pp -Or if using -.Xr sh 1 : -.Bd -literal -offset indent -$ tmux bind-key F1 set-window-option force-width 81 -.Ed -.Pp -Multiple commands may be specified together as part of a -.Em command sequence . -Each command should be separated by spaces and a semicolon; -commands are executed sequentially from left to right and -lines ending with a backslash continue on to the next line, -except when escaped by another backslash. -A literal semicolon may be included by escaping it with a backslash (for -example, when specifying a command sequence to -.Ic bind-key ) . -.Pp -Example -.Nm -commands include: -.Bd -literal -offset indent -refresh-client -t/dev/ttyp2 - -rename-session -tfirst newname - -set-window-option -t:0 monitor-activity on - -new-window ; split-window -d - -bind-key R source-file ~/.tmux.conf \e; \e - display-message "source-file done" -.Ed -.Pp -Or from -.Xr sh 1 : -.Bd -literal -offset indent -$ tmux kill-window -t :1 - -$ tmux new-window \e; split-window -d - -$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach -.Ed -.Sh CLIENTS AND SESSIONS -The -.Nm -server manages clients, sessions, windows and panes. -Clients are attached to sessions to interact with them, either -when they are created with the -.Ic new-session -command, or later with the -.Ic attach-session -command. -Each session has one or more windows -.Em linked -into it. -Windows may be linked to multiple sessions and are made up of one or -more panes, -each of which contains a pseudo terminal. -Commands for creating, linking and otherwise manipulating windows -are covered -in the -.Sx WINDOWS AND PANES -section. -.Pp -The following commands are available to manage clients and sessions: -.Bl -tag -width Ds -.It Xo Ic attach-session -.Op Fl dr -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic attach ) -If run from outside -.Nm , -create a new client in the current terminal and attach it to -.Ar target-session . -If used from inside, switch the current client. -If -.Fl d -is specified, any other clients attached to the session are detached. -.Fl r -signifies the client is read-only (only keys bound to the -.Ic detach-client -or -.Ic switch-client -commands have any effect) -.Pp -If no server is started, -.Ic attach-session -will attempt to start it; this will fail unless sessions are created in the -configuration file. -.Pp -The -.Ar target-session -rules for -.Ic attach-session -are slightly adjusted: if -.Nm -needs to select the most recently used session, it will prefer the most -recently used -.Em unattached -session. -.It Xo Ic detach-client -.Op Fl P -.Op Fl a -.Op Fl s Ar target-session -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic detach ) -Detach the current client if bound to a key, the client specified with -.Fl t , -or all clients currently attached to the session specified by -.Fl s . -The -.Fl a -option kills all but the client given with -.Fl t . -If -.Fl P -is given, send SIGHUP to the parent process of the client, typically causing it -to exit. -.It Ic has-session Op Fl t Ar target-session -.D1 (alias: Ic has ) -Report an error and exit with 1 if the specified session does not exist. -If it does exist, exit with 0. -.It Ic kill-server -Kill the -.Nm -server and clients and destroy all sessions. -.It Ic kill-session -.Op Fl a -.Op Fl t Ar target-session -Destroy the given session, closing any windows linked to it and no other -sessions, and detaching all clients attached to it. -If -.Fl a -is given, all sessions but the specified one is killed. -.It Xo Ic list-clients -.Op Fl F Ar format -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic lsc ) -List all clients attached to the server. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -If -.Ar target-session -is specified, list only clients connected to that session. -.It Ic list-commands -.D1 (alias: Ic lscm ) -List the syntax of all commands supported by -.Nm . -.It Ic list-sessions Op Fl F Ar format -.D1 (alias: Ic ls ) -List all sessions managed by the server. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Ic lock-client Op Fl t Ar target-client -.D1 (alias: Ic lockc ) -Lock -.Ar target-client , -see the -.Ic lock-server -command. -.It Ic lock-session Op Fl t Ar target-session -.D1 (alias: Ic locks ) -Lock all clients attached to -.Ar target-session . -.It Xo Ic new-session -.Op Fl AdDP -.Op Fl F Ar format -.Op Fl n Ar window-name -.Op Fl s Ar session-name -.Op Fl t Ar target-session -.Op Fl x Ar width -.Op Fl y Ar height -.Op Ar shell-command -.Xc -.D1 (alias: Ic new ) -Create a new session with name -.Ar session-name . -.Pp -The new session is attached to the current terminal unless -.Fl d -is given. -.Ar window-name -and -.Ar shell-command -are the name of and shell command to execute in the initial window. -If -.Fl d -is used, -.Fl x -and -.Fl y -specify the size of the initial window (80 by 24 if not given). -.Pp -If run from a terminal, any -.Xr termios 4 -special characters are saved and used for new windows in the new session. -.Pp -The -.Fl A -flag makes -.Ic new-session -behave like -.Ic attach-session -if -.Ar session-name -already exists; in the case, -.Fl D -behaves like -.Fl d -to -.Ic attach-session . -.Pp -If -.Fl t -is given, the new session is -.Em grouped -with -.Ar target-session . -This means they share the same set of windows - all windows from -.Ar target-session -are linked to the new session and any subsequent new windows or windows being -closed are applied to both sessions. -The current and previous window and any session options remain independent and -either session may be killed without affecting the other. -Giving -.Fl n -or -.Ar shell-command -are invalid if -.Fl t -is used. -.Pp -The -.Fl P -option prints information about the new session after it has been created. -By default, it uses the format -.Ql #{session_name}: -but a different format may be specified with -.Fl F . -.It Xo Ic refresh-client -.Op Fl S -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic refresh ) -Refresh the current client if bound to a key, or a single client if one is given -with -.Fl t . -If -.Fl S -is specified, only update the client's status bar. -.It Xo Ic rename-session -.Op Fl t Ar target-session -.Ar new-name -.Xc -.D1 (alias: Ic rename ) -Rename the session to -.Ar new-name . -.It Xo Ic show-messages -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic showmsgs ) -Any messages displayed on the status line are saved in a per-client message -log, up to a maximum of the limit set by the -.Ar message-limit -session option for the session attached to that client. -This command displays the log for -.Ar target-client . -.It Ic source-file Ar path -.D1 (alias: Ic source ) -Execute commands from -.Ar path . -.It Ic start-server -.D1 (alias: Ic start ) -Start the -.Nm -server, if not already running, without creating any sessions. -.It Xo Ic suspend-client -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic suspendc ) -Suspend a client by sending -.Dv SIGTSTP -(tty stop). -.It Xo Ic switch-client -.Op Fl lnpr -.Op Fl c Ar target-client -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic switchc ) -Switch the current session for client -.Ar target-client -to -.Ar target-session . -If -.Fl l , -.Fl n -or -.Fl p -is used, the client is moved to the last, next or previous session -respectively. -.Fl r -toggles whether a client is read-only (see the -.Ic attach-session -command). -.El -.Sh WINDOWS AND PANES -A -.Nm -window may be in one of several modes. -The default permits direct access to the terminal attached to the window. -The other is copy mode, which permits a section of a window or its -history to be copied to a -.Em paste buffer -for later insertion into another window. -This mode is entered with the -.Ic copy-mode -command, bound to -.Ql \&[ -by default. -It is also entered when a command that produces output, such as -.Ic list-keys , -is executed from a key binding. -.Pp -The keys available depend on whether emacs or vi mode is selected -(see the -.Ic mode-keys -option). -The following keys are supported as appropriate for the mode: -.Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent -.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" -.It Li "Back to indentation" Ta "^" Ta "M-m" -.It Li "Bottom of history" Ta "G" Ta "M-<" -.It Li "Clear selection" Ta "Escape" Ta "C-g" -.It Li "Copy selection" Ta "Enter" Ta "M-w" -.It Li "Cursor down" Ta "j" Ta "Down" -.It Li "Cursor left" Ta "h" Ta "Left" -.It Li "Cursor right" Ta "l" Ta "Right" -.It Li "Cursor to bottom line" Ta "L" Ta "" -.It Li "Cursor to middle line" Ta "M" Ta "M-r" -.It Li "Cursor to top line" Ta "H" Ta "M-R" -.It Li "Cursor up" Ta "k" Ta "Up" -.It Li "Delete entire line" Ta "d" Ta "C-u" -.It Li "Delete/Copy to end of line" Ta "D" Ta "C-k" -.It Li "End of line" Ta "$" Ta "C-e" -.It Li "Go to line" Ta ":" Ta "g" -.It Li "Half page down" Ta "C-d" Ta "M-Down" -.It Li "Half page up" Ta "C-u" Ta "M-Up" -.It Li "Jump forward" Ta "f" Ta "f" -.It Li "Jump to forward" Ta "t" Ta "" -.It Li "Jump backward" Ta "F" Ta "F" -.It Li "Jump to backward" Ta "T" Ta "" -.It Li "Jump again" Ta ";" Ta ";" -.It Li "Jump again in reverse" Ta "," Ta "," -.It Li "Next page" Ta "C-f" Ta "Page down" -.It Li "Next space" Ta "W" Ta "" -.It Li "Next space, end of word" Ta "E" Ta "" -.It Li "Next word" Ta "w" Ta "" -.It Li "Next word end" Ta "e" Ta "M-f" -.It Li "Paste buffer" Ta "p" Ta "C-y" -.It Li "Previous page" Ta "C-b" Ta "Page up" -.It Li "Previous word" Ta "b" Ta "M-b" -.It Li "Previous space" Ta "B" Ta "" -.It Li "Quit mode" Ta "q" Ta "Escape" -.It Li "Rectangle toggle" Ta "v" Ta "R" -.It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down" -.It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up" -.It Li "Search again" Ta "n" Ta "n" -.It Li "Search again in reverse" Ta "N" Ta "N" -.It Li "Search backward" Ta "?" Ta "C-r" -.It Li "Search forward" Ta "/" Ta "C-s" -.It Li "Start of line" Ta "0" Ta "C-a" -.It Li "Start selection" Ta "Space" Ta "C-Space" -.It Li "Top of history" Ta "g" Ta "M->" -.It Li "Transpose characters" Ta "" Ta "C-t" -.El -.Pp -The next and previous word keys use space and the -.Ql - , -.Ql _ -and -.Ql @ -characters as word delimiters by default, but this can be adjusted by -setting the -.Em word-separators -session option. -Next word moves to the start of the next word, next word end to the end of the -next word and previous word to the start of the previous word. -The three next and previous space keys work similarly but use a space alone as -the word separator. -.Pp -The jump commands enable quick movement within a line. -For instance, typing -.Ql f -followed by -.Ql / -will move the cursor to the next -.Ql / -character on the current line. -A -.Ql \&; -will then jump to the next occurrence. -.Pp -Commands in copy mode may be prefaced by an optional repeat count. -With vi key bindings, a prefix is entered using the number keys; with -emacs, the Alt (meta) key and a number begins prefix entry. -For example, to move the cursor forward by ten words, use -.Ql M-1 0 M-f -in emacs mode, and -.Ql 10w -in vi. -.Pp -When copying the selection, the repeat count indicates the buffer index to -replace, if used. -.Pp -Mode key bindings are defined in a set of named tables: -.Em vi-edit -and -.Em emacs-edit -for keys used when line editing at the command prompt; -.Em vi-choice -and -.Em emacs-choice -for keys used when choosing from lists (such as produced by the -.Ic choose-window -command); and -.Em vi-copy -and -.Em emacs-copy -used in copy mode. -The tables may be viewed with the -.Ic list-keys -command and keys modified or removed with -.Ic bind-key -and -.Ic unbind-key . -One command accepts an argument, -.Ic copy-pipe , -which copies the selection and pipes it to a command. -For example the following will bind -.Ql C-q -to copy the selection into -.Pa /tmp -as well as the paste buffer: -.Bd -literal -offset indent -bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" -.Ed -.Pp -The paste buffer key pastes the first line from the top paste buffer on the -stack. -.Pp -The synopsis for the -.Ic copy-mode -command is: -.Bl -tag -width Ds -.It Xo Ic copy-mode -.Op Fl u -.Op Fl t Ar target-pane -.Xc -Enter copy mode. -The -.Fl u -option scrolls one page up. -.El -.Pp -Each window displayed by -.Nm -may be split into one or more -.Em panes ; -each pane takes up a certain area of the display and is a separate terminal. -A window may be split into panes using the -.Ic split-window -command. -Windows may be split horizontally (with the -.Fl h -flag) or vertically. -Panes may be resized with the -.Ic resize-pane -command (bound to -.Ql C-up , -.Ql C-down -.Ql C-left -and -.Ql C-right -by default), the current pane may be changed with the -.Ic select-pane -command and the -.Ic rotate-window -and -.Ic swap-pane -commands may be used to swap panes without changing their position. -Panes are numbered beginning from zero in the order they are created. -.Pp -A number of preset -.Em layouts -are available. -These may be selected with the -.Ic select-layout -command or cycled with -.Ic next-layout -(bound to -.Ql Space -by default); once a layout is chosen, panes within it may be moved and resized -as normal. -.Pp -The following layouts are supported: -.Bl -tag -width Ds -.It Ic even-horizontal -Panes are spread out evenly from left to right across the window. -.It Ic even-vertical -Panes are spread evenly from top to bottom. -.It Ic main-horizontal -A large (main) pane is shown at the top of the window and the remaining panes -are spread from left to right in the leftover space at the bottom. -Use the -.Em main-pane-height -window option to specify the height of the top pane. -.It Ic main-vertical -Similar to -.Ic main-horizontal -but the large pane is placed on the left and the others spread from top to -bottom along the right. -See the -.Em main-pane-width -window option. -.It Ic tiled -Panes are spread out as evenly as possible over the window in both rows and -columns. -.El -.Pp -In addition, -.Ic select-layout -may be used to apply a previously used layout - the -.Ic list-windows -command displays the layout of each window in a form suitable for use with -.Ic select-layout . -For example: -.Bd -literal -offset indent -$ tmux list-windows -0: ksh [159x48] - layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} -$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} -.Ed -.Pp -.Nm -automatically adjusts the size of the layout for the current window size. -Note that a layout cannot be applied to a window with more panes than that -from which the layout was originally defined. -.Pp -Commands related to windows and panes are as follows: -.Bl -tag -width Ds -.It Xo Ic break-pane -.Op Fl dP -.Op Fl F Ar format -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic breakp ) -Break -.Ar target-pane -off from its containing window to make it the only pane in a new window. -If -.Fl d -is given, the new window does not become the current window. -The -.Fl P -option prints information about the new window after it has been created. -By default, it uses the format -.Ql #{session_name}:#{window_index} -but a different format may be specified with -.Fl F . -.It Xo Ic capture-pane -.Op Fl aepPq -.Op Fl b Ar buffer-index -.Op Fl E Ar end-line -.Op Fl S Ar start-line -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic capturep ) -Capture the contents of a pane. -If -.Fl p -is given, the output goes to stdout, otherwise to the buffer specified with -.Fl b -or a new buffer if omitted. -If -.Fl a -is given, the alternate screen is used, and the history is not accessible. -If no alternate screen exists, an error will be returned unless -.Fl q -is given. -If -.Fl e -is given, the output includes escape sequences for text and background -attributes. -.Fl C -also escapes non-printable characters as octal \exxx. -.Fl J -joins wrapped lines and preserves trailing spaces at each line's end. -.Fl P -captures only any output that the pane has received that is the beginning of an -as-yet incomplete escape sequence. -.Pp -.Fl S -and -.Fl E -specify the starting and ending line numbers, zero is the first line of the -visible pane and negative numbers are lines in the history. -The default is to capture only the visible contents of the pane. -.It Xo -.Ic choose-client -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into client choice mode, allowing a client to be selected -interactively from a list. -After a client is chosen, -.Ql %% -is replaced by the client -.Xr pty 4 -path in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "detach-client -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-list -.Op Fl l Ar items -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into list choice mode, allowing -.Ar items -to be selected. -.Ar items -can be a comma-separated list to display more than one item. -If an item has spaces, that entry must be quoted. -After an item is chosen, -.Ql %% -is replaced by the chosen item in the -.Ar template -and the result is executed as a command. -If -.Ar template -is not given, "run-shell '%%'" is used. -.Ar items -also accepts format specifiers. -For the meaning of this see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-session -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into session choice mode, where a session may be selected -interactively from a list. -When one is chosen, -.Ql %% -is replaced by the session name in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "switch-client -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-tree -.Op Fl suw -.Op Fl b Ar session-template -.Op Fl c Ar window-template -.Op Fl S Ar format -.Op Fl W Ar format -.Op Fl t Ar target-window -.Xc -Put a window into tree choice mode, where either sessions or windows may be -selected interactively from a list. -By default, windows belonging to a session are indented to show their -relationship to a session. -.Pp -Note that the -.Ic choose-window -and -.Ic choose-session -commands are wrappers around -.Ic choose-tree . -.Pp -If -.Fl s -is given, will show sessions. -If -.Fl w -is given, will show windows. -.Pp -By default, the tree is collapsed and sessions must be expanded to windows -with the right arrow key. -The -.Fl u -option will start with all sessions expanded instead. -.Pp -If -.Fl b -is given, will override the default session command. -Note that -.Ql %% -can be used and will be replaced with the session name. -The default option if not specified is "switch-client -t '%%'". -If -.Fl c -is given, will override the default window command. -Like -.Fl b , -.Ql %% -can be used and will be replaced with the session name and window index. -When a window is chosen from the list, the session command is run before the -window command. -.Pp -If -.Fl S -is given will display the specified format instead of the default session -format. -If -.Fl W -is given will display the specified format instead of the default window -format. -For the meaning of the -.Fl s -and -.Fl w -options, see the -.Sx FORMATS -section. -.Pp -This command works only if at least one client is attached. -.It Xo -.Ic choose-window -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into window choice mode, where a window may be chosen -interactively from a list. -After a window is selected, -.Ql %% -is replaced by the session name and window index in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "select-window -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Ic display-panes Op Fl t Ar target-client -.D1 (alias: Ic displayp) -Display a visible indicator of each pane shown by -.Ar target-client . -See the -.Ic display-panes-time , -.Ic display-panes-colour , -and -.Ic display-panes-active-colour -session options. -While the indicator is on screen, a pane may be selected with the -.Ql 0 -to -.Ql 9 -keys. -.It Xo Ic find-window -.Op Fl CNT -.Op Fl F Ar format -.Op Fl t Ar target-window -.Ar match-string -.Xc -.D1 (alias: Ic findw ) -Search for the -.Xr fnmatch 3 -pattern -.Ar match-string -in window names, titles, and visible content (but not history). -The flags control matching behavior: -.Fl C -matches only visible window contents, -.Fl N -matches only the window name and -.Fl T -matches only the window title. -The default is -.Fl CNT . -If only one window is matched, it'll be automatically selected, -otherwise a choice list is shown. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo Ic join-pane -.Op Fl bdhv -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic joinp ) -Like -.Ic split-window , -but instead of splitting -.Ar dst-pane -and creating a new pane, split it and move -.Ar src-pane -into the space. -This can be used to reverse -.Ic break-pane . -The -.Fl b -option causes -.Ar src-pane -to be joined to left of or above -.Ar dst-pane . -.It Xo Ic kill-pane -.Op Fl a -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic killp ) -Destroy the given pane. -If no panes remain in the containing window, it is also destroyed. -The -.Fl a -option kills all but the pane given with -.Fl t . -.It Xo Ic kill-window -.Op Fl a -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic killw ) -Kill the current window or the window at -.Ar target-window , -removing it from any sessions to which it is linked. -The -.Fl a -option kills all but the window given with -.Fl t . -.It Ic last-pane Op Fl t Ar target-window -.D1 (alias: Ic lastp ) -Select the last (previously selected) pane. -.It Ic last-window Op Fl t Ar target-session -.D1 (alias: Ic last ) -Select the last (previously selected) window. -If no -.Ar target-session -is specified, select the last window of the current session. -.It Xo Ic link-window -.Op Fl dk -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic linkw ) -Link the window at -.Ar src-window -to the specified -.Ar dst-window . -If -.Ar dst-window -is specified and no such window exists, the -.Ar src-window -is linked there. -If -.Fl k -is given and -.Ar dst-window -exists, it is killed, otherwise an error is generated. -If -.Fl d -is given, the newly linked window is not selected. -.It Xo Ic list-panes -.Op Fl as -.Op Fl F Ar format -.Op Fl t Ar target -.Xc -.D1 (alias: Ic lsp ) -If -.Fl a -is given, -.Ar target -is ignored and all panes on the server are listed. -If -.Fl s -is given, -.Ar target -is a session (or the current session). -If neither is given, -.Ar target -is a window (or the current window). -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic list-windows -.Op Fl a -.Op Fl F Ar format -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic lsw ) -If -.Fl a -is given, list all windows on the server. -Otherwise, list windows in the current session or in -.Ar target-session . -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic move-pane -.Op Fl bdhv -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic movep ) -Like -.Ic join-pane , -but -.Ar src-pane -and -.Ar dst-pane -may belong to the same window. -.It Xo Ic move-window -.Op Fl rdk -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic movew ) -This is similar to -.Ic link-window , -except the window at -.Ar src-window -is moved to -.Ar dst-window . -With -.Fl r , -all windows in the session are renumbered in sequential order, respecting -the -.Ic base-index -option. -.It Xo Ic new-window -.Op Fl adkP -.Op Fl c Ar start-directory -.Op Fl F Ar format -.Op Fl n Ar window-name -.Op Fl t Ar target-window -.Op Ar shell-command -.Xc -.D1 (alias: Ic neww ) -Create a new window. -With -.Fl a , -the new window is inserted at the next index up from the specified -.Ar target-window , -moving windows up if necessary, -otherwise -.Ar target-window -is the new window location. -.Pp -If -.Fl d -is given, the session does not make the new window the current window. -.Ar target-window -represents the window to be created; if the target already exists an error is -shown, unless the -.Fl k -flag is used, in which case it is destroyed. -.Ar shell-command -is the command to execute. -If -.Ar shell-command -is not specified, the value of the -.Ic default-command -option is used. -.Fl c -specifies the working directory in which the new window is created. -It may have an absolute path or one of the following values (or a subdirectory): -.Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent -.It Li "Empty string" Ta "Current pane's directory" -.It Li "~" Ta "User's home directory" -.It Li "-" Ta "Where session was started" -.It Li "." Ta "Where server was started" -.El -.Pp -When the shell command completes, the window closes. -See the -.Ic remain-on-exit -option to change this behaviour. -.Pp -The -.Ev TERM -environment variable must be set to -.Dq screen -for all programs running -.Em inside -.Nm . -New windows will automatically have -.Dq TERM=screen -added to their environment, but care must be taken not to reset this in shell -start-up files. -.Pp -The -.Fl P -option prints information about the new window after it has been created. -By default, it uses the format -.Ql #{session_name}:#{window_index} -but a different format may be specified with -.Fl F . -.It Ic next-layout Op Fl t Ar target-window -.D1 (alias: Ic nextl ) -Move a window to the next layout and rearrange the panes to fit. -.It Xo Ic next-window -.Op Fl a -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic next ) -Move to the next window in the session. -If -.Fl a -is used, move to the next window with an alert. -.It Xo Ic pipe-pane -.Op Fl o -.Op Fl t Ar target-pane -.Op Ar shell-command -.Xc -.D1 (alias: Ic pipep ) -Pipe any output sent by the program in -.Ar target-pane -to a shell command. -A pane may only be piped to one command at a time, any existing pipe is -closed before -.Ar shell-command -is executed. -The -.Ar shell-command -string may contain the special character sequences supported by the -.Ic status-left -option. -If no -.Ar shell-command -is given, the current pipe (if any) is closed. -.Pp -The -.Fl o -option only opens a new pipe if no previous pipe exists, allowing a pipe to -be toggled with a single key, for example: -.Bd -literal -offset indent -bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' -.Ed -.It Xo Ic previous-layout -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic prevl ) -Move to the previous layout in the session. -.It Xo Ic previous-window -.Op Fl a -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic prev ) -Move to the previous window in the session. -With -.Fl a , -move to the previous window with an alert. -.It Xo Ic rename-window -.Op Fl t Ar target-window -.Ar new-name -.Xc -.D1 (alias: Ic renamew ) -Rename the current window, or the window at -.Ar target-window -if specified, to -.Ar new-name . -.It Xo Ic resize-pane -.Op Fl DLRUZ -.Op Fl t Ar target-pane -.Op Fl x Ar width -.Op Fl y Ar height -.Op Ar adjustment -.Xc -.D1 (alias: Ic resizep ) -Resize a pane, up, down, left or right by -.Ar adjustment -with -.Fl U , -.Fl D , -.Fl L -or -.Fl R , -or -to an absolute size -with -.Fl x -or -.Fl y . -The -.Ar adjustment -is given in lines or cells (the default is 1). -.Pp -With -.Fl Z , -the active pane is toggled between zoomed (occupying the whole of the window) -and unzoomed (its normal position in the layout). -.It Xo Ic respawn-pane -.Op Fl k -.Op Fl t Ar target-pane -.Op Ar shell-command -.Xc -.D1 (alias: Ic respawnp ) -Reactivate a pane in which the command has exited (see the -.Ic remain-on-exit -window option). -If -.Ar shell-command -is not given, the command used when the pane was created is executed. -The pane must be already inactive, unless -.Fl k -is given, in which case any existing command is killed. -.It Xo Ic respawn-window -.Op Fl k -.Op Fl t Ar target-window -.Op Ar shell-command -.Xc -.D1 (alias: Ic respawnw ) -Reactivate a window in which the command has exited (see the -.Ic remain-on-exit -window option). -If -.Ar shell-command -is not given, the command used when the window was created is executed. -The window must be already inactive, unless -.Fl k -is given, in which case any existing command is killed. -.It Xo Ic rotate-window -.Op Fl DU -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic rotatew ) -Rotate the positions of the panes within a window, either upward (numerically -lower) with -.Fl U -or downward (numerically higher). -.It Xo Ic select-layout -.Op Fl np -.Op Fl t Ar target-window -.Op Ar layout-name -.Xc -.D1 (alias: Ic selectl ) -Choose a specific layout for a window. -If -.Ar layout-name -is not given, the last preset layout used (if any) is reapplied. -.Fl n -and -.Fl p -are equivalent to the -.Ic next-layout -and -.Ic previous-layout -commands. -.It Xo Ic select-pane -.Op Fl lDLRU -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic selectp ) -Make pane -.Ar target-pane -the active pane in window -.Ar target-window . -If one of -.Fl D , -.Fl L , -.Fl R , -or -.Fl U -is used, respectively the pane below, to the left, to the right, or above the -target pane is used. -.Fl l -is the same as using the -.Ic last-pane -command. -.It Xo Ic select-window -.Op Fl lnpT -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic selectw ) -Select the window at -.Ar target-window . -.Fl l , -.Fl n -and -.Fl p -are equivalent to the -.Ic last-window , -.Ic next-window -and -.Ic previous-window -commands. -If -.Fl T -is given and the selected window is already the current window, -the command behaves like -.Ic last-window . -.It Xo Ic split-window -.Op Fl dhvP -.Op Fl c Ar start-directory -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl t Ar target-pane -.Op Ar shell-command -.Op Fl F Ar format -.Xc -.D1 (alias: Ic splitw ) -Create a new pane by splitting -.Ar target-pane : -.Fl h -does a horizontal split and -.Fl v -a vertical split; if neither is specified, -.Fl v -is assumed. -The -.Fl l -and -.Fl p -options specify the size of the new pane in lines (for vertical split) or in -cells (for horizontal split), or as a percentage, respectively. -All other options have the same meaning as for the -.Ic new-window -command. -.It Xo Ic swap-pane -.Op Fl dDU -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic swapp ) -Swap two panes. -If -.Fl U -is used and no source pane is specified with -.Fl s , -.Ar dst-pane -is swapped with the previous pane (before it numerically); -.Fl D -swaps with the next pane (after it numerically). -.Fl d -instructs -.Nm -not to change the active pane. -.It Xo Ic swap-window -.Op Fl d -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic swapw ) -This is similar to -.Ic link-window , -except the source and destination windows are swapped. -It is an error if no window exists at -.Ar src-window . -.It Xo Ic unlink-window -.Op Fl k -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic unlinkw ) -Unlink -.Ar target-window . -Unless -.Fl k -is given, a window may be unlinked only if it is linked to multiple sessions - -windows may not be linked to no sessions; -if -.Fl k -is specified and the window is linked to only one session, it is unlinked and -destroyed. -.El -.Sh KEY BINDINGS -.Nm -allows a command to be bound to most keys, with or without a prefix key. -When specifying keys, most represent themselves (for example -.Ql A -to -.Ql Z ) . -Ctrl keys may be prefixed with -.Ql C- -or -.Ql ^ , -and Alt (meta) with -.Ql M- . -In addition, the following special key names are accepted: -.Em Up , -.Em Down , -.Em Left , -.Em Right , -.Em BSpace , -.Em BTab , -.Em DC -(Delete), -.Em End , -.Em Enter , -.Em Escape , -.Em F1 -to -.Em F20 , -.Em Home , -.Em IC -(Insert), -.Em NPage/PageDown/PgDn , -.Em PPage/PageUp/PgUp , -.Em Space , -and -.Em Tab . -Note that to bind the -.Ql \&" -or -.Ql ' -keys, quotation marks are necessary, for example: -.Bd -literal -offset indent -bind-key '"' split-window -bind-key "'" new-window -.Ed -.Pp -Commands related to key bindings are as follows: -.Bl -tag -width Ds -.It Xo Ic bind-key -.Op Fl cnr -.Op Fl t Ar key-table -.Ar key Ar command Op Ar arguments -.Xc -.D1 (alias: Ic bind ) -Bind key -.Ar key -to -.Ar command . -By default (without -.Fl t ) -the primary key bindings are modified (those normally activated with the prefix -key); in this case, if -.Fl n -is specified, it is not necessary to use the prefix key, -.Ar command -is bound to -.Ar key -alone. -The -.Fl r -flag indicates this key may repeat, see the -.Ic repeat-time -option. -.Pp -If -.Fl t -is present, -.Ar key -is bound in -.Ar key-table : -the binding for command mode with -.Fl c -or for normal mode without. -To view the default bindings and possible commands, see the -.Ic list-keys -command. -.It Ic list-keys Op Fl t Ar key-table -.D1 (alias: Ic lsk ) -List all key bindings. -Without -.Fl t -the primary key bindings - those executed when preceded by the prefix key - -are printed. -.Pp -With -.Fl t , -the key bindings in -.Ar key-table -are listed; this may be one of: -.Em vi-edit , -.Em emacs-edit , -.Em vi-choice , -.Em emacs-choice , -.Em vi-copy -or -.Em emacs-copy . -.It Xo Ic send-keys -.Op Fl lR -.Op Fl t Ar target-pane -.Ar key Ar ... -.Xc -.D1 (alias: Ic send ) -Send a key or keys to a window. -Each argument -.Ar key -is the name of the key (such as -.Ql C-a -or -.Ql npage -) to send; if the string is not recognised as a key, it is sent as a series of -characters. -The -.Fl l -flag disables key name lookup and sends the keys literally. -All arguments are sent sequentially from first to last. -The -.Fl R -flag causes the terminal state to be reset. -.It Xo Ic send-prefix -.Op Fl 2 -.Op Fl t Ar target-pane -.Xc -Send the prefix key, or with -.Fl 2 -the secondary prefix key, to a window as if it was pressed. -.It Xo Ic unbind-key -.Op Fl acn -.Op Fl t Ar key-table -.Ar key -.Xc -.D1 (alias: Ic unbind ) -Unbind the command bound to -.Ar key . -Without -.Fl t -the primary key bindings are modified; in this case, if -.Fl n -is specified, the command bound to -.Ar key -without a prefix (if any) is removed. -If -.Fl a -is present, all key bindings are removed. -.Pp -If -.Fl t -is present, -.Ar key -in -.Ar key-table -is unbound: the binding for command mode with -.Fl c -or for normal mode without. -.El -.Sh OPTIONS -The appearance and behaviour of -.Nm -may be modified by changing the value of various options. -There are three types of option: -.Em server options , -.Em session options -and -.Em window options . -.Pp -The -.Nm -server has a set of global options which do not apply to any particular -window or session. -These are altered with the -.Ic set-option -.Fl s -command, or displayed with the -.Ic show-options -.Fl s -command. -.Pp -In addition, each individual session may have a set of session options, and -there is a separate set of global session options. -Sessions which do not have a particular option configured inherit the value -from the global session options. -Session options are set or unset with the -.Ic set-option -command and may be listed with the -.Ic show-options -command. -The available server and session options are listed under the -.Ic set-option -command. -.Pp -Similarly, a set of window options is attached to each window, and there is -a set of global window options from which any unset options are inherited. -Window options are altered with the -.Ic set-window-option -command and can be listed with the -.Ic show-window-options -command. -All window options are documented with the -.Ic set-window-option -command. -.Pp -.Nm -also supports user options which are prefixed with a -.Ql \&@ . -User options may have any name, so long as they are prefixed with -.Ql \&@ , -and be set to any string. -For example -.Bd -literal -offset indent -$ tmux setw -q @foo "abc123" -$ tmux showw -v @foo -abc123 -.Ed -.Pp -Commands which set options are as follows: -.Bl -tag -width Ds -.It Xo Ic set-option -.Op Fl agoqsuw -.Op Fl t Ar target-session | Ar target-window -.Ar option Ar value -.Xc -.D1 (alias: Ic set ) -Set a window option with -.Fl w -(equivalent to the -.Ic set-window-option -command), -a server option with -.Fl s , -otherwise a session option. -.Pp -If -.Fl g -is specified, the global session or window option is set. -With -.Fl a , -and if the option expects a string, -.Ar value -is appended to the existing setting. -The -.Fl u -flag unsets an option, so a session inherits the option from the global -options. -It is not possible to unset a global option. -.Pp -The -.Fl o -flag prevents setting an option that is already set. -.Pp -The -.Fl q -flag suppresses the informational message (as if the -.Ic quiet -server option was set). -.Pp -Available window options are listed under -.Ic set-window-option . -.Pp -.Ar value -depends on the option and may be a number, a string, or a flag (on, off, or -omitted to toggle). -.Pp -Available server options are: -.Bl -tag -width Ds -.It Ic buffer-limit Ar number -Set the number of buffers; as new buffers are added to the top of the stack, -old ones are removed from the bottom if necessary to maintain this maximum -length. -.It Ic escape-time Ar time -Set the time in milliseconds for which -.Nm -waits after an escape is input to determine if it is part of a function or meta -key sequences. -The default is 500 milliseconds. -.It Xo Ic exit-unattached -.Op Ic on | off -.Xc -If enabled, the server will exit when there are no attached clients. -.It Xo Ic quiet -.Op Ic on | off -.Xc -Enable or disable the display of various informational messages (see also the -.Fl q -command line flag). -.It Xo Ic set-clipboard -.Op Ic on | off -.Xc -Attempt to set the terminal clipboard content using the -\ee]52;...\e007 -.Xr xterm 1 -escape sequences. -This option is on by default if there is an -.Em \&Ms -entry in the -.Xr terminfo 5 -description for the client terminal. -Note that this feature needs to be enabled in -.Xr xterm 1 -by setting the resource: -.Bd -literal -offset indent -disallowedWindowOps: 20,21,SetXprop -.Ed -.Pp -Or changing this property from the -.Xr xterm 1 -interactive menu when required. -.El -.Pp -Available session options are: -.Bl -tag -width Ds -.It Ic assume-paste-time Ar milliseconds -If keys are entered faster than one in -.Ar milliseconds , -they are assumed to have been pasted rather than typed and -.Nm -key bindings are not processed. -The default is one millisecond and zero disables. -.It Ic base-index Ar index -Set the base index from which an unused index should be searched when a new -window is created. -The default is zero. -.It Xo Ic bell-action -.Op Ic any | none | current -.Xc -Set action on window bell. -.Ic any -means a bell in any window linked to a session causes a bell in the current -window of that session, -.Ic none -means all bells are ignored and -.Ic current -means only bells in windows other than the current window are ignored. -.It Xo Ic bell-on-alert -.Op Ic on | off -.Xc -If on, ring the terminal bell when an alert -occurs. -.It Ic default-command Ar shell-command -Set the command used for new windows (if not specified when the window is -created) to -.Ar shell-command , -which may be any -.Xr sh 1 -command. -The default is an empty string, which instructs -.Nm -to create a login shell using the value of the -.Ic default-shell -option. -.It Ic default-path Ar path -Set the default working directory for new panes. -If empty (the default), the working directory is determined from the process -running in the active pane, from the command line environment or from the -working directory where the session was created. -Otherwise the same options are available as for the -.Fl c -flag to -.Ic new-window . -.It Ic default-shell Ar path -Specify the default shell. -This is used as the login shell for new windows when the -.Ic default-command -option is set to empty, and must be the full path of the executable. -When started -.Nm -tries to set a default value from the first suitable of the -.Ev SHELL -environment variable, the shell returned by -.Xr getpwuid 3 , -or -.Pa /bin/sh . -This option should be configured when -.Nm -is used as a login shell. -.It Ic default-terminal Ar terminal -Set the default terminal for new windows created in this session - the -default value of the -.Ev TERM -environment variable. -For -.Nm -to work correctly, this -.Em must -be set to -.Ql screen -or a derivative of it. -.It Xo Ic destroy-unattached -.Op Ic on | off -.Xc -If enabled and the sessio