Guide 2 of 7 · New Mac

Setting up a new Mac

One pasted line does the lot. A bare Mac reaches a working shell in under three minutes, plus however long the apps take to download.

The one command

Open Terminal on the new Mac and paste this. It downloads a script called script/bootstrap and runs it.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/shaneog/dotfiles/HEAD/script/bootstrap)"

In plain words

Bootstrap is a moving crew with a checklist. It asks for your password once at the door, then works through the list in order: fetch the tools, bring the boxes in, put things where they belong, set the thermostat, stock the shelves. If any step fails it stops and tells you which.

What happens, in order

Every step below is real code in script/bootstrap or a script it calls. The label on each one says which.

  1. Check it is safe to start bootstrap

    Refuses to run as root, checks you are an administrator, and asks for your password once. The password is kept in a temporary file only you can read, which is deleted when the script exits, however it exits. The Mac is kept awake until the work is done.

  2. Install Homebrew bootstrap

    Homebrew is how everything else arrives. On a Mac that has never had them, it installs Apple's Command Line Tools first, which is where git comes from. If Homebrew is already installed this step is skipped, which keeps a second run quick.

  3. Fetch the dotfiles bootstrap

    Clones this repository to ~/.dotfiles. If that folder already exists it pulls the latest changes instead, keeping any local edits safe. If the repository cannot be reached, bootstrap stops here and says so, so it never reports success without any dotfiles.

  4. Link everything into place script/setup

    Creates the signposts from your home folder into the repository. Anything already in the way is moved aside with a date stamp, never deleted. Where files live has the full picture.

  5. Apply macOS settings script/macos

    First it records the current values and writes a script that can put them back. Then it applies one table of settings: Dock, Finder, sounds, Touch ID for sudo, and the Gotham theme for Terminal.

  6. Install everything on the shopping list Brewfile

    Runs brew bundle --global, which reads ~/.Brewfile. That is one of the signposts from two steps ago, pointing at the Brewfile in the repository.

  7. Switch the login shell bootstrap

    Makes Homebrew's newer zsh the default shell. It happens after the shopping list on purpose: the shell has to be installed before the Mac can be pointed at it.

  8. Finish the editor script/after-setup

    Starts Neovim with no window, installs its plugins at the exact versions recorded in the lockfile, and builds the syntax parsers.

  9. Open a new terminal window you

    The first shell fetches its own plugins, which takes around twelve seconds, once. Every shell after that starts in a fraction of a second.

The bootstrap checklist, top to bottom. The last step is the only one that needs you.

Two things only you can do

Everything above is automatic. These two are not, because they involve your identity.

# ~/.gitconfig-user
[user]
	name = Your Name
	email = [email protected]
	signingkey = ssh-ed25519 AAAA...   # the public key, not a path

How long it takes

These numbers come from the virtual machine test, which installs onto a completely fresh copy of macOS. The first bar includes Apple's Command Line Tools, which Homebrew installs before anything else. Apps are left out because their download time depends on your connection.

  • Homebrew from scratch96 s
  • script/macos<1 s
  • Brewfile, command-line tools55 s
  • script/after-setup7 s
  • First shell, installing plugins12 s
Measured on macOS 27 in a Tart virtual machine. The whole run, image already downloaded: 195 seconds.

Running it again is safe

Bootstrap is written so a second run only does what is still missing. That makes it the way to update a Mac as well as the way to set one up.

StepOn a Mac that is already set up
HomebrewFound, so the installer is skipped.
DotfilesPulled instead of cloned. Local edits are stashed and put back.
LinksEach one already points into the repository, so it is reported as unchanged.
macOS settingsEach setting is read first and only written if it differs. The record of the original values is never overwritten.
BrewfileChecked first. Nothing is installed if nothing is missing.
Login shellAlready Homebrew's zsh, so it is left alone.

Installing from somewhere else

Two variables change where the dotfiles come from. That is handy for trying a branch, or for a Mac that has no GitHub login yet and gets the repository from a USB stick.

DOTFILES_REF=some-branch ./script/bootstrap
DOTFILES_URL=/Volumes/stick/dotfiles ./script/bootstrap

Taking it all out again

script/remove is the undo. It asks “Are you sure?” first, and by default it only removes what this repository put there.