Skip to content

getting-started.md

Latest commit

 

History

History
188 lines (137 loc) · 4.22 KB

getting-started.md

File metadata and controls

188 lines (137 loc) · 4.22 KB

Getting Started

This guide will walk you through setting up your macOS development environment.

Prerequisites

  • macOS: Sequoia 15.5+ (optimized for Apple Silicon)
  • Admin Access: Required for installing some tools
  • Internet Connection: For downloading packages
  • Xcode Command Line Tools: Required for git, compilers, and dev tools
  • Time: ~15-30 minutes for full setup

Installing Xcode Command Line Tools

If not already installed, run:

xcode-select --install

This provides essential development tools including git, make, gcc, and more.

Installation Steps

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/macbook-dev-setup.git
cd macbook-dev-setup

2. Preview Installation (Recommended)

See what will be installed without making changes:

./setup.sh preview

3. Run Setup

# Standard installation
./setup.sh

# Minimal installation (essential tools only)
./setup.sh minimal

# Fix common issues automatically
./setup.sh fix

# Configure Warp terminal optimizations
./setup.sh warp

# View backup management options
./setup.sh backup

# Power user options (environment variables)
SETUP_VERBOSE=1 ./setup.sh        # Verbose output
SETUP_JOBS=8 ./setup.sh           # Custom parallel jobs
SETUP_LOG=setup.log ./setup.sh    # Log to file
SETUP_NO_WARP=true ./setup.sh     # Skip Warp detection

4. Reload Your Shell

After setup completes, reload your shell configuration:

# Option 1: Source the config (quickest)
source ~/.zshrc

# Option 2: Start a new shell
exec zsh

# Option 3: Close and reopen your terminal (cleanest)

Post-Installation Setup

Required Configuration

  1. Git Configuration

    git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

  2. Claude CLI Authentication

    claude setup-token

Optional Configuration

  1. SSH Keys for GitHub

    ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Copy public key to GitHub
pbcopy < ~/.ssh/id_ed25519.pub

  2. VS Code Settings Sync

    • Sign in to GitHub in VS Code
    • Enable Settings Sync

  3. Node.js Version

    # Install specific Node version
nvm install 20
nvm use 20
nvm alias default 20

Verify Installation

Run the health check to ensure everything is properly installed:

./scripts/health-check.sh

Expected output:

  • ✅ for properly installed tools
  • ❌ for missing tools (with fix suggestions)
  • Health score percentage

Common Issues

Command Not Found

If commands aren't found after installation:

  1. Ensure you've reloaded your shell
  2. Check that /opt/homebrew/bin is in your PATH
  3. Run brew doctor for diagnostics

Permission Errors

Some installations may require admin access:

sudo ./setup.sh  # Not recommended
# Better: Fix specific permission issues as they arise

Slow Installation

To speed up installation:

  • Use --minimal flag for essential tools only
  • Close other applications to free up resources
  • Ensure stable internet connection

Next Steps

Quick Reference

Command Description
./setup.sh Run standard setup
./setup.sh preview Preview what will be installed
./setup.sh minimal Install essential tools only
./setup.sh fix Run diagnostics and fix issues
./setup.sh warp Configure Warp terminal
./setup.sh backup Manage backups
./setup.sh backup clean Remove old backups
./setup.sh help Show help message
./scripts/health-check.sh Verify installation
./scripts/update.sh Update all tools
./scripts/pre-push-check.sh Pre-commit validation

For Contributors

Set up git hooks for conventional commits:

./scripts/setup-git-hooks.sh

This enables:

  • Commit message validation
  • Git commit template
  • Interactive commit helper (./scripts/commit-helper.sh)

See Commit Guide for details.