Yeah, the words of warning are a bit of a thorn in my side. They’re somewhat overly dramatic, but to be fair, lots of people with no programming experience, let alone nix experience, try out home-manager and get confused. While the things the warning talks about are true, it fails to explain why.
I don’t think you’ll struggle if you actually understand how your configuration works, and so far you seem like the kind of person who does.
So important caveats to the words of warning:
- I don’t think the advice of reading the nix pills is good. They’re notoriously complex and don’t explain the actual ecosystem, so good luck new users.
- home-manager can’t always detect if it will overwrite something. This is very uncommon though, only really applies to database-based configs like
dconf (which isn’t a thing on MacOS afaik), and you’re in full control - if you know how the application stores its configuration this should be transparent to you.
- When in doubt, you can look at the module implementations to see if they’re doing something odd. And even then, the module authors do their best not to mess with things
- If you still don’t trust the configuration modules, none of this code runs if you don’t enable them, so you should not need to fear other applications breaking. Though if you’re using home-manager only to manage packages just using a flake like I described is probably better.
- The warning about incompatibility is mostly targeted at the situations in which some non-user owned things interact with the user-owned ones. Think X11 or graphics drivers.
- You can do rollbacks, you just don’t have the support of the home-manager cli tool for them. I think you only rarely need rollbacks for home config too, git works fine. They’re only for when git stopped working.
Generally I find home-manager works great for TUI tools, and a bit less well for GUI ones.
It doesn’t just thrash about on the system without me asking, so I have never experienced “messing things up” - just a config that didn’t end up working because of, say, graphics drivers not playing ball. It’s easy to just fall back to a non-nix package for those situations (or find the workaround).
The advice of starting small, and incrementally adding more things to it, is the best advice given in the documentation. If you go application-by-application, you’ll have full control over what’s happening, and be able to experiment as you wish.
And again, you don’t need to touch the configuration modules. For complex applications, just adding them to
home.packages has zero risk as well.
This I’m less sure about. Sure, the whole nix ecosystem struggles with documentation - far too few of us are good at writing things targeted at various levels of experience, and there are still far too few of us to make up for that with numbers.
But the home-manager docs are pretty ok IMO. I suspect you’re not using nix-darwin, so you want the standalone setup, maybe that’s tripping you up?