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.

mpane.Options(ctx) returns a fresh typed snapshot, including inherited values. Its accessors return an SOptionValue; use mOptionValue.Get to distinguish a present value from an absent one. Check the read error before inspecting the snapshot.

Use the handle that owns the option’s scope. For example, oautomatic-rename belongs to a window: use mWindow.SetOption or mWindow.UnsetOption, then read mWindow.Options again for an updated snapshot.

For a single raw value, mPane.RawOption returns the string, its presence, and an error. Do not treat an error as an absent option.

Examples¶

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

if err := window.SetOption(ctx, "automatic-rename", "off", tmux.SetOptionOptions{}); err != nil {
    return fmt.Errorf("set automatic rename: %w", err)
}
options, err := window.Options(ctx)
if err != nil {
    return fmt.Errorf("read window options: %w", err)
}
value, present := options.AutomaticRename().Get()
fmt.Println("automatic rename:", value, "present:", present)
if err := window.UnsetOption(ctx, "automatic-rename", tmux.UnsetOptionOptions{}); err != nil {
    return fmt.Errorf("unset automatic rename: %w", err)
}

Hooks¶

Use msession.SetHook to register a command and msession.Hooks to read the session’s typed hook values. msession.UnsetHook removes a registration. mSession.SetHooks writes indexed entries when an event needs more than one command.

Use mserver.GlobalSessionScope() for hooks shared by sessions. Keep hook registration at a scope supported by the tmux event.

Examples¶

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

mSession.SetHooks accepts indexed hook entries. Pass a context and check errors from both mutations and reads; a successful write does not refresh earlier snapshots.

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

if err := session.SetHook(ctx, "session-renamed", "display-message 'renamed'"); err != nil {
    return fmt.Errorf("set session hook: %w", err)
}
value, present, err := session.RawHook(ctx, "session-renamed")
if err != nil {
    return fmt.Errorf("read session hooks: %w", err)
}
fmt.Println("session-renamed:", value, "present:", present)

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.

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.