tmux
includes an optional status line which is displayed in the
bottom line of each terminal.
By default, the status line is enabled and one line in height (it
may be disabled or made multiple lines with the 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.
Each line of the status line is configured with the status-format
option. The default 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 status-left
,
status-left-length
, status-right
, and 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 window-status-format and
window-status-current-format options. The flag is one of the
following symbols appended to the window name:
Symbol Meaning
* Denotes the current window.
- Marks the last window (previously selected).
# Window activity is monitored and activity has been
detected.
! Window bells are monitored and a bell has occurred
in the window.
~ The window has been silent for the monitor-silence
interval.
M The window contains the marked pane.
Z The window's active pane is zoomed.
The # symbol relates to the monitor-activity
window option. The
window name is printed in inverted colours if an alert (bell,
activity or silence) is present.
The colour and attributes of the status line may be configured, the
entire status line using the status-style
session option and
individual windows using the window-status-style
window option.
The status line is automatically refreshed at interval if it has
changed, the interval may be controlled with the status-interval
session option.
Commands related to the status line are as follows:
clear-prompt-history
[-T
prompt-type]
(alias: clrphist)
Clear status prompt history for prompt type prompt-type.
If -T
is omitted, then clear history for all types. See
command-prompt
for possible values for prompt-type.
command-prompt
[-1bFikN
] [-I
inputs] [-p
prompts] [-t
target-client] [-T
prompt-type] [template]
Open the command prompt in a client. This may be used from
inside tmux
to execute commands interactively.
If template is specified, it is used as the command. With
-F
, template is expanded as a format.
If present, -I
is a comma-separated list of the initial
text for each prompt. If -p
is given, prompts is a comma-
separated list of prompts which are displayed in order;
otherwise a single prompt is displayed, constructed from
template if it is present, or ':' if not.
Before the command is executed, the first occurrence of the
string '%%' and all occurrences of '%1' are replaced by the
response to the first prompt, all '%2' are replaced with
the response to the second prompt, and so on for further
prompts. Up to nine prompt responses may be replaced ('%1'
to '%9'). '%%%' is like '%%' but any quotation marks are
escaped.
-1
makes the prompt only accept one key press, in this case
the resulting input is a single character. -k
is like -1
but the key press is translated to a key name. -N
makes
the prompt only accept numeric key presses. -i
executes
the command every time the prompt input changes instead of
when the user exits the command prompt.
-T
tells tmux
the prompt type. This affects what
completions are offered when Tab is pressed. Available
types are: 'command', 'search', 'target' and
'window-target'.
The following keys have a special meaning in the command
prompt, depending on the value of the status-keys
option:
Function vi emacs
Cancel command prompt q Escape
Delete from cursor to start of word C-w
Delete entire command d C-u
Delete from cursor to end D C-k
Execute command Enter Enter
Get next command from history Down
Get previous command from history Up
Insert top paste buffer p C-y
Look for completions Tab Tab
Move cursor left h Left
Move cursor right l Right
Move cursor to end $ C-e
Move cursor to next word w M-f
Move cursor to previous word b M-b
Move cursor to start 0 C-a
Transpose characters C-t
With -b
, the prompt is shown in the background and the
invoking client does not exit until it is dismissed.
confirm-before
[-b
] [-p
prompt] [-t
target-client] command
(alias: confirm
)
Ask for confirmation before executing command. If -p
is
given, prompt is the prompt to display; otherwise a prompt
is constructed from command. It may contain the special
character sequences supported by the status-left
option.
With -b
, the prompt is shown in the background and the
invoking client does not exit until it is dismissed.
display-menu
[-O
] [-c
target-client] [-t
target-pane] [-T
title]
[-x
position] [-y
position] name key command ...
(alias: menu
)
Display a menu on target-client. target-pane gives the
target for any commands run from the menu.
A menu is passed as a series of arguments: first the menu
item name, second the key shortcut (or empty for none) and
third the command to run when the menu item is chosen. The
name and command are formats, see the FORMATS and STYLES
sections. If the name begins with a hyphen (-), then the
item is disabled (shown dim) and may not be chosen. The
name may be empty for a separator line, in which case both
the key and command should be omitted.
-T
is a format for the menu title (see FORMATS).
-x
and -y
give the position of the menu. Both may be a row
or column number, or one of the following special values:
Value Flag Meaning
C Both The centre of the terminal
R -x
The right side of the terminal
P Both The bottom left of the pane
M Both The mouse position
W Both The window position on the status
line
S -y
The line above or below the status
line
Or a format, which is expanded including the following
additional variables:
Variable name Replaced with
popup_centre_x Centered in the client
popup_centre_y Centered in the client
popup_height Height of menu or popup
popup_mouse_bottom Bottom of at the mouse
popup_mouse_centre_x Horizontal centre at
the mouse
popup_mouse_centre_y Vertical centre at the
mouse
popup_mouse_top Top at the mouse
popup_mouse_x Mouse X position
popup_mouse_y Mouse Y position
popup_pane_bottom Bottom of the pane
popup_pane_left Left of the pane
popup_pane_right Right of the pane
popup_pane_top Top of the pane
popup_status_line_y Above or below the
status line
popup_width Width of menu or popup
popup_window_status_line_x At the window position
in status line
popup_window_status_line_y At the status line
showing the window
Each menu consists of items followed by a key shortcut
shown in brackets. If the menu is too large to fit on the
terminal, it is not displayed. Pressing the key shortcut
chooses the corresponding item. If the mouse is enabled
and the menu is opened from a mouse key binding, releasing
the mouse button with an item selected chooses that item
and releasing the mouse button without an item selected
closes the menu. -O
changes this behaviour so that the
menu does not close when the mouse button is released
without an item selected the menu is not closed and a mouse
button must be clicked to choose an item.
The following keys are also available:
Key Function
Enter Choose selected item
Up Select previous item
Down Select next item
q Exit menu
display-message
[-aINpv
] [-c
target-client] [-d
delay] [-t
target-pane] [message]
(alias: display
)
Display a message. If -p
is given, the output is printed
to stdout, otherwise it is displayed in the target-client
status line for up to delay milliseconds. If delay is not
given, the message-time
option is used; a delay of zero
waits for a key press. 'N' ignores key presses and closes
only after the delay expires. The format of message is
described in the FORMATS section; information is taken from
target-pane if -t
is given, otherwise the active pane.
-v
prints verbose logging as the format is parsed and -a
lists the format variables and their values.
-I
forwards any input read from stdin to the empty pane
given by target-pane.
display-popup
[-BCE
] [-c
target-client] [-d
start-directory] [-h
height] [-t
target-pane] [-w
width] [-x
position] [-y
position] [shell-command]
(alias: popup
)
Display a popup running shell-command on target-client. A
popup is a rectangular box drawn over the top of any panes.
Panes are not updated while a popup is present.
-E
closes the popup automatically when shell-command exits.
Two -E
closes the popup only if shell-command exited with
success.
-x
and -y
give the position of the popup, they have the
same meaning as for the display-menu
command. -w
and -h
give the width and height - both may be a percentage
(followed by '%'). If omitted, half of the terminal size
is used. -B
does not surround the popup by a border.
The -C
flag closes any popup on the client.
show-prompt-history
[-T
prompt-type]
(alias: showphist)
Display status prompt history for prompt type prompt-type.
If -T
is omitted, then show history for all types. See
command-prompt
for possible values for prompt-type.