mirror of
https://github.com/tmate-io/tmate.git
synced 2024-11-27 18:43:11 +01:00
29b1b2fb5e
Infrastructure and commands to manage the environment for processes started within tmux. There is a global environment, copied from the external environment when the server is started and each session has an (initially empty) session environment which overrides it. New commands set-environment and show-environment manipulate or display the environments. A new session option, update-environment, is a space-separated list of variables which are updated from the external environment into the session environment every time a new session is created - the default is DISPLAY.
1921 lines
46 KiB
Groff
1921 lines
46 KiB
Groff
.\" $Id: tmux.1,v 1.145 2009-08-09 17:48:55 tcunha Exp $
|
|
.\"
|
|
.\" Copyright (c) 2007 Nicholas Marriott <nicm@users.sourceforge.net>
|
|
.\"
|
|
.\" 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: August 8 2009 $
|
|
.Dt TMUX 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tmux
|
|
.Nd terminal multiplexer
|
|
.Sh SYNOPSIS
|
|
.Nm tmux
|
|
.Bk -words
|
|
.Op Fl 28dqUuv
|
|
.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.
|
|
.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
|
|
For a quick start guide,
|
|
see the
|
|
.Sx EXAMPLES
|
|
section at the bottom of the page.
|
|
An overview of the sections in this manual page:
|
|
.Bl -ohang
|
|
.It Sy Commands
|
|
An overview of how
|
|
.Nm
|
|
commands work.
|
|
.It Sy Clients and sessions
|
|
Commands for managing clients and sessions.
|
|
.It Sy Windows and panes
|
|
Commands for managing windows and panes.
|
|
.It Sy Key bindings
|
|
How key bindings work.
|
|
.It Sy Options
|
|
Configuration options for
|
|
.Nm .
|
|
.It Sy Status line
|
|
Commands pertinent to the status line.
|
|
.It Sy Buffers
|
|
Copy and paste operations.
|
|
.It Sy Miscellaneous
|
|
Miscellaneous commands.
|
|
.It Sy Examples
|
|
A quick start guide.
|
|
.El
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width "XXXXXXXXXXXX"
|
|
.It Fl 2
|
|
Force
|
|
.Nm
|
|
to assume the terminal supports 256 colours.
|
|
.It Fl 8
|
|
Like
|
|
.Fl 2 ,
|
|
but indicates that the terminal supports 88 colours.
|
|
.It Fl d
|
|
Force
|
|
.Nm
|
|
to assume the terminal supports default colours.
|
|
.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 .
|
|
The configuration file is a set of
|
|
.Nm
|
|
commands which are executed in sequence when the server is first started.
|
|
.Pp
|
|
If a command in the configuration file fails,
|
|
.Nm
|
|
will report an error and exit without executing further commands.
|
|
.It Fl L Ar socket-name
|
|
.Nm
|
|
stores the server socket in a directory under
|
|
.Pa /tmp ;
|
|
the default socket is named
|
|
.Em default .
|
|
This option allows a different socket name to be specified, allowing several
|
|
independent
|
|
.Nm
|
|
servers to be run.
|
|
Unlike
|
|
.Fl S
|
|
a full path is not necessary: the sockets are all created in the same
|
|
directory.
|
|
.Pp
|
|
If the socket is accidentally removed, the
|
|
.Dv SIGUSR1
|
|
signal may be sent to the
|
|
.Nm
|
|
server process to recreate it.
|
|
.It Fl q
|
|
Prevent the server sending various informational messages, for example when
|
|
window flags are altered.
|
|
.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
|
|
Unlock the server.
|
|
.It Fl u
|
|
.Nm
|
|
attempts to guess if the terminal is likely to support UTF-8 by checking the
|
|
first of the
|
|
.Ev LC_ALL ,
|
|
.Ev LC_CTYPE
|
|
and
|
|
.Ev LANG
|
|
environment variables to be set for the string "UTF-8".
|
|
This is not always correct: the
|
|
.Fl u
|
|
flag explicitly informs
|
|
.Nm
|
|
that UTF-8 is supported.
|
|
.Pp
|
|
If the server is started from a client passed
|
|
.Fl u
|
|
or where UTF-8 is detected, the
|
|
.Ic utf8
|
|
and
|
|
.Ic status-utf8
|
|
options are enabled in the global window and session options respectively.
|
|
.It Fl v
|
|
Request verbose logging.
|
|
This option may be specified multiple times for increasing verbosity.
|
|
Log messages will be saved into
|
|
.Pa tmux-client-PID.log
|
|
and
|
|
.Pa tmux-server-PID.log
|
|
files in the current directory, where
|
|
.Em PID
|
|
is the PID of the server or client process.
|
|
.It 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 COMMANDS
|
|
This section contains a list of the commands supported by
|
|
.Nm .
|
|
Most commands accept the optional
|
|
.Fl t
|
|
argument with one of
|
|
.Ar target-client ,
|
|
.Ar target-session
|
|
.Ar target-window ,
|
|
or
|
|
.Ar target-pane .
|
|
These specify the client, session, window or pane which a command should affect.
|
|
.Ar target-client
|
|
is the name of the
|
|
.Xr pty 4
|
|
file to which the client is connected, for example either of
|
|
.Pa /dev/ttyp1
|
|
or
|
|
.Pa ttyp1
|
|
for the client attached to
|
|
.Pa /dev/ttyp1 .
|
|
If no client is specified, the current client is chosen, if possible, or an
|
|
error is reported.
|
|
Clients may be listed with the
|
|
.Ic list-clients
|
|
command.
|
|
.Pp
|
|
.Ar target-session
|
|
is either the name of a session (as listed by the
|
|
.Ic list-sessions
|
|
command) or the name of a client with the same syntax as
|
|
.Ar target-client ,
|
|
in which case the session attached to the client is used.
|
|
When looking for the session name,
|
|
.Nm
|
|
initially searches for an exact match; if none is found, the session names
|
|
are checked for any for which
|
|
.Ar target-session
|
|
is a prefix or for which it matches as an
|
|
.Xr fnmatch 3
|
|
pattern.
|
|
If a single match is found, it is used as the target session; multiple matches
|
|
produce an error.
|
|
If a session is omitted, the current session is used if available; if no
|
|
current session is available, the most recently created is chosen.
|
|
.Pp
|
|
.Ar target-window
|
|
specifies a window in the form
|
|
.Em session Ns \&: Ns Em window .
|
|
.Em session
|
|
follows the same rules as for
|
|
.Ar target-session ,
|
|
and
|
|
.Em window
|
|
is looked for in order: as a window index, for example mysession:1; as an exact
|
|
window name, such as mysession:mywindow; then as an
|
|
.Xr fnmatch 3
|
|
pattern or the start of a window name, such as mysession:mywin* or
|
|
mysession:mywin.
|
|
An empty window name specifies the next unused index if appropriate (for
|
|
example the
|
|
.Ic new-window
|
|
and
|
|
.Ic link-window
|
|
commands)
|
|
otherwise the current window in
|
|
.Em session
|
|
is chosen.
|
|
When the argument does not contain a colon,
|
|
.Nm
|
|
first attempts to parse it as window; if that fails, an attempt is made to
|
|
match a session.
|
|
.Pp
|
|
.Ar target-pane
|
|
takes a similar form to
|
|
.Ar target-window
|
|
but with the optional addition of a period followed by a pane index, for
|
|
example: mysession:mywindow.1.
|
|
If the pane index is omitted, the currently active pane in the specified
|
|
window is used.
|
|
If neither a colon nor period appears,
|
|
.Nm
|
|
first attempts to use the argument as a pane index; if that fails, it is looked
|
|
up as for
|
|
.Ar target-window .
|
|
.Pp
|
|
Multiple commands may be specified together as part of a
|
|
.Em command sequence .
|
|
Each command should be separated by spaces and a semicolon;
|
|
commands are executed sequentially from left to right.
|
|
A literal semicolon may be included by escaping it with a backslash (for
|
|
example, when specifying a command sequence to
|
|
.Ic bind-key ) .
|
|
.Pp
|
|
Examples include:
|
|
.Bd -literal -offset indent
|
|
refresh-client -t/dev/ttyp2
|
|
|
|
rename-session -tfirst newname
|
|
|
|
set-window-option -t:0 monitor-activity on
|
|
|
|
new-window ; split-window -d
|
|
|
|
bind-key D detach-client \e\; lock-server
|
|
.Ed
|
|
.Sh CLIENTS AND SESSIONS
|
|
The following commands are available:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic attach-session
|
|
.Op Fl d
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
.D1 (alias: Ic attach )
|
|
If run from outside
|
|
.Nm ,
|
|
create a new client in the current terminal and attach it to
|
|
.Ar target-session .
|
|
If used from inside, switch the current client.
|
|
If
|
|
.Fl d
|
|
is specified, any other clients attached to the session are detached.
|
|
.Pp
|
|
If no server is started,
|
|
.Ic attach-session
|
|
will attempt to start it; this will fail unless sessions are created in the
|
|
configuration file.
|
|
.It Ic detach-client Op Fl t Ar target-client
|
|
.D1 (alias: Ic detach )
|
|
Detach the current client if bound to a key, or the specified client with
|
|
.Fl t .
|
|
.It Ic has-session Op Fl t Ar target-session
|
|
.D1 (alias: Ic has )
|
|
Report an error and exit with 1 if the specified session does not exist.
|
|
If it does exist, exit with 0.
|
|
.It Ic kill-server
|
|
Kill the
|
|
.Nm
|
|
server and clients and destroy all sessions.
|
|
.It Ic kill-session Op Fl t Ar target-session
|
|
Destroy the given session, closing any windows linked to it and no other
|
|
sessions, and detaching all clients attached to it.
|
|
.It Ic list-clients
|
|
.D1 (alias: Ic lsc )
|
|
List all clients attached to the server.
|
|
.It Ic list-commands
|
|
.D1 (alias: Ic lscm )
|
|
List the syntax of all commands supported by
|
|
.Nm .
|
|
.It Ic list-sessions
|
|
.D1 (alias: Ic ls )
|
|
List all sessions managed by the server.
|
|
.It Xo Ic new-session
|
|
.Op Fl d
|
|
.Op Fl n Ar window-name
|
|
.Op Fl s Ar session-name
|
|
.Op Ar command
|
|
.Xc
|
|
.D1 (alias: Ic new )
|
|
Create a new session with name
|
|
.Ar session-name .
|
|
The new session is attached to the current terminal unless
|
|
.Fl d
|
|
is given.
|
|
.Ar window-name
|
|
and
|
|
.Ar command
|
|
are the name of and command to execute in the initial window.
|
|
.It Ic refresh-client Op Fl t Ar target-client
|
|
.D1 (alias: Ic refresh )
|
|
Refresh the current client if bound to a key, or a single client if one is given
|
|
with
|
|
.Fl t .
|
|
.It Xo Ic rename-session
|
|
.Op Fl t Ar target-session
|
|
.Ar new-name
|
|
.Xc
|
|
.D1 (alias: Ic rename )
|
|
Rename the session to
|
|
.Ar new-name .
|
|
.It Ic source-file Ar path
|
|
.D1 (alias: Ic source )
|
|
Execute commands from
|
|
.Ar path .
|
|
.It Ic start-server
|
|
.D1 (alias: Ic start )
|
|
Start the
|
|
.Nm
|
|
server, if not already running, without creating any sessions.
|
|
.It Xo Ic suspend-client
|
|
.Op Fl c Ar target-client
|
|
.Xc
|
|
.D1 (alias: Ic suspendc )
|
|
Suspend a client by sending
|
|
.Dv SIGTSTP
|
|
(tty stop).
|
|
.It Xo Ic switch-client
|
|
.Op Fl c Ar target-client
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
.D1 (alias: Ic switchc )
|
|
Switch the current session for client
|
|
.Ar target-client
|
|
to
|
|
.Ar target-session .
|
|
.El
|
|
.Sh WINDOWS AND PANES
|
|
A
|
|
.Nm
|
|
window may be in one of several modes.
|
|
The default permits direct access to the terminal attached to the window.
|
|
The others are:
|
|
.Bl -tag -width Ds
|
|
.It Em output mode
|
|
This is entered when a command which produces output, such as
|
|
.Ic list-keys ,
|
|
is executed from a key binding.
|
|
.It Em scroll mode
|
|
This is entered with the
|
|
.Ic scroll-mode
|
|
command (bound to
|
|
.Ql =
|
|
by default) and permits the window history buffer to be inspected.
|
|
.It Em copy mode
|
|
This 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.
|
|
.El
|
|
.Pp
|
|
The keys available depend on whether emacs or vi mode is selected
|
|
(see the
|
|
.Ic mode-keys
|
|
option).
|
|
The following keys are supported as appropriate for the mode:
|
|
.Bl -column "FunctionXXXXXXXXXXXX" "viXXXXXX" "emacs" -offset indent
|
|
.It Sy "Function" Ta Sy "vi" Ta Sy "emacs"
|
|
.It Li "Start of line" Ta "0" Ta "C-a"
|
|
.It Li "Back to indentation" Ta "^" Ta "M-m"
|
|
.It Li "Clear selection" Ta "Escape" Ta "C-g"
|
|
.It Li "Copy selection" Ta "Enter" Ta "M-w"
|
|
.It Li "Cursor down" Ta "j" Ta "Down"
|
|
.It Li "End of line" Ta "$" Ta "C-e"
|
|
.It Li "Cursor left" Ta "h" Ta "Left"
|
|
.It Li "Next page" Ta "C-f" Ta "Page down"
|
|
.It Li "Next word" Ta "w" Ta "M-f"
|
|
.It Li "Previous page" Ta "C-u" Ta "Page up"
|
|
.It Li "Previous word" Ta "b" Ta "M-b"
|
|
.It Li "Quit mode" Ta "q" Ta "Escape"
|
|
.It Li "Cursor right" Ta "l" Ta "Right"
|
|
.It Li "Start selection" Ta "Space" Ta "C-Space"
|
|
.It Li "Cursor up" Ta "k" Ta "Up"
|
|
.It Li "Delete to end of line" Ta "D" Ta "C-k"
|
|
.It Li "Paste buffer" Ta "p" Ta "C-y"
|
|
.El
|
|
.Pp
|
|
These key bindings are defined in a set of named tables:
|
|
.Em vi-edit
|
|
and
|
|
.Em emacs-edit
|
|
for keys used when line editing at the command prompt;
|
|
.Em vi-choice
|
|
and
|
|
.Em emacs-choice
|
|
for keys used when choosing from lists (such as produced by the
|
|
.Ic window-choose
|
|
command) or in output mode; and
|
|
.Em vi-copy
|
|
and
|
|
.Em emacs-copy
|
|
used in copy and scroll modes.
|
|
The tables may be viewed with the
|
|
.Ic list-keys
|
|
command and keys modified or removed with
|
|
.Ic bind-key
|
|
and
|
|
.Ic unbind-key .
|
|
.Pp
|
|
The paste buffer key pastes the first line from the top paste buffer on the
|
|
stack.
|
|
.Pp
|
|
The mode commands are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic copy-mode
|
|
.Op Fl u
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
Enter copy mode.
|
|
The
|
|
.Fl u
|
|
option scrolls one page up.
|
|
.It Xo Ic scroll-mode
|
|
.Op Fl u
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
Enter scroll mode.
|
|
The
|
|
.Fl u
|
|
has the same meaning as in the
|
|
.Ic copy-mode
|
|
command.
|
|
.El
|
|
.Pp
|
|
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 up-pane
|
|
and
|
|
.Ic down-pane
|
|
commands 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 C-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.
|
|
.El
|
|
.Pp
|
|
Commands related to windows and panes are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic break-pane
|
|
.Op Fl d
|
|
.Op Fl t Ar target-pane
|
|
.Xc
|
|
.D1 (alias: Ic breakp )
|
|
Break
|
|
.Ar target-pane
|
|
off from its containing window to make it the only pane in a new window.
|
|
If
|
|
.Fl d
|
|
is given, the new window does not become the current window.
|
|
.It Ic choose-session Op Fl t Ar target-window
|
|
Put a window into session choice mode, where the session for the current
|
|
client may be selected interactively from a list.
|
|
This command works only from inside
|
|
.Nm .
|
|
.It Ic choose-window Op Fl t Ar target-window
|
|
Put a window into window choice mode, where the window for the session
|
|
attached to the current client may be selected interactively from a list.
|
|
This command works only from inside
|
|
.Nm .
|
|
.It Ic down-pane Op Fl t Ar target-pane
|
|
.D1 (alias: Ic downp )
|
|
Move down a pane.
|
|
.It Xo Ic find-window
|
|
.Op Fl t Ar target-window
|
|
.Ar match-string
|
|
.Xc
|
|
.D1 (alias: Ic findw )
|
|
Search for the
|
|
.Xr fnmatch 3
|
|
pattern
|
|
.Ar match-string
|
|
in window names, titles, and visible content (but not history).
|
|
If only one window is matched, it'll be automatically selected, otherwise a
|
|
choice list is shown.
|
|
This command only works from inside
|
|
.Nm .
|
|
.It Ic kill-pane Op Fl t Ar target-pane
|
|
.D1 (alias: Ic killp )
|
|
Destroy the given pane.
|
|
If no panes remain in the containing window, it is also destroyed.
|
|
.It Ic kill-window Op Fl t Ar target-window
|
|
.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.
|
|
.It Ic last-window Op Fl t Ar target-session
|
|
.D1 (alias: Ic last )
|
|
Select the last (previously selected) window.
|
|
If no
|
|
.Ar target-session
|
|
is specified, select the last window of the current session.
|
|
.It Xo Ic link-window
|
|
.Op Fl dk
|
|
.Op Fl s Ar src-window
|
|
.Op Fl t Ar dst-window
|
|
.Xc
|
|
.D1 (alias: Ic linkw )
|
|
Link the window at
|
|
.Ar src-window
|
|
to the specified
|
|
.Ar dst-window .
|
|
If
|
|
.Ar dst-window
|
|
is specified and no such window exists, the
|
|
.Ar src-window
|
|
is linked there.
|
|
If
|
|
.Fl k
|
|
is given and
|
|
.Ar dst-window
|
|
exists, it is killed, otherwise an error is generated.
|
|
If
|
|
.Fl d
|
|
is given, the newly linked window is not selected.
|
|
.It Ic list-windows Op Fl t Ar target-session
|
|
.D1 (alias: Ic lsw )
|
|
List windows in the current session or in
|
|
.Ar target-session .
|
|
.It Xo Ic move-window
|
|
.Op Fl d
|
|
.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 .
|
|
.It Xo Ic new-window
|
|
.Op Fl dk
|
|
.Op Fl n Ar window-name
|
|
.Op Fl t Ar target-window
|
|
.Op Ar command
|
|
.Xc
|
|
.D1 (alias: Ic neww )
|
|
Create a new window.
|
|
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 command
|
|
is the command to execute.
|
|
If
|
|
.Ar command
|
|
is not specified, the default command is used.
|
|
.Pp
|
|
The
|
|
.Ev TERM
|
|
environment variable must be set to
|
|
.Dq screen
|
|
for all programs running
|
|
.Em inside
|
|
.Nm .
|
|
New windows will automatically have
|
|
.Dq TERM=screen
|
|
added to their environment, but care must be taken not to reset this in shell
|
|
start-up files.
|
|
.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 a bell, activity or content alert.
|
|
.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 a bell, activity or content 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 DLRU
|
|
.Op Fl t Ar target-pane
|
|
.Op Ar adjustment
|
|
.Xc
|
|
.D1 (alias: Ic resizep )
|
|
Resize a pane, upward with
|
|
.Fl U
|
|
(the default), downward with
|
|
.Fl D ,
|
|
to the left with
|
|
.Fl L
|
|
and to the right with
|
|
.Fl R .
|
|
The
|
|
.Ar adjustment
|
|
is given in lines or cells (the default is 1).
|
|
.It Xo Ic respawn-window
|
|
.Op Fl k
|
|
.Op Fl t Ar target-window
|
|
.Op Ar command
|
|
.Xc
|
|
.D1 (alias: Ic respawnw )
|
|
Reactive a window in which the command has exited (see the
|
|
.Ic remain-on-exit
|
|
window option).
|
|
If
|
|
.Ar command
|
|
is not given, the command used when the window was created is executed.
|
|
The window must be already inactive, unless
|
|
.Fl k
|
|
is given, in which case any existing command is killed.
|
|
.It Xo Ic rotate-window
|
|
.Op Fl DU
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
.D1 (alias: Ic rotatew )
|
|
Rotate the positions of the panes within a window, either upward (numerically
|
|
lower) with
|
|
.Fl U
|
|
or downward (numerically higher).
|
|
.It Xo Ic select-layout
|
|
.Op Fl t Ar target-window
|
|
.Op Ar layout-name
|
|
.Xc
|
|
.D1 (alias: selectl )
|
|
Choose a specific layout for a window.
|
|
If
|
|
.Ar layout-name
|
|
is not given, the last layout used (if any) is reapplied.
|
|
.It Ic select-pane Op Fl t Ar target-pane
|
|
.D1 (alias: Ic selectp )
|
|
Make pane
|
|
.Ar target-pane
|
|
the active pane in window
|
|
.Ar target-window .
|
|
.It Ic select-window Op Fl t Ar target-window
|
|
.D1 (alias: Ic selectw )
|
|
Select the window at
|
|
.Ar target-window .
|
|
.It Xo Ic split-window
|
|
.Op Fl dhv
|
|
.Oo Fl l
|
|
.Ar size |
|
|
.Fl p Ar percentage Oc
|
|
.Op Fl t Ar target-window
|
|
.Op Ar command
|
|
.Xc
|
|
.D1 (alias: splitw )
|
|
Creates a new pane by splitting the active pane:
|
|
.Fl h
|
|
does a horizontal split and
|
|
.Fl v
|
|
a vertical split; if neither is specified,
|
|
.Fl v
|
|
is assumed.
|
|
The
|
|
.Fl l
|
|
and
|
|
.Fl p
|
|
options specify the size of the new window in lines (for vertical split) or in
|
|
cells (for horizontal split), or as a percentage, respectively.
|
|
All other options have the same meaning as in the
|
|
.Ic new-window
|
|
command.
|
|
.It Xo Ic swap-pane
|
|
.Op Fl dDU
|
|
.Op Fl s Ar src-pane
|
|
.Op Fl t Ar dst-pane
|
|
.Xc
|
|
.D1 (alias: Ic swapp )
|
|
Swap two panes.
|
|
If
|
|
.Fl U
|
|
is used and no source pane is specified with
|
|
.Fl s ,
|
|
.Ar dst-pane
|
|
is swapped with the previous pane (before it numerically);
|
|
.Fl D
|
|
swaps with the next pane (after it numerically).
|
|
.It Xo Ic swap-window
|
|
.Op Fl d
|
|
.Op Fl s Ar src-window
|
|
.Op Fl t Ar dst-window
|
|
.Xc
|
|
.D1 (alias: Ic swapw )
|
|
This is similar to
|
|
.Ic link-window ,
|
|
except the source and destination windows are swapped.
|
|
It is an error if no window exists at
|
|
.Ar src-window .
|
|
.It Xo Ic unlink-window
|
|
.Op Fl k
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
.D1 (alias: Ic unlinkw )
|
|
Unlink
|
|
.Ar target-window .
|
|
Unless
|
|
.Fl k
|
|
is given, a window may be unlinked only if it is linked to multiple sessions -
|
|
windows may not be linked to no sessions;
|
|
if
|
|
.Fl k
|
|
is specified and the window is linked to only one session, it is unlinked and
|
|
destroyed.
|
|
.It Ic up-pane Op Fl t Ar target-pane
|
|
.D1 (alias: Ic upp )
|
|
Move up a pane.
|
|
.El
|
|
.Sh KEY BINDINGS
|
|
.Nm
|
|
may be controlled from an attached client by using a key combination of a
|
|
prefix key,
|
|
.Ql C-b
|
|
(Ctrl-b) by default, followed by a command key.
|
|
.Pp
|
|
Some of the default key bindings include:
|
|
.Pp
|
|
.Bl -tag -width Ds -offset 3n -compact
|
|
.It c
|
|
Create new window.
|
|
.It d
|
|
Detach current client.
|
|
.It l
|
|
Move to last (previously selected) window in the current session.
|
|
.It n
|
|
Change to next window in the current session.
|
|
.It p
|
|
Change to previous window in the current session.
|
|
.It t
|
|
Display a large clock.
|
|
.It \&?
|
|
List current key bindings.
|
|
.El
|
|
.Pp
|
|
A complete list may be obtained with the
|
|
.Ic list-keys
|
|
command (bound to
|
|
.Ql \&?
|
|
by default).
|
|
Key bindings may be changed with the
|
|
.Ic bind-key
|
|
and
|
|
.Ic unbind-key
|
|
commands.
|
|
.Pp
|
|
Commands related to key bindings are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic bind-key
|
|
.Op Fl cnr
|
|
.Op Fl t Ar key-table
|
|
.Ar key Ar command Op Ar arguments
|
|
.Xc
|
|
.D1 (alias: Ic bind )
|
|
Bind key
|
|
.Ar key
|
|
to
|
|
.Ar command .
|
|
Keys may be specified prefixed with
|
|
.Ql C-
|
|
or
|
|
.Ql ^
|
|
for Ctrl keys, or
|
|
.Ql M-
|
|
for Alt (meta) keys.
|
|
.Pp
|
|
By default (without
|
|
.Fl t )
|
|
the primary key bindings are modified (those normally activated with the prefix
|
|
key); in this case, if
|
|
.Fl n
|
|
is specified, it is not necessary to use the prefix key,
|
|
.Ar command
|
|
is bound to
|
|
.Ar key
|
|
alone.
|
|
The
|
|
.Fl r
|
|
flag indicates this key may repeat, see the
|
|
.Ic repeat-time
|
|
option.
|
|
.Pp
|
|
If
|
|
.Fl t
|
|
is present,
|
|
.Ar key
|
|
is bound in
|
|
.Ar key-table :
|
|
the binding for command mode with
|
|
.Fl c
|
|
or for normal mode without.
|
|
To view the default bindings and possible commands, see the
|
|
.Ic list-keys
|
|
command.
|
|
.It Ic list-keys Op Fl t Ar key-table
|
|
.D1 (alias: Ic lsk )
|
|
List all key bindings.
|
|
Without
|
|
.Fl t
|
|
the primary key bindings - those executed when preceded by the prefix key -
|
|
are printed.
|
|
Keys bound without the prefix key (see
|
|
.Ic bind-key
|
|
.Fl n )
|
|
are enclosed in square brackets.
|
|
.Pp
|
|
With
|
|
.Fl t ,
|
|
the key bindings in
|
|
.Ar key-table
|
|
are listed; this may be one of:
|
|
.Em vi-edit ,
|
|
.Em emacs-edit ,
|
|
.Em vi-choice ,
|
|
.Em emacs-choice ,
|
|
.Em vi-copy
|
|
or
|
|
.Em emacs-copy .
|
|
.It Xo Ic send-keys
|
|
.Op Fl t Ar target-window
|
|
.Ar key Ar ...
|
|
.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.
|
|
All arguments are sent sequentially from first to last.
|
|
.It Ic send-prefix Op Fl t Ar target-window
|
|
Send the prefix key to a window as if it was pressed.
|
|
.It Xo Ic unbind-key
|
|
.Op Fl cn
|
|
.Op Fl t Ar key-table
|
|
.Ar key
|
|
.Xc
|
|
.D1 (alias: Ic unbind )
|
|
Unbind the command bound to
|
|
.Ar key .
|
|
Without
|
|
.Fl t
|
|
the primary key bindings are modified; in this case, if
|
|
.Fl n
|
|
is specified, the command bound to
|
|
.Ar key
|
|
without a prefix (if any) is removed.
|
|
.Pp
|
|
If
|
|
.Fl t
|
|
is present,
|
|
.Ar key
|
|
in
|
|
.Ar key-table
|
|
is unbound: the binding for command mode with
|
|
.Fl c
|
|
or for normal mode without.
|
|
.El
|
|
.Sh OPTIONS
|
|
The appearance and behaviour of
|
|
.Nm
|
|
may be modified by changing the value of various options.
|
|
There are two types of option:
|
|
.Em session options
|
|
and
|
|
.Em window options .
|
|
.Pp
|
|
Each individual session may have a set of session options, and there is a
|
|
separate set of global session options.
|
|
Sessions which do not have a particular option configured inherit the value
|
|
from the global session options.
|
|
Session options are set or unset with the
|
|
.Ic set-option
|
|
command and may be listed with the
|
|
.Ic show-options
|
|
command.
|
|
The available session options are listed under the
|
|
.Ic set-option
|
|
command.
|
|
.Pp
|
|
Similarly, a set of window options is attached to each window, and there is
|
|
a set of global window options from which any unset options are inherited.
|
|
Window options are altered with the
|
|
.Ic set-window-option
|
|
command and can be listed with the
|
|
.Ic show-window-options
|
|
command.
|
|
All window options are documented with the
|
|
.Ic set-window-option
|
|
command.
|
|
.Pp
|
|
Commands which set options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic set-option
|
|
.Op Fl agu
|
|
.Op Fl t Ar target-session
|
|
.Ar option Ar value
|
|
.Xc
|
|
.D1 (alias: Ic set )
|
|
Set a session option.
|
|
With
|
|
.Fl a ,
|
|
and if the option expects a string,
|
|
.Ar value
|
|
is appended to the existing setting.
|
|
If
|
|
.Fl g
|
|
is specified, the global session option is set.
|
|
The
|
|
.Fl u
|
|
flag unsets an option, so a session inherits the option from the global
|
|
options - it is not possible to unset a global option.
|
|
.Pp
|
|
Available session options are:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic bell-action
|
|
.Op Ic any | none | current
|
|
.Xc
|
|
Set action on window bell.
|
|
.Ic any
|
|
means a bell in any window linked to a session causes a bell in the current
|
|
window of that session,
|
|
.Ic none
|
|
means all bells are ignored and
|
|
.Ic current
|
|
means only bell in windows other than the current window are ignored.
|
|
.It Ic buffer-limit Ar number
|
|
Set the number of buffers kept for each session; as new buffers are added to
|
|
the top of the stack, old ones are removed from the bottom if necessary to
|
|
maintain this maximum length.
|
|
.It Ic default-command Ar command
|
|
Set the command used for new windows (if not specified when the window is
|
|
created) to
|
|
.Ar command .
|
|
The default is an empty string, which instructs
|
|
.Nm
|
|
to create a login shell using the
|
|
.Ev SHELL
|
|
environment variable or, if it is unset, the user's shell returned by
|
|
.Xr getpwuid 3 .
|
|
.It Ic default-path Ar path
|
|
Set the default working directory for processes created from keys, or
|
|
interactively from the prompt.
|
|
The default is the current working directory when the server is started.
|
|
.It Ic default-terminal Ar terminal
|
|
Set the default terminal for new windows created in this session - the
|
|
default value of the
|
|
.Ev TERM
|
|
environment variable.
|
|
For
|
|
.Nm
|
|
to work correctly, this
|
|
.Em must
|
|
be set to
|
|
.Ql screen
|
|
or a derivative of it.
|
|
.It Ic display-time Ar time
|
|
Set the amount of time for which status line messages are displayed.
|
|
.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 lock-after-time Ar number
|
|
Lock the server after
|
|
.Ar number
|
|
seconds of inactivity.
|
|
The default is off (set to 0).
|
|
This has no effect as a session option; it must be set as a global option using
|
|
.Fl g .
|
|
.It Ic message-attr Ar attributes
|
|
Set status line message attributes, where
|
|
.Ar attributes
|
|
is either
|
|
.Ic default
|
|
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 ,
|
|
or
|
|
.Ic italics .
|
|
.It Ic message-bg Ar colour
|
|
Set status line message background colour, where
|
|
.Ar colour
|
|
is one of:
|
|
.Ic black ,
|
|
.Ic red ,
|
|
.Ic green ,
|
|
.Ic yellow ,
|
|
.Ic blue ,
|
|
.Ic magenta ,
|
|
.Ic cyan ,
|
|
.Ic white
|
|
or
|
|
.Ic default .
|
|
.It Ic message-fg Ar colour
|
|
Set status line message foreground colour.
|
|
.It Ic prefix Ar key
|
|
Set the current prefix key.
|
|
.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-remain-on-exit
|
|
.Op Ic on | off
|
|
.Xc
|
|
Set the
|
|
.Ic remain-on-exit
|
|
window option for any windows first created in this session.
|
|
.It Xo Ic set-titles
|
|
.Op Ic on | off
|
|
.Xc
|
|
Attempt to set the window title using the \ee]2;...\e007 xterm code and
|
|
the terminal appears to be an xterm.
|
|
This option is off by default.
|
|
Note that elinks
|
|
will only attempt to set the window title if the STY environment
|
|
variable is set.
|
|
.It Xo Ic status
|
|
.Op Ic on | off
|
|
.Xc
|
|
Show or hide the status line.
|
|
.It Ic status-attr Ar attributes
|
|
Set status line attributes.
|
|
.It Ic status-bg Ar colour
|
|
Set status line background colour.
|
|
.It Ic status-fg Ar colour
|
|
Set status line foreground colour.
|
|
.It Ic status-interval Ar interval
|
|
Update the status bar 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.
|
|
Defaults to emacs.
|
|
.It Ic status-left Ar string
|
|
Display
|
|
.Ar string
|
|
to the left of the status bar.
|
|
.Ar string
|
|
will be passed through
|
|
.Xr strftime 3
|
|
before being used.
|
|
By default, the session name is shown.
|
|
.Ar string
|
|
may contain any of the following special character pairs:
|
|
.Bl -column "Character pair" "Replaced with" -offset indent
|
|
.It Sy "Character pair" Ta Sy "Replaced with"
|
|
.It Li "#(command)" Ta "First line of command's output"
|
|
.It Li "#H" Ta "Hostname of local host"
|
|
.It Li "#I" Ta "Current window index"
|
|
.It Li "#P" Ta "Current pane index"
|
|
.It Li "#S" Ta "Session name"
|
|
.It Li "#T" Ta "Current window title"
|
|
.It Li "#W" Ta "Current window name"
|
|
.It Li "##" Ta "A literal" Ql #
|
|
.El
|
|
.Pp
|
|
Where appropriate, these may be prefixed with a number to specify the maximum
|
|
length, for example
|
|
.Ql #24T .
|
|
.Pp
|
|
By default, UTF-8 in
|
|
.Ar string
|
|
is not interpreted, to enable UTF-8, use the
|
|
.Ic status-utf8
|
|
option.
|
|
.It Ic status-left-attr Ar attributes
|
|
Set the attribute of the left part of the status line.
|
|
.It Ic status-left-fg Ar colour
|
|
Set the foreground colour of the left part of the status line.
|
|
.It Ic status-left-bg Ar colour
|
|
Set the background colour of the left part of the status line.
|
|
.It Ic status-left-length Ar length
|
|
Set the maximum
|
|
.Ar length
|
|
of the left component of the status bar.
|
|
The default is 10.
|
|
.It Ic status-right Ar string
|
|
Display
|
|
.Ar string
|
|
to the right of the status bar.
|
|
By default, the date and time will be shown.
|
|
As with
|
|
.Ic status-left ,
|
|
.Ar string
|
|
will be passed to
|
|
.Xr strftime 3 ,
|
|
character pairs are replaced, and UTF-8 is dependent on the
|
|
.Ic status-utf8
|
|
option.
|
|
.It Ic status-right-attr Ar attributes
|
|
Set the attribute of the right part of the status line.
|
|
.It Ic status-right-fg Ar colour
|
|
Set the foreground colour of the right part of the status line.
|
|
.It Ic status-right-bg Ar colour
|
|
Set the background colour of the right part of the status line.
|
|
.It Ic status-right-length Ar length
|
|
Set the maximum
|
|
.Ar length
|
|
of the right component of the status bar.
|
|
The default is 40.
|
|
.Pp
|
|
.It Xo Ic status-utf8
|
|
.Op Ic on | off
|
|
.Xc
|
|
Instruct
|
|
.Nm
|
|
to treat top-bit-set characters in the
|
|
.Ic status-left
|
|
and
|
|
.Ic status-right
|
|
strings as UTF-8; notably, this is important for wide characters.
|
|
This option defaults to off.
|
|
.It Ic terminal-overrides Ar string
|
|
Contains a list of entries which override terminal descriptions read using
|
|
.Xr terminfo 5 .
|
|
.Ar string
|
|
is a comma-separated list of items each 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 and the
|
|
.Ql dch1
|
|
entry to
|
|
.Ql \ee[P
|
|
for the
|
|
.Ql rxvt
|
|
terminal type, the option could be set to the string:
|
|
.Bd -literal -offset indent
|
|
"*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P"
|
|
.Ed
|
|
.Pp
|
|
The terminal entry value is passed through
|
|
.Xr strunvis 3
|
|
before interpretation.
|
|
The default value forcibly corrects the
|
|
.Ql colors
|
|
entry for terminals which support 88 or 256 colours:
|
|
.Bd -literal -offset indent
|
|
"*88col*:colors=88,*256col*:colors=256"
|
|
.Ed
|
|
.It Ic update-environment Ar variables
|
|
Set a space-separated string containing a 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).
|
|
The default is
|
|
.Ev DISPLAY .
|
|
.It Xo Ic visual-activity
|
|
.Op Ic on | off
|
|
.Xc
|
|
If on, display a status line message when activity occurs in a window
|
|
for which the
|
|
.Ic monitor-activity
|
|
window option is enabled.
|
|
.It Xo Ic visual-bell
|
|
.Op Ic on | off
|
|
.Xc
|
|
If this option is on, a message is shown on a bell instead of it being passed
|
|
through to the terminal (which normally makes a sound).
|
|
Also see the
|
|
.Ic bell-action
|
|
option.
|
|
.It Xo Ic visual-content
|
|
.Op Ic on | off
|
|
.Xc
|
|
Like
|
|
.Ic visual-activity ,
|
|
display a message when content is present in a window
|
|
for which the
|
|
.Ic monitor-content
|
|
window option is enabled.
|
|
.El
|
|
.It Xo Ic set-window-option
|
|
.Op Fl agu
|
|
.Op Fl t Ar target-window
|
|
.Ar option Ar value
|
|
.Xc
|
|
.D1 (alias: Ic setw )
|
|
Set a window option.
|
|
The
|
|
.Fl a ,
|
|
.Fl g
|
|
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 automatic-rename
|
|
.Op Ic on | off
|
|
.Xc
|
|
Control automatic window renaming.
|
|
When this setting is enabled,
|
|
.Nm
|
|
will attempt - on supported platforms - to rename the window to reflect the
|
|
command currently running in it.
|
|
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 .
|
|
It may be switched off globally with:
|
|
.Bd -literal -offset indent
|
|
set-window-option -g automatic-rename off
|
|
.Ed
|
|
.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-width Ar width
|
|
.It Ic main-pane-height Ar height
|
|
Set the width or height of the main (left or top) pane in the
|
|
.Ic main-horizontal
|
|
or
|
|
.Ic main-vertical
|
|
layouts.
|
|
.Pp
|
|
.It Ic mode-attr Ar attributes
|
|
Set window modes attributes.
|
|
.Pp
|
|
.It Ic mode-bg Ar colour
|
|
Set window modes background colour.
|
|
.Pp
|
|
.It Ic mode-fg Ar colour
|
|
Set window modes foreground colour.
|
|
.Pp
|
|
.It Xo Ic mode-keys
|
|
.Op Ic vi | emacs
|
|
.Xc
|
|
Use vi or emacs-style key bindings in scroll, copy and choice modes.
|
|
Key bindings default to emacs.
|
|
.Pp
|
|
.It Xo Ic mode-mouse
|
|
.Op Ic on | off
|
|
.Xc
|
|
Mouse state in modes.
|
|
If on,
|
|
.Nm
|
|
will respond to mouse clicks by moving the cursor in copy mode or selecting an
|
|
option in choice mode.
|
|
.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 Ic monitor-content Ar match-string
|
|
Monitor content in the window.
|
|
When
|
|
.Xr fnmatch 3
|
|
pattern
|
|
.Ar match-string
|
|
appears in the window, it is highlighted in the status line.
|
|
.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 utf8
|
|
.Op Ic on | off
|
|
.Xc
|
|
Instructs
|
|
.Nm
|
|
to expect UTF-8 sequences to appear in this window.
|
|
.Pp
|
|
.It Ic window-status-attr Ar attributes
|
|
Set status line attributes for a single window.
|
|
.Pp
|
|
.It Ic window-status-bg Ar colour
|
|
Set status line background colour for a single window.
|
|
.Pp
|
|
.It Ic window-status-fg Ar colour
|
|
Set status line foreground colour for a single window.
|
|
.Pp
|
|
.It Ic window-status-current-attr Ar attributes
|
|
Set status line attributes for the currently active window.
|
|
.Pp
|
|
.It Ic window-status-current-bg Ar colour
|
|
Set status line background colour for the currently active window.
|
|
.Pp
|
|
.It Ic window-status-current-fg Ar colour
|
|
Set status line foreground colour for the currently active window.
|
|
.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 g
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
.D1 (alias: Ic show )
|
|
Show the session options for
|
|
.Ar target session ,
|
|
or the global session options with
|
|
.Fl g .
|
|
.It Xo Ic show-window-options
|
|
.Op Fl g
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
.D1 (alias: Ic showw )
|
|
List the window options for
|
|
.Ar target-window ,
|
|
or the global window options if
|
|
.Fl g
|
|
is used.
|
|
.El
|
|
.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 with
|
|
the session environment overriding any variable present in both.
|
|
This 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
|
|
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 g
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
Display the environment for
|
|
.Ar target-session
|
|
or the global environment with
|
|
.Fl g .
|
|
Variables removed from the environment are prefixed with
|
|
.Ql - .
|
|
.El
|
|
.Sh STATUS LINE
|
|
.Nm
|
|
includes an optional status line which is displayed in the bottom line of each
|
|
terminal.
|
|
By default, the status line is enabled (it may be disabled with the
|
|
.Ic status
|
|
session option) and contains, from left-to-right: the name of the current
|
|
session in square brackets; the window list; the current window title in double
|
|
quotes; and the time and date.
|
|
.Pp
|
|
The status line is made of three parts: configurable left and right sections
|
|
(which may contain dynamic content such as the time or output from a shell
|
|
command, see the
|
|
.Ic status-left ,
|
|
.Ic status-left-length ,
|
|
.Ic status-right ,
|
|
and
|
|
.Ic status-right-length
|
|
options below), and a central window list.
|
|
The window list shows the index, name and (if any) flag of the windows
|
|
present in the current session in ascending numerical order.
|
|
The flag is one of the following symbols appended to the window name:
|
|
.Bl -column "Symbol" "Meaning" -offset indent
|
|
.It Sy "Symbol" Ta Sy "Meaning"
|
|
.It Li "*" Ta "Denotes the current window."
|
|
.It Li "-" Ta "Marks the last window (previously selected)."
|
|
.It Li "#" Ta "Window is monitored and activity has been detected."
|
|
.It Li "!" Ta "A bell has occurred in the window."
|
|
.It Li "+" Ta "Window is monitored for content and it has appeared."
|
|
.El
|
|
.Pp
|
|
The # symbol relates to the
|
|
.Ic monitor-activity
|
|
and + to the
|
|
.Ic monitor-content
|
|
window options.
|
|
The window name is printed in inverted colours if an alert (bell, activity or
|
|
content) is present.
|
|
.Pp
|
|
The colour and attributes of the status line may be configured, the entire status line using
|
|
the
|
|
.Ic status-attr ,
|
|
.Ic status-fg
|
|
and
|
|
.Ic status-bg
|
|
session options and individual windows using the
|
|
.Ic window-status-attr ,
|
|
.Ic window-status-fg
|
|
and
|
|
.Ic window-status-bg
|
|
window options.
|
|
.Pp
|
|
The status line is automatically refreshed at interval if it has changed, the interval may be
|
|
controlled with the
|
|
.Ic status-interval
|
|
session option.
|
|
.Pp
|
|
Commands related to the status line are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Xo Ic command-prompt
|
|
.Op Fl t Ar target-client
|
|
.Op Ar template
|
|
.Xc
|
|
Open the command prompt in a client.
|
|
This may be used from inside
|
|
.Nm
|
|
to execute commands interactively.
|
|
If
|
|
.Ar template
|
|
is specified, it is used as the command; any %% in the template will be
|
|
replaced by what is entered at the prompt.
|
|
.It Xo Ic confirm-before
|
|
.Op Fl t Ar target-client
|
|
.Ar command
|
|
.Xc
|
|
.D1 (alias: Ic confirm )
|
|
Ask for confirmation before executing
|
|
.Ar command .
|
|
This command works only from inside
|
|
.Nm .
|
|
.It Xo Ic display-message
|
|
.Op Fl t Ar target-client
|
|
.Op Ar message
|
|
.Xc
|
|
.D1 (alias: Ic display )
|
|
Display a message (see the
|
|
.Ic status-left
|
|
option below)
|
|
in the status line.
|
|
.It Ic select-prompt Op Fl t Ar target-client
|
|
Open a prompt inside
|
|
.Ar target-client
|
|
allowing a window index to be entered interactively.
|
|
.El
|
|
.Sh BUFFERS
|
|
.Nm
|
|
maintains a stack of
|
|
.Em paste buffers
|
|
for each session.
|
|
Up to the value of the
|
|
.Ic buffer-limit
|
|
option are kept; when a new buffer is added, the buffer at the bottom of the
|
|
stack is removed.
|
|
Buffers may be added using
|
|
.Ic copy-mode
|
|
or the
|
|
.Ic set-buffer
|
|
command, and pasted into a window using the
|
|
.Ic paste-buffer
|
|
command.
|
|
.Pp
|
|
A configurable history buffer is also maintained for each window.
|
|
By default, up to 2000 lines are kept; this can be altered with the
|
|
.Ic history-limit
|
|
option (see the
|
|
.Ic set-option
|
|
command above).
|
|
.Pp
|
|
The buffer commands are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Ic clear-history Op Fl t Ar target-pane
|
|
.D1 (alias: Ic clearhist )
|
|
Remove and free the history for the specified pane.
|
|
.It Xo Ic copy-buffer
|
|
.Op Fl a Ar src-index
|
|
.Op Fl b Ar dst-index
|
|
.Op Fl s Ar src-session
|
|
.Op Fl t Ar dst-session
|
|
.Xc
|
|
.D1 (alias: Ic copyb )
|
|
Copy a session paste buffer to another session.
|
|
If no sessions are specified, the current one is used instead.
|
|
.It Xo Ic delete-buffer
|
|
.Op Fl b Ar buffer-index
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
.D1 (alias: Ic deleteb )
|
|
Delete the buffer at
|
|
.Ar buffer-index ,
|
|
or the top buffer if not specified.
|
|
.It Ic list-buffers Op Fl t Ar target-session
|
|
.D1 (alias: Ic lsb )
|
|
List the buffers in the given session.
|
|
.It Xo Ic load-buffer
|
|
.Op Fl b Ar buffer-index
|
|
.Op Fl t Ar target-session
|
|
.Ar path
|
|
.Xc
|
|
.D1 (alias: Ic loadb )
|
|
Load the contents of the specified paste buffer from
|
|
.Ar path .
|
|
.It Xo Ic paste-buffer
|
|
.Op Fl dr
|
|
.Op Fl b Ar buffer-index
|
|
.Op Fl t Ar target-window
|
|
.Xc
|
|
.D1 (alias: Ic pasteb )
|
|
Insert the contents of a paste buffer into the current window.
|
|
With
|
|
.Fl d ,
|
|
also delete the paste buffer from the stack.
|
|
When output, any linefeed (LF) characters in the paste buffer are replaced with
|
|
carriage returns (CR).
|
|
This translation may be disabled with the
|
|
.Fl r
|
|
flag.
|
|
.It Xo Ic save-buffer
|
|
.Op Fl a
|
|
.Op Fl b Ar buffer-index
|
|
.Op Fl t Ar target-session
|
|
.Ar path
|
|
.Xc
|
|
.D1 (alias: Ic saveb )
|
|
Save the contents of the specified paste buffer to
|
|
.Ar path .
|
|
The
|
|
.Fl a
|
|
option appends to rather than overwriting the file.
|
|
.It Xo Ic set-buffer
|
|
.Op Fl b Ar buffer-index
|
|
.Op Fl t Ar target-session
|
|
.Ar data
|
|
.Xc
|
|
.D1 (alias: Ic setb )
|
|
Set the contents of the specified buffer to
|
|
.Ar data .
|
|
.It Xo Ic show-buffer
|
|
.Op Fl b Ar buffer-index
|
|
.Op Fl t Ar target-session
|
|
.Xc
|
|
.D1 (alias: Ic showb )
|
|
Display the contents of the specified buffer.
|
|
.El
|
|
.Sh MISCELLANEOUS
|
|
.Pp
|
|
Miscellaneous commands are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Ic clock-mode Op Fl t Ar target-window
|
|
Display a large clock.
|
|
.It Ic if-shell Ar shell-command command
|
|
.D1 (alias: Ic if )
|
|
Execute
|
|
.Ar command
|
|
if
|
|
.Ar shell-command
|
|
returns success.
|
|
.It Ic lock-server
|
|
.D1 (alias: Ic lock )
|
|
Lock the server until a password is entered.
|
|
.It Ic server-info
|
|
.D1 (alias: Ic info )
|
|
Show server information and terminal details.
|
|
.It Xo Ic set-password
|
|
.Op Fl c
|
|
.Ar password
|
|
.Xc
|
|
.D1 (alias: Ic pass )
|
|
Set the server password.
|
|
If the
|
|
.Fl c
|
|
option is given, a pre-encrypted password may be specified.
|
|
By default, the password is blank, thus any entered password will be accepted
|
|
when unlocking the server (see the
|
|
.Ic lock-server
|
|
command).
|
|
To prevent variable expansion when an encrypted password is read from a
|
|
configuration file, enclose it in single quotes (').
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/etc/tmux.confXXX" -compact
|
|
.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
|
|
and reattached with:
|
|
.Pp
|
|
.Dl $ tmux attach-session
|
|
.Pp
|
|
Typing
|
|
.Ql C-b \&?
|
|
lists the current key bindings in the current window; up and down may be used
|
|
to navigate the list or
|
|
.Ql q
|
|
to exit from it.
|
|
.Pp
|
|
Commands to be run when the
|
|
.Nm
|
|
server is started may be placed in the
|
|
.Pa ~/.tmux.conf
|
|
configuration file.
|
|
Common examples include:
|
|
.Pp
|
|
Changing the default prefix key:
|
|
.Bd -literal -offset indent
|
|
set-option -g prefix C-a
|
|
unbind-key C-b
|
|
bind-key C-a send-prefix
|
|
.Ed
|
|
.Pp
|
|
Turning the status line off, or changing its colour:
|
|
.Bd -literal -offset indent
|
|
set-option -g status off
|
|
set-option -g status-bg blue
|
|
.Ed
|
|
.Pp
|
|
Setting other options, such as the default command,
|
|
or locking after 30 minutes of inactivity:
|
|
.Bd -literal -offset indent
|
|
set-option -g default-command "exec /bin/ksh"
|
|
set-option -g lock-after-time 1800
|
|
.Ed
|
|
.Pp
|
|
Creating new key bindings:
|
|
.Bd -literal -offset indent
|
|
bind-key b set-option status
|
|
bind-key / command-prompt "split-window 'exec man %%'"
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr pty 4
|
|
.Sh AUTHORS
|
|
.An Nicholas Marriott Aq nicm@users.sourceforge.net
|