[BACK]Return to tmux.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / tmux

Diff for /src/usr.bin/tmux/tmux.1 between version 1.650 and 1.651

version 1.650, 2019/05/21 07:01:14 version 1.651, 2019/05/23 11:13:30
Line 355 
Line 355 
 and  and
 .Ic unbind-key  .Ic unbind-key
 commands.  commands.
   .Sh COMMAND PARSING AND EXECUTION
   .Nm
   supports a large number of commands which can be used to control its
   behaviour.
   Each command is named and can accept zero or more flags and arguments.
   They may be bound to a key with the
   .Ic bind-key
   command or run from the shell prompt, a shell script, a configuration file or
   the command prompt.
   For example, the same
   .Ic set-option
   command run from the shell prompt, from
   .Pa ~/.tmux.conf
   and bound to a key may look like:
   .Bd -literal -offset indent
   $ tmux set-option -g status-style bg=cyan
   
   set-option -g status-style bg=cyan
   
   bind-key C set-option -g status-style bg=cyan
   .Ed
   .Pp
   Here, the command name is
   .Ql set-option ,
   .Ql Fl g
   is a flag and
   .Ql status-style
   and
   .Ql bg=cyan
   are arguments.
   .Pp
   .Nm
   distinguishes between command parsing and execution.
   In order to execute a command,
   .Nm
   needs it to be split up into its name and arguments.
   This is command parsing.
   If a command is run from the shell, the shell parses it; from inside
   .Nm
   or from a configuration file,
   .Nm
   does.
   Examples of when
   .Nm
   parses commands are:
   .Bl -dash -offset indent
   .It
   in a configuration file;
   .It
   typed at the command prompt (see
   .Ic command-prompt ) ;
   .It
   given to
   .Ic bind-key ;
   .It
   passed as arguments to
   .Ic if-shell
   or
   .Ic confirm-before .
   .El
   .Pp
   To execute commands, each client has a
   .Ql command queue .
   A global command queue not attached to any client is used on startup
   for configuration files like
   .Pa ~/.tmux.conf .
   Parsed commands added to the queue are executed in order.
   Some commands, like
   .Ic if-shell
   and
   .Ic confirm-before ,
   parse their argument to create a new command which is inserted immediately
   after themselves.
   This means that arguments can be parsed twice or more - once when the parent command (such as
   .Ic if-shell )
   is parsed and again when it parses and executes its command.
   Commands like
   .Ic if-shell ,
   .Ic run-shell
   and
   .Ic display-panes
   stop execution of subsequent commands on the queue until something happens -
   .Ic if-shell
   and
   .Ic run-shell
   until a shell command finishes and
   .Ic display-panes
   until a key is pressed.
   For example, the following commands:
   .Bd -literal -offset indent
   new-session; new-window
   if-shell "true" "split-window"
   kill-session
   .Ed
   .Pp
   Will execute
   .Ic new-session ,
   .Ic new-window ,
   .Ic if-shell ,
   the shell command
   .Xr true 1 ,
   .Ic new-window
   and
   .Ic kill-session
   in that order.
   .Pp
   The
   .Sx COMMANDS
   section lists the
   .Nm
   commands and their arguments.
   .Sh PARSING SYNTAX
   This section describes the syntax of commands parsed by
   .Nm ,
   for example in a configuration file or at the command prompt.
   Note the when commands are entered into the shell, they are parsed by the shell
   - see for example
   .Xr ksh 1
   or
   .Xr csh 1 .
   .Pp
   Each command is terminated by a newline or a semicolon (;).
   Commands separated by semicolons together form a
   .Ql command sequence
   - if a command in the sequence encounters an error, no subsequent commands are
   executed.
   .Pp
   Comments are marked by the unquoted # character - any remaining text after a
   comment is ignored until the end of the line.
   .Pp
   If the last character of a line is \e, the line is joined with the following
   line (the \e and the newline are completely removed).
   This is called line continuation and applies both inside and outside quoted
   strings and in comments.
   .Pp
   Command arguments may be specified as strings surrounded by either single (')
   or double quotes (").
   .\" "
   This is required when the argument contains any special character.
   Strings cannot span multiple lines except with line continuation.
   .Pp
   Outside of quotes and inside double quotes, these replacements are performed:
   .Bl -dash -offset indent
   .It
   Environment variables preceded by $ are replaced with their value from the
   global environment (see the
   .Sx GLOBAL AND SESSION ENVIRONMENT
   section).
   .It
   A leading ~ or ~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
   the given four or eight digit hexadecimal number.
   .It
   When preceded (escaped) by a \e, the following characters are replaced: \ee by
   the escape character; \er by a carriage return; \en by a newline; and \et by a
   tab.
   .Pp
   Any other characters preceded by \e are replaced by themselves (that is, the \e
   is removed) and are not treated as having any special meaning - so for example
   \e; will not mark a command sequence and \e$ will not expand an environment
   variable.
   .El
   .Pp
   Environment variables may be set by using the syntax
   .Ql name=value ,
   for example
   .Ql HOME=/home/user .
   Variables set during parsing are added to the global environment.
   .Pp
   Commands may be parsed conditionally by surrounding them with
   .Ql %if ,
   .Ql %elif ,
   .Ql %else
   and
   .Ql %endif .
   The argument to
   .Ql %if
   and
   .Ql %elif
   is expanded as a format (see
   .Sx FORMATS )
   and if it evaluates to false (zero or empty), subsequent text is ignored until
   the closing
   .Ql %elif ,
   .Ql %else
   or
   .Ql %endif .
   For example:
   .Bd -literal -offset indent
   %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
   .Ed
   .Pp
   Will change the status line to red if running on
   .Ql myhost ,
   green if running on
   .Ql myotherhost ,
   or blue if running on another host.
   Conditionals may be given on one line, for example:
   .Bd -literal -offset indent
   %if #{==:#{host},myhost} set -g status-style bg=red %endif
   .Ed
 .Sh COMMANDS  .Sh COMMANDS
 This section contains a list of the commands supported by  This section describes the commands supported by
 .Nm .  .Nm .
 Most commands accept the optional  Most commands accept the optional
 .Fl t  .Fl t
Line 622 
Line 831 
 $ tmux bind-key F1 set-option status off  $ tmux bind-key F1 set-option status off
 .Ed  .Ed
 .Pp  .Pp
 Multiple commands may be specified together as part of a  
 .Em command sequence .  
 Each command should be separated by spaces and a semicolon;  
 commands are executed sequentially from left to right and  
 lines ending with a backslash continue on to the next line,  
 except when escaped by another backslash.  
 A literal semicolon may be included by escaping it with a backslash (for  
 example, when specifying a command sequence to  
 .Ic bind-key ) .  
 .Pp  
 Example  Example
 .Nm  .Nm
 commands include:  commands include:
Line 1005 
Line 1204 
 .Fl T  .Fl T
 show debugging information about jobs and terminals.  show debugging information about jobs and terminals.
 .It Xo Ic source-file  .It Xo Ic source-file
 .Op Fl q  .Op Fl nq
 .Ar path  .Ar path
 .Xc  .Xc
 .D1 (alias: Ic source )  .D1 (alias: Ic source )
Line 1019 
Line 1218 
 is given, no error will be returned if  is given, no error will be returned if
 .Ar path  .Ar path
 does not exist.  does not exist.
 .Pp  With
 Within a configuration file, commands may be made conditional by surrounding  .Fl n ,
 them with  the file is parsed but no commands are executed.
 .Em %if  
 and  
 .Em %endif  
 lines.  
 Additional  
 .Em %elif  
 and  
 .Em %else  
 lines may also be used.  
 The argument to  
 .Em %if  
 and  
 .Em %elif  
 is expanded as a format and if it evaluates to false (zero or empty),  
 subsequent lines are ignored until the next  
 .Em %elif ,  
 .Em %else  
 or  
 .Em %endif .  
 For example:  
 .Bd -literal -offset indent  
 %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  
 .Ed  
 .Pp  
 Will change the status line to red if running on  
 .Ql myhost ,  
 green if running on  
 .Ql myotherhost ,  
 or blue if running on another host.  
 .It Ic start-server  .It Ic start-server
 .D1 (alias: Ic start )  .D1 (alias: Ic start )
 Start the  Start the
Line 4134 
Line 4298 
 .Ic norange  .Ic norange
 .Xc  .Xc
 Mark a range in the  Mark a range in the
 . Ic status-format  .Ic status-format
 option.  option.
 .Ic range=left  .Ic range=left
 and  and
Line 4450 
Line 4614 
 .Op Fl x Ar position  .Op Fl x Ar position
 .Op Fl y Ar position  .Op Fl y Ar position
 .Xc  .Xc
 .D1 (alias: Ic menu)  .D1 (alias: Ic menu )
 Display a menu on  Display a menu on
 .Ar target-client .  .Ar target-client .
 .Ar target-pane  .Ar target-pane
Legend:
Removed from v.1.650  
changed lines
  Added in v.1.651