Difference between global, server, session and window options
Solution 1:
There are three distinct classes of options: server, session, and window. These classes are exclusive: each option belongs to only one of the classes. There is never any inheritance between the option classes.
There is only one level of server options, so there is no inheritance there (although you can have multiple, independent servers using the -L
or -S
command line flags).
The session and window options each use a two-level hierarchy: the global session (window) options provide default values for session (window) options that are unset. Session and window options are all initially unset, so new sessions/windows will automatically use the global session/window option values.
When a session option is set (set-option
), the newly set value will override the global value for that session. To go back to using the global value, unset the option (set-option -u
). Changes to the global session option values will affect all sessions in which that option is currently unset. The same idea applies to the window options (except setting a window option overrides the value for an individual window instead of an individual session).
For example, to find the effective value for the base-index
session option for a particular session:
- Check the session’s
base-index
option (i.e. what you get fromtmux -t «target-session» show-options base-index
*).- If the session has a
base-index
value, then use it. - If the session’s value was not set, then use the global value (i.e. what you get from
tmux show-options -g base-index
).
- If the session has a
Similarly, to find the effective value for the mode-keys
window option for a particular window:
- Check the window’s
mode-keys
option (i.e. what you get fromtmux -t «target-window» show-options -w mode-keys
**).- If the window has a
mode-keys
value, then use it. - If the window’s value was not set, then use the global value (i.e. what you get from
tmux show-options -gw mode-keys
).
- If the window has a
* Older versions of tmux do not accept an option name argument for show-options
. With those versions you will have to do something like grep for it: tmux -t target show-options | grep '^base-index '
.
** This is the same as tmux show-window-options base-index
, if you like that better. The related command for the global window options is tmux show-window-options -g base-index
.
Here is a diagram:
.---------------.
( server options )
`---------------'
===========================================================
.----------------------.
( global session options ) base-index 1
`---------+--+---------' visual-bell on
--/ \--
--/ \--
+-----/-----+ +-----\-----+
| session X | | session Y |
+-----------+ +-----------+
base-index 0 visual-bell off
effective values for X:
base-index 0 (set)
visual-bell on (global)
effective values for Y:
base-index 1 (global)
visual-bell off (set)
===========================================================
.---------------------.
( global window options ) pane-base-index 1
`---------+++---------' mode-keys emacs
---/ | \---
--/ | \---
---/ | \---
---/ | \---
+-------/----+ +------+-----+ +------\-----+
| window X.0 | | window X.1 | | window Y.0 |
+------------+ +------------+ +------------+
pane-base-index 0 mode-keys vi
mode-keys vi
effective values for X.0:
pane-base-index 0 (set)
mode-keys vi (set)
effective values for X.1:
pane-base-index 1 (global)
mode-keys emacs (global)
effective values for Y.0:
pane-base-index 1 (global)
mode-keys vi (set)