Skip to content

setup-osx.md

Latest commit

 

History

History
167 lines (116 loc) · 3.21 KB

setup-osx.md

File metadata and controls

167 lines (116 loc) · 3.21 KB

Setting Up Dotfiles on macOS

Prerequisites

  1. Clone the repository:

    cd ~
git clone <your-repo-url> .dotfiles
cd .dotfiles

  2. Install stow (for symlinking dotfiles):

    brew install stow

Setup Steps

1. Install Packages

Run the unified setup script (auto-detects macOS and runs the appropriate installer):

# Preview what will be installed (dry run)
DRY_RUN=true ./setup.sh

# Check current package status
./setup.sh check

# Validate package configuration
./setup.sh validate

# List all packages
./setup.sh list

# Run the installation
./setup.sh

setup.sh script automatically detects macOS and runs scripts/setup-osx.sh. You can also run the macOS script directly if needed.

The script automatically installs Homebrew (if needed) and all required packages.

2. Symlink Dotfiles

Use the OS-aware stow script to create symlinks (automatically stows only relevant packages for macOS):

# Stow all dotfiles (auto-detects OS and only stows relevant packages)
./stow-dotfiles.sh

# Stow without adopting existing files (use if starting fresh)
./stow-dotfiles.sh ""

The script automatically stows common and macOS-specific packages. Note: The nix/ folder is not stowed automatically.

Verify symlinks:

ls -la ~ | grep "\->"

3. Configure Shell Environment

Add to your ~/.zshrc:

# NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Pyenv
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"

# Mise
eval "$(mise activate zsh)"

# Rust
source "$HOME/.cargo/env"

Reload your shell:

source ~/.zshrc

4. Post-Installation (Optional)

Neovim plugins (if using LazyVim):

nvim --headless -c "Lazy sync" -c "qa"

OrbStack (Docker alternative):

# Set the default docker context to orbstack
docker context use orbstack

About stow --adopt

The --adopt flag moves existing files into the package directory and replaces them with symlinks. Always use dry-run first:

stow --adopt -n <package>

Troubleshooting

  • Check distribution detection: ./setup.sh check
  • List packages: ./setup.sh list
  • Validate package config: ./setup.sh validate
  • Dry run setup: DRY_RUN=true ./setup.sh
  • Verify symlinks: ls -la ~ | grep "\->"

Notes

  • Homebrew will be installed automatically if missing
  • Some packages may require manual configuration after installation
  • Setup is based on mac.install.guide

zsh

## When each is loaded:
.zshenv
        → .zprofile
                → .zshrc 
                        → .zlogin

Packages

Mise

mise activate zsh

OrbStack

macOS-specific Docker alternative. See setup-osx.md for setup details.

Set the default docker context to orbstack:

docker context use orbstack

uv

Python package manager to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, etc.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment
uv venv

# Install packages
uv pip install <package>

# Run commands in the virtual environment
uv run <command>