32

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?

1 Answer 1

44

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)
4
  • To disdinguish server options from the global ones: Server options are options not applied to either session or window options. And there's only a few server options which can be listed by show -s. However from the usage perspective, server options are not necessary IMHO.
    – Bohr
    May 10, 2015 at 11:49
  • 1
    I mean I wish server options can also be specified with -g and remove -s just for the sake of UX simplicity. I just don't get any benefit by knowing an option is a server option.
    – Bohr
    May 10, 2015 at 12:00
  • man.openbsd.org/tmux#OPTIONS
    – NeilG
    Jul 21, 2021 at 3:11
  • I still want to know the differences and applicability of the different config commands like set, setw, set -w, set -g, etc and which kinds of options they affect.
    – NeilG
    Jul 21, 2021 at 3:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.