dotfiles

Personal macOS dotfiles — zsh, tmux, git, and a full developer toolchain.

This site documents the bradbergeron-us/dotfiles repository. For the canonical, always-current overview, see the README on GitHub.

Quick start

git clone https://github.com/bradbergeron-us/dotfiles.git ~/dotfiles
bash ~/dotfiles/bootstrap.sh

bootstrap.sh runs once on a fresh Mac: Homebrew, all packages, runtimes (Ruby, Node, Java, Python, Go, Rust), dotfile symlinks, and — on a first interactive run — a prompt for this machine's profile. Open a new terminal when it finishes.

Preview without changing anything: bash ~/dotfiles/bootstrap.sh --dry-run (see Dry-Run & Pre-flight).

New here? Walk through the Getting Started tutorial for a guided first hour.

Find your way around

This documentation follows the Diátaxis model — pick the lane that matches what you need.

Tutorials — learn by doing

• Getting started: your first hour
• Set up a work laptop
• Adopt a profile on an existing machine

How-to guides — accomplish a task

• Add a tracked dotfile
• Manage packages
• Manage secrets
• Add a zsh plugin
• Write a test
• Schedule updates
• Recover from a failed update

Reference — look something up

• Machine profiles and Usage & lifecycle
• Tool reference and Shell performance
• Troubleshooting
• Setup: Dry-run & pre-flight · GPG commit signing · Encrypted secrets
• Work machine: Overview · Complete setup guide · Claude Code SSL fix

Explanation — understand how it fits

• Architecture — how bootstrap, install, update, verify, status, and profiles fit together.
• Glossary — terms used across these docs.

Contributing

See Contributing for repo conventions, the bats-core test workflow, and CI.