.dotfiles

Operations

Operations

Core workflows for keeping your dotfiles running across platforms.

Platforms

macOS

Primary manager: Homebrew

  • Update:

    chezmoi update

    This pulls and applies the configuration only; it does not run brew bundle. To reconcile packages against the declared Brewfiles, run brew bundle --file ~/.config/shell/Brewfile.cli or bash ~/.dotfiles/install.sh --provision.

  • 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 dot theme font install, or bash ~/.dotfiles/install/provision/run_onchange_50-install-fonts.sh directly (chezmoi apply never runs install/provision/).

Windows (WSL2)

Primary manager: apt-get (inside WSL)

  • Update: Same as Linux.
  • 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 config 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 config export ~/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 shell update --prewarm

Debug

If something's slow or broken:

  1. Check health:

    dot doctor
dot doctor status --fix

  2. Smoke test:

    bash scripts/diagnostics/smoke-test.sh

  3. Scorecard:

    dot doctor score show

  4. Chaos testing (self-healing):

    bash scripts/ops/chaos.sh --force
dot doctor fix --force

  5. Startup profiling:

    dot doctor perf show --profile

  6. Post-merge verification:

    bash scripts/diagnostics/verify.sh

    Runs the doctor, status and diff checks and exits non-zero on issues.

  7. Inspect alias behavior:

    dot shell alias list
dot shell alias show dps
DOTFILES_ALIAS_POLICY=strict bash ~/.dotfiles/scripts/diagnostics/alias-governance.sh

  8. Verbose mode:

    DOTFILES_DEBUG=1 zsh -i -c exit   # zsh startup timings, per stage

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.