Guide 1 of 7 · Start here
How these dotfiles work
A picture-book tour of the small text files that turn a blank Mac into a familiar one, and of the scripts and tests that keep them honest.
What is a dotfile?
Almost every tool on a Mac keeps its settings in a plain text file. Many of those files have names that start with a dot, like .zshrc, which also makes them invisible in Finder. People call them dotfiles.
In plain words
A new Mac is an empty house. Dotfiles are the box you bring with you: where the furniture goes, which light switch does what, the labels on every drawer. This repository is that box. It lives in one place, so every Mac gets unpacked the same way.
Five ideas hold it together
Everything in the repository follows from five decisions. Each has a guide of its own.
-
01
One command sets up a Mac
Paste one line into Terminal. It installs Homebrew, fetches this repository, links it into place, applies macOS settings and installs every app on the list.
-
02
Files stay in one folder, linked into place
Nothing is copied around. The home folder holds signposts that point into the repository, so an edit in either place is the same edit.
-
03
It sits on top of whatever is already there
Some Macs come with a shell setup somebody else manages. These dotfiles never fight it. They load it first, then add their own layer above.
-
04
No secret ever touches the disk
SSH keys live inside 1Password. Logging in to servers and signing commits both ask 1Password, which asks for a fingerprint.
-
05
Fast, and proven to stay that way
A new terminal opens in about 145 milliseconds, and a test fails if that slips. More than two hundred other tests watch everything else.
-
+
The toolbox
A cheat sheet for what you actually get: the prompt, git shortcuts, tmux keys, the editor, fuzzy finding and the rest.
A map of the repository
The top level is small on purpose. Two folders are linked into your home folder piece by piece, one file is a shopping list, and the rest is machinery.
- BrewfileThe shopping list. Every command-line tool, app and font Homebrew should install.
- config/Settings for every tool. Each entry inside is linked into
~/.config. - zsh/The shell: four startup files, a
lib/folder with one file per topic, and a few handy functions. - git/Git settings, a global ignore list, a commit message template and the list of trusted signing keys.
- nvim/A deliberately small Neovim setup for commit messages and quick edits.
- tmux/Windows and panes inside the terminal, in the Gotham colors.
- ghostty/The Ghostty terminal app: its font and the same Gotham colors.
- mise/ gh/ homebrew/ karabiner/ starship.tomlLanguage runtimes, the GitHub CLI, Homebrew's own switches, the Caps Lock remap and the prompt.
- ssh/SSH settings. Its one file,
config, is linked into~/.ssh. - script/The robots:
bootstrap,setup,macos,after-setup,remove, and the maintenance checks. - test/Checks that all of the above still works, including on a brand-new Mac in a virtual machine.
- guides/These pages. Plain HTML, no build step.
Words you will meet
The guides avoid jargon where they can. These are the terms they could not avoid.
- Terminal
- The window you type commands into. On these Macs that is Apple's Terminal.app or Ghostty.
- Shell (zsh)
- The program inside that window that reads what you type and runs it. macOS ships one called zsh.
- Repository
- A folder whose whole history is tracked by git, so it can be copied to another Mac and kept in sync.
- Symlink
- A signpost on disk. It looks like a file or folder, but it only says “the real thing is over there”.
- Homebrew
- An app store for the command line.
brew installfetches tools and apps. - PATH
- The list of folders the shell searches when you type a command name. Earlier folders win.
- Login shell
- The first shell of a session, such as a new Terminal window. It reads a couple of extra startup files.
- Plugin
- An add-on for the shell or the editor, fetched from GitHub the first time it is needed.
- tmux
- A tool that splits one terminal window into several panes and keeps them alive if the window closes.
- Agent
- A helper that holds your keys and uses them for you, so the keys themselves never have to be handed out.
- Base layer
- A shell setup that somebody else installed and maintains, for example on a work Mac. These dotfiles load on top of it.
- XDG folders
- A tidy convention: settings in
~/.config, throwaway caches in~/.cache, your data in~/.local/share.