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()

Read effective/inherited: Not listed.

Set: mpane->set_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");
pane->options();
pane->unset_option("automatic-rename");

Hooks¶

Set: msession.set_hook(name, command): no CWindow/CPane overload exists at all

Unset: Not listed.

List: msession.hooks(), mserver.global_hooks()

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'");
session.hooks(); // No session unset helper is listed above.

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.

Use mSession::set_hook or mServer::global_hooks(). Window and pane handles do not provide hook methods.

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.