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.
-
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.
-
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
gitcomes from. If Homebrew is already installed this step is skipped, which keeps a second run quick. -
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. -
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.
-
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. -
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 theBrewfilein the repository. -
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.
-
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.
-
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.
Two things only you can do
Everything above is automatic. These two are not, because they involve your identity.
-
By hand · required
Create
~/.gitconfig-userYour name, your email and the public half of your signing key. Commit signing is always on, and this file is where git learns which key to use.
-
By hand · once
Turn on the 1Password SSH agent
In 1Password, open Settings, then Developer, and tick “Use the SSH agent”. Keys and 1Password explains why.
# ~/.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.
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.
| Step | On a Mac that is already set up |
|---|---|
| Homebrew | Found, so the installer is skipped. |
| Dotfiles | Pulled instead of cloned. Local edits are stashed and put back. |
| Links | Each one already points into the repository, so it is reported as unchanged. |
| macOS settings | Each setting is read first and only written if it differs. The record of the original values is never overwritten. |
| Brewfile | Checked first. Nothing is installed if nothing is missing. |
| Login shell | Already 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.
-
script/remove
The dotfiles
- The login shell goes back to
/bin/zsh. - The plugin and shell caches are deleted.
~/.dotfilesis deleted, and so is every signpost in your home folder,~/.configand~/.sshthat pointed into it. A signpost that was already broken belongs to something else and is left alone.
- The login shell goes back to
-
script/remove --everything
The dotfiles and Homebrew
- All of the above.
- Every package and app Homebrew installed.
- Homebrew itself, and the Command Line Tools. A full Xcode is never touched.
-
Either way
Left alone
- Your shell history.
- Every other app's files in
~/.configand~/.ssh. - The macOS settings. To put those back, run the
restorescript thatscript/macossaved in~/.local/share/dotfiles/macos-defaultson its first run.