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.

Upgrade-safe apply (recommended)

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:

Check health:
```
dot doctor
dot health --fix
```
Smoke test:
```
dot smoke-test
```
Scorecard:
```
dot scorecard
```
Chaos testing (self-healing):
```
dot chaos --force
dot heal --force
```
Startup profiling:
```
dot perf --profile
```
Post-merge verification:
```
dot verify
```

Inspect alias behavior:

dot aliases list
dot aliases why dprune
DOTFILES_ALIAS_POLICY=strict bash ~/.dotfiles/scripts/diagnostics/alias-governance.sh

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.