---

   tmux    ( 1 )

---

PARSING SYNTAX

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