Migration from Hjem

Manzil started from similar goals, but its current shape is intentionally narrower and more explicit. This guide focuses on the practical deltas you will hit while moving a configuration over.

Rename the top-level namespace

# old
hjem.users.alice.files.".zshrc".text = "...";

# new
manzil.users.alice.files.".zshrc".text = "...";

Likewise:

• hjem.clobberByDefault -> manzil.clobberByDefault
• hjem.extraModules -> manzil.extraModules
• hjem.specialArgs -> manzil.specialArgs
• hjem.linker -> manzil.linker
• hjem.linkerOptions -> manzil.linkerOptions

Module entrypoints

# old
inputs.hjem.nixosModules.default
inputs.hjem.darwinModules.default

# new
inputs.manzil.nixosModules.default
inputs.manzil.darwinModules.default

Linker expectations changed

The default manifest linker is Manzil's bundled Rust binary, manzil. It is built and shipped from this repository.

Linux still supports manzil.linker = null for systemd-tmpfiles mode, but that mode is deliberately narrower:

• only symlink entries
• source path required
• weaker cleanup semantics than manifest mode

If you relied on a custom smfh package before, start by trying the bundled linker first.

Manifest contracts are new

Generated v3 manifests include:

• contracts.target_root
• contracts.source_roots

These are validated by the bundled linker when loading the manifest and again against resolved runtime paths during activation. If you previously depended on writing outside the managed home root, or on linking from arbitrary mutable source trees, adjust the configuration first.

File model differences

Manzil keeps the file surface intentionally explicit:

• type = "symlink" | "copy" | "delete" | "directory" | "modify"
• exactly one of source / text / generator for source-like entries
• metadata fields only for copy / delete / directory / modify
• target paths must stay relative to the selected root and cannot contain . or ..

That stricter validation usually catches mistakes earlier during evaluation.

Generated user units

On NixOS, generated user units still land under ~/.config/systemd/user. Manzil additionally reacts to restartTriggers and reloadTriggers during manifest activation, so changed trigger payloads can restart or reload units automatically.

Environment handling

environment.sessionVariables and generated environment.loadEnv remain available. Manzil still does not source environment.loadEnv for you.

Suggested migration order

1. Rename the namespace from hjem to manzil.
2. Switch imports to manzil.nixosModules.default or manzil.darwinModules.default.
3. Keep file declarations unchanged where possible.
4. Move to the bundled linker.
5. Rebuild and inspect the generated manifest if you hit contract failures.
6. Add trigger options to user units only where you want automatic restarts or reloads.

Minimal example

A minimal NixOS and nix-darwin example is available under examples/ in this repository.