English | 简体中文

My Dotfiles

These dotfiles configure my macOS development environment and stay in sync across my Macs with chezmoi. The repository also includes bootstrap scripts for setting up a new Mac.

This setup supports Apple Silicon Macs only; Intel Macs are not supported.

Some settings depend on my accounts, GPG keys, and filesystem layout. Adjust them for a different environment.

Project overview

Area	Start with
Agent tooling	dot_agents, dot_claude, dot_codex
Git	dot_config/git, .chezmoitemplates/git
Repository design	CONCEPTS.md
Packages and bootstrap	Brewfile, .chezmoiscripts
Shell and applications	dot_zshrc, dot_zsh, dot_config
chezmoi configuration and templates	.chezmoi.toml.tmpl, .chezmoitemplates

Set up a new Mac

A fresh macOS install ships git as a stub that only opens the Command Line Tools installer dialog and exits with an error, so chezmoi init cannot clone this repository yet. Open Terminal.app on the new Mac and install the tools first:

xcode-select --install

Wait for the installer window to finish, then confirm xcode-select -p and git --version both print something. Now run:

sh -c "$(curl -fsLS https://get.chezmoi.io)" -- -b "$(mktemp -d)" init --apply liby

This starts an interactive setup, not an unattended installation. Keep Terminal.app open to enter private template values, respond to sudo prompts, and use your YubiKey when needed.

The command installs chezmoi, clones this repository into ~/.local/share/chezmoi, runs the bootstrap scripts, and applies the managed files to $HOME. -b puts that first binary in a temporary directory instead of the bin directory the install script creates in the working directory, which in Terminal.app is ~/bin: Brewfile installs the chezmoi every later command should use, and .zshrc puts ~/bin ahead of Homebrew on PATH, where a leftover copy would shadow it and never update.

A bootstrap script that fails stops the apply. Run the same one-liner again to continue; it reinstalls chezmoi into a new temporary directory and picks up where the failed run left off.

If chezmoi is already installed, run:

chezmoi init --apply liby

Common operations

chezmoi status                     # Show configuration status
chezmoi diff <target>              # Inspect changes to one configuration file
chezmoi apply                      # Apply configuration to $HOME
chezmoi edit <target>              # Edit a managed encrypted file
chezmoi edit-encrypted <filename>  # Edit an encrypted file not managed by chezmoi

Editing encrypted files requires a YubiKey and should not be delegated to an agent.

See chezmoi's daily operations guide for other commands.

Updating existing machines

When updating an existing Mac or merging upstream into a fork, review commits since the version last applied on that machine for retired paths and fields. Check their current contents before removing them, keeping any local changes you still need. Applying the new source does not clean up all retired configuration, even when chezmoi status is empty.

Reuse

Fork this repository and adapt it to your environment, or copy only the parts you need. Before applying the full setup, review and adjust .chezmoi.toml.tmpl, Brewfile, and .chezmoiscripts/.

Contributing

Before changing this repository, read AGENTS.md for repository-specific workflows, safety boundaries, and validation rules. Open an issue to report a problem or a pull request to propose a change.