My Dot Files

Prerequisites

• A terminal emulator, if not using the OS-native one, e.g. Ghostty or iTerm2.
• curl to fetch the chezmoi installer itself and run several of the installation scripts. Already present on stock macOS; but not on a minimal/server Ubuntu image, install it using: sudo apt-get update && sudo apt-get install -y curl.
• Homebrew, on macOS (brew.sh) to run the bootstrap command below. Homebrew's own installer may prompt for Xcode Command Line Tools if they're missing.
• An apt-based Linux distro, on Linux — Ubuntu/Debian. The installer only supports apt; other package managers aren't handled.

Installation

On a fresh machine, bootstrap everything: dotfiles, CLI/terminal packages, and mise-managed runtimes, with chezmoi:

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply aramirez-es/mydotfiles

You'll be prompted once for your git commit email and GPG signing key; the answers are cached, so later runs don't ask again.

This installs packages from Aptfile (Ubuntu/apt) or Brewfile (macOS/Homebrew, auto-detected), places dotfiles into $HOME, installs mise, and creates an empty ~/code directory. Re-running chezmoi apply is idempotent and only reinstalls packages or tools when their source file actually changes.

Two things it does not do:

• Set zsh as default login shell. Run this once per machine:

  chsh -s "$(command -v zsh)"

• Provision a GPG signing key. chezmoi init only records the key ID (into ~/.gitconfig, via the signingkey prompt) but it doesn't have the actual private key to install. Import it yourself (from password manager) or create one before signing commits.

Making changes

chezmoi init --apply aramirez-es/mydotfiles is only for bootstrapping a fresh machine: it clones this repo into chezmoi's own source directory (~/.local/share/chezmoi by default) and applies it from there.

If day-to-day development happens on a regular clone of this repo (e.g. ~/code/mydotfiles), edited and committed like any other project, to try out local edits on the machine without a push/pull round trip, point chezmoi at that clone explicitly:

chezmoi apply --source ~/code/mydotfiles

chezmoi diff --source ~/code/mydotfiles previews changes the same way before applying them. Once changes are pushed, chezmoi update (or a fresh chezmoi init --apply) picks them up from the remote as usual.

Extension points

Machine-specific files that aren't managed by chezmoi (therefore not present in this repo) but are picked up automatically if present. Create them by hand on a given machine when needed; nothing breaks if they're absent:

• $HOME/.personal-env.sh: sourced by dot_zshrc, if present. Environment variables and exports that shouldn't be public.
• ~/.claude/stack.md: read by home/dot_claude/CLAUDE.md's <stack> section if present.

Generic files that can be used for feature extension still versioned in this repo:

• $HOME/.config/zsh/functions.zsh: sourced by dot_zshrc if present. Personal or work-specific zsh functions and aliases that don't belong in the public dotfiles.

Testing

./tests/run.sh

This runs shellcheck on rendered scripts and ensures templates render correctly.

For a full bootstrap validation in a throwaway Docker container:

./tests/e2e-docker.sh

This exercises the complete .chezmoiroot-based bootstrap workflow.