setup-macos-developer

After years of switching machines — personal laptop, client laptop, lab Mac Mini — the bill I kept paying wasn't the day lost installing tools. It was the following week: finding out git had a different alias, node was a two-year-old version, the terminal didn't have the same theme and every command felt foreign. A hand-built environment isn't slow — it's irreproducible.

This repository solves that in the simplest way that still works: versioned Bash scripts that describe the workstation as code. Homebrew installs whatever is installable as a package; dotfiles carry shell, git and editor configuration; what's left are macOS tweaks I click through today and won't remember tomorrow.

The success criterion: run the same command on two Macs and end up with the same environment. Not "similar" — the same. If one machine drifts, the fix goes into the repository, not into the terminal history of a single machine.

It is not a dotfiles framework. Several exist, some excellent, and all of them charge a learning cost I didn't want to pay for something I run a few times a year. Plain Bash is what any engineer reads in five minutes.

Order matters and it is the same on every run. First the script checks whether Homebrew exists and installs it if not — nothing else runs without it, so it is step zero. Next comes the package list: command-line formulae and application casks, which Homebrew processes in one batch. Only then are the dotfiles linked into $HOME by symlink, because several of them reference binaries that were just installed. Last, the macOS tweaks worth automating: the ones I forget, and the ones that change keyboard and Finder behavior.

Idempotency: the script was written to be re-run. An installed package is skipped, an existing symlink is not recreated, and Homebrew knows to ignore what is already at the right version. That is what lets the same repository maintain the machine, not just build it.

Bash on purpose: there is no Python, Ansible or Nix. On a freshly wiped Mac what exists is zsh, bash and curl — everything here runs on that. The price is less abstraction; the gain is that anyone can open the script and understand what it will do to the machine before running it. In a script that asks for the administrator password, that is not a detail.

Since the README is short, the source of truth for file names and flags is the repository itself. Read the main script before the first run; it is the manual.

The repository follows the rules of fernandofatech/platform, the same place that governs my other public projects. Branches carry a type prefix — feat/, fix/, chore/, docs/ — and commits use Conventional Commits. The version comes from the commits; nobody types a version number by hand, and that holds even for a repository of scripts.

Why so much pipeline for dotfiles: because the cost is not writing the script — it's keeping it alive for years without rot. pr-lint rejects PRs with a non-conforming title; CI runs shell lint; the security scan catches a secret pasted by mistake into a .zshrc — and a dotfile is exactly where an API token ends up "just for today". Automated release tags every relevant change, so you can tell which version of the setup built which machine.

Fixing the bar means changing one file in platform, not here. That is the gain of centralizing: a small scripts repository gets the same discipline as a service, without carrying the YAML.

If you fork, you can ignore all of this: the scripts don't depend on the pipeline. It exists for the maintainer, not for whoever runs them.