New-machine workflows

A normal macOS or Linux machine

Clone the repository to the intended durable location and use the local script. This makes it easy to inspect the revision, preserve a working tree, and retry from the same source.

git clone https://github.com/cadebrown/dotfiles "$HOME/dotfiles"
cd "$HOME/dotfiles"
DF_NAME='Your Name' DF_EMAIL='[email protected]' ./bootstrap.sh

The local script records the repository as chezmoi’s source directory after applying its managed files (source). Linux installation is designed to be rootless; OS packages that require sudo are outside this lifecycle. On macOS, Homebrew casks may still trigger their own platform prompts.

After completion, open a fresh login shell and exercise only what was selected:

exec zsh -l
bash ~/dotfiles/install/verify-tools.sh
chezmoi diff

NFS home with local scratch

Use platform isolation only when the same home is mounted by machines with different CPU architectures. Put the large runtime state on a stable local disk before bootstrap, then ask the installer to resolve ~/.local through it:

mkdir -p "/local/$USER"
DF_SCRATCH="/local/$USER" DF_USE_PLAT=1 ./bootstrap.sh

Scratch redirection is intentionally conservative: it verifies copied entries before replacing the source directory (source). Do not point it at ephemeral tmpfs storage unless loss after reboot is acceptable; the script warns when it detects that filesystem type (source).

Update routine

Use update for the normal reconciliation path and upgrade when deliberately accepting managed runtime upgrades. upgrade can surface version or upstream configuration changes, so keep its output and resolve its final audit rather than treating it as a background refresh. See updates and platform isolation for the detailed limits.