Profiles

A profile is a directory inside profiles/ that describes everything needed to configure a machine. Running dotkit apply on a profile executes its folders in order.

Structure

• Directorydotkit/

  • dotkit.env
  • Directoryprofiles/

    • Directorypersonal/

      • profile.env
      • order.txt
      • Directoryconfigs/

        • …
      • Directorytools/

        • …
      • Directorypackages/

        • …
      • Directorydotfiles/

        • link.env
      • Directorymanual/

        • todo.env
    • Directorywork/

      • …

The profiles/ directory can hold any number of profiles. The bootstrap installer lists them and prompts for selection, or pass --profile NAME to skip the prompt.

Execution order

dotkit apply profiles/personal processes folders in this order:

1. configs/ - system preferences, no dependencies required
2. tools/ - package managers and toolchains (brew, cargo, fnm, uv)
3. packages/ - apps and packages installed via those tools
4. Other run folders, alphabetically
5. Link folders - folders with a link.env file (symlink farms)
6. Todo folders - folders with a todo.env file (manual checklists)

configs, tools, and packages are reserved names that always run first in that order. All other run folders follow, alphabetically.

Tip

Use order.txt to change the order or exclude folders. See below.

Folder types

Every folder under a profile is one of three types, determined by which .env marker file it contains:

Marker	Type	What happens
(none)	run	.txt, .md, and .sh files are executed
link.env	link	dotkit link is called and files are symlinked to DEST
todo.env	todo	dotkit todo is called and a TODO.md checklist is generated

A folder cannot have more than one type marker. For example, dotkit will error if both link.env and todo.env are present in a directory.

Run folders

The default. Any .txt, .md, or .sh file found at the top level of the folder is executed. Subfolders are not descended into, so users can place supporting files or data in them.

Link folders

Require a link.env with a DEST variable pointing to the symlink target:

dotfiles/link.env

DEST=~

Running dotkit apply (or dotkit link dotfiles) symlinks every file in the folder to ~/. Existing files are backed up with a timestamp before being replaced.

Todo folders

Requires a todo.env. The todo.env file requires zero configuration (it can be blank). Dotkit generates a TODO.md checklist of manual steps from .txt and .md files in the folder. These are optional configurations:

manual/todo.env

DEST=..           # output location (relative to todo.env)
TITLE=Setup       # H1 heading (default: folder name)
NAME=MANUAL.md    # output filename (default: TODO.md)

Tip

Add **/TODO.md to your dotkit repo’s .gitignore for easier git commits.

Config files

dotkit.env

Sits at the repo root. Sourced before any profile runs. Use it for variables shared across all profiles:

# dotkit.env
DOTKIT_DEV_DIR="~/dev"

profile.env

Sits at the profile root. Sourced after dotkit.env and can override any variable:

profiles/work/profile.env

DOTKIT_DEV_DIR="~/work"
GITHUB_ORG=acme

Both files are sourced with set -a, so all variables are automatically exported to scripts.

order.txt

Customize execution order by listing folder names, one per line:

configs
tools
tasks
packages

Any folder named in order.txt runs in that position. Any configs, tools, and packages folders will still get their default priority if omitted.

Prefix a name with ! to exclude a folder entirely:

!manual

Lines beginning with # are comments.

run.env

A run folder can have a run.env to set variables available to all files in that folder:

git/run.env

GITHUB_USER=yourname
DEV_DIR=$HOME/dev

Multiple profiles

A suggested pattern is one profile per context:

• Directoryprofiles/

  • Directorypersonal/

    • …
  • Directorywork/

    • …
  • Directoryserver/

    • …

Dotkit works in many ways. There could also be a common/ profile that runs first before applying any other profile.