Kit Environment

Environment for a dotkit file comes from .env files in the kit, not from a fixed set of configuration files.

The rule

Before running anything local, dotkit sources *.env files from the kit root down to the target’s directory, so nearer values win.

The kit root is the nearest ancestor directory, including the target’s own, that holds a *.dotkit file. The walk stops there, and also at your home directory and at /.

Naming

Any name ending in .env is read, plus a bare .env. Within a directory they are sourced in sorted order.

work/
  work.dotkit      ← kit root, walk stops here
  dotkit.env       ← read for everything under work/
  git/
    git.env        ← read for git/, wins over dotkit.env
    repos.txt

dotkit.env, profile.env, shared.env, and .env are all equivalent. The name carries no meaning and marks no folder type.

Layers

From outermost to innermost:

1. Variables already exported in your shell
2. .env files at the kit root
3. .env files at each directory in between
4. .env files in the target’s own directory

Files are sourced with set -a, so values are exported to any command the file runs, including separate processes like dotkit link.

Plain assignment overrides your shell. To let the environment win instead, use the default form:

# dotkit.env
DEV_DIR=~/dev              # always this value
${DEV_DIR:=~/dev}          # this value only if DEV_DIR is unset

Entry point does not matter

The walk starts at the file, not at the command. A single leaf file run on its own sees what it would see as part of a whole kit:

dotkit run ~/dotkit/work            # runs the kit
dotkit run ~/dotkit/work/git/repos  # same DEV_DIR, same GIT_USER

Fetched files have no kit

A file pulled from a URL or a remote ref does not live in your filesystem, so no walk happens and no .env files are read.

dotkit run :tools/brew              # no kit environment

Pass values inline if a community module needs them:

NONINTERACTIVE=1 dotkit run :tools/brew

Working directory

Every file runs with the working directory set to its own directory. Relative paths inside a dotkit file resolve against that file, not against wherever you invoked dotkit from.

When a variable is missing

An unset variable expands to nothing, which is rarely what you want in a path. Check the walk with:

dotkit run --dry-run <path>

It prints the resolved directory and every .env file it would source, in order.

Not env files

Two things that used to be .env files and are now command arguments:

Was	Now
link.env with DEST=~	dotkit link dotfiles (DEST defaults to ~)
todo.env with TITLE= / NAME= / DEST=	dotkit todo --title 'Setup' --out ~/TODO.md todo

Folders no longer have a type, so no file marks one. See Kits.