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.

~/.dotfiles One git repository. Settings, a shopping list of apps, and the scripts that install them.
A laptop same shell, same keys
A desktop same editor, same prompt
A managed work Mac layered on top, politely
One repository feeds every Mac. Change a setting once, pull it everywhere.

Five ideas hold it together

Everything in the repository follows from five decisions. Each has a guide of its own.

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.

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 install fetches 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.