mirror of
https://github.com/tmux/tmux.git
synced 2024-11-17 18:08:51 +00:00
4619 lines
110 KiB
Groff
4619 lines
110 KiB
Groff
.\" $OpenBSD$
|
|
.\"
|
|
.\" Copyright (c) 2007 Nicholas Marriott <nicholas.marriott@gmail.com>
|
|
.\"
|
|
.\" 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$
|
|
.Dt TMUX 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tmux
|
|
.Nd terminal multiplexer
|
|
.Sh SYNOPSIS
|
|
.Nm tmux
|
|
.Bk -words
|
|
.Op Fl 2Cluv
|
|
.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 (see the
|
|
.Sx CONTROL MODE
|
|
section).
|
|
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
|
|
or
|
|
.Pa /tmp
|
|
if it is 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 (note that this will fail if any parent
|
|
directories are missing).
|
|
.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 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
|
|
When starting,
|
|
.Nm
|
|
looks for the
|
|
.Ev LC_ALL ,
|
|
.Ev LC_CTYPE
|
|
and
|
|
.Ev LANG
|
|
environment variables: if the first found contains
|
|
.Ql UTF-8 ,
|
|
then the terminal is assumed to support UTF-8.
|
|
This is not always correct: the
|
|
.Fl u
|
|
flag explicitly informs
|
|
.Nm
|
|
that UTF-8 is supported.
|
|
.Pp
|
|
Note that
|
|
.Nm
|
|
itself always accepts UTF-8; this controls whether it will send UTF-8
|
|
characters to the terminal it is running (if not, they are replaced by
|
|
.Ql _ ) .
|
|
.It Fl v
|
|
Request verbose logging.
|
|
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.
|
|
.Pp
|
|
If
|
|
.Fl v
|
|
is specified twice, an additional
|
|
.Pa tmux-out-PID.log
|
|
file is generated with a copy of everything
|
|
.Nm
|
|
writes to the terminal.
|
|
.Pp
|
|
The
|
|
.Dv SIGUSR2
|
|
signal may be sent to the
|
|
.Nm
|
|
server process to toggle logging between on (as if
|
|
.Fl v
|
|
was given) and off.
|
|
.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 \&(
|
|
Switch the attached client to the previous session.
|
|
.It \&)
|
|
Switch the attached client to the next session.
|
|
.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 L
|
|
Switch the attached client back to the last session.
|
|
.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 m
|
|
Mark the current pane (see
|
|
.Ic select-pane
|
|
.Fl m ) .
|
|
.It M
|
|
Clear the marked pane.
|
|
.It s
|
|
Select a new session for the attached client interactively.
|
|
.It t
|
|
Show the time.
|
|
.It w
|
|
Choose the current window interactively.
|
|
.It x
|
|
Kill the current pane.
|
|
.It z
|
|
Toggle zoom state of 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 Space
|
|
Arrange the current window in the next preset layout.
|
|
.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
|
|
(and sometimes
|
|
.Fl s )
|
|
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.
|
|
.Pp
|
|
.Ar target-client
|
|
should be the name of the client,
|
|
typically 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,
|
|
.Nm
|
|
attempts to work out the client currently in use; if that fails, an error is
|
|
reported.
|
|
Clients may be listed with the
|
|
.Ic list-clients
|
|
command.
|
|
.Pp
|
|
.Ar target-session
|
|
is tried as, in order:
|
|
.Bl -enum -offset Ds
|
|
.It
|
|
A session ID prefixed with a $.
|
|
.It
|
|
An exact name of a session (as listed by the
|
|
.Ic list-sessions
|
|
command).
|
|
.It
|
|
The start of a session name, for example
|
|
.Ql mysess
|
|
would match a session named
|
|
.Ql mysession .
|
|
.It
|
|
An
|
|
.Xr fnmatch 3
|
|
pattern which is matched against the session name.
|
|
.El
|
|
.Pp
|
|
If the session name is prefixed with an
|
|
.Ql = ,
|
|
only an exact match is accepted (so
|
|
.Ql =mysess
|
|
will only match exactly
|
|
.Ql mysess ,
|
|
not
|
|
.Ql mysession ) .
|
|
.Pp
|
|
If a single session 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
|
|
(or
|
|
.Ar src-window
|
|
or
|
|
.Ar dst-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:
|
|
.Bl -enum -offset Ds
|
|
.It
|
|
A special token, listed below.
|
|
.It
|
|
A window index, for example
|
|
.Ql mysession:1
|
|
is window 1 in session
|
|
.Ql mysession .
|
|
.It
|
|
A window ID, such as @1.
|
|
.It
|
|
An exact window name, such as
|
|
.Ql mysession:mywindow .
|
|
.It
|
|
The start of a window name, such as
|
|
.Ql mysession:mywin .
|
|
.It
|
|
As an
|
|
.Xr fnmatch 3
|
|
pattern matched against the window name.
|
|
.El
|
|
.Pp
|
|
Like sessions, a
|
|
.Ql =
|
|
prefix will do an exact match only.
|
|
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.
|
|
.Pp
|
|
The following special tokens are available to indicate particular windows.
|
|
Each has a single-character alternative form.
|
|
.Bl -column "XXXXXXXXXX" "X"
|
|
.It Sy "Token" Ta Sy "" Ta Sy "Meaning"
|
|
.It Li "{start}" Ta "^" Ta "The lowest-numbered window"
|
|
.It Li "{end}" Ta "$" Ta "The highest-numbered window"
|
|
.It Li "{last}" Ta "!" Ta "The last (previously current) window"
|
|
.It Li "{next}" Ta "+" Ta "The next window by number"
|
|
.It Li "{previous}" Ta "-" Ta "The previous window by number"
|
|
.El
|
|
.Pp
|
|
.Ar target-pane
|
|
(or
|
|
.Ar src-pane
|
|
or
|
|
.Ar dst-pane )
|
|
may be a pane ID or takes a similar form to
|
|
.Ar target-window
|
|
but with the optional addition of a period followed by a pane index or pane ID,
|
|
for example:
|
|
.Ql mysession:mywindow.1 .
|
|
If the pane index is omitted, the currently active pane in the specified
|
|
window is used.
|
|
The following special tokens are available for the pane index:
|
|
.Bl -column "XXXXXXXXXXXXXX" "X"
|
|
.It Sy "Token" Ta Sy "" Ta Sy "Meaning"
|
|
.It Li "{last}" Ta "!" Ta "The last (previously active) pane"
|
|
.It Li "{next}" Ta "+" Ta "The next pane by number"
|
|
.It Li "{previous}" Ta "-" Ta "The previous pane by number"
|
|
.It Li "{top}" Ta "" Ta "The top pane"
|
|
.It Li "{bottom}" Ta "" Ta "The bottom pane"
|
|
.It Li "{left}" Ta "" Ta "The leftmost pane"
|
|
.It Li "{right}" Ta "" Ta "The rightmost pane"
|
|
.It Li "{top-left}" Ta "" Ta "The top-left pane"
|
|
.It Li "{top-right}" Ta "" Ta "The top-right pane"
|
|
.It Li "{bottom-left}" Ta "" Ta "The bottom-left pane"
|
|
.It Li "{bottom-right}" Ta "" Ta "The bottom-right pane"
|
|
.It Li "{up-of}" Ta "" Ta "The pane above the active pane"
|
|
.It Li "{down-of}" Ta "" Ta "The pane below the active pane"
|
|
.It Li "{left-of}" Ta "" Ta "The pane to the left of the active pane"
|
|
.It Li "{right-of}" Ta "" Ta "The pane to the right of the active pane"
|
|
.El
|
|
.Pp
|
|
The tokens
|
|
.Ql +
|
|
and
|
|
.Ql -
|
|
may be followed by an offset, for example:
|
|
.Bd -literal -offset indent
|
|
select-window -t:+2
|
|
.Ed
|
|
.Pp
|
|
In addition,
|
|
.Em target-session ,
|
|
.Em target-window
|
|
or
|
|
.Em target-pane
|
|
may consist entirely of the token
|
|
.Ql {mouse}
|
|
(alternative form
|
|
.Ql = )
|
|
to specify the most recent mouse event
|
|
(see the
|
|
.Sx MOUSE SUPPORT
|
|
section)
|
|
or
|
|
.Ql {marked}
|
|
(alternative form
|
|
.Ql ~ )
|
|
to specify the marked pane (see
|
|
.Ic select-pane
|
|
.Fl m ) .
|
|
.Pp
|
|
Sessions, window and panes are each numbered with a unique ID; session IDs are
|
|
prefixed with a
|
|
.Ql $ ,
|
|
windows with a
|
|
.Ql @ ,
|
|
and panes with a
|
|
.Ql % .
|
|
These are unique and are unchanged for the life of the session, window or pane
|
|
in the
|
|
.Nm
|
|
server.
|
|
The pane ID is passed to the child process of the pane in the
|
|
.Ev TMUX_PANE
|
|
environment variable.
|
|
IDs may be displayed using the
|
|
.Ql session_id ,
|
|
.Ql window_id ,
|
|
or
|
|
.Ql pane_id
|
|
formats (see the
|
|
.Sx FORMATS
|
|
section) and the
|
|
.Ic display-message ,
|
|
.Ic list-sessions ,
|
|
.Ic list-windows
|
|
or
|
|
.Ic list-panes
|
|
commands.
|
|
.Pp
|
|
.Ar shell-command
|
|
arguments are
|
|
.Xr sh 1
|
|
commands.
|
|
This may be a single argument passed to the shell, for example:
|
|
.Bd -literal -offset indent
|
|
new-window 'vi /etc/passwd'
|
|
.Ed
|
|
.Pp
|
|
Will run:
|
|
.Bd -literal -offset indent
|
|
/bin/sh -c 'vi /etc/passwd'
|
|
.Ed
|
|
.Pp
|
|
Additionally, the
|
|
.Ic new-window ,
|
|
.Ic new-session ,
|
|
.Ic split-window ,
|
|
.Ic respawn-window
|
|
and
|
|
.Ic respawn-pane
|
|
commands allow
|
|
.Ar shell-command
|
|
to be given as multiple arguments and executed directly (without
|
|
.Ql sh -c ) .
|
|
This can avoid issues with shell quoting.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
$ tmux new-window vi /etc/passwd
|
|
.Ed
|
|
.Pp
|
|
Will run
|
|
.Xr vi 1
|
|
directly without invoking the shell.
|
|
.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 dEr
|
|
.Op Fl c Ar working-directory
|
|
.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.
|
|
.Pp
|
|
.Fl c
|
|
will set the session working directory (used for new windows) to
|
|
.Ar working-directory .
|
|
.Pp
|
|
If
|
|
.Fl E
|
|
is used, the
|
|
.Ic update-environment
|
|
option will not be applied.
|
|
.It Xo Ic detach-client
|
|
.Op Fl aP
|
|
.Op Fl E Ar shell-command
|
|
.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.
|
|
With
|
|
.Fl E ,
|
|
run
|
|
.Ar shell-command
|
|
to replace the client.
|
|
.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 Xo Ic kill-session
|
|
.Op Fl aC
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
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.
|
|
The
|
|
.Fl C
|
|
flag clears alerts (bell, activity, or silence) in all windows linked to the
|
|
session.
|
|
.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 Xo Ic list-commands
|
|
.Op Fl F Ar format
|
|
.Xc
|
|
.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 AdDEP
|
|
.Op Fl c Ar start-directory
|
|
.Op Fl F Ar format
|
|
.Op Fl n Ar window-name
|
|
.Op Fl s Ar session-name
|
|
.Op Fl t Ar group-name
|
|
.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.
|
|
With
|
|
.Fl d ,
|
|
the initial size is 80 x 24;
|
|
.Fl x
|
|
and
|
|
.Fl y
|
|
can be used to specify a different size.
|
|
.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 this case,
|
|
.Fl D
|
|
behaves like
|
|
.Fl d
|
|
to
|
|
.Ic attach-session .
|
|
.Pp
|
|
If
|
|
.Fl t
|
|
is given, it specifies a
|
|
.Ic session group .
|
|
Sessions in the same group share the same set of windows - new windows are
|
|
linked to all sessions in the group and any windows closed removed from all
|
|
sessions.
|
|
The current and previous window and any session options remain independent and
|
|
any session in a group may be killed without affecting the others.
|
|
The
|
|
.Ar group-name
|
|
argument may be:
|
|
.Bl -enum -width Ds
|
|
.It
|
|
the name of an existing group, in which case the new session is added to that
|
|
group;
|
|
.It
|
|
the name of an existing session - the new session is added to the same group
|
|
as that session, creating a new group if necessary;
|
|
.It
|
|
the name for a new group containing only the new session.
|
|
.El
|
|
.Pp
|
|
.Fl n
|
|
and
|
|
.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 .
|
|
.Pp
|
|
If
|
|
.Fl E
|
|
is used, the
|
|
.Ic update-environment
|
|
option will not be applied.
|
|
.It Xo Ic refresh-client
|
|
.Op Fl C Ar width,height
|
|
.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 line.
|
|
.Pp
|
|
.Fl C
|
|
sets the width and height of a control client.
|
|
.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 JT
|
|
.Op Fl t Ar target-client
|
|
.Xc
|
|
.D1 (alias: Ic showmsgs )
|
|
Show client messages or server information.
|
|
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
|
|
server option.
|
|
With
|
|
.Fl t ,
|
|
display the log for
|
|
.Ar target-client .
|
|
.Fl J
|
|
and
|
|
.Fl T
|
|
show debugging information about jobs and terminals.
|
|
.It Xo Ic source-file
|
|
.Op Fl q
|
|
.Ar path
|
|
.Xc
|
|
.D1 (alias: Ic source )
|
|
Execute commands from
|
|
.Ar path
|
|
(which may be a
|
|
.Xr glob 3
|
|
pattern).
|
|
If
|
|
.Fl q
|
|
is given, no error will be returned if
|
|
.Ar path
|
|
does not exist.
|
|
.Pp
|
|
Within a configuration file, commands may be made conditional by surrounding
|
|
them with
|
|
.Em %if
|
|
and
|
|
.Em %endif
|
|
lines.
|
|
Additional
|
|
.Em %elif
|
|
and
|
|
.Em %else
|
|
lines may also be used.
|
|
The argument to
|
|
.Em %if
|
|
and
|
|
.Em %elif
|
|
is expanded as a format and if it evaluates to false (zero or empty),
|
|
subsequent lines are ignored until the next
|
|
.Em %elif ,
|
|
.Em %else
|
|
or
|
|
.Em %endif .
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
%if #{==:#{host},myhost}
|
|
set -g status-style bg=red
|
|
%elif #{==:#{host},myotherhost}
|
|
set -g status-style bg=green
|
|
%else
|
|
set -g status-style bg=blue
|
|
%endif
|
|
.Ed
|
|
.Pp
|
|
Will change the status line to red if running on
|
|
.Ql myhost ,
|
|
green if running on
|
|
.Ql myotherhost ,
|
|
or blue if running on another host.
|
|
.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 Elnpr
|
|
.Op Fl c Ar target-client
|
|
.Op Fl t Ar target-session
|
|
.Op Fl T Ar key-table
|
|
.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).
|
|
.Pp
|
|
If
|
|
.Fl E
|
|
is used,
|
|
.Ic update-environment
|
|
option will not be applied.
|
|
.Pp
|
|
.Fl T
|
|
sets the client's key table; the next key from the client will be interpreted from
|
|
.Ar key-table .
|
|
This may be used to configure multiple prefix keys, or to bind commands to
|
|
sequences of keys.
|
|
For example, to make typing
|
|
.Ql abc
|
|
run the
|
|
.Ic list-keys
|
|
command:
|
|
.Bd -literal -offset indent
|
|
bind-key -Ttable2 c list-keys
|
|
bind-key -Ttable1 b switch-client -Ttable2
|
|
bind-key -Troot a switch-client -Ttable1
|
|
.Ed
|
|
.El
|
|
.Sh WINDOWS AND PANES
|
|
A
|
|
.Nm
|
|
window may be in one of two 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
|
|
Commands are sent to copy mode using the
|
|
.Fl X
|
|
flag to the
|
|
.Ic send-keys
|
|
command.
|
|
When a key is pressed, copy mode automatically uses one of two key tables,
|
|
depending on the
|
|
.Ic mode-keys
|
|
option:
|
|
.Ic copy-mode
|
|
for emacs, or
|
|
.Ic copy-mode-vi
|
|
for vi.
|
|
Key tables may be viewed with the
|
|
.Ic list-keys
|
|
command.
|
|
.Pp
|
|
The following commands are supported in copy mode:
|
|
.Bl -column "CommandXXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent
|
|
.It Sy "Command" Ta Sy "vi" Ta Sy "emacs"
|
|
.It Li "append-selection" Ta "" Ta ""
|
|
.It Li "append-selection-and-cancel" Ta "A" Ta ""
|
|
.It Li "back-to-indentation" Ta "^" Ta "M-m"
|
|
.It Li "begin-selection" Ta "Space" Ta "C-Space"
|
|
.It Li "bottom-line" Ta "L" Ta ""
|
|
.It Li "cancel" Ta "q" Ta "Escape"
|
|
.It Li "clear-selection" Ta "Escape" Ta "C-g"
|
|
.It Li "copy-end-of-line" Ta "D" Ta "C-k"
|
|
.It Li "copy-line" Ta "" Ta ""
|
|
.It Li "copy-pipe <command>" Ta "" Ta ""
|
|
.It Li "copy-pipe-and-cancel <command>" Ta "" Ta ""
|
|
.It Li "copy-selection" Ta "" Ta ""
|
|
.It Li "copy-selection-and-cancel" 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-up" Ta "k" Ta "Up"
|
|
.It Li "end-of-line" Ta "$" Ta "C-e"
|
|
.It Li "goto-line <line>" Ta ":" Ta "g"
|
|
.It Li "halfpage-down" Ta "C-d" Ta "M-Down"
|
|
.It Li "halfpage-down-and-cancel" Ta "" Ta ""
|
|
.It Li "halfpage-up" Ta "C-u" Ta "M-Up"
|
|
.It Li "history-bottom" Ta "G" Ta "M->"
|
|
.It Li "history-top" Ta "g" Ta "M-<"
|
|
.It Li "jump-again" Ta ";" Ta ";"
|
|
.It Li "jump-backward <to>" Ta "F" Ta "F"
|
|
.It Li "jump-forward <to>" Ta "f" Ta "f"
|
|
.It Li "jump-reverse" Ta "," Ta ","
|
|
.It Li "jump-to-backward <to>" Ta "T" Ta ""
|
|
.It Li "jump-to-forward <to>" Ta "t" Ta ""
|
|
.It Li "middle-line" Ta "M" Ta "M-r"
|
|
.It Li "next-paragraph" Ta "}" Ta "M-}"
|
|
.It Li "next-space" Ta "W" Ta ""
|
|
.It Li "next-space-end" Ta "E" Ta ""
|
|
.It Li "next-word" Ta "w" Ta ""
|
|
.It Li "next-word-end" Ta "e" Ta "M-f"
|
|
.It Li "other-end" Ta "o" Ta ""
|
|
.It Li "page-down" Ta "C-f" Ta "PageDown"
|
|
.It Li "page-down-and-cancel" Ta "" Ta ""
|
|
.It Li "page-up" Ta "C-b" Ta "PageUp"
|
|
.It Li "previous-paragraph" Ta "{" Ta "M-{"
|
|
.It Li "previous-space" Ta "B" Ta ""
|
|
.It Li "previous-word" Ta "b" Ta "M-b"
|
|
.It Li "rectangle-toggle" Ta "v" Ta "R"
|
|
.It Li "scroll-down" Ta "C-e" Ta "C-Down"
|
|
.It Li "scroll-down-and-cancel" Ta "" Ta ""
|
|
.It Li "scroll-up" Ta "C-y" Ta "C-Up"
|
|
.It Li "search-again" Ta "n" Ta "n"
|
|
.It Li "search-backward <for>" Ta "?" Ta ""
|
|
.It Li "search-forward <for>" Ta "/" Ta ""
|
|
.It Li "search-backward-incremental <for>" Ta "" Ta "C-r"
|
|
.It Li "search-forward-incremental <for>" Ta "" Ta "C-s"
|
|
.It Li "search-reverse" Ta "N" Ta "N"
|
|
.It Li "select-line" Ta "V" Ta ""
|
|
.It Li "start-of-line" Ta "0" Ta "C-a"
|
|
.It Li "stop-selection" Ta "" Ta ""
|
|
.It Li "top-line" Ta "H" Ta "M-R"
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql -and-cancel
|
|
variants of some commands exit copy mode after they have completed (for copy
|
|
commands) or when the cursor reaches the bottom (for scrolling commands).
|
|
.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.
|
|
.Pp
|
|
The synopsis for the
|
|
.Ic copy-mode
|
|
command is:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic copy-mode
|
|
.Op Fl Meu
|
|
.Op Fl t Ar target-pane
|
|
.Xc
|
|
Enter copy mode.
|
|
The
|
|
.Fl u
|
|
option scrolls one page up.
|
|
.Fl M
|
|
begins a mouse drag (only valid if bound to a mouse key binding, see
|
|
.Sx MOUSE SUPPORT ) .
|
|
.Fl e
|
|
specifies that scrolling to the bottom of the history (to the visible screen)
|
|
should exit copy mode.
|
|
While in copy mode, pressing a key other than those used for scrolling will
|
|
disable this behaviour.
|
|
This is intended to allow fast scrolling through a pane's history, for
|
|
example with:
|
|
.Bd -literal -offset indent
|
|
bind PageUp copy-mode -eu
|
|
.Ed
|
|
.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 n Ar window-name
|
|
.Op Fl s Ar src-pane
|
|
.Op Fl t Ar dst-window
|
|
.Xc
|
|
.D1 (alias: Ic breakp )
|
|
Break
|
|
.Ar src-pane
|
|
off from its containing window to make it the only pane in
|
|
.Ar dst-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 aepPqCJ
|
|
.Op Fl b Ar buffer-name
|
|
.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.
|
|
.Ql -
|
|
to
|
|
.Fl S
|
|
is the start of the history and to
|
|
.Fl E
|
|
the end of the visible pane.
|
|
The default is to capture only the visible contents of the pane.
|
|
.It Xo
|
|
.Ic choose-client
|
|
.Op Fl NZ
|
|
.Op Fl F Ar format
|
|
.Op Fl f Ar filter
|
|
.Op Fl O Ar sort-order
|
|
.Op Fl t Ar target-pane
|
|
.Op Ar template
|
|
.Xc
|
|
Put a pane into client mode, allowing a client to be selected interactively from
|
|
a list.
|
|
.Fl Z
|
|
zooms the pane.
|
|
The following keys may be used in client mode:
|
|
.Bl -column "Key" "Function" -offset indent
|
|
.It Sy "Key" Ta Sy "Function"
|
|
.It Li "Enter" Ta "Choose selected client"
|
|
.It Li "Up" Ta "Select previous client"
|
|
.It Li "Down" Ta "Select next client"
|
|
.It Li "C-s" Ta "Search by name"
|
|
.It Li "n" Ta "Repeat last search"
|
|
.It Li "t" Ta "Toggle if client is tagged"
|
|
.It Li "T" Ta "Tag no clients"
|
|
.It Li "C-t" Ta "Tag all clients"
|
|
.It Li "d" Ta "Detach selected client"
|
|
.It Li "D" Ta "Detach tagged clients"
|
|
.It Li "x" Ta "Detach and HUP selected client"
|
|
.It Li "X" Ta "Detach and HUP tagged clients"
|
|
.It Li "z" Ta "Suspend selected client"
|
|
.It Li "Z" Ta "Suspend tagged clients"
|
|
.It Li "f" Ta "Enter a format to filter items"
|
|
.It Li "O" Ta "Change sort order"
|
|
.It Li "v" Ta "Toggle preview"
|
|
.It Li "q" Ta "Exit mode"
|
|
.El
|
|
.Pp
|
|
After a client is chosen,
|
|
.Ql %%
|
|
is replaced by the client name in
|
|
.Ar template
|
|
and the result executed as a command.
|
|
If
|
|
.Ar template
|
|
is not given, "detach-client -t '%%'" is used.
|
|
.Pp
|
|
.Fl O
|
|
specifies the initial sort order: one of
|
|
.Ql name ,
|
|
.Ql size ,
|
|
.Ql creation ,
|
|
or
|
|
.Ql activity .
|
|
.Fl f
|
|
specifies an initial filter: the filter is a format - if it evaluates to zero,
|
|
the item in the list is not shown, otherwise it is shown.
|
|
If a filter would lead to an empty list, it is ignored.
|
|
.Fl F
|
|
specifies the format for each item in the list.
|
|
.Fl N
|
|
starts without the preview.
|
|
This command works only if at least one client is attached.
|
|
.It Xo
|
|
.Ic choose-tree
|
|
.Op Fl GNswZ
|
|
.Op Fl F Ar format
|
|
.Op Fl f Ar filter
|
|
.Op Fl O Ar sort-order
|
|
.Op Fl t Ar target-pane
|
|
.Op Ar template
|
|
.Xc
|
|
Put a pane into tree mode, where a session, window or pane may be chosen
|
|
interactively from a list.
|
|
.Fl s
|
|
starts with sessions collapsed and
|
|
.Fl w
|
|
with windows collapsed.
|
|
.Fl Z
|
|
zooms the pane.
|
|
The following keys may be used in tree mode:
|
|
.Bl -column "Key" "Function" -offset indent
|
|
.It Sy "Key" Ta Sy "Function"
|
|
.It Li "Enter" Ta "Choose selected item"
|
|
.It Li "Up" Ta "Select previous item"
|
|
.It Li "Down" Ta "Select next item"
|
|
.It Li "x" Ta "Kill selected item"
|
|
.It Li "X" Ta "Kill tagged items"
|
|
.It Li "<" Ta "Scroll list of previews left"
|
|
.It Li ">" Ta "Scroll list of previews right"
|
|
.It Li "C-s" Ta "Search by name"
|
|
.It Li "n" Ta "Repeat last search"
|
|
.It Li "t" Ta "Toggle if item is tagged"
|
|
.It Li "T" Ta "Tag no items"
|
|
.It Li "C-t" Ta "Tag all items"
|
|
.It Li "\&:" Ta "Run a command for each tagged item"
|
|
.It Li "f" Ta "Enter a format to filter items"
|
|
.It Li "O" Ta "Change sort order"
|
|
.It Li "v" Ta "Toggle preview"
|
|
.It Li "q" Ta "Exit mode"
|
|
.El
|
|
.Pp
|
|
After a session, window or pane is chosen,
|
|
.Ql %%
|
|
is replaced by the target in
|
|
.Ar template
|
|
and the result executed as a command.
|
|
If
|
|
.Ar template
|
|
is not given, "switch-client -t '%%'" is used.
|
|
.Pp
|
|
.Fl O
|
|
specifies the initial sort order: one of
|
|
.Ql index ,
|
|
.Ql name ,
|
|
or
|
|
.Ql time .
|
|
.Fl f
|
|
specifies an initial filter: the filter is a format - if it evaluates to zero,
|
|
the item in the list is not shown, otherwise it is shown.
|
|
If a filter would lead to an empty list, it is ignored.
|
|
.Fl F
|
|
specifies the format for each item in the tree.
|
|
.Fl N
|
|
starts without the preview.
|
|
.Fl G
|
|
includes all sessions in any session groups in the tree rather than only the
|
|
first.
|
|
This command works only if at least one client is attached.
|
|
.It Xo
|
|
.Ic display-panes
|
|
.Op Fl d Ar duration
|
|
.Op Fl t Ar target-client
|
|
.Op Ar template
|
|
.Xc
|
|
.D1 (alias: Ic displayp )
|
|
Display a visible indicator of each pane shown by
|
|
.Ar target-client .
|
|
See the
|
|
.Ic display-panes-colour
|
|
and
|
|
.Ic display-panes-active-colour
|
|
session options.
|
|
The indicator is closed when a key is pressed or
|
|
.Ar duration
|
|
milliseconds have passed.
|
|
If
|
|
.Fl d
|
|
is not given,
|
|
.Ic display-panes-time
|
|
is used.
|
|
A duration of zero means the indicator stays until a key is pressed.
|
|
While the indicator is on screen, a pane may be chosen with the
|
|
.Ql 0
|
|
to
|
|
.Ql 9
|
|
keys, which will cause
|
|
.Ar template
|
|
to be executed as a command with
|
|
.Ql %%
|
|
substituted by the pane ID.
|
|
The default
|
|
.Ar template
|
|
is "select-pane -t '%%'".
|
|
.It Xo Ic find-window
|
|
.Op Fl CNT
|
|
.Op Fl t Ar target-pane
|
|
.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 .
|
|
.Pp
|
|
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 .
|
|
.Pp
|
|
If
|
|
.Fl s
|
|
is omitted and a marked pane is present (see
|
|
.Ic select-pane
|
|
.Fl m ) ,
|
|
the marked pane is used rather than the current 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 Xo Ic last-pane
|
|
.Op Fl de
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
.D1 (alias: Ic lastp )
|
|
Select the last (previously selected) pane.
|
|
.Fl e
|
|
enables or
|
|
.Fl d
|
|
disables input to the 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 adk
|
|
.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.
|
|
With
|
|
.Fl a ,
|
|
the window is moved to the next index up (following windows
|
|
are moved if necessary).
|
|
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 ardk
|
|
.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.
|
|
.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
|
|
.Ql screen
|
|
or
|
|
.Ql tmux
|
|
for all programs running
|
|
.Em inside
|
|
.Nm .
|
|
New windows will automatically have
|
|
.Ql 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 IOo
|
|
.Op Fl t Ar target-pane
|
|
.Op Ar shell-command
|
|
.Xc
|
|
.D1 (alias: Ic pipep )
|
|
Pipe output sent by the program in
|
|
.Ar target-pane
|
|
to a shell command or vice versa.
|
|
A pane may only be connected 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
|
|
.Fl I
|
|
and
|
|
.Fl O
|
|
specify which of the
|
|
.Ar shell-command
|
|
output streams are connected to the pane:
|
|
with
|
|
.Fl I
|
|
stdout is connected (so anything
|
|
.Ar shell-command
|
|
prints is written to the pane as if it were typed);
|
|
with
|
|
.Fl O
|
|
stdin is connected (so any output in the pane is piped to
|
|
.Ar shell-command ) .
|
|
Both may be used together and if neither are specified,
|
|
.Fl O
|
|
is used.
|
|
.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 DLMRUZ
|
|
.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).
|
|
.Pp
|
|
.Fl M
|
|
begins mouse resizing (only valid if bound to a mouse key binding, see
|
|
.Sx MOUSE SUPPORT ) .
|
|
.It Xo Ic respawn-pane
|
|
.Op Fl c Ar start-directory
|
|
.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.
|
|
.Fl c
|
|
specifies a new working directory for the pane.
|
|
.It Xo Ic respawn-window
|
|
.Op Fl c Ar start-directory
|
|
.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.
|
|
.Fl c
|
|
specifies a new working directory for the window.
|
|
.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 Enop
|
|
.Op Fl t Ar target-pane
|
|
.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.
|
|
.Fl o
|
|
applies the last set layout if possible (undoes the most recent layout change).
|
|
.Fl E
|
|
spreads the current pane and any panes next to it out evenly.
|
|
.It Xo Ic select-pane
|
|
.Op Fl DdegLlMmRU
|
|
.Op Fl P Ar style
|
|
.Op Fl T Ar title
|
|
.Op Fl t Ar target-pane
|
|
.Xc
|
|
.D1 (alias: Ic selectp )
|
|
Make pane
|
|
.Ar target-pane
|
|
the active pane in window
|
|
.Ar target-window ,
|
|
or set its style (with
|
|
.Fl P ) .
|
|
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.
|
|
.Fl e
|
|
enables or
|
|
.Fl d
|
|
disables input to the pane.
|
|
.Pp
|
|
.Fl m
|
|
and
|
|
.Fl M
|
|
are used to set and clear the
|
|
.Em marked pane .
|
|
There is one marked pane at a time, setting a new marked pane clears the last.
|
|
The marked pane is the default target for
|
|
.Fl s
|
|
to
|
|
.Ic join-pane ,
|
|
.Ic swap-pane
|
|
and
|
|
.Ic swap-window .
|
|
.Pp
|
|
Each pane has a style: by default the
|
|
.Ic window-style
|
|
and
|
|
.Ic window-active-style
|
|
options are used,
|
|
.Ic select-pane
|
|
.Fl P
|
|
sets the style for a single pane.
|
|
For example, to set the pane 1 background to red:
|
|
.Bd -literal -offset indent
|
|
select-pane -t:.1 -P 'bg=red'
|
|
.Ed
|
|
.Pp
|
|
.Fl g
|
|
shows the current pane style.
|
|
.Pp
|
|
.Fl T
|
|
sets the pane title.
|
|
.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 bdfhvP
|
|
.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.
|
|
The
|
|
.Fl b
|
|
option causes the new pane to be created to the left of or above
|
|
.Ar target-pane .
|
|
The
|
|
.Fl f
|
|
option creates a new pane spanning the full window height (with
|
|
.Fl h )
|
|
or full window width (with
|
|
.Fl v ) ,
|
|
instead of splitting the active pane.
|
|
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.
|
|
.Pp
|
|
If
|
|
.Fl s
|
|
is omitted and a marked pane is present (see
|
|
.Ic select-pane
|
|
.Fl m ) ,
|
|
the marked pane is used rather than the current 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 .
|
|
.Pp
|
|
Like
|
|
.Ic swap-pane ,
|
|
if
|
|
.Fl s
|
|
is omitted and a marked pane is present (see
|
|
.Ic select-pane
|
|
.Fl m ) ,
|
|
the window containing the marked pane is used rather than the current 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 F12 ,
|
|
.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 nr
|
|
.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 are bound in a key table.
|
|
By default (without -T), the key is bound in
|
|
the
|
|
.Em prefix
|
|
key table.
|
|
This table is used for keys pressed after the prefix key (for example,
|
|
by default
|
|
.Ql c
|
|
is bound to
|
|
.Ic new-window
|
|
in the
|
|
.Em prefix
|
|
table, so
|
|
.Ql C-b c
|
|
creates a new window).
|
|
The
|
|
.Em root
|
|
table is used for keys pressed without the prefix key: binding
|
|
.Ql c
|
|
to
|
|
.Ic new-window
|
|
in the
|
|
.Em root
|
|
table (not recommended) means a plain
|
|
.Ql c
|
|
will create a new window.
|
|
.Fl n
|
|
is an alias
|
|
for
|
|
.Fl T Ar root .
|
|
Keys may also be bound in custom key tables and the
|
|
.Ic switch-client
|
|
.Fl T
|
|
command used to switch to them from a key binding.
|
|
The
|
|
.Fl r
|
|
flag indicates this key may repeat, see the
|
|
.Ic repeat-time
|
|
option.
|
|
.Pp
|
|
To view the default bindings and possible commands, see the
|
|
.Ic list-keys
|
|
command.
|
|
.It Xo Ic list-keys
|
|
.Op Fl T Ar key-table
|
|
.Xc
|
|
.D1 (alias: Ic lsk )
|
|
List all key bindings.
|
|
Without
|
|
.Fl T
|
|
all key tables are printed.
|
|
With
|
|
.Fl T
|
|
only
|
|
.Ar key-table .
|
|
.It Xo Ic send-keys
|
|
.Op Fl lMRX
|
|
.Op Fl N Ar repeat-count
|
|
.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.
|
|
.Pp
|
|
.Fl M
|
|
passes through a mouse event (only valid if bound to a mouse key binding, see
|
|
.Sx MOUSE SUPPORT ) .
|
|
.Pp
|
|
.Fl X
|
|
is used to send a command into copy mode - see
|
|
the
|
|
.Sx WINDOWS AND PANES
|
|
section.
|
|
.Fl N
|
|
specifies a repeat count.
|
|
.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 an
|
|
.Op Fl T Ar key-table
|
|
.Ar key
|
|
.Xc
|
|
.D1 (alias: Ic unbind )
|
|
Unbind the command bound to
|
|
.Ar key .
|
|
.Fl n
|
|
and
|
|
.Fl T
|
|
are the same as for
|
|
.Ic bind-key .
|
|
If
|
|
.Fl a
|
|
is present, all key bindings are removed.
|
|
.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 aFgoqsuw
|
|
.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.
|
|
If
|
|
.Fl g
|
|
is given, the global session or window option is set.
|
|
.Fl F
|
|
expands formats in the option value.
|
|
The
|
|
.Fl u
|
|
flag unsets an option, so a session inherits the option from the global
|
|
options (or with
|
|
.Fl g ,
|
|
restores a global option to the default).
|
|
.Pp
|
|
The
|
|
.Fl o
|
|
flag prevents setting an option that is already set and the
|
|
.Fl q
|
|
flag suppresses errors about unknown or ambiguous options.
|
|
.Pp
|
|
With
|
|
.Fl a ,
|
|
and if the option expects a string or a style,
|
|
.Ar value
|
|
is appended to the existing setting.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
set -g status-left "foo"
|
|
set -ag status-left "bar"
|
|
.Ed
|
|
.Pp
|
|
Will result in
|
|
.Ql foobar .
|
|
And:
|
|
.Bd -literal -offset indent
|
|
set -g status-style "bg=red"
|
|
set -ag status-style "fg=blue"
|
|
.Ed
|
|
.Pp
|
|
Will result in a red background
|
|
.Em and
|
|
blue foreground.
|
|
Without
|
|
.Fl a ,
|
|
the result would be the default background and a blue foreground.
|
|
.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 Xo Ic command-alias[]
|
|
.Ar name=value
|
|
.Xc
|
|
This is an array of custom aliases for commands.
|
|
If an unknown command matches
|
|
.Ar name ,
|
|
it is replaced with
|
|
.Ar value .
|
|
For example, after:
|
|
.Pp
|
|
.Dl set -s command-alias[100] zoom='resize-pane -Z'
|
|
.Pp
|
|
Using:
|
|
.Pp
|
|
.Dl zoom -t:.1
|
|
.Pp
|
|
Is equivalent to:
|
|
.Pp
|
|
.Dl resize-pane -Z -t:.1
|
|
.Pp
|
|
Note that aliases are expanded when a command is parsed rather than when it is
|
|
executed, so binding an alias with
|
|
.Ic bind-key
|
|
will bind the expanded form.
|
|
.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 ,
|
|
.Ql tmux
|
|
or a derivative of them.
|
|
.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-empty
|
|
.Op Ic on | off
|
|
.Xc
|
|
If enabled (the default), the server will exit when there are no active
|
|
sessions.
|
|
.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 focus-events
|
|
.Op Ic on | off
|
|
.Xc
|
|
When enabled, focus events are requested from the terminal if supported and
|
|
passed through to applications running in
|
|
.Nm .
|
|
Attached clients should be detached and attached again after changing this
|
|
option.
|
|
.It Ic history-file Ar path
|
|
If not empty, a file to which
|
|
.Nm
|
|
will write command prompt history on exit and load it from on start.
|
|
.It Ic message-limit Ar number
|
|
Set the number of error or information messages to save in the message log for
|
|
each client.
|
|
The default is 100.
|
|
.It Xo Ic set-clipboard
|
|
.Op Ic on | external | off
|
|
.Xc
|
|
Attempt to set the terminal clipboard content using the
|
|
.Xr xterm 1
|
|
escape sequence, if there is an
|
|
.Em \&Ms
|
|
entry in the
|
|
.Xr terminfo 5
|
|
description (see the
|
|
.Sx TERMINFO EXTENSIONS
|
|
section).
|
|
.Pp
|
|
If set to
|
|
.Ic on ,
|
|
.Nm
|
|
will both accept the escape sequence to create a buffer and attempt to set
|
|
the terminal clipboard.
|
|
If set to
|
|
.Ic external ,
|
|
.Nm
|
|
will attempt to set the terminal clipboard but ignore attempts
|
|
by applications to set
|
|
.Nm
|
|
buffers.
|
|
If
|
|
.Ic off ,
|
|
.Nm
|
|
will neither accept the clipboard escape sequence nor attempt to set the
|
|
clipboard.
|
|
.Pp
|
|
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.
|
|
.It Ic terminal-overrides[] Ar string
|
|
Allow terminal descriptions read using
|
|
.Xr terminfo 5
|
|
to be overridden.
|
|
Each entry is a colon-separated string made up of a terminal type pattern
|
|
(matched using
|
|
.Xr fnmatch 3 )
|
|
and a set of
|
|
.Em name=value
|
|
entries.
|
|
.Pp
|
|
For example, to set the
|
|
.Ql clear
|
|
.Xr terminfo 5
|
|
entry to
|
|
.Ql \ee[H\ee[2J
|
|
for all terminal types matching
|
|
.Ql rxvt* :
|
|
.Pp
|
|
.Dl "rxvt*:clear=\ee[H\ee[2J"
|
|
.Pp
|
|
The terminal entry value is passed through
|
|
.Xr strunvis 3
|
|
before interpretation.
|
|
.El
|
|
.Pp
|
|
Available session options are:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic activity-action
|
|
.Op Ic any | none | current | other
|
|
.Xc
|
|
Set action on window activity when
|
|
.Ic monitor-activity
|
|
is on.
|
|
.Ic any
|
|
means activity in any window linked to a session causes a bell or message
|
|
(depending on
|
|
.Ic visual-activity )
|
|
in the current window of that session,
|
|
.Ic none
|
|
means all activity is ignored (equivalent to
|
|
.Ic monitor-activity
|
|
being off),
|
|
.Ic current
|
|
means only activity in windows other than the current window are ignored and
|
|
.Ic other
|
|
means activity in the current window is ignored but not those in other windows.
|
|
.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 | other
|
|
.Xc
|
|
Set action on a bell in a window when
|
|
.Ic monitor-bell
|
|
is on.
|
|
The values are the same as those for
|
|
.Ic activity-action .
|
|
.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-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 Xo Ic destroy-unattached
|
|
.Op Ic on | off
|
|
.Xc
|
|
If enabled and the session is no longer attached to any clients, it is
|
|
destroyed.
|
|
.It Xo Ic detach-on-destroy
|
|
.Op Ic on | off
|
|
.Xc
|
|
If on (the default), the client is detached when the session it is attached to
|
|
is destroyed.
|
|
If off, the client is switched to the most recently active of the remaining
|
|
sessions.
|
|
.It Ic display-panes-active-colour Ar colour
|
|
Set the colour used by the
|
|
.Ic display-panes
|
|
command to show the indicator for the active pane.
|
|
.It Ic display-panes-colour Ar colour
|
|
Set the colour used by the
|
|
.Ic display-panes
|
|
command to show the indicators for inactive panes.
|
|
.It Ic display-panes-time Ar time
|
|
Set the time in milliseconds for which the indicators shown by the
|
|
.Ic display-panes
|
|
command appear.
|
|
.It Ic display-time Ar time
|
|
Set the amount of time for which status line messages and other on-screen
|
|
indicators are displayed.
|
|
If set to 0, messages and indicators are displayed until a key is pressed.
|
|
.Ar time
|
|
is in milliseconds.
|
|
.It Ic history-limit Ar lines
|
|
Set the maximum number of lines held in window history.
|
|
This setting applies only to new windows - existing window histories are not
|
|
resized and retain the limit at the point they were created.
|
|
.It Ic key-table Ar key-table
|
|
Set the default key table to
|
|
.Ar key-table
|
|
instead of
|
|
.Em root .
|
|
.It Ic lock-after-time Ar number
|
|
Lock the session (like the
|
|
.Ic lock-session
|
|
command) after
|
|
.Ar number
|
|
seconds of inactivity.
|
|
The default is not to lock (set to 0).
|
|
.It Ic lock-command Ar shell-command
|
|
Command to run when locking each client.
|
|
The default is to run
|
|
.Xr lock 1
|
|
with
|
|
.Fl np .
|
|
.It Ic message-command-style Ar style
|
|
Set status line message command style, where
|
|
.Ar style
|
|
is a comma-separated list of characteristics to be specified.
|
|
.Pp
|
|
These may be
|
|
.Ql bg=colour
|
|
to set the background colour,
|
|
.Ql fg=colour
|
|
to set the foreground colour, and a list of attributes as specified below.
|
|
.Pp
|
|
The colour is one of:
|
|
.Ic black ,
|
|
.Ic red ,
|
|
.Ic green ,
|
|
.Ic yellow ,
|
|
.Ic blue ,
|
|
.Ic magenta ,
|
|
.Ic cyan ,
|
|
.Ic white ,
|
|
aixterm bright variants (if supported:
|
|
.Ic brightred ,
|
|
.Ic brightgreen ,
|
|
and so on),
|
|
.Ic colour0
|
|
to
|
|
.Ic colour255
|
|
from the 256-colour set,
|
|
.Ic default ,
|
|
or a hexadecimal RGB string such as
|
|
.Ql #ffffff ,
|
|
which chooses the closest match from the default 256-colour set.
|
|
.Pp
|
|
The attributes is either
|
|
.Ic none
|
|
or a comma-delimited list of one or more of:
|
|
.Ic bright
|
|
(or
|
|
.Ic bold ) ,
|
|
.Ic dim ,
|
|
.Ic underscore ,
|
|
.Ic blink ,
|
|
.Ic reverse ,
|
|
.Ic hidden ,
|
|
.Ic italics ,
|
|
or
|
|
.Ic strikethrough
|
|
to turn an attribute on, or an attribute prefixed with
|
|
.Ql no
|
|
to turn one off.
|
|
.Pp
|
|
Examples are:
|
|
.Bd -literal -offset indent
|
|
fg=yellow,bold,underscore,blink
|
|
bg=black,fg=default,noreverse
|
|
.Ed
|
|
.Pp
|
|
With the
|
|
.Fl a
|
|
flag to the
|
|
.Ic set-option
|
|
command the new style is added otherwise the existing style is replaced.
|
|
.It Ic message-style Ar style
|
|
Set status line message style.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.It Xo Ic mouse
|
|
.Op Ic on | off
|
|
.Xc
|
|
If on,
|
|
.Nm
|
|
captures the mouse and allows mouse events to be bound as key bindings.
|
|
See the
|
|
.Sx MOUSE SUPPORT
|
|
section for details.
|
|
.It Ic prefix Ar key
|
|
Set the key accepted as a prefix key.
|
|
In addition to the standard keys described under
|
|
.Sx KEY BINDINGS ,
|
|
.Ic prefix
|
|
can be set to the special key
|
|
.Ql None
|
|
to set no prefix.
|
|
.It Ic prefix2 Ar key
|
|
Set a secondary key accepted as a prefix key.
|
|
Like
|
|
.Ic prefix ,
|
|
.Ic prefix2
|
|
can be set to
|
|
.Ql None .
|
|
.It Xo Ic renumber-windows
|
|
.Op Ic on | off
|
|
.Xc
|
|
If on, when a window is closed in a session, automatically renumber the other
|
|
windows in numerical order.
|
|
This respects the
|
|
.Ic base-index
|
|
option if it has been set.
|
|
If off, do not renumber the windows.
|
|
.It Ic repeat-time Ar time
|
|
Allow multiple commands to be entered without pressing the prefix-key again
|
|
in the specified
|
|
.Ar time
|
|
milliseconds (the default is 500).
|
|
Whether a key repeats may be set when it is bound using the
|
|
.Fl r
|
|
flag to
|
|
.Ic bind-key .
|
|
Repeat is enabled for the default keys bound to the
|
|
.Ic resize-pane
|
|
command.
|
|
.It Xo Ic set-titles
|
|
.Op Ic on | off
|
|
.Xc
|
|
Attempt to set the client terminal title using the
|
|
.Em tsl
|
|
and
|
|
.Em fsl
|
|
.Xr terminfo 5
|
|
entries if they exist.
|
|
.Nm
|
|
automatically sets these to the \ee]0;...\e007 sequence if
|
|
the terminal appears to be
|
|
.Xr xterm 1 .
|
|
This option is off by default.
|
|
.It Ic set-titles-string Ar string
|
|
String used to set the window title if
|
|
.Ic set-titles
|
|
is on.
|
|
Formats are expanded, see the
|
|
.Sx FORMATS
|
|
section.
|
|
.It Xo Ic silence-action
|
|
.Op Ic any | none | current | other
|
|
.Xc
|
|
Set action on window silence when
|
|
.Ic monitor-silence
|
|
is on.
|
|
The values are the same as those for
|
|
.Ic activity-action .
|
|
.It Xo Ic status
|
|
.Op Ic on | off
|
|
.Xc
|
|
Show or hide the status line.
|
|
.It Ic status-interval Ar interval
|
|
Update the status line every
|
|
.Ar interval
|
|
seconds.
|
|
By default, updates will occur every 15 seconds.
|
|
A setting of zero disables redrawing at interval.
|
|
.It Xo Ic status-justify
|
|
.Op Ic left | centre | right
|
|
.Xc
|
|
Set the position of the window list component of the status line: left, centre
|
|
or right justified.
|
|
.It Xo Ic status-keys
|
|
.Op Ic vi | emacs
|
|
.Xc
|
|
Use vi or emacs-style
|
|
key bindings in the status line, for example at the command prompt.
|
|
The default is emacs, unless the
|
|
.Ev VISUAL
|
|
or
|
|
.Ev EDITOR
|
|
environment variables are set and contain the string
|
|
.Ql vi .
|
|
.It Ic status-left Ar string
|
|
Display
|
|
.Ar string
|
|
(by default the session name) to the left of the status line.
|
|
.Ar string
|
|
will be passed through
|
|
.Xr strftime 3
|
|
and formats (see
|
|
.Sx FORMATS )
|
|
will be expanded.
|
|
It may also contain the special character sequence #[] to change the colour
|
|
or attributes, for example
|
|
.Ql #[fg=red,bright]
|
|
to set a bright red foreground.
|
|
See the
|
|
.Ic message-command-style
|
|
option for a description of colours and attributes.
|
|
.Pp
|
|
For details on how the names and titles can be set see the
|
|
.Sx "NAMES AND TITLES"
|
|
section.
|
|
.Pp
|
|
Examples are:
|
|
.Bd -literal -offset indent
|
|
#(sysctl vm.loadavg)
|
|
#[fg=yellow,bold]#(apm -l)%%#[default] [#S]
|
|
.Ed
|
|
.Pp
|
|
The default is
|
|
.Ql "[#S] " .
|
|
.It Ic status-left-length Ar length
|
|
Set the maximum
|
|
.Ar length
|
|
of the left component of the status line.
|
|
The default is 10.
|
|
.It Ic status-left-style Ar style
|
|
Set the style of the left part of the status line.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.It Xo Ic status-position
|
|
.Op Ic top | bottom
|
|
.Xc
|
|
Set the position of the status line.
|
|
.It Ic status-right Ar string
|
|
Display
|
|
.Ar string
|
|
to the right of the status line.
|
|
By default, the current pane title in double quotes, the date and the time
|
|
are shown.
|
|
As with
|
|
.Ic status-left ,
|
|
.Ar string
|
|
will be passed to
|
|
.Xr strftime 3
|
|
and character pairs are replaced.
|
|
.It Ic status-right-length Ar length
|
|
Set the maximum
|
|
.Ar length
|
|
of the right component of the status line.
|
|
The default is 40.
|
|
.It Ic status-right-style Ar style
|
|
Set the style of the right part of the status line.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.It Ic status-style Ar style
|
|
Set status line style.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.It Ic update-environment[] Ar variable
|
|
Set list of environment variables to be copied into the session environment
|
|
when a new session is created or an existing session is attached.
|
|
Any variables that do not exist in the source environment are set to be
|
|
removed from the session environment (as if
|
|
.Fl r
|
|
was given to the
|
|
.Ic set-environment
|
|
command).
|
|
.It Ic user-keys[] Ar key
|
|
Set list of user-defined key escape sequences.
|
|
Each item is associated with a key named
|
|
.Ql User0 ,
|
|
.Ql User1 ,
|
|
and so on.
|
|
.Pp
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
set -s user-keys[0] "\ee[5;30012~"
|
|
bind User0 resize-pane -L 3
|
|
.Ed
|
|
.It Xo Ic visual-activity
|
|
.Op Ic on | off | both
|
|
.Xc
|
|
If on, display a message instead of sending a bell when activity occurs in a
|
|
window for which the
|
|
.Ic monitor-activity
|
|
window option is enabled.
|
|
If set to both, a bell and a message are produced.
|
|
.It Xo Ic visual-bell
|
|
.Op Ic on | off | both
|
|
.Xc
|
|
If on, a message is shown on a bell in a window for which the
|
|
.Ic monitor-bell
|
|
window option is enabled instead of it being passed through to the
|
|
terminal (which normally makes a sound).
|
|
If set to both, a bell and a message are produced.
|
|
Also see the
|
|
.Ic bell-action
|
|
option.
|
|
.It Xo Ic visual-silence
|
|
.Op Ic on | off | both
|
|
.Xc
|
|
If
|
|
.Ic monitor-silence
|
|
is enabled, prints a message after the interval has expired on a given window
|
|
instead of sending a bell.
|
|
If set to both, a bell and a message are produced.
|
|
.It Ic word-separators Ar string
|
|
Sets the session's conception of what characters are considered word
|
|
separators, for the purposes of the next and previous word commands in
|
|
copy mode.
|
|
The default is
|
|
.Ql \ -_@ .
|
|
.El
|
|
.It Xo Ic set-window-option
|
|
.Op Fl aFgoqu
|
|
.Op Fl t Ar target-window
|
|
.Ar option Ar value
|
|
.Xc
|
|
.D1 (alias: Ic setw )
|
|
Set a window option.
|
|
The
|
|
.Fl a ,
|
|
.Fl F ,
|
|
.Fl g ,
|
|
.Fl o ,
|
|
.Fl q
|
|
and
|
|
.Fl u
|
|
flags work similarly to the
|
|
.Ic set-option
|
|
command.
|
|
.Pp
|
|
Supported window options are:
|
|
.Pp
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo Ic aggressive-resize
|
|
.Op Ic on | off
|
|
.Xc
|
|
Aggressively resize the chosen window.
|
|
This means that
|
|
.Nm
|
|
will resize the window to the size of the smallest session for which it is the
|
|
current window, rather than the smallest session to which it is attached.
|
|
The window may resize when the current window is changed on another sessions;
|
|
this option is good for full-screen programs which support
|
|
.Dv SIGWINCH
|
|
and poor for interactive programs such as shells.
|
|
.Pp
|
|
.It Xo Ic allow-rename
|
|
.Op Ic on | off
|
|
.Xc
|
|
Allow programs to change the window name using a terminal escape
|
|
sequence (\eek...\ee\e\e).
|
|
The default is off.
|
|
.Pp
|
|
.It Xo Ic alternate-screen
|
|
.Op Ic on | off
|
|
.Xc
|
|
This option configures whether programs running inside
|
|
.Nm
|
|
may use the terminal alternate screen feature, which allows the
|
|
.Em smcup
|
|
and
|
|
.Em rmcup
|
|
.Xr terminfo 5
|
|
capabilities.
|
|
The alternate screen feature preserves the contents of the window when an
|
|
interactive application starts and restores it on exit, so that any output
|
|
visible before the application starts reappears unchanged after it exits.
|
|
The default is on.
|
|
.Pp
|
|
.It Xo Ic automatic-rename
|
|
.Op Ic on | off
|
|
.Xc
|
|
Control automatic window renaming.
|
|
When this setting is enabled,
|
|
.Nm
|
|
will rename the window automatically using the format specified by
|
|
.Ic automatic-rename-format .
|
|
This flag is automatically disabled for an individual window when a name
|
|
is specified at creation with
|
|
.Ic new-window
|
|
or
|
|
.Ic new-session ,
|
|
or later with
|
|
.Ic rename-window ,
|
|
or with a terminal escape sequence.
|
|
It may be switched off globally with:
|
|
.Bd -literal -offset indent
|
|
set-window-option -g automatic-rename off
|
|
.Ed
|
|
.Pp
|
|
.It Ic automatic-rename-format Ar format
|
|
The format (see
|
|
.Sx FORMATS )
|
|
used when the
|
|
.Ic automatic-rename
|
|
option is enabled.
|
|
.Pp
|
|
.It Ic clock-mode-colour Ar colour
|
|
Set clock colour.
|
|
.Pp
|
|
.It Xo Ic clock-mode-style
|
|
.Op Ic 12 | 24
|
|
.Xc
|
|
Set clock hour format.
|
|
.Pp
|
|
.It Ic force-height Ar height
|
|
.It Ic force-width Ar width
|
|
Prevent
|
|
.Nm
|
|
from resizing a window to greater than
|
|
.Ar width
|
|
or
|
|
.Ar height .
|
|
A value of zero restores the default unlimited setting.
|
|
.Pp
|
|
.It Ic main-pane-height Ar height
|
|
.It Ic main-pane-width Ar width
|
|
Set the width or height of the main (left or top) pane in the
|
|
.Ic main-horizontal
|
|
or
|
|
.Ic main-vertical
|
|
layouts.
|
|
.Pp
|
|
.It Xo Ic mode-keys
|
|
.Op Ic vi | emacs
|
|
.Xc
|
|
Use vi or emacs-style key bindings in copy mode.
|
|
The default is emacs, unless
|
|
.Ev VISUAL
|
|
or
|
|
.Ev EDITOR
|
|
contains
|
|
.Ql vi .
|
|
.Pp
|
|
.It Ic mode-style Ar style
|
|
Set window modes style.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Xo Ic monitor-activity
|
|
.Op Ic on | off
|
|
.Xc
|
|
Monitor for activity in the window.
|
|
Windows with activity are highlighted in the status line.
|
|
.Pp
|
|
.It Xo Ic monitor-bell
|
|
.Op Ic on | off
|
|
.Xc
|
|
Monitor for a bell in the window.
|
|
Windows with a bell are highlighted in the status line.
|
|
.Pp
|
|
.It Xo Ic monitor-silence
|
|
.Op Ic interval
|
|
.Xc
|
|
Monitor for silence (no activity) in the window within
|
|
.Ic interval
|
|
seconds.
|
|
Windows that have been silent for the interval are highlighted in the
|
|
status line.
|
|
An interval of zero disables the monitoring.
|
|
.Pp
|
|
.It Ic other-pane-height Ar height
|
|
Set the height of the other panes (not the main pane) in the
|
|
.Ic main-horizontal
|
|
layout.
|
|
If this option is set to 0 (the default), it will have no effect.
|
|
If both the
|
|
.Ic main-pane-height
|
|
and
|
|
.Ic other-pane-height
|
|
options are set, the main pane will grow taller to make the other panes the
|
|
specified height, but will never shrink to do so.
|
|
.Pp
|
|
.It Ic other-pane-width Ar width
|
|
Like
|
|
.Ic other-pane-height ,
|
|
but set the width of other panes in the
|
|
.Ic main-vertical
|
|
layout.
|
|
.Pp
|
|
.It Ic pane-active-border-style Ar style
|
|
Set the pane border style for the currently active pane.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
Attributes are ignored.
|
|
.Pp
|
|
.It Ic pane-base-index Ar index
|
|
Like
|
|
.Ic base-index ,
|
|
but set the starting index for pane numbers.
|
|
.Pp
|
|
.It Ic pane-border-format Ar format
|
|
Set the text shown in pane border status lines.
|
|
.Pp
|
|
.It Xo Ic pane-border-status
|
|
.Op Ic off | top | bottom
|
|
.Xc
|
|
Turn pane border status lines off or set their position.
|
|
.Pp
|
|
.It Ic pane-border-style Ar style
|
|
Set the pane border style for panes aside from the active pane.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
Attributes are ignored.
|
|
.Pp
|
|
.It Xo Ic remain-on-exit
|
|
.Op Ic on | off
|
|
.Xc
|
|
A window with this flag set is not destroyed when the program running in it
|
|
exits.
|
|
The window may be reactivated with the
|
|
.Ic respawn-window
|
|
command.
|
|
.Pp
|
|
.It Xo Ic synchronize-panes
|
|
.Op Ic on | off
|
|
.Xc
|
|
Duplicate input to any pane to all other panes in the same window (only
|
|
for panes that are not in any special mode).
|
|
.Pp
|
|
.It Ic window-active-style Ar style
|
|
Set the style for the window's active pane.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Ic window-status-activity-style Ar style
|
|
Set status line style for windows with an activity alert.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Ic window-status-bell-style Ar style
|
|
Set status line style for windows with a bell alert.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Ic window-status-current-format Ar string
|
|
Like
|
|
.Ar window-status-format ,
|
|
but is the format used when the window is the current window.
|
|
.Pp
|
|
.It Ic window-status-current-style Ar style
|
|
Set status line style for the currently active window.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Ic window-status-format Ar string
|
|
Set the format in which the window is displayed in the status line window list.
|
|
See the
|
|
.Ar status-left
|
|
option for details of special character sequences available.
|
|
The default is
|
|
.Ql #I:#W#F .
|
|
.Pp
|
|
.It Ic window-status-last-style Ar style
|
|
Set status line style for the last active window.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Ic window-status-separator Ar string
|
|
Sets the separator drawn between windows in the status line.
|
|
The default is a single space character.
|
|
.Pp
|
|
.It Ic window-status-style Ar style
|
|
Set status line style for a single window.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Ic window-style Ar style
|
|
Set the default window style.
|
|
For how to specify
|
|
.Ar style ,
|
|
see the
|
|
.Ic message-command-style
|
|
option.
|
|
.Pp
|
|
.It Xo Ic wrap-search
|
|
.Op Ic on | off
|
|
.Xc
|
|
If this option is set, searches will wrap around the end of the pane contents.
|
|
The default is on.
|
|
.Pp
|
|
.It Xo Ic xterm-keys
|
|
.Op Ic on | off
|
|
.Xc
|
|
If this option is set,
|
|
.Nm
|
|
will generate
|
|
.Xr xterm 1 -style
|
|
function key sequences; these have a number included to indicate modifiers such
|
|
as Shift, Alt or Ctrl.
|
|
.El
|
|
.It Xo Ic show-options
|
|
.Op Fl gqsvw
|
|
.Op Fl t Ar target-session | Ar target-window
|
|
.Op Ar option
|
|
.Xc
|
|
.D1 (alias: Ic show )
|
|
Show the window options (or a single window option if given) with
|
|
.Fl w
|
|
(equivalent to
|
|
.Ic show-window-options ) ,
|
|
the server options with
|
|
.Fl s ,
|
|
otherwise the session options for
|
|
.Ar target session .
|
|
Global session or window options are listed if
|
|
.Fl g
|
|
is used.
|
|
.Fl v
|
|
shows only the option value, not the name.
|
|
If
|
|
.Fl q
|
|
is set, no error will be returned if
|
|
.Ar option
|
|
is unset.
|
|
.It Xo Ic show-window-options
|
|
.Op Fl gv
|
|
.Op Fl t Ar target-window
|
|
.Op Ar option
|
|
.Xc
|
|
.D1 (alias: Ic showw )
|
|
List the window options or a single option for
|
|
.Ar target-window ,
|
|
or the global window options if
|
|
.Fl g
|
|
is used.
|
|
.Fl v
|
|
shows only the option value, not the name.
|
|
.El
|
|
.Sh HOOKS
|
|
.Nm
|
|
allows commands to run on various triggers, called
|
|
.Em hooks .
|
|
Most
|
|
.Nm
|
|
commands have an
|
|
.Em after
|
|
hook and there are a number of hooks not associated with commands.
|
|
.Pp
|
|
A command's after
|
|
hook is run after it completes, except when the command is run as part of a hook
|
|
itself.
|
|
They are named with an
|
|
.Ql after-
|
|
prefix.
|
|
For example, the following command adds a hook to select the even-vertical
|
|
layout after every
|
|
.Ic split-window :
|
|
.Bd -literal -offset indent
|
|
set-hook after-split-window "selectl even-vertical"
|
|
.Ed
|
|
.Pp
|
|
All the notifications listed in the
|
|
.Sx CONTROL MODE
|
|
section are hooks (without any arguments), except
|
|
.Ic %exit .
|
|
The following additional hooks are available:
|
|
.Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXX"
|
|
.It alert-activity
|
|
Run when a window has activity.
|
|
See
|
|
.Ic monitor-activity .
|
|
.It alert-bell
|
|
Run when a window has received a bell.
|
|
See
|
|
.Ic monitor-bell .
|
|
.It alert-silence
|
|
Run when a window has been silent.
|
|
See
|
|
.Ic monitor-silence .
|
|
.It client-attached
|
|
Run when a client is attached.
|
|
.It client-detached
|
|
Run when a client is detached
|
|
.It client-resized
|
|
Run when a client is resized.
|
|
.It client-session-changed
|
|
Run when a client's attached session is changed.
|
|
.It pane-died
|
|
Run when the program running in a pane exits, but
|
|
.Ic remain-on-exit
|
|
is on so the pane has not closed.
|
|
.It pane-exited
|
|
Run when the program running in a pane exits.
|
|
.It pane-set-clipboard
|
|
Run when the terminal clipboard is set using the
|
|
.Xr xterm 1
|
|
escape sequence.
|
|
.It session-created
|
|
Run when a new session created.
|
|
.It session-closed
|
|
Run when a session closed.
|
|
.It session-renamed
|
|
Run when a session is renamed.
|
|
.It window-linked
|
|
Run when a window is linked into a session.
|
|
.It window-renamed
|
|
Run when a window is renamed.
|
|
.It window-unlinked
|
|
Run when a window is unlinked from a session.
|
|
.El
|
|
.Pp
|
|
Hooks are managed with these commands:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic set-hook
|
|
.Op Fl gu
|
|
.Op Fl t Ar target-session
|
|
.Ar hook-name
|
|
.Ar command
|
|
.Xc
|
|
Sets (or with
|
|
.Fl u
|
|
unsets) hook
|
|
.Ar hook-name
|
|
to
|
|
.Ar command .
|
|
If
|
|
.Fl g
|
|
is given,
|
|
.Em hook-name
|
|
is added to the global list of hooks, otherwise it is added to the session
|
|
hooks (for
|
|
.Ar target-session
|
|
with
|
|
.Fl t ) .
|
|
Like options, session hooks inherit from the global ones.
|
|
.It Xo Ic show-hooks
|
|
.Op Fl g
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
Shows the global list of hooks with
|
|
.Fl g ,
|
|
otherwise the session hooks.
|
|
.El
|
|
.Sh MOUSE SUPPORT
|
|
If the
|
|
.Ic mouse
|
|
option is on (the default is off),
|
|
.Nm
|
|
allows mouse events to be bound as keys.
|
|
The name of each key is made up of a mouse event (such as
|
|
.Ql MouseUp1 )
|
|
and a location suffix (one of
|
|
.Ql Pane
|
|
for the contents of a pane,
|
|
.Ql Border
|
|
for a pane border or
|
|
.Ql Status
|
|
for the status line).
|
|
The following mouse events are available:
|
|
.Bl -column "MouseDown1" "MouseDrag1" "WheelDown" -offset indent
|
|
.It Li "WheelUp" Ta "WheelDown" Ta ""
|
|
.It Li "MouseDown1" Ta "MouseUp1" Ta "MouseDrag1" Ta "MouseDragEnd1"
|
|
.It Li "MouseDown2" Ta "MouseUp2" Ta "MouseDrag2" Ta "MouseDragEnd2"
|
|
.It Li "MouseDown3" Ta "MouseUp3" Ta "MouseDrag3" Ta "MouseDragEnd3"
|
|
.It Li "DoubleClick1" Ta "DoubleClick2" Ta "DoubleClick3"
|
|
.It Li "TripleClick1" Ta "TripleClick2" Ta "TripleClick3"
|
|
.El
|
|
.Pp
|
|
Each should be suffixed with a location, for example
|
|
.Ql MouseDown1Status .
|
|
.Pp
|
|
The special token
|
|
.Ql {mouse}
|
|
or
|
|
.Ql =
|
|
may be used as
|
|
.Ar target-window
|
|
or
|
|
.Ar target-pane
|
|
in commands bound to mouse key bindings.
|
|
It resolves to the window or pane over which the mouse event took place
|
|
(for example, the window in the status line over which button 1 was released for a
|
|
.Ql MouseUp1Status
|
|
binding, or the pane over which the wheel was scrolled for a
|
|
.Ql WheelDownPane
|
|
binding).
|
|
.Pp
|
|
The
|
|
.Ic send-keys
|
|
.Fl M
|
|
flag may be used to forward a mouse event to a pane.
|
|
.Pp
|
|
The default key bindings allow the mouse to be used to select and resize panes,
|
|
to copy text and to change window using the status line.
|
|
These take effect if the
|
|
.Ic mouse
|
|
option is turned on.
|
|
.Sh FORMATS
|
|
Certain commands accept the
|
|
.Fl F
|
|
flag with a
|
|
.Ar format
|
|
argument.
|
|
This is a string which controls the output format of the command.
|
|
Replacement variables are enclosed in
|
|
.Ql #{
|
|
and
|
|
.Ql } ,
|
|
for example
|
|
.Ql #{session_name} .
|
|
The possible variables are listed in the table below, or the name of a
|
|
.Nm
|
|
option may be used for an option's value.
|
|
Some variables have a shorter alias such as
|
|
.Ql #S ,
|
|
and
|
|
.Ql ##
|
|
is replaced by a single
|
|
.Ql # .
|
|
.Pp
|
|
Conditionals are available by prefixing with
|
|
.Ql \&?
|
|
and separating two alternatives with a comma;
|
|
if the specified variable exists and is not zero, the first alternative
|
|
is chosen, otherwise the second is used.
|
|
For example
|
|
.Ql #{?session_attached,attached,not attached}
|
|
will include the string
|
|
.Ql attached
|
|
if the session is attached and the string
|
|
.Ql not attached
|
|
if it is unattached, or
|
|
.Ql #{?automatic-rename,yes,no}
|
|
will include
|
|
.Ql yes
|
|
if
|
|
.Ic automatic-rename
|
|
is enabled, or
|
|
.Ql no
|
|
if not.
|
|
.Pp
|
|
Comparisons may be expressed by prefixing two comma-separated
|
|
alternatives by
|
|
.Ql ==
|
|
or
|
|
.Ql !=
|
|
and a colon.
|
|
For example
|
|
.Ql #{==:#{host},myhost}
|
|
will be replaced by
|
|
.Ql 1
|
|
if running on
|
|
.Ql myhost ,
|
|
otherwise by
|
|
.Ql 0 .
|
|
An
|
|
.Ql m
|
|
specifies an
|
|
.Xr fnmatch 3
|
|
comparison where the first argument is the pattern and the second the string to
|
|
compare, for example
|
|
.Ql #{m:*foo*,#{host}} .
|
|
.Ql ||
|
|
and
|
|
.Ql &&
|
|
evaluate to true if either or both of two comma-separated alternatives are
|
|
true, for example
|
|
.Ql #{||:#{pane_in_mode},#{alternate_on}} .
|
|
A
|
|
.Ql C
|
|
performs a search for an
|
|
.Xr fnmatch 3
|
|
pattern in the pane content and evaluates to zero if not found, or a line
|
|
number if found.
|
|
.Pp
|
|
A limit may be placed on the length of the resultant string by prefixing it
|
|
by an
|
|
.Ql = ,
|
|
a number and a colon.
|
|
Positive numbers count from the start of the string and negative from the end,
|
|
so
|
|
.Ql #{=5:pane_title}
|
|
will include at most the first 5 characters of the pane title, or
|
|
.Ql #{=-5:pane_title}
|
|
the last 5 characters.
|
|
Prefixing a time variable with
|
|
.Ql t:
|
|
will convert it to a string, so if
|
|
.Ql #{window_activity}
|
|
gives
|
|
.Ql 1445765102 ,
|
|
.Ql #{t:window_activity}
|
|
gives
|
|
.Ql Sun Oct 25 09:25:02 2015 .
|
|
The
|
|
.Ql b:
|
|
and
|
|
.Ql d:
|
|
prefixes are
|
|
.Xr basename 3
|
|
and
|
|
.Xr dirname 3
|
|
of the variable respectively.
|
|
A prefix of the form
|
|
.Ql s/foo/bar/:
|
|
will substitute
|
|
.Ql foo
|
|
with
|
|
.Ql bar
|
|
throughout.
|
|
.Pp
|
|
In addition, the first line of a shell command's output may be inserted using
|
|
.Ql #() .
|
|
For example,
|
|
.Ql #(uptime)
|
|
will insert the system's uptime.
|
|
When constructing formats,
|
|
.Nm
|
|
does not wait for
|
|
.Ql #()
|
|
commands to finish; instead, the previous result from running the same command is used,
|
|
or a placeholder if the command has not been run before.
|
|
If the command hasn't exited, the most recent line of output will be used, but the status
|
|
line will not be updated more than once a second.
|
|
Commands are executed with the
|
|
.Nm
|
|
global environment set (see the
|
|
.Sx ENVIRONMENT
|
|
section).
|
|
.Pp
|
|
The following variables are available, where appropriate:
|
|
.Bl -column "XXXXXXXXXXXXXXXXXXX" "XXXXX"
|
|
.It Sy "Variable name" Ta Sy "Alias" Ta Sy "Replaced with"
|
|
.It Li "alternate_on" Ta "" Ta "If pane is in alternate screen"
|
|
.It Li "alternate_saved_x" Ta "" Ta "Saved cursor X in alternate screen"
|
|
.It Li "alternate_saved_y" Ta "" Ta "Saved cursor Y in alternate screen"
|
|
.It Li "buffer_created" Ta "" Ta "Time buffer created"
|
|
.It Li "buffer_name" Ta "" Ta "Name of buffer"
|
|
.It Li "buffer_sample" Ta "" Ta "Sample of start of buffer"
|
|
.It Li "buffer_size" Ta "" Ta "Size of the specified buffer in bytes"
|
|
.It Li "client_activity" Ta "" Ta "Time client last had activity"
|
|
.It Li "client_created" Ta "" Ta "Time client created"
|
|
.It Li "client_control_mode" Ta "" Ta "1 if client is in control mode"
|
|
.It Li "client_discarded" Ta "" Ta "Bytes discarded when client behind"
|
|
.It Li "client_height" Ta "" Ta "Height of client"
|
|
.It Li "client_key_table" Ta "" Ta "Current key table"
|
|
.It Li "client_last_session" Ta "" Ta "Name of the client's last session"
|
|
.It Li "client_name" Ta "" Ta "Name of client"
|
|
.It Li "client_pid" Ta "" Ta "PID of client process"
|
|
.It Li "client_prefix" Ta "" Ta "1 if prefix key has been pressed"
|
|
.It Li "client_readonly" Ta "" Ta "1 if client is readonly"
|
|
.It Li "client_session" Ta "" Ta "Name of the client's session"
|
|
.It Li "client_termname" Ta "" Ta "Terminal name of client"
|
|
.It Li "client_termtype" Ta "" Ta "Terminal type of client"
|
|
.It Li "client_tty" Ta "" Ta "Pseudo terminal of client"
|
|
.It Li "client_utf8" Ta "" Ta "1 if client supports utf8"
|
|
.It Li "client_width" Ta "" Ta "Width of client"
|
|
.It Li "client_written" Ta "" Ta "Bytes written to client"
|
|
.It Li "command" Ta "" Ta "Name of command in use, if any"
|
|
.It Li "command_list_name" Ta "" Ta "Command name if listing commands"
|
|
.It Li "command_list_alias" Ta "" Ta "Command alias if listing commands"
|
|
.It Li "command_list_usage" Ta "" Ta "Command usage if listing commands"
|
|
.It Li "cursor_flag" Ta "" Ta "Pane cursor flag"
|
|
.It Li "cursor_x" Ta "" Ta "Cursor X position in pane"
|
|
.It Li "cursor_y" Ta "" Ta "Cursor Y position in pane"
|
|
.It Li "history_bytes" Ta "" Ta "Number of bytes in window history"
|
|
.It Li "history_limit" Ta "" Ta "Maximum window history lines"
|
|
.It Li "history_size" Ta "" Ta "Size of history in lines"
|
|
.It Li "hook" Ta "" Ta "Name of running hook, if any"
|
|
.It Li "hook_pane" Ta "" Ta "ID of pane where hook was run, if any"
|
|
.It Li "hook_session" Ta "" Ta "ID of session where hook was run, if any"
|
|
.It Li "hook_session_name" Ta "" Ta "Name of session where hook was run, if any"
|
|
.It Li "hook_window" Ta "" Ta "ID of window where hook was run, if any"
|
|
.It Li "hook_window_name" Ta "" Ta "Name of window where hook was run, if any"
|
|
.It Li "host" Ta "#H" Ta "Hostname of local host"
|
|
.It Li "host_short" Ta "#h" Ta "Hostname of local host (no domain name)"
|
|
.It Li "insert_flag" Ta "" Ta "Pane insert flag"
|
|
.It Li "keypad_cursor_flag" Ta "" Ta "Pane keypad cursor flag"
|
|
.It Li "keypad_flag" Ta "" Ta "Pane keypad flag"
|
|
.It Li "line" Ta "" Ta "Line number in the list"
|
|
.It Li "mouse_any_flag" Ta "" Ta "Pane mouse any flag"
|
|
.It Li "mouse_button_flag" Ta "" Ta "Pane mouse button flag"
|
|
.It Li "mouse_standard_flag" Ta "" Ta "Pane mouse standard flag"
|
|
.It Li "mouse_all_flag" Ta "" Ta "Pane mouse all flag"
|
|
.It Li "pane_active" Ta "" Ta "1 if active pane"
|
|
.It Li "pane_at_bottom" Ta "" Ta "1 if pane is at the bottom of window"
|
|
.It Li "pane_at_left" Ta "" Ta "1 if pane is at the left of window"
|
|
.It Li "pane_at_right" Ta "" Ta "1 if pane is at the right of window"
|
|
.It Li "pane_at_top" Ta "" Ta "1 if pane is at the top of window"
|
|
.It Li "pane_bottom" Ta "" Ta "Bottom of pane"
|
|
.It Li "pane_current_command" Ta "" Ta "Current command if available"
|
|
.It Li "pane_dead" Ta "" Ta "1 if pane is dead"
|
|
.It Li "pane_dead_status" Ta "" Ta "Exit status of process in dead pane"
|
|
.It Li "pane_format" Ta "" Ta "1 if format is for a pane (not assuming the current)"
|
|
.It Li "pane_height" Ta "" Ta "Height of pane"
|
|
.It Li "pane_id" Ta "#D" Ta "Unique pane ID"
|
|
.It Li "pane_in_mode" Ta "" Ta "If pane is in a mode"
|
|
.It Li "pane_input_off" Ta "" Ta "If input to pane is disabled"
|
|
.It Li "pane_index" Ta "#P" Ta "Index of pane"
|
|
.It Li "pane_left" Ta "" Ta "Left of pane"
|
|
.It Li "pane_mode" Ta "" Ta "Name of pane mode, if any."
|
|
.It Li "pane_pid" Ta "" Ta "PID of first process in pane"
|
|
.It Li "pane_pipe" Ta "" Ta "1 if pane is being piped"
|
|
.It Li "pane_right" Ta "" Ta "Right of pane"
|
|
.It Li "pane_search_string" Ta "" Ta "Last search string in copy mode"
|
|
.It Li "pane_start_command" Ta "" Ta "Command pane started with"
|
|
.It Li "pane_synchronized" Ta "" Ta "If pane is synchronized"
|
|
.It Li "pane_tabs" Ta "" Ta "Pane tab positions"
|
|
.It Li "pane_title" Ta "#T" Ta "Title of pane"
|
|
.It Li "pane_top" Ta "" Ta "Top of pane"
|
|
.It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
|
|
.It Li "pane_width" Ta "" Ta "Width of pane"
|
|
.It Li "pid" Ta "" Ta "Server PID"
|
|
.It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
|
|
.It Li "scroll_region_upper" Ta "" Ta "Top of scroll region in pane"
|
|
.It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
|
|
.It Li "selection_present" Ta "" Ta "1 if selection started in copy mode"
|
|
.It Li "session_alerts" Ta "" Ta "List of window indexes with alerts"
|
|
.It Li "session_attached" Ta "" Ta "Number of clients session is attached to"
|
|
.It Li "session_activity" Ta "" Ta "Time of session last activity"
|
|
.It Li "session_created" Ta "" Ta "Time session created"
|
|
.It Li "session_format" Ta "" Ta "1 if format is for a session (not assuming the current)"
|
|
.It Li "session_last_attached" Ta "" Ta "Time session last attached"
|
|
.It Li "session_group" Ta "" Ta "Name of session group"
|
|
.It Li "session_group_size" Ta "" Ta "Size of session group"
|
|
.It Li "session_group_list" Ta "" Ta "List of sessions in group"
|
|
.It Li "session_grouped" Ta "" Ta "1 if session in a group"
|
|
.It Li "session_height" Ta "" Ta "Height of session"
|
|
.It Li "session_id" Ta "" Ta "Unique session ID"
|
|
.It Li "session_many_attached" Ta "" Ta "1 if multiple clients attached"
|
|
.It Li "session_name" Ta "#S" Ta "Name of session"
|
|
.It Li "session_stack" Ta "" Ta "Window indexes in most recent order"
|
|
.It Li "session_width" Ta "" Ta "Width of session"
|
|
.It Li "session_windows" Ta "" Ta "Number of windows in session"
|
|
.It Li "socket_path" Ta "" Ta "Server socket path"
|
|
.It Li "start_time" Ta "" Ta "Server start time"
|
|
.It Li "window_activity" Ta "" Ta "Time of window last activity"
|
|
.It Li "window_activity_flag" Ta "" Ta "1 if window has activity"
|
|
.It Li "window_active" Ta "" Ta "1 if window active"
|
|
.It Li "window_bell_flag" Ta "" Ta "1 if window has bell"
|
|
.It Li "window_flags" Ta "#F" Ta "Window flags"
|
|
.It Li "window_format" Ta "" Ta "1 if format is for a window (not assuming the current)"
|
|
.It Li "window_height" Ta "" Ta "Height of window"
|
|
.It Li "window_id" Ta "" Ta "Unique window ID"
|
|
.It Li "window_index" Ta "#I" Ta "Index of window"
|
|
.It Li "window_last_flag" Ta "" Ta "1 if window is the last used"
|
|
.It Li "window_layout" Ta "" Ta "Window layout description, ignoring zoomed window panes"
|
|
.It Li "window_linked" Ta "" Ta "1 if window is linked across sessions"
|
|
.It Li "window_name" Ta "#W" Ta "Name of window"
|
|
.It Li "window_panes" Ta "" Ta "Number of panes in window"
|
|
.It Li "window_silence_flag" Ta "" Ta "1 if window has silence alert"
|
|
.It Li "window_stack_index" Ta "" Ta "Index in session most recent stack"
|
|
.It Li "window_visible_layout" Ta "" Ta "Window layout description, respecting zoomed window panes"
|
|
.It Li "window_width" Ta "" Ta "Width of window"
|
|
.It Li "window_zoomed_flag" Ta "" Ta "1 if window is zoomed"
|
|
.It Li "wrap_flag" Ta "" Ta "Pane wrap flag"
|
|
.El
|
|
.Sh NAMES AND TITLES
|
|
.Nm
|
|
distinguishes between names and titles.
|
|
Windows and sessions have names, which may be used to specify them in targets
|
|
and are displayed in the status line and various lists: the name is the
|
|
.Nm
|
|
identifier for a window or session.
|
|
Only panes have titles.
|
|
A pane's title is typically set by the program running inside the pane using
|
|
an escape sequence (like it would set the
|
|
.Xr xterm 1
|
|
window title in
|
|
.Xr X 7 ) .
|
|
Windows themselves do not have titles - a window's title is the title of its
|
|
active pane.
|
|
.Nm
|
|
itself may set the title of the terminal in which the client is running, see
|
|
the
|
|
.Ic set-titles
|
|
option.
|
|
.Pp
|
|
A session's name is set with the
|
|
.Ic new-session
|
|
and
|
|
.Ic rename-session
|
|
commands.
|
|
A window's name is set with one of:
|
|
.Bl -enum -width Ds
|
|
.It
|
|
A command argument (such as
|
|
.Fl n
|
|
for
|
|
.Ic new-window
|
|
or
|
|
.Ic new-session ) .
|
|
.It
|
|
An escape sequence:
|
|
.Bd -literal -offset indent
|
|
$ printf '\e033kWINDOW_NAME\e033\e\e'
|
|
.Ed
|
|
.It
|
|
Automatic renaming, which sets the name to the active command in the window's
|
|
active pane.
|
|
See the
|
|
.Ic automatic-rename
|
|
option.
|
|
.El
|
|
.Pp
|
|
When a pane is first created, its title is the hostname.
|
|
A pane's title can be set via the OSC title setting sequence, for example:
|
|
.Bd -literal -offset indent
|
|
$ printf '\e033]2;My Title\e033\e\e'
|
|
.Ed
|
|
.Pp
|
|
It can also be modified with the
|
|
.Ic select-pane
|
|
.Fl T
|
|
command.
|
|
.Sh ENVIRONMENT
|
|
When the server is started,
|
|
.Nm
|
|
copies the environment into the
|
|
.Em global environment ;
|
|
in addition, each session has a
|
|
.Em session environment .
|
|
When a window is created, the session and global environments are merged.
|
|
If a variable exists in both, the value from the session environment is used.
|
|
The result is the initial environment passed to the new process.
|
|
.Pp
|
|
The
|
|
.Ic update-environment
|
|
session option may be used to update the session environment from the client
|
|
when a new session is created or an old reattached.
|
|
.Nm
|
|
also initialises the
|
|
.Ev TMUX
|
|
variable with some internal information to allow commands to be executed
|
|
from inside, and the
|
|
.Ev TERM
|
|
variable with the correct terminal setting of
|
|
.Ql screen .
|
|
.Pp
|
|
Commands to alter and view the environment are:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic set-environment
|
|
.Op Fl gru
|
|
.Op Fl t Ar target-session
|
|
.Ar name Op Ar value
|
|
.Xc
|
|
.D1 (alias: Ic setenv )
|
|
Set or unset an environment variable.
|
|
If
|
|
.Fl g
|
|
is used, the change is made in the global environment; otherwise, it is applied
|
|
to the session environment for
|
|
.Ar target-session .
|
|
The
|
|
.Fl u
|
|
flag unsets a variable.
|
|
.Fl r
|
|
indicates the variable is to be removed from the environment before starting a
|
|
new process.
|
|
.It Xo Ic show-environment
|
|
.Op Fl gs
|
|
.Op Fl t Ar target-session
|
|
.Op Ar variable
|
|
.Xc
|
|
.D1 (alias: Ic showenv )
|
|
Display the environment for
|
|
.Ar target-session
|
|
or the global environment with
|
|
.Fl g .
|
|
If
|
|
.Ar variable
|
|
is omitted, all variables are shown.
|
|
Variables removed from the environment are prefixed with
|
|
.Ql - .
|
|
If
|
|
.Fl s
|
|
is used, the output is formatted as a set of Bourne shell commands.
|
|
.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 title of the active pane
|
|
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.
|
|
By default, the window list shows the index, name and (if any) flag of the
|
|
windows present in the current session in ascending numerical order.
|
|
It may be customised with the
|
|
.Ar window-status-format
|
|
and
|
|
.Ar window-status-current-format
|
|
options.
|
|
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 activity is monitored and activity has been detected."
|
|
.It Li "\&!" Ta "Window bells are monitored and a bell has occurred in the window."
|
|
.It Li "~" Ta "The window has been silent for the monitor-silence interval."
|
|
.It Li "M" Ta "The window contains the marked pane."
|
|
.It Li "Z" Ta "The window's active pane is zoomed."
|
|
.El
|
|
.Pp
|
|
The # symbol relates to the
|
|
.Ic monitor-activity
|
|
window option.
|
|
The window name is printed in inverted colours if an alert (bell, activity or
|
|
silence) is present.
|
|
.Pp
|
|
The colour and attributes of the status line may be configured, the entire
|
|
status line using the
|
|
.Ic status-style
|
|
session option and individual windows using the
|
|
.Ic window-status-style
|
|
window option.
|
|
.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 1i
|
|
.Op Fl I Ar inputs
|
|
.Op Fl p Ar prompts
|
|
.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.
|
|
.Pp
|
|
If
|
|
.Ar template
|
|
is specified, it is used as the command.
|
|
If present,
|
|
.Fl I
|
|
is a comma-separated list of the initial text for each prompt.
|
|
If
|
|
.Fl p
|
|
is given,
|
|
.Ar prompts
|
|
is a comma-separated list of prompts which are displayed in order; otherwise
|
|
a single prompt is displayed, constructed from
|
|
.Ar template
|
|
if it is present, or
|
|
.Ql \&:
|
|
if not.
|
|
.Pp
|
|
Before the command is executed, the first occurrence of the string
|
|
.Ql %%
|
|
and all occurrences of
|
|
.Ql %1
|
|
are replaced by the response to the first prompt, all
|
|
.Ql %2
|
|
are replaced with the response to the second prompt, and so on for further
|
|
prompts.
|
|
Up to nine prompt responses may be replaced
|
|
.Po
|
|
.Ql %1
|
|
to
|
|
.Ql %9
|
|
.Pc .
|
|
.Ql %%%
|
|
is like
|
|
.Ql %%
|
|
but any quotation marks are escaped.
|
|
.Pp
|
|
.Fl 1
|
|
makes the prompt only accept one key press, in this case the resulting input
|
|
is a single character.
|
|
.Fl i
|
|
executes the command every time the prompt input changes instead of when the
|
|
user exits the command prompt.
|
|
.Pp
|
|
The following keys have a special meaning in the command prompt, depending
|
|
on the value of the
|
|
.Ic status-keys
|
|
option:
|
|
.Bl -column "FunctionXXXXXXXXXXXXXXXXXXXXXXXXX" "viXXXX" "emacsX" -offset indent
|
|
.It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
|
|
.It Li "Cancel command prompt" Ta "Escape" Ta "Escape"
|
|
.It Li "Delete current word" Ta "" Ta "C-w"
|
|
.It Li "Delete entire command" Ta "d" Ta "C-u"
|
|
.It Li "Delete from cursor to end" Ta "D" Ta "C-k"
|
|
.It Li "Execute command" Ta "Enter" Ta "Enter"
|
|
.It Li "Get next command from history" Ta "" Ta "Down"
|
|
.It Li "Get previous command from history" Ta "" Ta "Up"
|
|
.It Li "Insert top paste buffer" Ta "p" Ta "C-y"
|
|
.It Li "Look for completions" Ta "Tab" Ta "Tab"
|
|
.It Li "Move cursor left" Ta "h" Ta "Left"
|
|
.It Li "Move cursor right" Ta "l" Ta "Right"
|
|
.It Li "Move cursor to end" Ta "$" Ta "C-e"
|
|
.It Li "Move cursor to next word" Ta "w" Ta "M-f"
|
|
.It Li "Move cursor to previous word" Ta "b" Ta "M-b"
|
|
.It Li "Move cursor to start" Ta "0" Ta "C-a"
|
|
.It Li "Transpose characters" Ta "" Ta "C-t"
|
|
.El
|
|
.It Xo Ic confirm-before
|
|
.Op Fl p Ar prompt
|
|
.Op Fl t Ar target-client
|
|
.Ar command
|
|
.Xc
|
|
.D1 (alias: Ic confirm )
|
|
Ask for confirmation before executing
|
|
.Ar command .
|
|
If
|
|
.Fl p
|
|
is given,
|
|
.Ar prompt
|
|
is the prompt to display; otherwise a prompt is constructed from
|
|
.Ar command .
|
|
It may contain the special character sequences supported by the
|
|
.Ic status-left
|
|
option.
|
|
.Pp
|
|
This command works only from inside
|
|
.Nm .
|
|
.It Xo Ic display-message
|
|
.Op Fl p
|
|
.Op Fl c Ar target-client
|
|
.Op Fl t Ar target-pane
|
|
.Op Ar message
|
|
.Xc
|
|
.D1 (alias: Ic display )
|
|
Display a message.
|
|
If
|
|
.Fl p
|
|
is given, the output is printed to stdout, otherwise it is displayed in the
|
|
.Ar target-client
|
|
status line.
|
|
The format of
|
|
.Ar message
|
|
is described in the
|
|
.Sx FORMATS
|
|
section; information is taken from
|
|
.Ar target-pane
|
|
if
|
|
.Fl t
|
|
is given, otherwise the active pane for the session attached to
|
|
.Ar target-client .
|
|
.El
|
|
.Sh BUFFERS
|
|
.Nm
|
|
maintains a set of named
|
|
.Em paste buffers .
|
|
Each buffer may be either explicitly or automatically named.
|
|
Explicitly named buffers are named when created with the
|
|
.Ic set-buffer
|
|
or
|
|
.Ic load-buffer
|
|
commands, or by renaming an automatically named buffer with
|
|
.Ic set-buffer
|
|
.Fl n .
|
|
Automatically named buffers are given a name such as
|
|
.Ql buffer0001 ,
|
|
.Ql buffer0002
|
|
and so on.
|
|
When the
|
|
.Ic buffer-limit
|
|
option is reached, the oldest automatically named buffer is deleted.
|
|
Explicitly named buffers are not subject to
|
|
.Ic buffer-limit
|
|
and may be deleted with
|
|
.Ic delete-buffer
|
|
command.
|
|
.Pp
|
|
Buffers may be added using
|
|
.Ic copy-mode
|
|
or the
|
|
.Ic set-buffer
|
|
and
|
|
.Ic load-buffer
|
|
commands, and pasted into a window using the
|
|
.Ic paste-buffer
|
|
command.
|
|
If a buffer command is used and no buffer is specified, the most
|
|
recently added automatically named buffer is assumed.
|
|
.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 Xo
|
|
.Ic choose-buffer
|
|
.Op Fl NZ
|
|
.Op Fl F Ar format
|
|
.Op Fl f Ar filter
|
|
.Op Fl O Ar sort-order
|
|
.Op Fl t Ar target-pane
|
|
.Op Ar template
|
|
.Xc
|
|
Put a pane into buffer mode, where a buffer may be chosen interactively from
|
|
a list.
|
|
.Fl Z
|
|
zooms the pane.
|
|
The following keys may be used in buffer mode:
|
|
.Bl -column "Key" "Function" -offset indent
|
|
.It Sy "Key" Ta Sy "Function"
|
|
.It Li "Enter" Ta "Paste selected buffer"
|
|
.It Li "Up" Ta "Select previous buffer"
|
|
.It Li "Down" Ta "Select next buffer"
|
|
.It Li "C-s" Ta "Search by name or content"
|
|
.It Li "n" Ta "Repeat last search"
|
|
.It Li "t" Ta "Toggle if buffer is tagged"
|
|
.It Li "T" Ta "Tag no buffers"
|
|
.It Li "C-t" Ta "Tag all buffers"
|
|
.It Li "p" Ta "Paste selected buffer"
|
|
.It Li "P" Ta "Paste tagged buffers"
|
|
.It Li "d" Ta "Delete selected buffer"
|
|
.It Li "D" Ta "Delete tagged buffers"
|
|
.It Li "f" Ta "Enter a format to filter items"
|
|
.It Li "O" Ta "Change sort order"
|
|
.It Li "v" Ta "Toggle preview"
|
|
.It Li "q" Ta "Exit mode"
|
|
.El
|
|
.Pp
|
|
After a buffer is chosen,
|
|
.Ql %%
|
|
is replaced by the buffer name in
|
|
.Ar template
|
|
and the result executed as a command.
|
|
If
|
|
.Ar template
|
|
is not given, "paste-buffer -b '%%'" is used.
|
|
.Pp
|
|
.Fl O
|
|
specifies the initial sort order: one of
|
|
.Ql time ,
|
|
.Ql name
|
|
or
|
|
.Ql size .
|
|
.Fl f
|
|
specifies an initial filter: the filter is a format - if it evaluates to zero,
|
|
the item in the list is not shown, otherwise it is shown.
|
|
If a filter would lead to an empty list, it is ignored.
|
|
.Fl F
|
|
specifies the format for each item in the list.
|
|
.Fl N
|
|
starts without the preview.
|
|
This command works only if at least one client is attached.
|
|
.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 delete-buffer Op Fl b Ar buffer-name
|
|
.D1 (alias: Ic deleteb )
|
|
Delete the buffer named
|
|
.Ar buffer-name ,
|
|
or the most recently added automatically named buffer if not specified.
|
|
.It Xo Ic list-buffers
|
|
.Op Fl F Ar format
|
|
.Xc
|
|
.D1 (alias: Ic lsb )
|
|
List the global buffers.
|
|
For the meaning of the
|
|
.Fl F
|
|
flag, see the
|
|
.Sx FORMATS
|
|
section.
|
|
.It Xo Ic load-buffer
|
|
.Op Fl b Ar buffer-name
|
|
.Ar path
|
|
.Xc
|
|
.D1 (alias: Ic loadb )
|
|
Load the contents of the specified paste buffer from
|
|
.Ar path .
|
|
.It Xo Ic paste-buffer
|
|
.Op Fl dpr
|
|
.Op Fl b Ar buffer-name
|
|
.Op Fl s Ar separator
|
|
.Op Fl t Ar target-pane
|
|
.Xc
|
|
.D1 (alias: Ic pasteb )
|
|
Insert the contents of a paste buffer into the specified pane.
|
|
If not specified, paste into the current one.
|
|
With
|
|
.Fl d ,
|
|
also delete the paste buffer.
|
|
When output, any linefeed (LF) characters in the paste buffer are replaced with
|
|
a separator, by default carriage return (CR).
|
|
A custom separator may be specified using the
|
|
.Fl s
|
|
flag.
|
|
The
|
|
.Fl r
|
|
flag means to do no replacement (equivalent to a separator of LF).
|
|
If
|
|
.Fl p
|
|
is specified, paste bracket control codes are inserted around the
|
|
buffer if the application has requested bracketed paste mode.
|
|
.It Xo Ic save-buffer
|
|
.Op Fl a
|
|
.Op Fl b Ar buffer-name
|
|
.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 a
|
|
.Op Fl b Ar buffer-name
|
|
.Op Fl n Ar new-buffer-name
|
|
.Ar data
|
|
.Xc
|
|
.D1 (alias: Ic setb )
|
|
Set the contents of the specified buffer to
|
|
.Ar data .
|
|
The
|
|
.Fl a
|
|
option appends to rather than overwriting the buffer.
|
|
The
|
|
.Fl n
|
|
option renames the buffer to
|
|
.Ar new-buffer-name .
|
|
.It Xo Ic show-buffer
|
|
.Op Fl b Ar buffer-name
|
|
.Xc
|
|
.D1 (alias: Ic showb )
|
|
Display the contents of the specified buffer.
|
|
.El
|
|
.Sh MISCELLANEOUS
|
|
Miscellaneous commands are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Ic clock-mode Op Fl t Ar target-pane
|
|
Display a large clock.
|
|
.It Xo Ic if-shell
|
|
.Op Fl bF
|
|
.Op Fl t Ar target-pane
|
|
.Ar shell-command command
|
|
.Op Ar command
|
|
.Xc
|
|
.D1 (alias: Ic if )
|
|
Execute the first
|
|
.Ar command
|
|
if
|
|
.Ar shell-command
|
|
returns success or the second
|
|
.Ar command
|
|
otherwise.
|
|
Before being executed,
|
|
.Ar shell-command
|
|
is expanded using the rules specified in the
|
|
.Sx FORMATS
|
|
section, including those relevant to
|
|
.Ar target-pane .
|
|
With
|
|
.Fl b ,
|
|
.Ar shell-command
|
|
is run in the background.
|
|
.Pp
|
|
If
|
|
.Fl F
|
|
is given,
|
|
.Ar shell-command
|
|
is not executed but considered success if neither empty nor zero (after formats
|
|
are expanded).
|
|
.It Ic lock-server
|
|
.D1 (alias: Ic lock )
|
|
Lock each client individually by running the command specified by the
|
|
.Ic lock-command
|
|
option.
|
|
.It Xo Ic run-shell
|
|
.Op Fl b
|
|
.Op Fl t Ar target-pane
|
|
.Ar shell-command
|
|
.Xc
|
|
.D1 (alias: Ic run )
|
|
Execute
|
|
.Ar shell-command
|
|
in the background without creating a window.
|
|
Before being executed, shell-command is expanded using the rules specified in
|
|
the
|
|
.Sx FORMATS
|
|
section.
|
|
With
|
|
.Fl b ,
|
|
the command is run in the background.
|
|
After it finishes, any output to stdout is displayed in copy mode (in the pane
|
|
specified by
|
|
.Fl t
|
|
or the current pane if omitted).
|
|
If the command doesn't return success, the exit status is also displayed.
|
|
.It Xo Ic wait-for
|
|
.Op Fl L | S | U
|
|
.Ar channel
|
|
.Xc
|
|
.D1 (alias: Ic wait )
|
|
When used without options, prevents the client from exiting until woken using
|
|
.Ic wait-for
|
|
.Fl S
|
|
with the same channel.
|
|
When
|
|
.Fl L
|
|
is used, the channel is locked and any clients that try to lock the same
|
|
channel are made to wait until the channel is unlocked with
|
|
.Ic wait-for
|
|
.Fl U .
|
|
This command only works from outside
|
|
.Nm .
|
|
.El
|
|
.Sh TERMINFO EXTENSIONS
|
|
.Nm
|
|
understands some unofficial extensions to
|
|
.Xr terminfo 5 :
|
|
.Bl -tag -width Ds
|
|
.It Em Cs , Cr
|
|
Set the cursor colour.
|
|
The first takes a single string argument and is used to set the colour;
|
|
the second takes no arguments and restores the default cursor colour.
|
|
If set, a sequence such as this may be used
|
|
to change the cursor colour from inside
|
|
.Nm :
|
|
.Bd -literal -offset indent
|
|
$ printf '\e033]12;red\e033\e\e'
|
|
.Ed
|
|
.It Em \&Ss , Se
|
|
Set or reset the cursor style.
|
|
If set, a sequence such as this may be used
|
|
to change the cursor to an underline:
|
|
.Bd -literal -offset indent
|
|
$ printf '\e033[4 q'
|
|
.Ed
|
|
.Pp
|
|
If
|
|
.Em Se
|
|
is not set, \&Ss with argument 0 will be used to reset the cursor style instead.
|
|
.It Em \&Tc
|
|
Indicate that the terminal supports the
|
|
.Ql direct colour
|
|
RGB escape sequence (for example, \ee[38;2;255;255;255m).
|
|
.Pp
|
|
If supported, this is used for the OSC initialize colour escape sequence (which
|
|
may be enabled by adding the
|
|
.Ql initc
|
|
and
|
|
.Ql ccc
|
|
capabilities to the
|
|
.Nm
|
|
.Xr terminfo 5
|
|
entry).
|
|
.It Em \&Ms
|
|
Store the current buffer in the host terminal's selection (clipboard).
|
|
See the
|
|
.Em set-clipboard
|
|
option above and the
|
|
.Xr xterm 1
|
|
man page.
|
|
.El
|
|
.Sh CONTROL MODE
|
|
.Nm
|
|
offers a textual interface called
|
|
.Em control mode .
|
|
This allows applications to communicate with
|
|
.Nm
|
|
using a simple text-only protocol.
|
|
.Pp
|
|
In control mode, a client sends
|
|
.Nm
|
|
commands or command sequences terminated by newlines on standard input.
|
|
Each command will produce one block of output on standard output.
|
|
An output block consists of a
|
|
.Em %begin
|
|
line followed by the output (which may be empty).
|
|
The output block ends with a
|
|
.Em %end
|
|
or
|
|
.Em %error .
|
|
.Em %begin
|
|
and matching
|
|
.Em %end
|
|
or
|
|
.Em %error
|
|
have two arguments: an integer time (as seconds from epoch) and command number.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
%begin 1363006971 2
|
|
0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
|
|
%end 1363006971 2
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Ic refresh-client
|
|
.Fl C
|
|
command may be used to set the size of a client in control mode.
|
|
.Pp
|
|
In control mode,
|
|
.Nm
|
|
outputs notifications.
|
|
A notification will never occur inside an output block.
|
|
.Pp
|
|
The following notifications are defined:
|
|
.Bl -tag -width Ds
|
|
.It Ic %client-session-changed Ar client Ar session-id Ar name
|
|
The client is now attached to the session with ID
|
|
.Ar session-id ,
|
|
which is named
|
|
.Ar name .
|
|
.It Ic %exit Op Ar reason
|
|
The
|
|
.Nm
|
|
client is exiting immediately, either because it is not attached to any session
|
|
or an error occurred.
|
|
If present,
|
|
.Ar reason
|
|
describes why the client exited.
|
|
.It Ic %layout-change Ar window-id Ar window-layout Ar window-visible-layout Ar window-flags
|
|
The layout of a window with ID
|
|
.Ar window-id
|
|
changed.
|
|
The new layout is
|
|
.Ar window-layout .
|
|
The window's visible layout is
|
|
.Ar window-visible-layout
|
|
and the window flags are
|
|
.Ar window-flags .
|
|
.It Ic %output Ar pane-id Ar value
|
|
A window pane produced output.
|
|
.Ar value
|
|
escapes non-printable characters and backslash as octal \\xxx.
|
|
.It Ic %pane-mode-changed Ar pane-id
|
|
The pane with ID
|
|
.Ar pane-id
|
|
has changed mode.
|
|
.It Ic %session-changed Ar session-id Ar name
|
|
The client is now attached to the session with ID
|
|
.Ar session-id ,
|
|
which is named
|
|
.Ar name .
|
|
.It Ic %session-renamed Ar name
|
|
The current session was renamed to
|
|
.Ar name .
|
|
.It Ic %session-window-changed Ar session-id Ar window-id
|
|
The session with ID
|
|
.Ar session-id
|
|
changed its active window to the window with ID
|
|
.Ar window-id .
|
|
.It Ic %sessions-changed
|
|
A session was created or destroyed.
|
|
.It Ic %unlinked-window-add Ar window-id
|
|
The window with ID
|
|
.Ar window-id
|
|
was created but is not linked to the current session.
|
|
.It Ic %window-add Ar window-id
|
|
The window with ID
|
|
.Ar window-id
|
|
was linked to the current session.
|
|
.It Ic %window-close Ar window-id
|
|
The window with ID
|
|
.Ar window-id
|
|
closed.
|
|
.It Ic %window-pane-changed Ar window-id Ar pane-id
|
|
The active pane in the window with ID
|
|
.Ar window-id
|
|
changed to the pane with ID
|
|
.Ar pane-id .
|
|
.It Ic %window-renamed Ar window-id Ar name
|
|
The window with ID
|
|
.Ar window-id
|
|
was renamed to
|
|
.Ar name .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/etc/tmux.confXXX" -compact
|
|
.It Pa ~/.tmux.conf
|
|
Default
|
|
.Nm
|
|
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
|
|
(or by an external event such as
|
|
.Xr ssh 1
|
|
disconnection) 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-style 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 %%'"
|
|
bind-key S command-prompt "new-window -n %1 'ssh %1'"
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr pty 4
|
|
.Sh AUTHORS
|
|
.An Nicholas Marriott Aq Mt nicholas.marriott@gmail.com
|