Mac Setup Guide
A Developer's Playbook

How to Fork & Customize This Guide

This is a community guide — fork it, modify it, and make it your own:

1. Clone or fork the repository containing these files
2. Update the hero section with your name and machine details
3. Customize the Brewfile to include your preferred tools and apps
4. Modify the PARA structure to match your project organization
5. Adjust macOS defaults in the .macos script to your preferences
6. Share your version — your customizations might help others!

PARA Folder Structure

Everything lives under ~/Desktop/workshop/ using the PARA method.

~/Desktop/workshop/
├── 01_projects/      # Active, time-bound work
├── 02_areas/         # Ongoing responsibilities
├── 03_resources/     # Reference material & configs
│   ├── dotfiles/     # Symlinked config files
│   ├── mac-setup/    # Setup scripts (personal + public)
│   └── ...
└── 04_archive/       # Completed / inactive

Migration Pipeline

Dotfile Symlink Flow

link.sh creates symlinks from your home directory back to the repo:

~/.zshrc           → ~/Desktop/workshop/03_resources/dotfiles/.zshrc
~/.gitconfig       → ~/Desktop/workshop/03_resources/dotfiles/.gitconfig
~/.gitignore_global → ~/Desktop/workshop/03_resources/dotfiles/.gitignore_global
~/.editorconfig    → ~/Desktop/workshop/03_resources/dotfiles/.editorconfig
~/.config/starship.toml → .../dotfiles/starship.toml

Run on the Old Machine

The pre-migrate.sh script exports everything you'll need. Run it before wiping or shelving the old machine.

chmod +x backup.sh && ./backup.sh

It performs 9 steps:

Steps 1–4 of mac-setup.sh

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

# 3. Create PARA folder structure
mkdir -p ~/Desktop/workshop/{01_projects,02_areas,03_resources,04_archive}

# 4. Install Brewfile packages
brew bundle --file=./Brewfile

Brewfile Categories

Steps 5–6: Dotfiles & Runtimes

# 5. Symlink dotfiles
cd ~/Desktop/workshop/03_resources/dotfiles && chmod +x link.sh && ./link.sh

# 6. Install runtimes via Mise
mise use --global node@20
mise use --global python@3.12

link.sh handles all symlinks to your dotfiles, keeping your configs in version control and easy to maintain.

Git Configuration

The symlinked .gitconfig includes:

• push.autoSetupRemote = true — no more --set-upstream
• pull.rebase = true — clean linear history
• core.pager = bat — syntax-highlighted diffs
• core.excludesFile = ~/.gitignore_global — system-wide ignores
• 20+ aliases: git st, git lg, git sync, etc.

Global Gitignore

.gitignore_global covers OS files, editor artifacts, secrets, and project-specific temp files:

.DS_Store
.env, .env.local
node_modules/, __pycache__/
.idea/, .vscode/settings.json
*.tmp, *.bak          # Project-specific temp files
credentials/, secrets/
*.pem, *.key

EditorConfig

.editorconfig ensures consistent formatting across all editors:

Steps 7–9: macOS Defaults, SSH, Apps

# 7. Apply macOS defaults (90+ settings)
chmod +x .macos && ./.macos

# 8. Generate SSH key
ssh-keygen -t ed25519 -C "you@example.com"
eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519
gh ssh-key add ~/.ssh/id_ed25519.pub

# 9. Install GUI apps (manual)
# VS Code, Raycast, WezTerm, CleanShot X, Figma, etc.

Manual App Setup

• Raycast — import settings from backup
• VS Code — Settings Sync via GitHub account
• CleanShot X — Setapp or license, configure screenshot folder

Steps 10–12: Automation & Verification

# 10. Set up folder actions (interactive)
./folder-actions.sh setup

# 11. Complete setup verification
chmod +x verify.sh && ./verify.sh

# 12. Run verification
chmod +x verify.sh && ./verify.sh

90+ System Settings via .macos

Based on Mathias Bynens' dotfiles and webpro's collection, curated for music production and development. Organized into 16 categories:

Shell Environment

Customize your shell with a .zshrc, aliases, and functions:

# Essential aliases for development
alias ll='ls -lah'
alias gs='git status'
alias gc='git commit'
alias gp='git push'
alias np='npm'
alias py='python3'
alias reload='exec zsh'

Prompt & Theme

Install Oh My Zsh or Starship for a modern prompt experience. Both are included in the Brewfile.

• Oh My Zsh — Framework with plugins (git, node, npm, etc.)
• Starship — Fast, minimal, language-aware prompt
• Nerd Fonts — Install for icon support (already in Brewfile)

Key Bindings & Plugins

Keyboard Shortcuts

macOS Keyboard Shortcuts can automate common tasks. Set these up in System Settings > Keyboard > Shortcuts:

• Open Terminal in current Finder directory
• Quick screenshot to file
• Toggle dark mode
• Launch favorite apps with custom shortcuts

Scripting & Automation

Create shell scripts in ~/bin for repeated tasks:

# Example: backup-projects.sh
#!/bin/bash
tar -czf ~/backups/projects-$(date +%Y%m%d).tar.gz ~/Projects/
echo "Backup complete"

Launchd for Scheduled Tasks

Use launchd to run scripts on a schedule:

• Daily syncs or backups
• Periodic cleanup tasks
• Scheduled deployments
• Reference: ~/Library/LaunchAgents

Shell Aliases & Git Shortcuts

fzf Keybindings

Common Issues

Post-Setup Verification

Run verify.sh after completing the setup to check everything is working. It tests 10 categories:

chmod +x verify.sh && ./verify.sh

Quick Health Check

# One-liner to check the essentials
command -v brew && command -v git && command -v starship && \
  test -L ~/.zshrc && test -L ~/.gitconfig && \
  echo "✓ Core setup OK" || echo "✗ Something's missing"