Between Versions

Sections are chronological. Find the version you’re upgrading from and read downward — everything below it applies to you.

Caution

dotkit is pre-1.0. Under semver, every 0.x minor release may break existing kits, so each one gets a section here. Once 1.0 lands, only major releases will.

If dotkit showed you a warning pointing here, silence it once you’re done:

dotkit self dismiss

---

From 0.1.0 to 0.2.0

Profiles became kits, and dotkit apply folded into dotkit run.

Folders no longer have a type

Marker files are gone. A folder is a symlink source or a checklist because a dotkit file says so, not because of a file inside it.

Delete	Replaced by
link.env with DEST=~	dotkit link dotfiles (DEST defaults to ~)
todo.env with TITLE=/NAME=/DEST=	dotkit todo --title 'Setup' --out ~/TODO.md todo
run.env	any *.env name; it’s now plain configuration
order.txt	the order you write lines in your dotkit file
profile.env	any *.env name

Add a dotkit file

It replaces order.txt:

map dotkit run {{item}}

configs
tools
packages
git
---
dotkit link dotfiles
dotkit todo -f --title 'Setup Checklist' --out ~/TODO.md todo

Name it .dotkit for a kit that runs without prompting. See Kits for the full precedence list.

configs/, tools/, and packages/ are no longer reserved names and no longer run in a fixed order. Order is the order you write.

A dotkit file is not required. dotkit run configs works on any folder and simply executes its .txt, .md, and .sh files alphabetically. What the file gives you is an entry point that names several folders in one go, and a boundary: the nearest dotkit file above any file, walking upward, marks that file’s kit root, which is where the .env search stops.

work/
  work.dotkit      ← nearest dotkit file above repos.txt, so the walk stops here
  dotkit.env       ← read
  git/
    git.env        ← read, and wins over dotkit.env
    repos.txt

Without one anywhere above it, a file gets only the .env files in its own directory.

Commands

Was	Now
dotkit apply DIR	dotkit run DIR, or bare dotkit run for the current directory
dotkit link SRC (read link.env)	dotkit link SRC [DEST], DEST defaults to ~
dotkit todo -f DIR (read todo.env)	dotkit todo -f --title T --out PATH DIR
--profile NAME (installer)	--dotkit NAME

dotkit apply no longer exists.

Environment

dotkit.env → profile.env → run.env was a fixed three-level cascade. Now any file ending in .env is read, walking from the kit root down to whichever file is running, so a nearer one wins. The walk stops at the kit root, at ~, and at /.

Renaming is usually all that’s needed: profile.env and run.env already sit in the right places, and their names no longer mean anything.

Environment variables

DOTKIT_PROFILE and DOTKIT_PROFILE_DIR are gone. dotkit add now finds its kit by walking up from your working directory, so run it from inside the repo.

Minimal example

before/                          after/
  dotkit.env                       .dotkit          ← new
  profiles/work/                   dotkit.env
    profile.env                    configs/
    order.txt                      packages/
    configs/                       dotfiles/        ← link.env deleted
    packages/                      todo/            ← todo.env deleted
    dotfiles/link.env
    todo/todo.env

dotkit run --dry-run .    # confirm resolution before running anything