A declarative dotfiles manager like chezmoi allows you to securely manage personal configurations across multiple workstations. Here is a practical quick-start setup and cheat sheet for daily operations.

🛠️ Initialization & Prerequisites

If Homebrew is not installed yet on your system, bootstrap it first:

cd $HOME
git clone https://github.com/Homebrew/brew homebrew
curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew
export PATH=$HOME/homebrew/bin:$PATH

[!NOTE] Configure your HOMEBREW_PREFIX if it differs from ~/homebrew or /opt/homebrew. Best practice is to set HOMEBREW_PREFIX=~/homebrew.

Next, install Xcode command line tools and the core utility package:

xcode-select --install

# Install minimum environment tools
export HOMEBREW_CASK_OPTS="--appdir=~/Applications"
brew install -q \
    jq yq curl wget coreutils diffutils findutils gawk gnu-sed gnu-tar rsync make just age chezmoi nnn gopass

Initialize your personalized dotfiles repository:

chezmoi init --exclude encrypted \
  --ssh --guess-repo-url=false \
  -C ~/.config/chezmoi/chezmoi.toml \
  git@git.apealive.net:epcim/dotfiles.git

# Apply the configurations
chezmoi apply -v

🚀 Daily Operations Reference

Syncing & Diffing

# Preview differences before applying
chezmoi diff

# Apply changes to your local home directory
chezmoi apply -v

# Single command to pull, diff, and update
chezmoi update

# Sync shared updates from git
chezmoi git pull -- --autostash --rebase && chezmoi diff

Adding New Managed Files

# Add a regular configuration file
chezmoi add ~/.config/opencode/opencode.jsonc

# Track a file and automatically follow symbolic links
chezmoi add --follow ~/.zshrc.f5

# Track a file as a template
chezmoi add --follow --template ~/.bashrc.$HOSTNAME

Interactive Editing

# Edit file directly in source state
chezmoi edit ~/.gitconfig.$HOSTNAME

# Watch and edit files interactively
chezmoi edit --watch ~/.config/fish/config.$HOSTNAME.fish

# Commit changes directly in the chezmoi source directory
chezmoi git status
chezmoi git add -A
chezmoi git commit -m "update dotfiles configuration"

Visualizing Divergent Configurations

To quickly find and check local differences using vimdiff:

chezmoi diff | grep 'diff --git' | sed -e 's,a/,~/,' -e 's,b/\.,dot_,' -e 's,b/,,' -e 's,diff --git,vimdiff,'

📖 Useful Resources