One profile for many projects

Most of my projects want the same three things: an editor, a dev server and a log tail. The only parts that change are the directory and, on a bad day, the editor. One .glaze per project means a dozen copies of the same file that drift apart quietly. Variables fix that. You declare the inputs once, pass the values on the command line and keep one profile.

This guide builds that template. The reference for each piece is on Variables and Locals.

The template#

This workspace starts an editor, a dev server and a log tail:

variable "project" {
  description = "absolute path to the project you're jacking into"
  type        = string
}

variable "branch" {
  description = "branch shown in the session name"
  type        = string
  default     = "main"
}

variable "editor" {
  type    = string
  default = "nvim"
}

session {
  name               = "${var.branch}@${path.base}"
  starting_directory = var.project

  window {
    name  = "edit"
    focus = true

    pane {
      commands = ["${var.editor} ."]
    }
  }

  window {
    name = "run"

    pane {
      commands = ["npm run dev"]
    }

    pane {
      commands = ["tail -f ${var.project}/logs/dev.log"]
    }
  }
}

What each piece does:

• var.project has no default, thus it is required. If you omit it, glaze reports a missing variable and does not build a partial session.
• var.branch and var.editor have defaults. You ignore them in the common case. You override them only when necessary.
• The session name combines the branch and the basename of the current directory. Thus feature-x@glazier tells you what you see.
• starting_directory = var.project uses the value directly. The ${...} wrapper is necessary only when you splice a value into a larger string.

Run it#

The same file gives two different workspaces. The flags decide:

$ glaze up --var project=$HOME/code/glazier                                  # nvim, on main
$ glaze up --var project=$HOME/code/glazier --var branch=feature-x --var editor=hx

Run glaze up without --var project=... and Glazier stops before it touches tmux:

$ glaze up
Error: Required variable not set

  on /home/v/code/glazier/.glaze line 1, in variable "project":
   1: variable "project" {

Variable "project" declares no default, so a value must be supplied with --var
project=... or via --var-file.

the glaze profile contains errors

The rules for a value:

• A --var flag with a name that no variable block declares causes an error.
• Glazier converts each value to the declared type: string, number or bool. A value that cannot convert causes an error.
• A --var value is text. For a bool, true and 1 become true, and false and 0 become false. Glazier refuses each other value, for example TRUE or yes.
• For a number, --var base_index=two causes an error before the session starts.

Values from a file#

Ten --var flags on one line get old fast. A var file is a native HCL file of name = value attributes. Keep one per project:

project = "/home/v/code/arasaka"
editor  = "hx"

$ glaze up --var-file vars/arasaka.hcl
$ glaze up --var-file vars/arasaka.hcl --var branch=feature-x

Glazier applies values in this order: the default first, then the var file, then each --var flag. The last value for a name applies. A var file entry with an undeclared name causes an error. Glazier does not support JSON var files.

Derived values with locals#

The log path appears twice in the run window as soon as you add a second command for it. A locals block declares a value once, so the profile reads it as local.log:

locals {
  log = "${var.project}/logs/dev.log"
}

# ...in the run window:
pane {
  commands = ["touch ${local.log}", "tail -f ${local.log}"]
}

A local can reference var.*, env.*, path.*, the functions and other locals. The CLI cannot set a local. Declaration order has no effect, and a circular reference causes an error.

Tear it down#

glaze down evaluates only the session name. Here the name uses var.branch and path.base, not var.project, so you pass only the branch:

$ glaze down                        # kills main@glazier
$ glaze down --var branch=feature-x # kills feature-x@glazier

A variable that appears only deeper in the profile is not required for teardown. Thus a script can tear a session down without the full set of values. See glaze down.