Setting up a new Mac.
A repeatable way to turn a fresh Mac into a familiar place to work.
A new Mac is a reset. For a moment, there are no old assumptions, accumulated tools, or half-remembered settings. It is tempting to turn that blankness into a checklist: install everything, sign in everywhere, and keep moving until the desktop looks familiar.
I prefer to make it a smaller question: what are the few decisions that make this computer feel like mine?
That is what my dotfiles are for. They are not a copy of an old machine. They are a record of the tools, settings, and small systems I want to be able to return to.
Why I keep dotfiles
Computer setup is easy to lose track of. A package gets installed from a terminal, a preference changes in System Settings, and a configuration file is adjusted late at night. Each choice is small, but after a while it is hard to say what is intentional and what simply accumulated.
Keeping the setup in one repository makes those choices visible. I can see what it manages, change one piece without replaying the whole process, and start fresh without relying on memory.
The setup, in layers
My macOS dotfiles repository keeps the setup deliberately small. It has one bootstrap command and a CLI that can report the current state, preview changes, or apply the full setup.
Packages and applications
Homebrew manages packages and applications through a single Brewfile. That gives the tool list one home instead of scattering it across old notes and shell history.
Configuration
The repository links the configurations for the tools I use every day, including Zsh, tmux, Ghostty, Neovim, Zed, Yazi, Starship, and Atuin. If a configuration already exists, the setup moves it to a timestamped backup instead of silently replacing it.
macOS settings
The setup also keeps the system preferences that matter over a day of work: fast key repeat, hidden files and extensions visible in Finder, a Dock that stays out of the way, screenshots in a predictable folder, and text substitutions switched off. They live beside the rest of the setup so they can be revisited deliberately.
What stays on the machine
Some things should not be portable configuration. Authentication, SSH keys, browser profiles, shell history, application credentials, caches, and generated runtime files stay local. The repository should be a reliable starting point, not a fragile copy of one computer.
Starting from a clean machine
./bin/macos-setup status
./bin/macos-setup --dry-run apply
./bin/macos-setup applyI start with status, then use the dry run before making changes. The final command is there when I want to set up the whole machine. The commands are simple on purpose. They make the process easy to inspect, and easy to repeat.
A new computer will never be exactly the one it replaces. That is useful. The setup preserves the choices worth keeping while leaving room for the rest to change.