Environment & Templates
Template variables
Interpolated in a single pass with {name} syntax. {{ escapes a literal {.
| Variable | Value |
|---|---|
{path} | Absolute worktree path |
{repo_path} | Absolute primary-repo path |
{data_dir} | Per-workspace data directory |
{project} | Project name |
{ref} | The ref string as you typed it |
{branch} | Resolved branch name, or short SHA when detached |
{slug} | Workspace slug |
{port} | First allocated port |
{port+N} | port + N, valid for N < ports |
They work in:
[env]valuescommands.*.runandcommands.*.cwdhooks.*- editor templates
ports = 2
[env]
PORT = "{port}"
API_PORT = "{port+1}"
DATABASE_URL = "file:{data_dir}/dev.db"
VITE_BASE_URL = "http://localhost:{port}"
{port+N} is only valid while N < ports. {port+1} with the default
ports = 1 is a configuration error.The exported environment
Every child process — run, exec, shell, [setup], and hooks — receives
these, whether or not your config mentions them:
| Variable | Value |
|---|---|
UXD_PATH | Absolute worktree path |
UXD_REPO_PATH | Absolute primary-repo path |
UXD_DATA_DIR | Per-workspace data directory |
UXD_PROJECT | Project name |
UXD_REF | The ref as typed |
UXD_BRANCH | Resolved branch name |
UXD_SLUG | Workspace slug |
UXD_PORT | First allocated port |
UXD_PORT_1 … UXD_PORT_{ports-1} | The rest of the block |
Your [env] values are layered on top, then a command's own [commands.x.env],
then any --env K=V passed on the command line.
Seeing the result
--dry-run on run, exec or shell prints the resolved environment as
export lines followed by the shell-quoted command:
uxd my-project feat/login run dev --dry-run
export UXD_PATH=~/dev/uxd/my-project/trees/feat-login
export UXD_REPO_PATH=~/dev/uxd/my-project/repo
export UXD_DATA_DIR=~/dev/uxd/my-project/trees/.data/feat-login
export UXD_PROJECT=my-project
export UXD_REF=feat/login
export UXD_BRANCH=feat/login
export UXD_SLUG=feat-login
export UXD_PORT=3053
export PORT=3053
bash -c 'npm run dev "$@"' uxd
That is the fastest way to check an interpolation without starting anything.
The data directory
$UXD_DATA_DIR is a private directory outside the worktree, at
{worktrees_path}/.data/<slug>. Use it for anything that must not land in the
git tree — SQLite files, uploads, caches. It is created before setup runs and
removed with the workspace.
See Workspaces & worktrees for how ports and the data directory fit into the workspace model.