Glazier
Documentation

Profiles

Locals

Named values that a profile computes once and reads everywhere.

A local is a value you compute once and reuse, so that a slug or a derived name lives in one place instead of five. Nothing here is clever. The only rules worth knowing are the ones that stop a profile from eating your memory, and those are at the bottom.

The locals block

HCL
locals {
  slug     = lower(replace(var.district, " ", "-"))
  session  = "gig-${local.slug}"
  editors  = ["nvim", "hx", "vim"]
}

session {
  name = local.session

  window {
    name = "${local.slug}-ops"

    pane {
      commands = ["${local.editors[0]} ."]
    }
  }
}

You read a local as local.<name>. A profile can contain more than one locals block.

Rules

RuleBehaviour
ReferencesA local can reference var.*, env.*, path.*, every function and other locals.
OrderThe declaration order of locals has no effect. Glazier resolves them in as many passes as necessary.
CyclesLocals that refer to each other are an error. Glazier reports each group of such locals once, with every name in the group.
DuplicatesThe same name in two locals blocks is an error.
SizeAll locals together can hold at most 1 MiB. See Limits.
CLIThe command line cannot set a local. Use a variable for an input.
Session nameA local that calls random() must not reach the session name. See Session.

A cycle looks like this:

Console
$ glaze format --validate --profile-path cycle.glaze
Error: Circular reference between locals

  on cycle.glaze line 2, in locals:
   2:   a = local.b

These locals refer to each other, so none of them can have a value: local.a,
local.b.

the glaze profile contains errors

A local that depends on a cycle but is not part of it gets no error of its own. The cycle is the cause, so Glazier reports the cycle and keeps quiet about the fallout.

glaze down and locals

down evaluates only the session name. A local that the name does not reach can stay unresolved without an error. A local that the name does reach needs its variables. See Variables.

Why a budget on locals?

Because locals is the one place in a profile where a value can grow on its own. A local that concatenates the one before it doubles with each line, and a dozen lines of that is a gigabyte of string before tmux has heard a word. The 1 MiB budget covers every local together, counted as the bytes of each string plus one per element, and the first local to push the total over the line is the one that gets the error. No real profile comes anywhere near it. A profile that does is telling you something.