Dotfiles (chezmoi)

This repo manages personal/work dotfiles with chezmoi.

Fresh macOS Setup

Use this on a brand-new machine.

1. Install Xcode Command Line Tools.

xcode-select --install

2. Install Homebrew.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
if [ -x /opt/homebrew/bin/brew ]; then
  eval "$(/opt/homebrew/bin/brew shellenv)"
elif [ -x /usr/local/bin/brew ]; then
  eval "$(/usr/local/bin/brew shellenv)"
fi

3. Install base tooling used by these dotfiles.

brew install git chezmoi fish tmux neovim bat git-delta lazygit jq zoxide atuin pyenv fzf yt-dlp

4. Set Fish as the default shell.

which fish
grep -q "$(which fish)" /etc/shells || echo "$(which fish)" | sudo tee -a /etc/shells
chsh -s "$(which fish)"

5. Initialize chezmoi source and apply dotfiles.

chezmoi init <your-repo-url>

6. Set required chezmoi template data.

Create ~/.config/chezmoi/chezmoi.toml:

[data]
git_name = "Your Name"
git_email = "you@company.com"

7. Apply dotfiles.

chezmoi apply

8. Install Fisher and Fish plugins declared in .config/fish/fish_plugins.

Open a new Fish shell, then run:

curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source
fisher install (cat ~/.config/fish/fish_plugins)

9. Install tmux plugin manager (TPM) and tmux plugins.

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Then start tmux and press Ctrl-a then Shift-i (capital I) to install plugins. This config uses Ctrl-a as tmux prefix.

10. Bootstrap Neovim plugins.

nvim

lazy.nvim auto-installs on first launch. Quit and reopen once after install.

11. Optional app login/bootstrap.

• Atuin sync: atuin login
• Cursor and VS Code settings are already managed by chezmoi at:
  • ~/Library/Application Support/Cursor/User/settings.json
  • ~/Library/Application Support/Code/User/settings.json

Required chezmoi Data

dot_gitconfig.tmpl expects:

• git_name
• git_email

Optional machine-specific git overrides can go in:

• ~/.gitconfig.local

That file is included by generated ~/.gitconfig.

Daily chezmoi Workflow

# see drift
chezmoi status

# edit a managed file
chezmoi edit ~/.gitconfig

# apply source changes to target
chezmoi apply

# add a new file to source state
chezmoi add ~/.somefile

# stop managing a file
chezmoi forget ~/.somefile

Fish Policy

Do not commit machine-generated Fish files. This repo ignores:

• .config/fish/fish_variables
• .config/fish/config.fish-e

For ~/.config/fish/functions:

• Keep custom functions in repo.
• Do not vendor third-party plugin function files.
• Keep plugin declarations in .config/fish/fish_plugins.

Machine-Specific Notes

• SSH 1Password agent is configured conditionally in .ssh/config.
• IdentityAgent is applied only when the 1Password socket exists.
• This keeps SSH config portable across machines with and without 1Password.
• ForwardAgent yes is currently global in this repo. If you want tighter security, set it to no globally and enable per host.

Transferability Checklist

When adding new dotfiles, avoid:

• hardcoded usernames/paths (for example /Users/<name>)
• machine IDs or hardware serials unless intentional
• generated caches/history/session files
• lock/state artifacts generated by tools

If a file is machine-local:

• keep it out of source state with chezmoi forget, or
• template/guard machine-specific sections.