Unset
The first week of my second nix-darwin config: sorting every setting on my Mac by who can own it, and everything null turned out to mean.
I'd been running my Mac on nix-darwin since September, from a repository I eventually stopped working on. It held my packages, my dotfiles and shell, some development tooling, and a handful of macOS settings I'd picked by hand, like how big the Dock is and how far its icons grow under the pointer. At the end of February I started a new one, and this time I went after System Settings as a whole. That meant asking something the first config never had, which is what a Mac's settings actually are.
So on the first evening I made an inventory. I listed every option nix-darwin has under system.defaults, and the other kinds of system state I knew about: launchd jobs, Home Manager options, the payload families an MDM profile can set. Each pane of System Settings got a placeholder row as well, to be mapped later. It came to 334 rows, and by the end of the evening each one had a single answer to the question of who can own it:
- nix-darwin, through an option it already has;
- a raw
defaultswrite, for keys nix-darwin doesn't know about; - Home Manager, or launchd;
- only an MDM profile;
- only me, by hand.
nix-darwin's own options were the biggest group, 217 rows. For each of those I needed the value the config would declare, and I resolved it from the most trusted source down: my own overrides, then whatever the config already said, then what the machine currently had, then nix-darwin's default for the option. The most common value in the result was nothing. 152 of the 217 came out null, each with the same note: the key was absent from the machine's defaults, so fall back to null. In illustrative form, a row looked something like this:
"system.defaults.trackpad.Dragging" = {
value = null;
source = "evaluated-default";
note = "defaults key absent; fallback null";
};
I'd used that null to mean several different things.
The drift checker I wrote that evening reads every declared setting back off the live machine, from the defaults domains, systemsetup, scutil and the firewall, and compares. To the checker, null against a live value is a mismatch. So null meant "this key must be absent", and toggling one of those settings in System Settings would make the next check report that the Mac had drifted. The checklist I wrote the same evening, for going through System Settings by hand, reads the same value the other way: areas that are null "should be treated as user preference unless promoted". There, null means unmanaged, and nothing should complain when it changes.
The restart setting found a third meaning. power.restartAfterPowerFailure decides whether the Mac turns itself back on when the power returns. I'd first declared it false, with the note that a mobile workstation should avoid restarting itself after a power failure. A few minutes later I set it back to null, with a new note: "Unsupported on this hardware class; leave unset so nix-darwin does not attempt to manage it." nix-darwin's own description of the option warns that it "is not supported on all devices". This null means "don't touch", which is closer to the checklist than to the checker.
Some settings can't be read back at all, and those went in a column of their own. Seven options are marked unprobeable, all of them keyboard settings, by one rule that covers anything starting with system.keyboard.. The checker warns about each one and moves on. I'd also written a probe that reads one of them, userKeyMapping, back through hidutil, and the rule marks it unprobeable anyway.
A few rows I gave up on from the start: signing in to my Apple ID, the privacy approvals for things like screen recording and full disk access, app sign-ins and licenses. The proper route for the privacy approvals is a configuration profile from an MDM server, which sits outside what this repository does. I wrote those up as a checklist of things I'd do by hand after a restore.
A domain that read as empty#
The fourth meaning of null was a bug. Late that first night I rewrote the pipeline in Go. The Go version read each defaults domain by asking plutil to convert it to JSON, and plutil refuses to convert any property list that contains a date or a blob of raw data:
$ plutil -convert json -o - ~/Library/Preferences/com.apple.dock.plist
… Invalid object in plist for JSON format
When the conversion failed, my code returned an empty domain. NSGlobalDomain had a date in it, and the Dock and Finder came back empty too, so all three read as empty, every key in them looked absent, and the regenerated config quietly declared my Dock unset. The size its icons grow to under magnification, 128 since I'd set it in the old config in September, went to null.
I switched the Go version to XML and wrote a small parser for that. Within the hour I'd taken the whole Go port back out and returned to the Python version, which parses property lists itself and never had the problem, and I added a check to CI that fails if any Go turns up in the repository again.
The restore#
Three days later I erased the Mac, installed macOS Sequoia 15.7.4, and rebuilt it from the repository. Most of what I fixed that evening was in the bootstrapping: Nix daemons that an earlier installer had left registered with launchd, and launchd state pointing at store paths that no longer existed. At one point I'd repointed the system's certificate bundle by hand to get TLS working, and nix-darwin refuses to activate over a file it expects to own, so the bootstrap now moves it aside first. Git Credential Manager's installer writes to my git config, which Home Manager keeps as a read-only link into the Nix store, so I left it out, temporarily.
Then I snapshotted the restored machine's settings, and three of the files came out empty: NSGlobalDomain, the Dock and Finder. The snapshot script converted each domain with the same plutil -convert json, and wrote an empty file whenever that failed. Beside the files I'd generated a README to explain them:
Empty *.json files indicate the domain was unavailable on this machine.
Those three domains were there the whole time, unreadable to one command, and the file had no way to say so.