restructure the layout of this page, moving the commands into various

subsections; lots of tweaks to come on the text

from nicm and myself

1 files changed, 802 insertions, 749 deletions

diff --git a/usr.bin/tmux/tmux.1 b/usr.bin/tmux/tmux.1
index 4b2cdf272bd..50464bd8d55 100644
--- a/usr.bin/tmux/tmux.1
+++ b/usr.bin/tmux/tmux.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: tmux.1,v 1.56 2009/08/04 07:56:38 jmc Exp $
+.\" $OpenBSD: tmux.1,v 1.57 2009/08/04 18:41:28 jmc Exp $
 .\"
 .\" Copyright (c) 2007 Nicholas Marriott <nicm@users.sourceforge.net>
 .\"
@@ -34,26 +34,6 @@
 is a terminal multiplexer: it enables a number of terminals to be accessed and
 controlled from a single terminal.
 .Pp
-.Nm
-runs as a server-client system.
-A server holds a number of
-.Em sessions ,
-each of which may have a number of
-.Em windows
-linked to it.
-A server is started automatically when the first session is created and exits
-when all the sessions it contains are destroyed.
-A window may be split on screen into one or more
-.Em panes ,
-each of which is a separate terminal.
-Any number of
-.Em clients
-may connect to a session, or the server
-may be controlled by issuing commands with
-.Nm .
-Communication takes place through a socket, by default placed in
-.Pa /tmp .
-.Pp
 The options are as follows:
 .Bl -tag -width "XXXXXXXXXXXX"
 .It Fl 2
@@ -151,137 +131,258 @@ If no command and flags are specified, the
 .Ic new-session
 command is assumed.
 .El
-.Sh QUICK START
-To create a new
+.Sh INTRODUCTION
 .Nm
-session running
-.Xr vi 1 :
-.Pp
-.Dl $ tmux new-session vi
-.Pp
-Most commands have a shorter form, known as an alias.
-For new-session, this is
-.Ic new :
-.Pp
-.Dl $ tmux new vi
-.Pp
-Alternatively, the shortest unambiguous form of a command is accepted.
-If there are several options, they are listed:
-.Bd -literal -offset indent
-$ tmux n
-ambiguous command: n, could be: new-session, new-window, next-window
-.Ed
-.Pp
-Within an active session, a new window may be created by typing
-.Ql C-b c
-(Ctrl
-followed by the
-.Ql b
-key
-followed by the
-.Ql c
-key).
-.Pp
-Windows may be navigated with:
-.Ql C-b 0
-(to select window 0),
-.Ql C-b 1
-(to select window 1), and so on;
-.Ql C-b n
-to select the next window; and
-.Ql C-b p
-to select the previous window.
-.Pp
-A session may be detached using
-.Ql C-b d
-and reattached with:
+runs as a server-client system.
+A server holds a number of
+.Em sessions ,
+each of which may have a number of
+.Em windows
+linked to it.
+A server is started automatically when the first session is created and exits
+when all the sessions it contains are destroyed.
+A window may be split on screen into one or more
+.Em panes ,
+each of which is a separate terminal.
+Any number of
+.Em clients
+may connect to a session, or the server
+may be controlled by issuing commands with
+.Nm .
+Communication takes place through a socket, by default placed in
+.Pa /tmp .
 .Pp
-.Dl $ tmux attach-session
+This is an overview of the sections in this manual page:
+.Bl -ohang
+.It Sy Commands
+An overview of how
+.Nm
+commands work.
+.It Sy Clients and sessions
+Commands for managing clients and sessions.
+.It Sy Windows and panes
+Commands for managing windows and panes.
+.It Sy Key bindings
+How key bindings work.
+.It Sy Options
+Configuration options for
+.Nm .
+.It Sy Status line
+Commands pertinent to the status line.
+.It Sy Buffers
+Copy and paste operations.
+.It Sy Miscellaneous
+Miscellaneous commands.
+.It Sy Examples
+A quick start guide.
+.El
+.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
-Typing
-.Ql C-b \&?
-lists the current key bindings in the current window; up and down may be used
-to navigate the list or
-.Ql q
-to exit from it.
+.Ar target-session
+is either 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 created is chosen.
 .Pp
-Commands to be run when the
+.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 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.
+When the argument does not contain a colon,
 .Nm
-server is started may be placed in the
-.Pa ~/.tmux.conf
-configuration file.
-Common examples include:
+first attempts to parse it as window; if that fails, an attempt is made to
+match a session.
 .Pp
-Changing the default prefix key:
-.Bd -literal -offset indent
-set-option -g prefix C-a
-unbind-key C-b
-bind-key C-a send-prefix
-.Ed
+.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 .
 .Pp
-Turning the status line off, or changing its colour:
-.Bd -literal -offset indent
-set-option -g status off
-set-option -g status-bg blue
-.Ed
+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.
+A literal semicolon may be included by escaping it with a backslash (for
+example, when specifying a command sequence to
+.Ic bind-key ) .
 .Pp
-Setting other options, such as the default command,
-or locking after 30 minutes of inactivity:
+Examples include:
 .Bd -literal -offset indent
-set-option -g default-command "exec /bin/ksh"
-set-option -g lock-after-time 1800
+refresh-client -t/dev/ttyp2
+
+rename-session -tfirst newname
+
+set-window-option -t:0 monitor-activity on
+
+new-window ; split-window -d
+
+bind-key D detach-client \e\; lock-server
 .Ed
+.Sh CLIENTS AND SESSIONS
+The following commands are available:
+.Bl -tag -width Ds
+.It Xo Ic attach-session
+.Op Fl d
+.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.
 .Pp
-Creating new key bindings:
-.Bd -literal -offset indent
-bind-key b set-option status
-bind-key / command-prompt "split-window 'exec man %%'"
-.Ed
-.Sh KEY BINDINGS
+If no server is started,
+.Ic attach-session
+will attempt to start it; this will fail unless sessions are created in the
+configuration file.
+.It Ic detach-client Op Fl t Ar target-client
+.D1 (alias: Ic detach )
+Detach the current client if bound to a key, or the specified client with
+.Fl t .
+.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
-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
-Some of the default key bindings include:
-.Pp
-.Bl -tag -width Ds -offset 3n -compact
-.It c
-Create new window.
-.It d
-Detach current client.
-.It l
-Move to last (previously selected) window in the current session.
-.It n
-Change to next window in the current session.
-.It p
-Change to previous window in the current session.
-.It t
-Display a large clock.
-.It \&?
-List current key bindings.
-.El
-.Pp
-A complete list may be obtained with the
-.Ic list-keys
-command (bound to
-.Ql \&?
-by default).
-Key bindings may be changed with the
-.Ic bind-key
+server and clients and destroy all sessions.
+.It Ic kill-session 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.
+.It Ic list-clients
+.D1 (alias: Ic lsc )
+List all clients attached to the server.
+.It Ic list-commands
+.D1 (alias: Ic lscm )
+List the syntax of all commands supported by
+.Nm .
+.It Ic list-sessions
+.D1 (alias: Ic ls )
+List all sessions managed by the server.
+.It Xo Ic new-session
+.Op Fl d
+.Op Fl n Ar window-name
+.Op Fl s Ar session-name
+.Op Ar command
+.Xc
+.D1 (alias: Ic new )
+Create a new session with name
+.Ar session-name .
+The new session is attached to the current terminal unless
+.Fl d
+is given.
+.Ar window-name
 and
-.Ic unbind-key
-commands.
-.Sh HISTORY
+.Ar command
+are the name of and command to execute in the initial window.
+.It Ic refresh-client Op Fl t Ar target-client
+.D1 (alias: Ic refresh )
+Refresh the current client if bound to a key, or a single client if one is given
+with
+.Fl t .
+.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 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
-maintains a configurable history buffer for each window.
-By default, up to 2000 lines are kept; this can be altered with the
-.Ic history-limit
-option (see the
-.Ic set-option
-command below).
-.Sh MODES
+server, if not already running, without creating any sessions.
+.It Xo Ic suspend-client
+.Op Fl c Ar target-client
+.Xc
+.D1 (alias: Ic suspendc )
+Suspend a client by sending
+.Dv SIGTSTP
+(tty stop).
+.It Xo Ic switch-client
+.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 .
+.El
+.Sh WINDOWS AND PANES
 A
 .Nm
 window may be in one of several modes.
@@ -359,55 +460,29 @@ and
 .Pp
 The paste buffer key pastes the first line from the top paste buffer on the
 stack.
-.Sh BUFFERS
-.Nm
-maintains a stack of
-.Em paste buffers
-for each session.
-Up to the value of the
-.Ic buffer-limit
-option are kept; when a new buffer is added, the buffer at the bottom of the
-stack is removed.
-Buffers may be added using
-.Ic copy-mode
-or the
-.Ic set-buffer
-command, and pasted into a window using the
-.Ic paste-buffer
-command.
-.Sh OPTIONS
-The appearance and behaviour of
-.Nm
-may be modified by changing the value of various options.
-There are two types of option:
-.Em session options
-and
-.Em window options .
 .Pp
-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 session options are listed under the
-.Ic set-option
+The mode commands are as follows:
+.Bl -tag -width Ds
+.It Xo Ic copy-mode
+.Op Fl u
+.Op Fl t Ar target-window
+.Xc
+Enter copy mode.
+The
+.Fl u
+option scrolls one page up.
+.It Xo Ic scroll-mode
+.Op Fl u
+.Op Fl t Ar target-window
+.Xc
+Enter scroll mode.
+The
+.Fl u
+has the same meaning as in the
+.Ic copy-mode
 command.
+.El
 .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.
-.Sh PANES AND LAYOUTS
 Each window displayed by
 .Nm
 may be split into one or more
@@ -470,235 +545,9 @@ See the
 .Em main-pane-width
 window option.
 .El
-.Sh STATUS LINE
-.Nm
-includes an optional status line which is displayed in the bottom line of each
-terminal.
-By default, the status line is enabled (it may be disabled with the
-.Ic status
-session option) and contains, from left-to-right: the name of the current
-session in square brackets; the window list; the current window title in double
-quotes; and the time and date.
 .Pp
-The status line is made of three parts: configurable left and right sections
-(which may contain dynamic content such as the time or output from a shell
-command, see the
-.Ic status-left ,
-.Ic status-left-length ,
-.Ic status-right ,
-and
-.Ic status-right-length
-options below), and a central window list.
-The window list shows the index, name and (if any) flag of the windows
-present in the current session in ascending numerical order.
-The flag is one of the following symbols appended to the window name:
-.Bl -column "Symbol" "Meaning" -offset indent
-.It Sy "Symbol" Ta Sy "Meaning"
-.It Li "*" Ta "Denotes the current window."
-.It Li "-" Ta "Marks the last window (previously selected)."
-.It Li "#" Ta "Window is monitored and activity has been detected."
-.It Li "!" Ta "A bell has occurred in the window."
-.It Li "+" Ta "Window is monitored for content and it has appeared."
-.El
-.Pp
-The # symbol relates to the
-.Ic monitor-activity
-and + to the
-.Ic monitor-content
-window options.
-The window name is printed in inverted colours if an alert (bell, activity or
-content) is present.
-.Pp
-The colour and attributes of the status line may be configured, the entire status line using
-the
-.Ic status-attr ,
-.Ic status-fg
-and
-.Ic status-bg
-session options and individual windows using the
-.Ic window-status-attr ,
-.Ic window-status-fg
-and
-.Ic window-status-bg
-window options.
-.Pp
-The status line is automatically refreshed at interval if it has changed, the interval may be
-controlled with the
-.Ic status-interval
-session option.
-.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 either 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 created 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 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.
-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 .
-.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.
-A literal semicolon may be included by escaping it with a backslash (for
-example, when specifying a command sequence to
-.Ic bind-key ) .
-.Pp
-Examples 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 D detach-client \e\; lock-server
-.Ed
-.Pp
-The following commands are available:
+Commands related to windows and panes are as follows:
 .Bl -tag -width Ds
-.It Xo Ic attach-session
-.Op Fl d
-.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.
-.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.
-.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 .
-Keys may be specified prefixed with
-.Ql C-
-or
-.Ql ^
-for Ctrl keys, or
-.Ql M-
-for Alt (meta) keys.
-.Pp
-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 Xo Ic break-pane
 .Op Fl d
 .Op Fl t Ar target-pane
@@ -720,70 +569,6 @@ Put a window into window choice mode, where the window for the session
 attached to the current client may be selected interactively from a list.
 This command works only from inside
 .Nm .
-.It Ic clear-history Op Fl t Ar target-pane
-.D1 (alias: Ic clearhist )
-Remove and free the history for the specified pane.
-.It Ic clock-mode Op Fl t Ar target-window
-Display a large clock.
-.It Xo Ic command-prompt
-.Op Fl t Ar target-client
-.Op Ar template
-.Xc
-Open the command prompt in a client.
-This may be used from inside
-.Nm
-to execute commands interactively.
-If
-.Ar template
-is specified, it is used as the command; any %% in the template will be
-replaced by what is entered at the prompt.
-.It Xo Ic confirm-before
-.Op Fl t Ar target-client
-.Ar command
-.Xc
-.D1 (alias: Ic confirm )
-Ask for confirmation before executing
-.Ar command .
-This command works only from inside
-.Nm .
-.It Xo Ic copy-buffer
-.Op Fl a Ar src-index
-.Op Fl b Ar dst-index
-.Op Fl s Ar src-session
-.Op Fl t Ar dst-session
-.Xc
-.D1 (alias: Ic copyb )
-Copy a session paste buffer to another session.
-If no sessions are specified, the current one is used instead.
-.It Xo Ic copy-mode
-.Op Fl u
-.Op Fl t Ar target-window
-.Xc
-Enter copy mode.
-The
-.Fl u
-option scrolls one page up.
-.It Xo Ic delete-buffer
-.Op Fl b Ar buffer-index
-.Op Fl t Ar target-session
-.Xc
-.D1 (alias: Ic deleteb )
-Delete the buffer at
-.Ar buffer-index ,
-or the top buffer if not specified.
-.It Ic detach-client Op Fl t Ar target-client
-.D1 (alias: Ic detach )
-Detach the current client if bound to a key, or the specified client with
-.Fl t .
-.It Xo Ic display-message
-.Op Fl t Ar target-client
-.Op Ar message
-.Xc
-.D1 (alias: Ic display )
-Display a message (see the
-.Ic status-left
-option below)
-in the status line.
 .It Ic down-pane Op Fl t Ar target-pane
 .D1 (alias: Ic downp )
 Move down a pane.
@@ -801,28 +586,10 @@ If only one window is matched, it'll be automatically selected, otherwise a
 choice list is shown.
 This command only works from inside
 .Nm .
-.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 if-shell Ar shell-command command
-.D1 (alias: Ic if )
-Execute
-.Ar command
-if
-.Ar shell-command
-returns success.
 .It Ic kill-pane Op Fl t Ar target-pane
 .D1 (alias: Ic killp )
 Destroy the given pane.
 If no panes remain in the containing window, it is also destroyed.
-.It Ic kill-server
-Kill the
-.Nm
-server and clients and destroy all sessions.
-.It Ic kill-session 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.
 .It Ic kill-window Op Fl t Ar target-window
 .D1 (alias: Ic killw )
 Kill the current window or the window at
@@ -857,58 +624,10 @@ exists, it is killed, otherwise an error is generated.
 If
 .Fl d
 is given, the newly linked window is not selected.
-.It Ic list-buffers Op Fl t Ar target-session
-.D1 (alias: Ic lsb )
-List the buffers in the given session.
-.It Ic list-clients
-.D1 (alias: Ic lsc )
-List all clients attached to the server.
-.It Ic list-commands
-.D1 (alias: Ic lscm )
-List the syntax of all commands supported by
-.Nm .
-.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.
-Keys bound without the prefix key (see
-.Ic bind-key
-.Fl n )
-are enclosed in square brackets.
-.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 Ic list-sessions
-.D1 (alias: Ic ls )
-List all sessions managed by the server.
 .It Ic list-windows Op Fl t Ar target-session
 .D1 (alias: Ic lsw )
 List windows in the current session or in
 .Ar target-session .
-.It Xo Ic load-buffer
-.Op Fl b Ar buffer-index
-.Op Fl t Ar target-session
-.Ar path
-.Xc
-.D1 (alias: Ic loadb )
-Load the contents of the specified paste buffer from
-.Ar path .
-.It Ic lock-server
-.D1 (alias: Ic lock )
-Lock the server until a password is entered.
 .It Xo Ic move-window
 .Op Fl d
 .Op Fl s Ar src-window
@@ -921,22 +640,6 @@ except the window at
 .Ar src-window
 is moved to
 .Ar dst-window .
-.It Xo Ic new-session
-.Op Fl d
-.Op Fl n Ar window-name
-.Op Fl s Ar session-name
-.Op Ar command
-.Xc
-.D1 (alias: Ic new )
-Create a new session with name
-.Ar session-name .
-The new session is attached to the current terminal unless
-.Fl d
-is given.
-.Ar window-name
-and
-.Ar command
-are the name of and command to execute in the initial window.
 .It Xo Ic new-window
 .Op Fl dk
 .Op Fl n Ar window-name
@@ -982,21 +685,6 @@ Move to the next window in the session.
 If
 .Fl a
 is used, move to the next window with a bell, activity or content alert.
-.It Xo Ic paste-buffer
-.Op Fl dr
-.Op Fl b Ar buffer-index
-.Op Fl t Ar target-window
-.Xc
-.D1 (alias: Ic pasteb )
-Insert the contents of a paste buffer into the current window.
-With
-.Fl d ,
-also delete the paste buffer from the stack.
-When output, any linefeed (LF) characters in the paste buffer are replaced with
-carriage returns (CR).
-This translation may be disabled with the
-.Fl r
-flag.
 .It Xo Ic previous-window
 .Op Fl a
 .Op Fl t Ar target-session
@@ -1006,18 +694,6 @@ Move to the previous window in the session.
 With
 .Fl a ,
 move to the previous window with a bell, activity or content alert.
-.It Ic refresh-client Op Fl t Ar target-client
-.D1 (alias: Ic refresh )
-Refresh the current client if bound to a key, or a single client if one is given
-with
-.Fl t .
-.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 rename-window
 .Op Fl t Ar target-window
 .Ar new-name
@@ -1068,28 +744,6 @@ Rotate the positions of the panes within a window, either upward (numerically
 lower) with
 .Fl U
 or downward (numerically higher).
-.It Xo Ic save-buffer
-.Op Fl a
-.Op Fl b Ar buffer-index
-.Op Fl t Ar target-session
-.Ar path
-.Xc
-.D1 (alias: Ic saveb )
-Save the contents of the specified paste buffer to
-.Ar path .
-The
-.Fl a
-option appends to rather than overwriting the file.
-.It Xo Ic scroll-mode
-.Op Fl u
-.Op Fl t Ar target-window
-.Xc
-Enter scroll mode.
-The
-.Fl u
-has the same meaning as in the
-.Ic copy-mode
-command.
 .It Xo Ic select-layout
 .Op Fl t Ar target-window
 .Op Ar layout-name
@@ -1105,14 +759,189 @@ Make pane
 .Ar target-pane
 the active pane in window
 .Ar target-window .
-.It Ic select-prompt Op Fl t Ar target-client
-Open a prompt inside
-.Ar target-client
-allowing a window index to be entered interactively.
 .It Ic select-window Op Fl t Ar target-window
 .D1 (alias: Ic selectw )
 Select the window at
 .Ar target-window .
+.It Xo Ic split-window
+.Op Fl dhv
+.Oo Fl l
+.Ar size |
+.Fl p Ar percentage Oc
+.Op Fl t Ar target-window
+.Op Ar command
+.Xc
+.D1 (alias: splitw )
+Creates a new pane by splitting the active 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 window in lines (for vertical split) or in
+cells (for horizontal split), or as a percentage, respectively.
+All other options have the same meaning as in 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).
+.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.
+.It Ic up-pane Op Fl t Ar target-pane
+.D1 (alias: Ic upp )
+Move up a pane.
+.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
+Some of the default key bindings include:
+.Pp
+.Bl -tag -width Ds -offset 3n -compact
+.It c
+Create new window.
+.It d
+Detach current client.
+.It l
+Move to last (previously selected) window in the current session.
+.It n
+Change to next window in the current session.
+.It p
+Change to previous window in the current session.
+.It t
+Display a large clock.
+.It \&?
+List current key bindings.
+.El
+.Pp
+A complete list may be obtained with the
+.Ic list-keys
+command (bound to
+.Ql \&?
+by default).
+Key bindings may be changed with the
+.Ic bind-key
+and
+.Ic unbind-key
+commands.
+.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 .
+Keys may be specified prefixed with
+.Ql C-
+or
+.Ql ^
+for Ctrl keys, or
+.Ql M-
+for Alt (meta) keys.
+.Pp
+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.
+Keys bound without the prefix key (see
+.Ic bind-key
+.Fl n )
+are enclosed in square brackets.
+.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 t Ar target-window
 .Ar key Ar ...
@@ -1130,17 +959,67 @@ characters.
 All arguments are sent sequentially from first to last.
 .It Ic send-prefix Op Fl t Ar target-window
 Send the prefix key to a window as if it was pressed.
-.It Ic server-info
-.D1 (alias: Ic info )
-Show server information and terminal details.
-.It Xo Ic set-buffer
-.Op Fl b Ar buffer-index
-.Op Fl t Ar target-session
-.Ar data
+.It Xo Ic unbind-key
+.Op Fl cn
+.Op Fl t Ar key-table
+.Ar key
 .Xc
-.D1 (alias: Ic setb )
-Set the contents of the specified buffer to
-.Ar data .
+.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.
+.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 two types of option:
+.Em session options
+and
+.Em window options .
+.Pp
+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 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
+Commands which set options are as follows:
+.Bl -tag -width Ds
 .It Xo Ic set-option
 .Op Fl gu
 .Op Fl t Ar target-session
@@ -1430,21 +1309,6 @@ for which the
 .Ic monitor-content
 window option is enabled.
 .El
-.It Xo Ic set-password
-.Op Fl c
-.Ar password
-.Xc
-.D1 (alias: Ic pass )
-Set the server password.
-If the
-.Fl c
-option is given, a pre-encrypted password may be specified.
-By default, the password is blank, thus any entered password will be accepted
-when unlocking the server (see the
-.Ic lock-server
-command).
-To prevent variable expansion when an encrypted password is read from a
-configuration file, enclose it in single quotes (').
 .It Xo Ic set-window-option
 .Op Fl gu
 .Op Fl t Ar target-window
@@ -1603,12 +1467,6 @@ will generate
 function key sequences; these have a number included to indicate modifiers such
 as Shift, Alt or Ctrl.
 .El
-.It Xo Ic show-buffer
-.Op Fl b Ar buffer-index
-.Op Fl t Ar target-session
-.Xc
-.D1 (alias: Ic showb )
-Display the contents of the specified buffer.
 .It Xo Ic show-options
 .Op Fl g
 .Op Fl t Ar target-session
@@ -1628,125 +1486,234 @@ List the window options for
 or the global window options if
 .Fl g
 is used.
-.It Ic source-file Ar path
-.D1 (alias: Ic source )
-Execute commands from
-.Ar path .
-.It Xo Ic split-window
-.Op Fl dhv
-.Oo Fl l
-.Ar size |
-.Fl p Ar percentage Oc
-.Op Fl t Ar target-window
-.Op Ar command
-.Xc
-.D1 (alias: splitw )
-Creates a new pane by splitting the active pane:
-.Fl h
-does a horizontal split and
-.Fl v
-a vertical split; if neither is specified,
-.Fl v
-is assumed.
-The
-.Fl l
+.El
+.Sh STATUS LINE
+.Nm
+includes an optional status line which is displayed in the bottom line of each
+terminal.
+By default, the status line is enabled (it may be disabled with the
+.Ic status
+session option) and contains, from left-to-right: the name of the current
+session in square brackets; the window list; the current window title in double
+quotes; and the time and date.
+.Pp
+The status line is made of three parts: configurable left and right sections
+(which may contain dynamic content such as the time or output from a shell
+command, see the
+.Ic status-left ,
+.Ic status-left-length ,
+.Ic status-right ,
 and
-.Fl p
-options specify the size of the new window in lines (for vertical split) or in
-cells (for horizontal split), or as a percentage, respectively.
-All other options have the same meaning as in the
-.Ic new-window
-command.
-.It Ic start-server
-.D1 (alias: Ic start )
-Start the
+.Ic status-right-length
+options below), and a central window list.
+The window list shows the index, name and (if any) flag of the windows
+present in the current session in ascending numerical order.
+The flag is one of the following symbols appended to the window name:
+.Bl -column "Symbol" "Meaning" -offset indent
+.It Sy "Symbol" Ta Sy "Meaning"
+.It Li "*" Ta "Denotes the current window."
+.It Li "-" Ta "Marks the last window (previously selected)."
+.It Li "#" Ta "Window is monitored and activity has been detected."
+.It Li "!" Ta "A bell has occurred in the window."
+.It Li "+" Ta "Window is monitored for content and it has appeared."
+.El
+.Pp
+The # symbol relates to the
+.Ic monitor-activity
+and + to the
+.Ic monitor-content
+window options.
+The window name is printed in inverted colours if an alert (bell, activity or
+content) is present.
+.Pp
+The colour and attributes of the status line may be configured, the entire status line using
+the
+.Ic status-attr ,
+.Ic status-fg
+and
+.Ic status-bg
+session options and individual windows using the
+.Ic window-status-attr ,
+.Ic window-status-fg
+and
+.Ic window-status-bg
+window options.
+.Pp
+The status line is automatically refreshed at interval if it has changed, the interval may be
+controlled with the
+.Ic status-interval
+session option.
+.Pp
+Commands related to the status line are as follows:
+.Bl -tag -width Ds
+.It Xo Ic command-prompt
+.Op Fl t Ar target-client
+.Op Ar template
+.Xc
+Open the command prompt in a client.
+This may be used from inside
 .Nm
-server, if not already running, without creating any sessions.
-.It Xo Ic suspend-client
-.Op Fl c Ar target-client
+to execute commands interactively.
+If
+.Ar template
+is specified, it is used as the command; any %% in the template will be
+replaced by what is entered at the prompt.
+.It Xo Ic confirm-before
+.Op Fl t Ar target-client
+.Ar command
 .Xc
-.D1 (alias: Ic suspendc )
-Suspend a client by sending
-.Dv SIGTSTP
-(tty stop).
-.It Xo Ic swap-pane
-.Op Fl dDU
-.Op Fl s Ar src-pane
-.Op Fl t Ar dst-pane
+.D1 (alias: Ic confirm )
+Ask for confirmation before executing
+.Ar command .
+This command works only from inside
+.Nm .
+.It Xo Ic display-message
+.Op Fl t Ar target-client
+.Op Ar message
 .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).
-.It Xo Ic swap-window
-.Op Fl d
-.Op Fl s Ar src-window
-.Op Fl t Ar dst-window
+.D1 (alias: Ic display )
+Display a message (see the
+.Ic status-left
+option below)
+in the status line.
+.It Ic select-prompt Op Fl t Ar target-client
+Open a prompt inside
+.Ar target-client
+allowing a window index to be entered interactively.
+.El
+.Sh BUFFERS
+.Nm
+maintains a stack of
+.Em paste buffers
+for each session.
+Up to the value of the
+.Ic buffer-limit
+option are kept; when a new buffer is added, the buffer at the bottom of the
+stack is removed.
+Buffers may be added using
+.Ic copy-mode
+or the
+.Ic set-buffer
+command, and pasted into a window using the
+.Ic paste-buffer
+command.
+.Pp
+A configurable history buffer is also maintained for each window.
+By default, up to 2000 lines are kept; this can be altered with the
+.Ic history-limit
+option (see the
+.Ic set-option
+command above).
+.Pp
+The buffer commands are as follows:
+.Bl -tag -width Ds
+.It Ic clear-history Op Fl t Ar target-pane
+.D1 (alias: Ic clearhist )
+Remove and free the history for the specified pane.
+.It Xo Ic copy-buffer
+.Op Fl a Ar src-index
+.Op Fl b Ar dst-index
+.Op Fl s Ar src-session
+.Op Fl t Ar dst-session
 .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 switch-client
-.Op Fl c Ar target-client
+.D1 (alias: Ic copyb )
+Copy a session paste buffer to another session.
+If no sessions are specified, the current one is used instead.
+.It Xo Ic delete-buffer
+.Op Fl b Ar buffer-index
 .Op Fl t Ar target-session
 .Xc
-.D1 (alias: Ic switchc )
-Switch the current session for client
-.Ar target-client
-to
-.Ar target-session .
-.It Xo Ic unbind-key
-.Op Fl cn
-.Op Fl t Ar key-table
-.Ar key
+.D1 (alias: Ic deleteb )
+Delete the buffer at
+.Ar buffer-index ,
+or the top buffer if not specified.
+.It Ic list-buffers Op Fl t Ar target-session
+.D1 (alias: Ic lsb )
+List the buffers in the given session.
+.It Xo Ic load-buffer
+.Op Fl b Ar buffer-index
+.Op Fl t Ar target-session
+.Ar path
 .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.
-.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.
-.It Xo Ic unlink-window
-.Op Fl k
+.D1 (alias: Ic loadb )
+Load the contents of the specified paste buffer from
+.Ar path .
+.It Xo Ic paste-buffer
+.Op Fl dr
+.Op Fl b Ar buffer-index
 .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;
+.D1 (alias: Ic pasteb )
+Insert the contents of a paste buffer into the current window.
+With
+.Fl d ,
+also delete the paste buffer from the stack.
+When output, any linefeed (LF) characters in the paste buffer are replaced with
+carriage returns (CR).
+This translation may be disabled with the
+.Fl r
+flag.
+.It Xo Ic save-buffer
+.Op Fl a
+.Op Fl b Ar buffer-index
+.Op Fl t Ar target-session
+.Ar path
+.Xc
+.D1 (alias: Ic saveb )
+Save the contents of the specified paste buffer to
+.Ar path .
+The
+.Fl a
+option appends to rather than overwriting the file.
+.It Xo Ic set-buffer
+.Op Fl b Ar buffer-index
+.Op Fl t Ar target-session
+.Ar data
+.Xc
+.D1 (alias: Ic setb )
+Set the contents of the specified buffer to
+.Ar data .
+.It Xo Ic show-buffer
+.Op Fl b Ar buffer-index
+.Op Fl t Ar target-session
+.Xc
+.D1 (alias: Ic showb )
+Display the contents of the specified buffer.
+.El
+.Sh MISCELLANEOUS
+.Pp
+Miscellaneous commands are as follows:
+.Bl -tag -width Ds
+.It Ic clock-mode Op Fl t Ar target-window
+Display a large clock.
+.It Ic if-shell Ar shell-command command
+.D1 (alias: Ic if )
+Execute
+.Ar command
 if
-.Fl k
-is specified and the window is linked to only one session, it is unlinked and
-destroyed.
-.It Ic up-pane Op Fl t Ar target-pane
-.D1 (alias: Ic upp )
-Move up a pane.
+.Ar shell-command
+returns success.
+.It Ic lock-server
+.D1 (alias: Ic lock )
+Lock the server until a password is entered.
+.It Ic server-info
+.D1 (alias: Ic info )
+Show server information and terminal details.
+.It Xo Ic set-password
+.Op Fl c
+.Ar password
+.Xc
+.D1 (alias: Ic pass )
+Set the server password.
+If the
+.Fl c
+option is given, a pre-encrypted password may be specified.
+By default, the password is blank, thus any entered password will be accepted
+when unlocking the server (see the
+.Ic lock-server
+command).
+To prevent variable expansion when an encrypted password is read from a
+configuration file, enclose it in single quotes (').
 .El
 .Sh FILES
 .Bl -tag -width "/etc/tmux.confXXX" -compact
@@ -1757,6 +1724,92 @@ configuration file.
 .It Pa /etc/tmux.conf
 System-wide configuration file.
 .El
+.Sh EXAMPLES
+To create a new
+.Nm
+session running
+.Xr vi 1 :
+.Pp
+.Dl $ tmux new-session vi
+.Pp
+Most commands have a shorter form, known as an alias.
+For new-session, this is
+.Ic new :
+.Pp
+.Dl $ tmux new vi
+.Pp
+Alternatively, the shortest unambiguous form of a command is accepted.
+If there are several options, they are listed:
+.Bd -literal -offset indent
+$ tmux n
+ambiguous command: n, could be: new-session, new-window, next-window
+.Ed
+.Pp
+Within an active session, a new window may be created by typing
+.Ql C-b c
+(Ctrl
+followed by the
+.Ql b
+key
+followed by the
+.Ql c
+key).
+.Pp
+Windows may be navigated with:
+.Ql C-b 0
+(to select window 0),
+.Ql C-b 1
+(to select window 1), and so on;
+.Ql C-b n
+to select the next window; and
+.Ql C-b p
+to select the previous window.
+.Pp
+A session may be detached using
+.Ql C-b d
+and reattached with:
+.Pp
+.Dl $ tmux attach-session
+.Pp
+Typing
+.Ql C-b \&?
+lists the current key bindings in the current window; up and down may be used
+to navigate the list or
+.Ql q
+to exit from it.
+.Pp
+Commands to be run when the
+.Nm
+server is started may be placed in the
+.Pa ~/.tmux.conf
+configuration file.
+Common examples include:
+.Pp
+Changing the default prefix key:
+.Bd -literal -offset indent
+set-option -g prefix C-a
+unbind-key C-b
+bind-key C-a send-prefix
+.Ed
+.Pp
+Turning the status line off, or changing its colour:
+.Bd -literal -offset indent
+set-option -g status off
+set-option -g status-bg blue
+.Ed
+.Pp
+Setting other options, such as the default command,
+or locking after 30 minutes of inactivity:
+.Bd -literal -offset indent
+set-option -g default-command "exec /bin/ksh"
+set-option -g lock-after-time 1800
+.Ed
+.Pp
+Creating new key bindings:
+.Bd -literal -offset indent
+bind-key b set-option status
+bind-key / command-prompt "split-window 'exec man %%'"
+.Ed
 .Sh SEE ALSO
 .Xr pty 4
 .Sh AUTHORS