driesvints/dotfiles: a macOS bootstrap script built around Homebrew and Mackup

What driesvints/dotfiles actually solves, and for whom

Setting up a new Mac by hand is a long sequence of small decisions: which Homebrew formulae and casks, which shell aliases, which macOS defaults, which SSH key. This repository turns that sequence into files you can read and re-run. The README frames it plainly as "my way to help me setup and maintain my Mac", and the author invites readers to "explore, learn and copy parts for your own dotfiles".

The audience is narrow and worth stating. It is for a macOS user who already works in zsh, already has Oh My Zsh installed, and wants a reference implementation rather than a configurable tool. The README repeats that assumption in the section on building your own: the instructions "assume you already have set up Oh My Zsh". If you are on Linux, or you want one repository to cover a laptop and a desktop on different operating systems, this is the wrong starting point. Nothing in the top-level layout suggests a portable path: the entries are Brewfile, .macos, minimal.zsh-theme, aliases.zsh, path.zsh, plus the installer scripts.

How the pieces fit together: fresh.sh, Brewfile, Mackup and the ZSH_CUSTOM trick

The repository is a set of dotfiles plus a small amount of glue. The mechanism is worth tracing because it explains both the convenience and the coupling.

Installation is driven by fresh.sh, which the README runs from inside the cloned directory. The Brewfile is the declarative list of Homebrew packages, and the README describes migrating to a Brewfile as a deliberate change credited to a talk on Homebrew. The .macos file holds system defaults, and the README points readers to Mathias Bynens' original script and Kevin Suttle's macOS Defaults project for more settings, which tells you the file is a curated subset rather than a complete catalogue. Shell configuration is split across aliases.zsh, path.zsh and .zshrc, with the theme in minimal.zsh-theme. The README states that aliases.zsh and path.zsh are loaded because the $ZSH_CUSTOM setting points at the .dotfiles directory, so the repository plugs itself into Oh My Zsh rather than replacing it.

The one genuinely stateful part is Mackup. The README's own instructions for building your own dotfiles say to back settings up with mackup and that settings sync to iCloud by default, with other storage documented upstream. That means the repository does not hold your application preferences; it holds the code that installs applications and then asks Mackup to restore preferences from elsewhere. Two machines stay similar only if that external store is reachable.

Installing it: clone, run fresh.sh, then restore with Mackup

The README gives an ordered procedure for a new Mac. Steps 1 and 2 are macOS updates and an SSH key. For the key it offers two paths: use 1Password's SSH agent, or generate a new key with a script fetched from the repository. The second path is a one-liner that pipes a remote script into a shell, which is the kind of thing you should read before running.

curl https://raw.githubusercontent.com/driesvints/dotfiles/HEAD/ssh.sh | sh -s "<your-email-address>"

That fetches ssh.sh from the default branch and passes your email as an argument, which the script uses when generating the key pair.

The next step clones into a fixed location. The --recursive flag matters: the repository has a .gitmodules file and a plugins/ directory, so submodules are part of the setup.

git clone --recursive [email protected]:driesvints/dotfiles.git ~/.dotfiles

Then the installer runs from inside that directory.

cd ~/.dotfiles && ./fresh.sh

After that the README moves to manual steps: start Herd.app and run its install process, restore preferences with mackup once it has synced with cloud storage, and restart. The Mackup commands for a first-time setup are given in the section on building your own dotfiles.

brew install mackup
mackup backup

If you prefer a different directory than ~/.dotfiles, the README says you can use one, but you must also update the references in .zshrc and fresh.sh. That is a hardcoded path, not a configurable variable, and it is the first thing to check when a fork behaves oddly.

Where this repository will fight you

The most obvious limitation is the platform. Every installer path, the .macos defaults file and the Homebrew casks assume macOS. On Linux you would be deleting the parts that do the work and keeping the shell aliases.

The second is that this is a personal configuration, not a product. There are no releases. The README warns that you should adjust the Brewfile to the apps you want, which is a polite way of saying the default list is one person's choices; running fresh.sh unmodified installs what the author uses. The same applies to .macos, where the README points elsewhere for the full set of options rather than documenting its own.

Third, the failure mode of a piped install script is silent. The ssh.sh example downloads and executes remote code, and fresh.sh is executed directly from the working tree. If either assumes a path, a shell or a tool that is not present, you find out partway through a system change. There is no dry-run flag documented, and the README does not describe rollback. The only documented recovery path is the backup checklist at the top, which is about your data, not about undoing the script.

Finally, the coupling to Oh My Zsh through $ZSH_CUSTOM means that if you later move to a different shell framework, the aliases and path files stop being loaded and you have to wire them up yourself.

Compared with a general dotfiles manager such as GNU Stow

The related searches include "dotfiles stow", and the comparison is instructive because the two solve different problems. GNU Stow is a symlink manager: it maps files from a package directory into a target prefix, and it knows nothing about Homebrew, macOS defaults or application preferences. You point it at a directory and it creates links.

driesvints/dotfiles is the opposite shape. It is a bootstrap script with opinions. fresh.sh installs software, .macos writes system settings, and Mackup handles application preferences outside the repository. There is no symlink farm to reason about, but there is also no generic mechanism you can reuse for a second machine running a different OS. If your goal is a portable set of shell files that works on Linux and macOS, a symlink manager is the better tool and this repository is a source of ideas. If your goal is to rebuild one Mac quickly, the script is more direct than assembling your own Stow packages plus a Brewfile.

Maintenance, licence and what a fork owes upstream

The repository is not archived, and the last push was on 2026-07-18. That is recent enough that the files reflect a current macOS setup, but it is still a personal repository with no published releases, so there is no version number to pin and no changelog to read. Upgrading means pulling the default branch and diffing it against your fork, paying attention to fresh.sh, the Brewfile and .macos, because those are the files that change system state.

The licence is MIT, declared in LICENSE.md. MIT is permissive: you can copy, modify and redistribute the files, including commercially, provided the copyright notice and permission notice are kept. That is a summary of the licence text, not legal advice. The practical implication for a fork is that you may strip it down to the parts you want, and the README explicitly invites copying parts rather than the whole. Nothing in the repository suggests a trademark or branding restriction, but the README does link to a sponsorship page, which is a request, not a licence term.

Editorial conclusion

Adopt it if you run macOS, already use Homebrew and Oh My Zsh, and want a concrete example to fork rather than a framework to configure. Do not adopt it if you are on Linux, if you want one manager to handle many machines and platforms, or if you are unwilling to read every line of fresh.sh and .macos before running them, because both change system state. Before you run anything, verify that the clone path matches the hardcoded references in .zshrc and fresh.sh, and check the Brewfile for applications you do not want installed. The repository is one person's machine, not a supported product, and no release has been published.

Frequently asked questions

Official sources

1. driesvints/dotfiles on GitHub
2. Issues
3. License: MIT
4. Project website
5. README