src/usr.bin/tmux/tmux.1 - diff

Return to tmux.1 CVS log

Up to [local] / src / usr.bin / tmux

Diff for /src/usr.bin/tmux/tmux.1 between version 1.933 and 1.934

version 1.933, 2023/09/16 16:18:29

version 1.934, 2023/12/27 20:20:50

Line 140

loads the system configuration file from

.Pa /etc/tmux.conf ,

if present, then looks for a user configuration file at

.Pa ~/.tmux.conf .

.Pa \[ti]/.tmux.conf .

.Pp

The configuration file is a set of

.Nm

Line 287

Split the current pane into two, left and right.

.It &

Kill the current window.

.It '

.It \[aq]

Prompt for a window index to select.

.It \&(

Switch the attached client to the previous session.

Line 359

Swap the current pane with the previous pane.

.It }

Swap the current pane with the next pane.

.It ~

.It \[ti]

Show previous messages from

.Nm ,

if any.

Line 405

For example, the same

.Ic set-option

command run from the shell prompt, from

.Pa ~/.tmux.conf

.Pa \[ti]/.tmux.conf

and bound to a key may look like:

.Bd -literal -offset indent

$ tmux set-option -g status-style bg=cyan

Line 458

.Ql command queue .

A global command queue not attached to any client is used on startup

for configuration files like

.Pa ~/.tmux.conf .

.Pa \[ti]/.tmux.conf .

Parsed commands added to the queue are executed in order.

Some commands, like

.Ic if-shell

Line 530

.Pp

Or:

.Bd -literal -offset indent

$ tmux neww ';' splitw

$ tmux neww \[aq];\[aq] splitw

.Ed

.Pp

Or from the tmux command prompt:

Line 548

.Pp

Or:

.Bd -literal -offset indent

$ tmux 'neww;' splitw

$ tmux \[aq]neww;\[aq] splitw

.Ed

.Pp

As in these examples, when running tmux from the shell extra care must be taken

Line 560

For

.Xr sh 1

this typically means quoted (such as

.Ql neww ';' splitw )

.Ql neww \[aq];\[aq] splitw )

or escaped (such as

.Ql neww \e\e\e\e; splitw ) .

.It

Line 570

.Nm ;

for example:

.Bd -literal -offset indent

$ tmux neww 'foo\e\e;' bar

$ tmux neww \[aq]foo\e\e;\[aq] bar

$ tmux neww foo\e\e\e\e; bar

.Ed

.It

Semicolons that are not individual tokens or trailing another token should only

be escaped once according to shell conventions; for example:

.Bd -literal -offset indent

$ tmux neww 'foo-;-bar'

$ tmux neww \[aq]foo-;-bar\[aq]

$ tmux neww foo-\e\e;-bar

.Ed

.El

Line 590

This is called line continuation and applies both inside and outside quoted

strings and in comments, but not inside braces.

.Pp

Command arguments may be specified as strings surrounded by single (') quotes,

Command arguments may be specified as strings surrounded by single (\[aq]) quotes,

double quotes (") or braces ({}).

double quotes (\[dq]) or braces ({}).

.\" "

This is required when the argument contains any special character.

Single and double quoted strings cannot span multiple lines except with line

Line 606

.Sx GLOBAL AND SESSION ENVIRONMENT

section).

.It

A leading ~ or ~user is expanded to the home directory of the current or

A leading \[ti] or \[ti]user is expanded to the home directory of the current or

specified user.

.It

\euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to

Line 638

needed when using {}:

.Bd -literal -offset indent

if-shell true {

display -p 'brace-dollar-foo: }$foo'

display -p \[aq]brace-dollar-foo: }$foo\[aq]

}

if-shell true "display -p 'brace-dollar-foo: }\e$foo'"

if-shell true "display -p \[aq]brace-dollar-foo: }\e$foo\[aq]"

.Ed

.Pp

Braces may be enclosed inside braces, for example:

Line 892

.Ql {marked}

(alternative form

.Ql ~ )

.Ql \[ti] )

to specify the marked pane (see

.Ic select-pane

.Fl m ) .

Line 932

commands.

This may be a single argument passed to the shell, for example:

.Bd -literal -offset indent

new-window 'vi ~/.tmux.conf'

new-window \[aq]vi \[ti]/.tmux.conf\[aq]

.Ed

.Pp

Will run:

.Bd -literal -offset indent

/bin/sh -c 'vi ~/.tmux.conf'

/bin/sh -c \[aq]vi \[ti]/.tmux.conf\[aq]

.Ed

.Pp

Additionally, the

Line 954

This can avoid issues with shell quoting.

For example:

.Bd -literal -offset indent

$ tmux new-window vi ~/.tmux.conf

$ tmux new-window vi \[ti]/.tmux.conf

.Ed

.Pp

Will run

Line 989

new-window ; split-window -d

bind-key R source-file ~/.tmux.conf \e; \e

bind-key R source-file \[ti]/.tmux.conf \e; \e

display-message "source-file done"

.Ed

.Pp

Line 1000

$ tmux new-window \e; split-window -d

$ tmux new-session -d 'vi ~/.tmux.conf' \e; split-window -d \e; attach

$ tmux new-session -d \[aq]vi \[ti]/.tmux.conf\[aq] \e; split-window -d \e; attach

.Ed

.Sh CLIENTS AND SESSIONS

The

Line 1581

.Nm

server will exit with no sessions, this is only useful if a session is created

.Pa ~/.tmux.conf ,

.Pa \[ti]/.tmux.conf ,

.Ic exit-empty

is turned off, or another command is run as part of the same command sequence.

For example:

Line 2171

$ 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}'

$ tmux select-layout \[aq]bb62,159x48,0,0{79x48,0,0,79x48,80,0}\[aq]

.Ed

.Pp

.Nm

Line 2311

and the result executed as a command.

.Ar template

is not given, "detach-client -t '%%'" is used.

is not given, "detach-client -t \[aq]%%\[aq]" is used.

.Pp

.Fl O

specifies the initial sort field: one of

Line 2396

and the result executed as a command.

.Ar template

is not given, "switch-client -t '%%'" is used.

is not given, "switch-client -t \[aq]%%\[aq]" is used.

.Pp

.Fl O

specifies the initial sort field: one of

Line 2508

substituted by the pane ID.

The default

.Ar template

is "select-pane -t '%%'".

is "select-pane -t \[aq]%%\[aq]".

With

.Fl b ,

other commands are not blocked from running until the indicator is closed.

Line 2870

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'

bind-key C-p pipe-pane -o \[aq]cat >>\[ti]/output.#I-#P\[aq]

.Ed

.Tg prevl

.It Xo Ic previous-layout

Line 3174

.Pp

An empty

.Ar shell-command

('') will create a pane with no command running in it.

(\[aq]\[aq]) will create a pane with no command running in it.

Output can be sent to such a pane with the

.Ic display-message

command.

Line 3301

Note that to bind the

.Ql \&"

.Ql '

.Ql \[aq]

keys, quotation marks are necessary, for example:

.Bd -literal -offset indent

bind-key '"' split-window

bind-key \[aq]"\[aq] split-window

bind-key "'" new-window

bind-key "\[aq]" new-window

.Ed

.Pp

A command bound to the

Line 3701

.Ar value .

For example, after:

.Pp

.Dl set -s command-alias[100] zoom='resize-pane -Z'

.Dl set -s command-alias[100] zoom=\[aq]resize-pane -Z\[aq]

.Pp

Using:

.Pp

Line 3939

.Pp

For example:

.Bd -literal -offset indent

set -s user-keys[0] "\ee[5;30012~"

set -s user-keys[0] "\ee[5;30012\[ti]"

bind User0 resize-pane -L 3

.Ed

.El

Line 4838

.Fl H .

The following two commands are equivalent:

.Bd -literal -offset indent.

set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'

set-hook -g pane-mode-changed[42] \[aq]set -g status-left-style bg=red\[aq]

set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'

set-option -g pane-mode-changed[42] \[aq]set -g status-left-style bg=red\[aq]

.Ed

.Pp

Setting a hook without specifying an array index clears the hook and sets the

Line 5778

.Ic allow-rename

option is turned on):

.Bd -literal -offset indent

$ printf '\e033kWINDOW_NAME\e033\e\e'

$ printf \[aq]\e033kWINDOW_NAME\e033\e\e\[aq]

.Ed

.It

Automatic renaming, which sets the name to the active command in the window's

Line 5791

When a pane is first created, its title is the hostname.

A pane's title can be set via the title setting escape sequence, for example:

.Bd -literal -offset indent

$ printf '\e033]2;My Title\e033\e\e'

$ printf \[aq]\e033]2;My Title\e033\e\e\[aq]

.Ed

.Pp

It can also be modified with the

Line 5916

.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 "\[ti]" 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

Line 6451

and the result executed as a command.

.Ar template

is not given, "paste-buffer -b '%%'" is used.

is not given, "paste-buffer -b \[aq]%%\[aq]" is used.

.Pp

.Fl O

specifies the initial sort field: one of

Line 6750

to change the cursor colour from inside

.Nm :

.Bd -literal -offset indent

$ printf '\e033]12;red\e033\e\e'

$ printf \[aq]\e033]12;red\e033\e\e\[aq]

.Ed

.Pp

The colour is an

Line 6806

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'

$ printf \[aq]\e033[4 q\[aq]

.Ed

.Pp

Line 7125

.El

.Sh FILES

.Bl -tag -width "/etc/tmux.confXXX" -compact

.It Pa ~/.tmux.conf

.It Pa \[ti]/.tmux.conf

Default

.Nm

configuration file.

Line 7191

Commands to be run when the

.Nm

server is started may be placed in the

.Pa ~/.tmux.conf

.Pa \[ti]/.tmux.conf

configuration file.

Common examples include:

.Pp

Line 7218

Creating new key bindings:

.Bd -literal -offset indent

bind-key b set-option status

bind-key / command-prompt "split-window 'exec man %%'"

bind-key / command-prompt "split-window \[aq]exec man %%\[aq]"

bind-key S command-prompt "new-window -n %1 'ssh %1'"

bind-key S command-prompt "new-window -n %1 \[aq]ssh %1\[aq]"

.Ed

.Sh SEE ALSO

.Xr pty 4