Kits

A kit is any directory holding a *.dotkit file. That file is the entry point, and its directory is the boundary for environment variables.

Kits sit anywhere. A repo of them, a single flat repo, or the root of an ordinary project so teammates can run dotkit run . after cloning.

Structure

• Directorydotkit/

  • mac.dotkit - a target
  • fedora.dotkit - another target, same kit
  • dotkit.env
  • Directoryconfigs/

    • …
  • Directorypackages/

    • …
  • Directorygit/

    • git.env
    • repos.txt
  • Directorydotfiles/

    • …
  • Directorytodo/

    • …

Nothing here is special except the *.dotkit files. configs/, packages/, and dotfiles/ are ordinary folders with no type of their own.

The dotkit file

A .dotkit file is an ordinary dotkit file that happens to name the entry point. It says what to do with each folder:

map dotkit run {{item}}

configs
packages
git
---
dotkit link dotfiles
dotkit todo --out ~/TODO.md todo

Order is the order you write. There is no reserved folder name and no separate ordering file.

dotkit link and dotkit todo are ordinary commands here, not built-in folder behaviours. Swap in stow or anything else and nothing about the model changes.

Tip

Because a .dotkit file is just a dotkit file, it can do anything a dotkit file can: try blocks, ask prompts, plain shell, variables.

Choosing a target

One directory can hold several targets. These filenames all mean “this directory’s default target”, highest precedence first:

1. default.dotkit
2. index.dotkit
3. <foldername>.dotkit
4. .dotkit

Any lower one that also exists is reported and skipped:

dotkit run: ignoring index.dotkit, default.dotkit takes precedence

A default is the only thing that suppresses the prompt. Anything else, even a single named file, asks:

Dotkit files in /home/you/dotkit:

  1) mac
  2) fedora
  3) entire folder (ignore dotkits)
  0) cancel

Which one? [0-3]:

Option 3 skips the dotkit files entirely and runs the folder’s own .txt, .md, and .sh files.

With no terminal attached, the prompt becomes an error listing the candidates, so an unattended run never stops to ask. Pass a file directly to skip it:

dotkit run ~/dotkit/mac.dotkit

Caution

Renaming a directory demotes <foldername>.dotkit to an ordinary named target, and nothing warns you, because nothing is being ignored. A directory that ran without prompting will start prompting.

How folders run

dotkit run on a directory with no dotkit file executes its .txt, .md, and .sh files alphabetically. Subfolders are not descended into, so supporting files and data can live in them safely.

To descend, say so:

map dotkit run {{item}}

configs
configs/git
configs/post

Listing configs does not pull in configs/git. That is deliberate: recursion is always explicit, so dropping a folder into your kit never silently starts executing it.

Each file runs with the working directory set to its own directory, so relative paths inside a dotkit file resolve against that file rather than wherever you happened to be standing.

README.md, README.txt, LICENSE, LICENSE.md, and TODO.md are never executed.

Environment

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

• Directorywork/

  • work.dotkit
  • dotkit.env - read for everything under work/
  • Directorygit/

    • git.env - read for git/, wins over dotkit.env
    • repos.txt

The name does not matter. dotkit.env, git.env, and .env are all read, sorted within each directory. The walk stops at the kit root, at your home directory, and at /.

This holds however you enter. Running one leaf file on its own picks up exactly what it would get as part of a full run:

dotkit run work/git/repos.txt   # still sees dotkit.env and git.env

Values already in your shell are the outermost layer. Write ${DEV_DIR:=~/dev} when you want the environment to win over the file.

Tip

A variable used by one file does not need an .env file at all. Set it in a block above:

DEV_DIR=~/dev
---
map [ -d $DEV_DIR/{{item}} ] || gh repo clone {{item}} $DEV_DIR/{{item}}

shabados/api

Several kits in one repo

One kit per context, selected at bootstrap or by path:

• Directorydotkit/

  • Directorypersonal/

    • personal.dotkit
  • Directorywork/

    • work.dotkit
  • Directoryserver/

    • server.dotkit

The installer finds every *.dotkit up to three levels deep and offers them by name. See Install.

Nesting works because dotkit run on a directory resolves that directory’s kit. A top-level target can run several:

map dotkit run {{item}}

personal
work

Listing targets

dotkit run --list .

/home/you/dotkit
  mac
  fedora