dotfiles/README.md

New Mac Setup

Step-by-step guide to reproduce the terminal environment on a fresh macOS machine.

1. Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the post-install instructions to add Homebrew to your PATH (it will tell you to run two commands involving /opt/homebrew).

2. Clone this repo

git clone https://git.kestrelsnest.social/eric/dotfiles.git ~/dotfiles

3. Install Homebrew packages

cd ~/dotfiles
brew bundle

This installs all CLI tools, language version managers, databases, fonts, and casks.

If any formulae fail, you can skip them — they may not be needed on the new machine.

Managed work laptops: Some casks require admin rights and will fail if your account is restricted by MDM. Request these through your company's IT or self-service portal:

• Docker Desktop (docker)
• GPG Suite (gpg-suite)
• Cursor (cursor)
• iTerm2 (iterm2)
• ngrok (ngrok)

The shell configs guard against missing Docker, so everything else will still work.

4. Install Oh My Zsh

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Important: When the installer asks to set zsh as your default shell, say yes. It will also create a default .zshrc — that's fine, the install script in step 6 will replace it.

5. Install Oh My Zsh custom plugins and theme

# Powerlevel10k theme
git clone https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

# zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

6. Install NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

After install, open a new terminal or source ~/.zshenv, then:

nvm install --lts
nvm alias default node

7. Symlink dotfiles

cd ~/dotfiles
./install.sh

This creates symlinks from ~/.zshrc, ~/.gitconfig, etc. into this repo. Existing files are backed up with a .backup.* suffix.

8. Set up fzf key bindings

$(brew --prefix)/opt/fzf/install

Say yes to key bindings and completion, no to updating shell config files (the dotfiles already handle that).

9. Reload your shell

source ~/.zshrc

Or just open a new terminal window.

10. Optional: Reconfigure Powerlevel10k

The existing .p10k.zsh config is included, but if you want to run the wizard fresh:

p10k configure

Current config: classic powerline, unicode, light, 12h time, angled separators, sharp heads, flat tails, 1 line, sparse, fluent, transient prompt.

11. Install iTerm2 shell integration (if using iTerm2)

curl -L https://iterm2.com/shell_integration/zsh -o ~/.iterm2_shell_integration.zsh

12. Set your terminal font

The Brewfile installs MesloLGS NF (Nerd Font). Set this as your terminal font:

• iTerm2: Preferences > Profiles > Text > Font > MesloLGS NF
• Terminal.app: Preferences > Profiles > Font > Change > MesloLGS NF

13. Optional: Natera / work machine setup

On Natera machines, the main zshrc automatically sources ~/dotfiles/zshrc-natera if that file exists. That file adds work-specific aliases, Claude/Bedrock and OTEL env vars, and a refresh command for SSO + tunnel.

To enable the parts that use sensitive values (AWS profile, OTEL endpoint, Netskope cert paths, tunnel details), create a private config file that is gitignored and never committed:

cp ~/dotfiles/zshrc-natera.private.example ~/dotfiles/zshrc-natera.private

Edit zshrc-natera.private and replace the placeholders with your real values. zshrc-natera sources this file when present.

14. Set up work git identity

The .gitconfig uses your personal email by default. For work repos, create ~/.gitconfig-work:

cat > ~/.gitconfig-work << 'EOF'
[user]
    email = your-work-email@company.com
EOF

Any repos cloned under ~/work/ will automatically use your work email. Clone personal projects elsewhere.

15. Language version managers

The dotfiles configure these version managers — install runtimes as needed:

# Python (via pyenv)
pyenv install 3.13.3
pyenv global 3.13.3

# Node (via nvm, done in step 6)
# Terraform (via tfenv)
tfenv install latest

Custom git commands

The bin/ directory contains custom git subcommands that are symlinked into ~/bin by the install script. Make sure ~/bin is on your PATH (the dotfiles handle this).

Command	Description
git branch-backup	Create a timestamped backup branch of the current branch
git fix-author	Rewrite commit author/email on historical commits
git name-stash <name>	Stash changes with a named message
git name-stash-apply <name>	Apply a stash by name
git rebase-on <branch>	Back up current branch, then pull and rebase onto the given branch
git rename-branch <old> <new>	Rename a branch locally and on the remote

What's included

File	Purpose
zshrc	Main zsh config: plugins, aliases, key bindings; sources zshrc-dev and zshrc-natera when present
zshrc-dev	Developer enhancements (optional): rg wrapper, git helpers, project helpers
zshrc-natera	Natera-specific config (optional): work aliases, Claude/Bedrock, OTEL; sources zshrc-natera.private when present
zshrc-natera.private.example	Template for sensitive Natera values; copy to zshrc-natera.private and fill in (gitignored)
zshenv	PATH and version manager init (runs for all shell types)
p10k.zsh	Powerlevel10k prompt theme config
bashrc	Bash config (NVM, Docker, fzf)
bash_profile	Bash login shell (rbenv, Docker)
profile	Generic shell profile
gitconfig	Git aliases, colors, push config
gitignore_global	Global gitignore (.DS_Store, *~)
fzf.zsh	fzf PATH and shell integration
bin/git-*	Custom git subcommands (see above)
Brewfile	All Homebrew packages and casks
install.sh	Symlink installer script