https://github.com/z0al/plist-manager
Nix-Based macOS User Defaults Done Right
https://github.com/z0al/plist-manager
darwin home-manager macos nix nix-darwin nix-flake
Last synced: about 1 year ago
JSON representation
Nix-Based macOS User Defaults Done Right
- Host: GitHub
- URL: https://github.com/z0al/plist-manager
- Owner: z0al
- License: mit
- Created: 2024-12-15T19:43:43.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-03T00:26:52.000Z (over 1 year ago)
- Last Synced: 2025-04-10T08:55:36.242Z (about 1 year ago)
- Topics: darwin, home-manager, macos, nix, nix-darwin, nix-flake
- Language: Nix
- Homepage: https://z0al.github.io/plist-manager
- Size: 79.1 KB
- Stars: 18
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# plist-manager
## Introduction
Plist-manager (PM) is a Nix module for managing macOS user defaults. Unlike the built-in options offered by [nix-darwin](https://github.com/LnL7/nix-darwin) and [home-manager](https://github.com/nix-community/home-manager), PM provides the following advantages:
- Human-friendly naming of domains and options, e.g., `trackpad.draggingStyle = "three-fingers"`.
- Automatic reloading of system settings with `activateSettings -u` after applying changes.
- Unsetting an option or explicitly setting it to `null` _resets_ its value, effectively performing a `defaults delete ` command.
The _null equals reset_ rule makes this module particularly useful, as it ensures that any option previously set is restored to the system default. This behavior is crucial for configurations that are conditionally set, e.g., `NSGlobalDomain.AppleInterfaceStyle`, which is removed if the user opts for Light or Auto appearance mode.
> [!IMPORTANT]
>
> Since all options provided by this module default to `null`, by adding the module to a Nix flake you risk losing some user defaults that are not managed with Nix.
>
> This also makes the module incompatible with the built-in alternatives from nix-darwin and home-manager (unless used to set values that aren't touched by plist-manager; see the _"Affects: ..."_ block next to each option in the [reference](https://z0al.github.io/plist-manager#reference) for more information about which plist keys are affected).
>
> In the near future, I plan to keep track of unset values properly and only delete those instead of every attribute.
## Installation
To get started, add `plist-manager` to your [Nix flake](https://nix.dev/concepts/flakes) inputs:
```nix
{
inputs.plist-manager.url = "github:z0al/plist-manager";
inputs.plist-manager.inputs.nixpkgs.follows = "nixpkgs";
}
```
This module provides integrations for both nix-darwin and home-manager. You can use either one, but NOT both, to avoid behavior conflicts.
### For nix-darwin users
Add `plist-manager.darwinModules.default` to your nix-darwin modules:
```nix
{
darwinConfigurations.hostname = darwin.lib.darwinSystem {
modules = [
# ... other modules
plist-manager.darwinModules.default
];
};
}
```
### For home-manager users
Add `plist-manager.homeManagerModules.default` to your home-manager modules:
```nix
{
homeConfigurations.userName = home-manager.lib.homeManagerConfiguration {
modules = [
# ... other modules
plist-manager.homeManagerModules.default
];
};
}
```
## Documentation
See available options at https://z0al.github.io/plist-manager
## Development
### Local Environment
This repository provides a Nix shell to set up all the tools you need. You can integrate it with [direnv](https://github.com/nix-community/nix-direnv) by adding the following to your `.envrc`:
```sh
use_flake
```
### Running Unit Tests
All test files must be placed under `./tests` and prefixed with `test-*`. Tests are automatically imported. See [tests/setup.nix](./tests/setup.nix) for more details.
```sh
make test
```
### Serving Documentation Locally
```sh
make site
```
### Inspecting Plist Domains and Keys
This repository bundles [plistwatch](https://github.com/catilac/plistwatch), which is a handy tool for inspecting and identifying the associated plist domains and keys for various system settings.
```sh
make watch
```
## License
This project is licensed under the terms of the [MIT license](./LICENSE).