Testing¶

Ideally test changes in Docker containers before committing, but always before pushing to remote.

Quick Reference¶

Command	Purpose
`just maint test smoke local debian`	Run tests, then exit
`just maint test smoke debug-local bluefin`	Run setup, drop into shell
`just maint test smoke local-all`	Test all distros sequentially
`just dotfiles verify`	Check current machine's health

Workflow¶

Make changes to templates in the source directory
Run just maint test smoke debug-local <target> to test interactively
Inspect the container environment, verify configs are correct
Run just maint test smoke local-all before committing

Remote Testing¶

The *-local recipes mount your working tree into the container. There are equivalent *-repo recipes that clone from the git remote instead — use these to verify what has actually been pushed:

just maint test smoke repo debian      # Test from remote (main branch)

just maint test smoke repo-all          # Test all distros from remote

This is useful for confirming that a merge to main works as a fresh chezmoi init would.

Testing a Branch on a Live Machine¶

To apply dotfiles from a feature branch on a device that can't run Docker (e.g., a Mac without root):

chezmoi init codeberg.org/fungible --branch <branch-name> --apply

Alternatively,

sh -c "$(curl -fsLS get.chezmoi.io)" -- init codeberg.org/fungible --apply --branch <branch-name>

If chezmoi was already initialised, purge the existing state first:

Warning

chezmoi purge removes chezmoi's configuration, state, and source directory but leaves your deployed files intact. The subsequent chezmoi init --apply should be idempotent but there is always a risk of breaking your environment on a host. Safe in a container — be careful on a live machine.

chezmoi purge

Debugging¶

container-shell drops you into a clean base image with no dotfiles or chezmoi installed — just the bare OS, a user account, and bash. Useful for inspecting what the container looks like before chezmoi runs, or for manually stepping through the bootstrap:

just maint test smoke container-shell debian

Available Distros¶

debian — Debian Bookworm (default)
fedora — Fedora latest
bluefin — Bluefin LTS

macOS Testing¶

Docker smoke tests only cover Linux distros — macOS containers don't exist. A test user account on the same machine would work but requires root/sudo access. Without that, use a macOS VM via UTM or VirtualBuddy — both are installed by the Brewfile on macOS.

Smoke Test Approach¶

Smoke tests simulate a fresh-system bootstrap. The Dockerfile installs only bare minimum OS packages (curl, git, zsh, sudo) — everything else is installed by chezmoi's run_once scripts. Do not pre-install tools in the Dockerfile; that masks bugs.

Bluefin exception: Real Bluefin ships with Homebrew but the container image doesn't, so the Dockerfile installs it and runs ujust bluefin-cli to simulate the real user flow.

Dependency Management¶

External plugins (Zsh plugins, Fonts) are managed via .chezmoiexternals/externals.toml.tmpl.

Pinning Strategy¶

External dependencies are pinned to specific release tags where possible (e.g., v0.9.0) rather than tracking master. Some projects like Oh My Zsh don't publish releases, so those track master. Pinning prevents upstream breakage and keeps the setup reproducible across machines. Chezmoi rechecks externals weekly (refreshPeriod = "168h").

Updating Dependencies¶

Check what's outdated:
```
just dotfiles check-updates
```
This also runs automatically as part of just dotfiles update.
Edit .chezmoiexternals/externals.toml.tmpl with the new tag.
Apply and verify on your host:
```
chezmoi apply
```
```
just dotfiles verify
```
Commit, or rollback the tag if something broke.