Profiles
Session
The session block, its attributes and the rules for the session name.
A profile contains exactly one session block. It is the root of everything else: the windows live inside it and the panes live inside the windows. The name on it is what glaze down uses to find the session again later. Blocks have no labels. You set a name with the name attribute, which feels odd for about a day and then feels obvious.
Example
session {
name = "daemon-run" # the default value is "default"
starting_directory = "~/runs/arasaka" # the default value is the current directory
commands = ["echo jacked-in"]
envs = {
EDITOR = "nvim"
ICE_TARGET = "arasaka-mainframe"
}
hooks = {
"client-attached" = "run-shell 'echo jacked-in'"
}
options = {
"base-index" = "1"
}
window {
# ...at least one window is required
}
}Attributes
| Attribute | Type | Notes |
|---|---|---|
name | string | The session name. The default value is default. The name must not be empty. A number or a bool becomes a string. The name must not use random(), directly or through a local, because glaze down computes the name again. |
starting_directory | string | The directory must exist. A relative path is relative to the directory of the profile. The default value is the current directory. If the current directory was deleted, set this attribute. |
commands | list(string) | Commands that run in the active pane after Glazier creates all windows and panes. See Commands. |
envs | map(string) | Environment variables for the session. Only the session block accepts envs. See Environment. |
hooks | map(string) | A map of a tmux hook name to a tmux command. The name must be one that tmux 3.2a to 3.7c knows, for example session-created or after-new-window. See Hooks and options. |
options | map(string) | A map of a tmux option name to a value. A window or pane option, for example remain-on-exit, applies to every window. See Hooks and options. |
window | block(s) | One or more windows. At least one window is required. See Window. |
The session name
The name must not be empty. Leave out name to get default. A number or a bool converts to a string, so name = 2077 gives the session name 2077.
The name must not call random(), directly or through a chain of locals. Glazier reports this as an error before it starts tmux. Use random() in a window name, a pane name or a command instead.
tmux rewrites some characters in a session name. Glazier replaces these characters with - before it starts tmux, and shows a warning with the new name. glaze format --validate shows the same warning with the file and the line.
| Scope | Characters replaced with - |
|---|---|
| Session name | ., :, $, a backslash and control characters, for example a tab |
| Window name or pane name | A backslash and control characters |
Why the fuss over random() in one attribute? Because glaze down does not remember what glaze up built. It evaluates the profile again, computes the name again and kills the session with that name. A random name on the way up and a different random name on the way down means down hunts for a session that never existed. Everywhere else in the profile, roll the dice as much as you like.
Directories
Each level of the profile can set starting_directory. A level without one inherits from its parent:
- A pane without
starting_directoryuses the directory of its window. - A window without
starting_directoryuses the directory of the session. - A session without
starting_directoryuses the current directory.
A relative starting_directory is relative to the directory of the profile, not to the directory where you start glaze. Each directory must exist when glaze validates the profile. A window that you open later in tmux starts in the directory of the session.
No null elements
A list or a map, for example commands, envs, hooks or options, must not contain null. Glazier reports the element by index or by key, because tmux cannot get a null value.
Options and where tmux keeps them
tmux keeps each option on a session, a window or a pane. Glazier asks tmux where it keeps an option and applies the option there. A window option on the session block, for example remain-on-exit, applies to every window. A session option on a window or a pane, for example history-limit, applies to the whole session, and Glazier shows a warning. The full rules are on Hooks and options.