Dotfiles

Personal and work machine configuration managed with chezmoi. The repository defines shell configuration, developer tools, language runtimes, credentials-backed files, applications, and selected system preferences.

The shared configuration supports macOS and Linux. Automated package and application installation and system configuration target Apple Silicon macOS and assume Homebrew is installed at /opt/homebrew. Linux prerequisites and software installation remain outside chezmoi.

See CONTRIBUTING.md before changing the repository.

How it works

• chezmoi renders the source files under home/ into their locations in the home directory.
• Homebrew installs macOS command-line tools, applications, fonts, and Mac App Store applications from a generated Brewfile.
• mise provides the Node.js and Python versions used from the shell.
• uv manages Python projects while using mise-provided Python runtimes.
• 1Password CLI supplies profile-specific secret values and generated SSH host configuration. On personal machines it also supplies the personal GPG key. Private SSH keys remain in the 1Password SSH agent. Secrets are not stored in this repository.
• macOS lifecycle scripts install supporting tools, configure the login shell, and apply selected defaults and security settings.

On macOS, a full chezmoi apply can install software, request administrator privileges, change system preferences, and restart affected services. It is more than a file-copy operation.

Machine configuration

During initialization, home/.chezmoi.toml.tmpl prompts once for:

• a personal or work package profile;
• whether the machine is headless;
• the active profile's email address;
• on work, the public key used for SSH commit and tag signing;
• a 1Password account and the reference to one low-privilege GitHub API PAT for public-data readers and rate-limit elevation.

The answers are stored in chezmoi's machine-local configuration, not in the repository. Prompt for them again with:

chezmoi init --prompt

See MACHINE-PROFILES.md for the profile boundaries, credential rules, Git safeguards, platform policy, and validation principles.

The selected profile supplies the default Git identity and signing method globally: personal uses GPG and work uses an SSH key held by 1Password. SSH authentication is selected separately by SSH host configuration and 1Password Bookmarks. Repositories under ~/Code/reference/, the opposite profile's ~/Code/ tree, and the chezmoi source on work receive an empty identity guard.

Organize repositories by trust profile and then forge, for example ~/Code/personal/github.com/owner/repository, ~/Code/work/gitlab.com/group/repository, and ~/Code/reference/codeberg.org/owner/repository. Forge directories organize repositories; they do not select identity or credentials.

Repository layout

Path	Purpose
home/	Source state rendered into the home directory
home/.chezmoiscripts/darwin/	macOS bootstrap and configuration hooks
home/.chezmoitemplates/homebrew/	Common and profile-specific Homebrew packages
home/.chezmoidata/	Declarative data such as required Pi packages
scripts/lint-shell.sh	ShellCheck and shfmt validation for scripts and rendered templates
export-checklist.md	Manual application data to migrate between Macs

chezmoi filename conventions describe the target and its permissions. For example, private_dot_config/private_git/config.tmpl renders as ~/.config/git/config, with private permissions and template expansion.

Bootstrap

Install the chezmoi binary in ~/.local/bin with the official installer:

sh -c "$(curl -fsLS https://get.chezmoi.io)" -- -b "$HOME/.local/bin"

On Apple Silicon macOS, install the remaining prerequisites:

brew install --cask 1password 1password-cli

On Linux, install the native 1Password application and CLI using the distribution's supported method. The work profile additionally requires Git 2.34 or newer, compatible OpenSSH signing support, and the 1Password SSH agent. The personal profile requires GnuPG. Chezmoi does not install these Linux prerequisites.

The dotfiles add ~/.local/bin to PATH, but they have not been applied yet. Use the binary's full path during the bootstrap.

Before initializing chezmoi, open the 1Password desktop app and configure its developer settings:

1. Turn on the 1Password Developer experience.
2. Enable the 1Password SSH Agent.
3. Enable CLI integration with the desktop app.
4. Under the SSH Agent's advanced settings, enable Generate SSH config files from 1Password SSH bookmarks.
5. Ensure the active profile's SSH keys are available to the agent. Add ssh://user@host URLs to keys that should be associated with specific SSH hosts.

The SSH-config setting creates ~/.ssh/1Password/config and the public-key files referenced by this repository's generated SSH host configuration. Private keys remain in 1Password. If a setting is marked as managed, ask the work administrator whether it can be enabled. See 1Password's SSH Bookmarks documentation for the current interface and behavior.

Authenticate the CLI from an interactive terminal:

op signin

Initialize the repository without applying it immediately:

~/.local/bin/chezmoi --verbose init \
  https://github.com/jeromegamez/dotfiles.git

Review the changes before applying them:

~/.local/bin/chezmoi --verbose diff
~/.local/bin/chezmoi --verbose apply --dry-run

Rendered previews can contain values obtained from 1Password. Treat their output as sensitive and do not save or share it indiscriminately.

Apply the complete configuration from an interactive terminal:

~/.local/bin/chezmoi --verbose apply

On macOS, some hooks may request confirmation, administrator access, or a login-shell change. Open a new terminal after the bootstrap completes.

Exclude source code from Spotlight

After ~/Code exists, exclude it once on each Mac through System Settings -> Spotlight -> Search Privacy. Click the add button and select ~/Code.

macOS does not provide a supported command-line interface for excluding an individual folder. mdutil manages complete Spotlight volumes, so it must not be used to disable indexing for ~/Code. A .metadata_never_index marker inside an ordinary directory also does not exclude that directory on macOS Tahoe. See Apple's Spotlight Search Privacy instructions.

Tool ownership

The standalone installer owns chezmoi. Homebrew owns applications, including the ChatGPT desktop app, and general command-line tools. mise owns the Codex CLI as well as the Node.js and Python runtimes selected by the shell. Homebrew may retain its own Node.js and Python copies as dependencies of other formulae.

The default mise runtimes are declared in home/private_dot_config/private_mise/config.toml.tmpl. Pi is installed under ~/.local/share/pi and its launcher always executes it with Node.js 25. Required rolling Pi packages are listed in home/.chezmoidata/pi.yaml; other mutable Pi settings remain unmanaged. Bootstrap installs missing components but does not upgrade an existing Pi installation or package. Pi and its required packages are intentionally unpinned; pi update --all is the explicit approval boundary for rolling upgrades.

The main Pi bootstrap explicitly disables npm's release-age delay. Required package installs and updates use Pi's configured npm command and may inherit the user's npm release-age policy. Chezmoi apply does not perform routine Pi upgrades.

Maintenance

Edit source files through chezmoi rather than changing generated targets directly:

chezmoi edit --apply ~/.config/zsh/.zshrc

Pull and apply the latest committed source state on another machine:

chezmoi --verbose update

To review an update before applying it, pull the source state first and then inspect the resulting changes:

chezmoi --verbose update --apply=false
chezmoi --verbose diff
chezmoi --verbose apply --dry-run
chezmoi --verbose apply

Useful maintenance commands:

brew-maintenance         # update Homebrew and installed packages
mise upgrade             # update mise-managed runtimes
gcloud components update # update Google Cloud CLI and its components
pi update --all          # update Pi and its packages using Node.js 25
./scripts/lint-shell.sh

Install a Pi package for local evaluation with pi install npm:package-name. Add it to home/.chezmoidata/pi.yaml when it should be installed on every managed Mac.

Use export-checklist.md for application data that cannot be reproduced automatically.