Difference between global, server, session and window options

Question

The tmux manual discusses various types of options, for example global options, server options and so on. The question Where's the default tmux configuration file? also refers to some of these types of configuration.

Some of these types are easy to understand: window options deal with things that relate only to a single window. For example "allow-rename": windows have names, sessions do not. For other types, however, the distinction is not very clear.

What is the difference between

• server options (set-option -s),
• global session options (set-option -g),
• session options (set-option),
• global window options (set-window-option -g),
• window options (set-window-option)?

Also, what are the inheritance rules for these types?

Answer 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 from tmux -t «target-session» show-options base-index^*).
  1. If the session has a base-index value, then use it.
  2. 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).

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 from tmux -t «target-window» show-options -w mode-keys^**).
  1. If the window has a mode-keys value, then use it.
  2. 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).

---

^{* 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)