Options and hooks

Use options to change tmux behavior, such as oautomatic-rename or the status-line format. Use hooks to run commands on events such as hsession-renamed or hafter-split-window. Choose the scope supported by the option or hook.

Reading and writing options¶

Read, set, or unset an option at its supported scope. Distinguish a local override from the effective value inherited from a parent scope.

Read all (this scope): mpane.options() (typed BTreeMap), mpane.option_names()

Read effective/inherited: mpane.typed_option(name) decodes one value by its declared kind

Set: mpane.set_option(name, value), mpane.append_option(name, value)

Unset: mpane.unset_option(name)

Examples¶

After a successful write completes, read the option to obtain its updated value. The following examples set, read, and unset an option:

pane.set_option("automatic-rename", "off").await?;
pane.options().await?;
pane.unset_option("automatic-rename").await?;

Hooks¶

Set: mpane.set_hook(name, command)

Unset: mpane.unset_hook(name)

List: mpane.hook(name): one name only; no listing at pane/window scope, by design (see below)

Run now, without the event: Not listed.

Examples¶

tmux stores hook commands in indexed arrays, such as hafter-new-window[0].

Set and list a session hook. The next section explains window and pane scope limitations:

session.set_hook("session-renamed", "display-message 'renamed'").await?;
session.hooks().await?;

Supported hook scopes¶

tmux stores hooks globally or per session. Accepted $set-hook -w or -p flags do not imply a separate window or pane hook table, and $show-hooks does not provide a corresponding listing. Check the event’s supported scope if a hook is accepted but never fires.

mPane::set_hook and mWindow::set_hook return kError::OptionScopeMismatch for an unsupported scope.

Options have window and pane tables of their own. The hook-scope limitation does not apply to ordinary options.

tmux version compatibility¶

Check the library’s supported tmux versions before using a version-specific option or hook.