circlecloud/tmux
1
0
Fork 0
mirror of https://github.com/tmux/tmux.git synced 2025-11-04 09:26:05 +00:00
Code Issues Projects Releases Wiki Activity

Sync man page with OpenBSD.

Browse Source
This commit is contained in:
Nicholas Marriott
2009-06-25 15:30:29 +00:00
parent 3d7cf00359
commit 5b3db7b56c
1 changed files with 244 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
tmux.1
View File

@@ -1,4 +1,4 @@
.\" $Id: tmux.1,v 1.97 2009-05-19 13:32:55 tcunha Exp $
.\" $Id: tmux.1,v 1.98 2009-06-25 15:30:29 nicm Exp $
.\"
.\" Copyright (c) 2007 Nicholas Marriott <nicm@users.sourceforge.net>
.\"
@@ -14,16 +14,16 @@
.\" 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 April 20, 2009
.Dd $Mdocdate: June 24 2009 $
.Dt TMUX 1
.Os
.Sh NAME
.Nm tmux
.Nd "terminal multiplexer"
.Nd terminal multiplexer
.Sh SYNOPSIS
.Nm tmux
.Bk -words
.Op Fl 28dqUuVv
.Op Fl 28dqUuv
.Op Fl f Ar file
.Op Fl L Ar socket-name
.Op Fl S Ar socket-path
@@ -31,7 +31,7 @@
.Ek
.Sh DESCRIPTION
.Nm
is a terminal multiplexer; it enables a number of terminals to be accessed and
is a terminal multiplexer: it enables a number of terminals to be accessed and
controlled from a single terminal.
.Pp
.Nm
@@ -61,7 +61,7 @@ to assume the terminal supports 256 colours.
.It Fl 8
Like
.Fl 2 ,
indicates the terminal supports 88 colours.
but indicates that the terminal supports 88 colours.
.It Fl d
Force
.Nm
@@ -75,9 +75,6 @@ will look for a config file at
The configuration file is a set of
.Nm
commands which are executed in sequence when the server is first started.
.It Fl q
Prevent the server sending various information messages, for example when
window flags are altered.
.It Fl L Ar socket-name
.Nm
stores the server socket in a directory under
@@ -92,6 +89,15 @@ 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
@@ -102,11 +108,19 @@ flag is ignored.
.It Fl U
Unlock the server.
.It Fl u
Instruct
.Nm
that the terminal support UTF-8.
.It Fl V
Print program version.
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.
.It Fl v
Request verbose logging.
This option may be specified multiple times for increasing verbosity.
@@ -116,18 +130,19 @@ and
.Pa tmux-server-PID.log
files in the current directory, where
.Em PID
is the pid of the server or client process.
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 ,
and described in the following sections.
If no command and flags is specified, the
as described in the following sections.
If no command and flags are specified, the
.Ic new-session
command is assumed.
.Pp
.El
.Sh QUICK START
To create a new tmux session running
To create a new
.Nm
session running
.Xr vi 1 :
.Pp
.Dl $ tmux new-session vi
@@ -143,15 +158,17 @@ 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
(ctrl-b, known as the prefix key)
.Ql C-b c
(Ctrl
followed by the
.Ql b
key
followed by the
.Ql c
key.
key).
.Pp
Windows may be navigated with:
.Ql C-b 0
@@ -173,31 +190,64 @@ 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
.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 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.
(Ctrl-b) by default, followed by a command key.
.Pp
Some of the default key bindings include:
.Pp
.Bl -tag -width Ds -compact
.It Ql d
Detach current client.
.It Ql c
.Bl -tag -width Ds -offset 3n -compact
.It c
Create new window.
.It Ql n
Change to next window in the current session.
.It Ql p
Change to previous window in the current session.
.It Ql l
.It d
Detach current client.
.It l
Move to last (previously selected) window in the current session.
.It Ql t
.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 Ql \&?
.It \&?
List current key bindings.
.El
.Pp
@@ -214,7 +264,7 @@ commands.
.Sh HISTORY
.Nm
maintains a configurable history buffer for each window.
By default, up to 2000 lines are kept, this can be altered with the
By default, up to 2000 lines are kept; this can be altered with the
.Ic history-limit
option (see the
.Ic set-option
@@ -247,11 +297,8 @@ command, bound to
by default.
.El
.Pp
The keys available depend on whether
.Xr emacs 1
or
.Xr vi 1
mode is selected (see the
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:
@@ -271,8 +318,11 @@ The following keys are supported as appropriate for the mode:
.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 "Paste buffer" Ta "p" Ta "C-y"
.El
.Pp
The paste buffer key pastes the first line from the top paste buffer on the
stack.
.Sh BUFFERS
.Nm
maintains a stack of
@@ -319,21 +369,88 @@ commands may be used to swap panes without changing the window layout.
.Pp
The following layouts are supported:
.Bl -tag -width Ds
.It Ic active-only
Only the active pane is shown \(en all other panes are hidden.
.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 manual
Manual layout splits windows vertically (running across); only with this layout
may panes be resized using the
.Ic resize-pane
command.
.It Ic active-only
Only the active pane is shown - all other panes are hidden.
.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-vertical
A large (81 column) pane is shown on the left of the window and the remaining
panes are spread from top to bottom in the leftover space to the right.
.El
.Sh STATUS LINE
.Nm
includes an optional status line which is displayed in the bottom line of each
terminal.
By default, the status line is enabled (it may be disabled with the
.Ic status
session option) and contains, from left-to-right: the name of the current
session in square brackets; the window list; the current window title in double
quotes; and the time and date.
.Pp
The status line is made of three parts: configurable left and right sections
(which may contain dynamic content such as the time or output from a shell
command, see the
.Ic status-left ,
.Ic status-left-length ,
.Ic status-right ,
and
.Ic status-right-length
options below), and a central window list.
The window list shows the index, name and (if any) flag of the windows
present in the current session in ascending numerical order.
The flag is one of the following symbols appended to the window name:
.Bl -column "Symbol" "Meaning" -offset indent
.It Sy "Symbol" Ta Sy "Meaning"
.It Li "*" Ta "Denotes the current window."
.It Li "-" Ta "Marks the last window (previously selected)."
.It Li "#" Ta "Window is monitored and activity has been detected."
.It Li "!" Ta "A bell has occurred in the window."
.It Li "+" Ta "Window is monitored for content and it has appeared."
.El
.Pp
The # symbol relates to the
.Ic monitor-activity
and + to the
.Ic monitor-content
window options.
The window name is printed in inverted colours if an alert (bell, activity or
content) is present.
.Pp
The colour and attributes of the status line may be configured, the entire status line using
the
.Ic status-attr ,
.Ic status-fg
and
.Ic status-bg
session options and individual windows using the
.Ic window-status-attr ,
.Ic window-status-fg
and
.Ic window-status-bg
window options.
.Pp
The status line is automatically refreshed at interval if it has changed, the interval may be
controlled with the
.Ic status-interval
session option.
.Sh COMMANDS
This section contains a list of the commands supported by
.Nm .
@@ -357,9 +474,9 @@ command.
.Ar target-session
is either the name of a session (as listed by the
.Ic list-sessions
command); or the name of a client as for
command) or the name of a client,
.Ar target-client ,
in this case, the session attached to the client is used.
in which case the session attached to the client is used.
An
.Xr fnmatch 3
pattern may be used to match the session name.
@@ -386,22 +503,20 @@ is omitted, the same rules as for
are followed; if
.Em index
is not present, the current window for the given session is used.
When the argument does not contain a colon (:),
When the argument does not contain a colon,
.Nm
first attempts to parse it as window index; if that fails, an attempt is made
to match a session or client name.
.Pp
Multiple commands may be specified together as part of a
.Em command sequence .
Each command should be separated by spaces and a semicolon
.Eo ( Ql \& \&; \& Ec ) ;
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:
.Pp
.Bd -literal -offset indent
refresh-client -t/dev/ttyp2
@@ -443,9 +558,9 @@ Keys may be specified prefixed with
.Ql C-
or
.Ql ^
for ctrl keys, or
for Ctrl keys, or
.Ql M-
for alt (meta) keys.
for Alt (meta) keys.
The
.Fl r
flag indicates this key may repeat, see the
@@ -476,6 +591,12 @@ 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 Xo Ic clear-history
.Op Fl p Ar pane-index
.Op Fl t Ar target-window
.Xc
.D1 (alias: Ic clearhist)
Remove and free the history for the specified pane.
.It Xo Ic clock-mode
.Op Fl t Ar target-window
.Xc
@@ -543,7 +664,9 @@ Move down a pane.
.Ar match-string
.Xc
.D1 (alias: Ic findw )
Search for
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
@@ -714,10 +837,14 @@ start-up files.
.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 paste-buffer
.Op Fl d
.Op Fl b Ar buffer-index
@@ -726,10 +853,14 @@ Move to the next window in the session.
.D1 (alias: Ic pasteb )
Insert the contents of a paste buffer into the current window.
.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 refresh-client
.Op Fl t Ar target-client
.Xc
@@ -813,6 +944,12 @@ The
has the same meaning as in the
.Ic copy-mode
command.
.It Xo Ic select-layout
.Op Fl t Ar target-window
.Ar layout-name
.Xc
.D1 (alias: selectl)
Choose a specific layout for a window.
.It Xo Ic select-pane
.Op Fl p Ar pane-index
.Op Fl t Ar target-window
@@ -908,7 +1045,7 @@ Set the command used for new windows (if not specified when the window is
created) to
.Ar command .
The default is
.Dq exec $SHELL .
.Dq exec $SHELL -l .
.It Ic default-path Ar path
Set the default working directory for processes created from keys, or
interactively from the prompt.
@@ -985,9 +1122,8 @@ window option for any windows first created in this session.
.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 enabled by default.
Note that
.Xr elinks 1
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
@@ -1009,10 +1145,7 @@ A setting of zero disables redrawing at interval.
.It Xo Ic status-keys
.Op Ic vi | Ic emacs
.Xc
Use
.Xr vi 1 -
or
.Xr emacs 1 -style
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
@@ -1038,6 +1171,12 @@ may contain any of the following special character pairs:
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-length Ar length
Set the maximum
.Ar length
@@ -1052,13 +1191,27 @@ As with
.Ic status-left ,
.Ar string
will be passed to
.Xr strftime 3
and character pairs are replaced.
.Xr strftime 3 ,
character pairs are replaced, and UTF-8 is dependent on the
.Ic status-utf8
option.
.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 | Ic 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.
.El
.It Xo Ic set-password
.Op Fl c
@@ -1101,8 +1254,9 @@ This means that
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 SIGWINCH and poor for
interactive programs such as shells.
this option is good for full-screen programs which support
.Dv SIGWINCH
and poor for interactive programs such as shells.
.It Xo Ic automatic-rename
.Op Ic on | Ic off
.Xc
@@ -1136,6 +1290,13 @@ from resizing a window to greater than
or
.Ar height .
A value of zero restores the default unlimited setting.
.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.
.It Ic mode-attr Ar attributes
Set window modes attributes.
.It Ic mode-bg Ar colour
@@ -1145,10 +1306,7 @@ Set window modes foreground colour.
.It Xo Ic mode-keys
.Op Ic vi | Ic emacs
.Xc
Use
.Xr vi 1 -
or
.Xr emacs 1 -style
Use vi or emacs-style
key bindings in scroll and copy modes.
Key bindings default to emacs.
.It Xo Ic monitor-activity
@@ -1158,7 +1316,10 @@ Monitor for activity in the window.
Windows with activity are highlighted in the status line.
.It Xo Ic monitor-content Ar match-string
.Xc
Monitor content in the window. When
Monitor content in the window.
When
.Xr fnmatch 3
pattern
.Ar match-string
appears in the window, it is highlighted in the status line.
.It Xo Ic remain-on-exit
@@ -1189,7 +1350,7 @@ If this option is set,
will generate
.Xr xterm 1 -style
function key sequences; these have a number included to indicate modifiers such
as shift, meta or ctrl.
as Shift, Alt or Ctrl.
.El
.It Xo Ic show-buffer
.Op Fl b Ar buffer-index
@@ -1262,7 +1423,9 @@ server, if not already running, without creating any sessions.
.Op Fl c target-client
.Xc
.D1 (alias: Ic suspendc )
Suspend a client by sending SIGTSTP (tty stop).
Suspend a client by sending
.Dv SIGTSTP
(tty stop).
.It Xo Ic swap-pane
.Op Fl dDU
.Op Fl p Ar src-index
@@ -1319,11 +1482,11 @@ not be linked to no sessions.
Move up a pane.
.El
.Sh FILES
.Bl -tag -width Ds -compact
.Bl -tag -width "~/.tmux.confXXX" -compact
.It Pa ~/.tmux.conf
default
Default
.Nm
configuration file
configuration file.
.El
.Sh SEE ALSO
.Xr pty 4