This section describes the syntax of commands parsed by tmux, for
example in a configuration file or at the command prompt. Note
that when commands are entered into the shell, they are parsed by
the shell - see for example ksh(1) or csh(1).
Each command is terminated by a newline or a semicolon (;).
Commands separated by semicolons together form a 'command sequence'
- if a command in the sequence encounters an error, no subsequent
commands are executed.
It is recommended that a semicolon used as a command separator
should be written as an individual token, for example from sh(1):
$ tmux neww \; splitw
Or:
$ tmux neww ';' splitw
Or from the tmux command prompt:
neww ; splitw
However, a trailing semicolon is also interpreted as a command
separator, for example in these sh(1) commands:
$ tmux neww\\; splitw
Or:
$ tmux 'neww;' splitw
As in these examples, when running tmux from the shell extra care
must be taken to properly quote semicolons:
1. Semicolons that should be interpreted as a command
separator should be escaped according to the shell
conventions. For sh(1) this typically means quoted
(such as 'neww ';' splitw') or escaped (such as 'neww
\\\\; splitw').
2. Individual semicolons or trailing semicolons that should
be interpreted as arguments should be escaped twice:
once according to the shell conventions and a second
time for tmux; for example:
$ tmux neww 'foo\\;' bar
$ tmux neww foo\\\\; bar
3. Semicolons that are not individual tokens or trailing
another token should only be escaped once according to
shell conventions; for example:
$ tmux neww 'foo-;-bar'
$ tmux neww foo-\\;-bar
Comments are marked by the unquoted # character - any remaining
text after a comment is ignored until the end of the line.
If the last character of a line is \, the line is joined with the
following line (the \ and the newline are completely removed).
This is called line continuation and applies both inside and
outside quoted strings and in comments, but not inside braces.
Command arguments may be specified as strings surrounded by single
(') quotes, double quotes (") or braces ({}). This is required
when the argument contains any special character. Single and
double quoted strings cannot span multiple lines except with line
continuation. Braces can span multiple lines.
Outside of quotes and inside double quotes, these replacements are
performed:
- Environment variables preceded by $ are replaced with
their value from the global environment (see the GLOBAL
AND SESSION ENVIRONMENT section).
- A leading ~ or ~user is expanded to the home directory of
the current or specified user.
- \uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint
corresponding to the given four or eight digit
hexadecimal number.
- When preceded (escaped) by a \, the following characters
are replaced: \e by the escape character; \r by a
carriage return; \n by a newline; and \t by a tab.
- \ooo is replaced by a character of the octal value ooo.
Three octal digits are required, for example \001. The
largest valid character is \377.
- Any other characters preceded by \ are replaced by
themselves (that is, the \ is removed) and are not
treated as having any special meaning - so for example \;
will not mark a command sequence and \$ will not expand
an environment variable.
Braces are parsed as a configuration file (so conditions such as
'%if' are processed) and then converted into a string. They are
designed to avoid the need for additional escaping when passing a
group of tmux commands as an argument (for example to if-shell).
These two examples produce an identical command - note that no
escaping is needed when using {}:
if-shell true {
display -p 'brace-dollar-foo: }$foo'
}
if-shell true "display -p 'brace-dollar-foo: }\$foo'"
Braces may be enclosed inside braces, for example:
bind x if-shell "true" {
if-shell "true" {
display "true!"
}
}
Environment variables may be set by using the syntax 'name=value',
for example 'HOME=/home/user'. Variables set during parsing are
added to the global environment. A hidden variable may be set with
'%hidden', for example:
%hidden MYVAR=42
Hidden variables are not passed to the environment of processes
created by tmux. See the GLOBAL AND SESSION ENVIRONMENT section.
Commands may be parsed conditionally by surrounding them with
'%if', '%elif', '%else' and '%endif'. The argument to '%if' and
'%elif' is expanded as a format (see FORMATS) and if it evaluates
to false (zero or empty), subsequent text is ignored until the
closing '%elif', '%else' or '%endif'. For example:
%if "#{==:#{host},myhost}"
set -g status-style bg=red
%elif "#{==:#{host},myotherhost}"
set -g status-style bg=green
%else
set -g status-style bg=blue
%endif
Will change the status line to red if running on 'myhost', green if
running on 'myotherhost', or blue if running on another host.
Conditionals may be given on one line, for example:
%if #{==:#{host},myhost} set -g status-style bg=red %endif
