Skip to content

Operations

Core workflows for keeping your dotfiles running across platforms.

Platforms

macOS

Primary manager: Homebrew

  • Update:
chezmoi update

This runs brew bundle install behind the scenes to reconcile against the declared Brewfiles. - Permission issues: sudo chown -R $(whoami) $(brew --prefix)/* - Drift: Run brew bundle cleanup to remove unmanaged packages.

Linux (Debian, Ubuntu, Kali)

Primary manager: apt-get / snap

  • Update:
sudo apt update && sudo apt upgrade -y
chezmoi update

On Linux, chezmoi focuses on configuration. Package updates work best through the OS package manager to avoid sudo conflicts. - Font issues: If icons are missing, run ./install/provision/run_onchange_50-install-fonts.sh.tmpl manually via chezmoi apply or source directly with bash.

Windows (WSL2)

Primary manager: apt-get (inside WSL)

  • Update: Same as Linux.
  • Clipboard: Dotfiles configures win32yank.exe automatically for clipboard sharing.
  • Performance: Keep project files inside the Linux filesystem (~/projects), not in /mnt/c/, for dramatically better IO.

Workflows

Apply changes

After editing any config file:

dot apply

Triggers dot_zshrc reload and audit logging.

git pull
DOTFILES_NONINTERACTIVE=1 dot apply --force
dot doctor

dot apply includes post-apply checks that:

  • Remove stale read-only zsh cache files (~/.config/shell/*.zwc, ~/.config/zsh/**/*.zwc)
  • Validate that dot resolves to ~/.local/bin/dot in a fresh login shell

Finish by reloading your session (exec zsh) or restarting the terminal.

Async updates

Run updates in the background; you'll get a status banner on the next shell launch:

dot update --async

Roll back

If an update breaks your setup:

cd ~/.dotfiles
git reset --hard HEAD@{1}
chezmoi apply

Offline / air-gapped mode

# 1. On a connected machine, bundle your setup:
dot bundle ~/Downloads

# 2. Transfer the archive to the offline machine, then:
tar --zstd -xf dotfiles_offline_bundle_*.tar.zst -P
cd ~/.dotfiles
./install.sh --force

Pre-warm caches

Regenerate all tool caches to eliminate shell startup latency:

dot prewarm

Debug

If something's slow or broken:

  1. Check health:
dot doctor
dot health --fix
  1. Smoke test:
dot smoke-test
  1. Scorecard:
dot scorecard
  1. Chaos testing (self-healing):
dot chaos --force
dot heal --force
  1. Startup profiling:
dot perf --profile
  1. Post-merge verification:
dot verify
  1. Inspect alias behavior:
dot aliases list
dot aliases why dprune
DOTFILES_ALIAS_POLICY=strict bash ~/.dotfiles/scripts/diagnostics/alias-governance.sh
  1. Verbose mode:
DOTFILES_DEBUG=1 dot apply

Safety flags

Destructive aliases are disabled by default. Enable only when needed:

export DOTFILES_ENABLE_DANGEROUS_ALIASES=1

Tiered alias loading

Core aliases load eagerly. Ecosystem aliases are lazy-loaded and can be filtered:

export DOTFILES_ALIAS_ECOSYSTEMS=python,node

Valid ecosystem tags: python, node, rust, network, legacy.