Hooks and options

hooks and options look like two more maps on a block, and mostly they are. The catch is that tmux has its own opinion about where an option lives, and Glazier follows tmux rather than the block you wrote it on. That is the right behaviour, but it is surprising the first time, so here are the rules in full.

Hooks

A hooks map binds a tmux hook name to a tmux command. Each of session, window and pane accepts one.

HCL
session {
  hooks = { "client-attached" = "run-shell 'echo jacked-in'" }

  window {
    hooks = { "window-renamed" = "display 'trace detected'" }

    pane {
      hooks = { "pane-exited" = "display 'daemon down'" }
    }
  }
}

Block	tmux form
`session`	`set-hook -t <session> <name> <command>`
`window`	`set-hook -w -t <window> <name> <command>`
`pane`	`set-hook -p -t <pane> <name> <command>`

Rules:

The hook name must be one that tmux 3.2a to 3.7c knows, for example session-created or after-new-window. An unknown name is an error before tmux starts.
An index such as session-created[1] is allowed.
A null command is an error.
Glazier sets the hooks after it creates the object they belong to. A session-created hook on the session fires only for sessions that tmux creates later.

note

A hook is a command bound to an event. glaze save never exports hooks, for the same reason it never exports commands. See save.

Options

An options map sets a tmux option to a value. Each of session, window and pane accepts one.

HCL
session {
  options = { "base-index" = "1" }

  window {
    options = { "automatic-rename" = "off" }

    pane {
      options = { "remain-on-exit" = "on" }
    }
  }
}

Block	tmux form
`session`	`set-option -t <session> <name> <value>`
`window`	`set-option -w -t <window> <name> <value>`
`pane`	`set-option -p -t <pane> <name> <value>`

A null value is an error. A value that tmux rejects stops up with exit code 1.

Where tmux keeps an option

tmux keeps each option in one table: the session table, the window table or the pane table. Glazier reads the tables from tmux once, then applies each option in the table that tmux keeps it in.

Option declared on	Option kept by tmux on	What Glazier does
`session`	the session	Sets it on the session.
`session`	a window or a pane	Sets it on every window, right after Glazier creates the window and before any pane exists.
`window` or `pane`	the session	Sets it on the session and shows a warning.
`window`	a window	Sets it on the window, before the panes.
`pane`	a pane	Sets it on the pane.
Any block	an `@user` option or an unknown name	Sets it where you declared it.

Glazier sets window options before it creates the panes of the window. Thus remain-on-exit is in place before any command runs.

Why not just set the option where you wrote it and let tmux sort it out? Because tmux does not sort it out. set-option -t <session> remain-on-exit on sets a window option, so tmux applies it to the current window only and says nothing. You wrote it on the session because you wanted it everywhere, and silently getting one window is the worst kind of wrong. So Glazier asks tmux which table an option belongs to and does the thing you meant. A window option on the session goes to every window. A session option on a pane goes to the session with a warning, because that one will leak out to the whole session whether you like it or not.

note

glaze save never exports options. tmux reports only the effective state, which mixes your tmux.conf with what Glazier set. See save.

Hooks#

Options#

Where tmux keeps an option#

Hooks

Options

Where tmux keeps an option