dotfiles/README.md

# New Mac Setup

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

## 1. Install Homebrew

```bash
/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

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

## 3. Install Homebrew packages

```bash
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

```bash
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

```bash
# 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

```bash
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:

```bash
nvm install --lts
nvm alias default node
```

## 7. Symlink dotfiles

```bash
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

```bash
$(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

```bash
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:

```bash
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)

```bash
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:

```bash
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`:

```bash
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:

```bash
# 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 |

## Personalizing after cloning

A few files contain personal values you'll want to change:

- **`gitconfig`** — update `[user]` name, email, and `signingkey` with your own. If you don't use GPG commit signing, remove the `[commit] gpgsign = true` section and the `signingkey` line.
- **`zshrc`** — the `weather` alias defaults to Athens, GA. Change it to your city: `alias weather='curl wttr.in/YourCity'`

## 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 |