Copland Home

A first Home configuration

Copland Home manages a user's packages and configuration files. This example installs Git and provides its configuration for an existing user named alice.

Directory structure

Keep the Home configuration under the host that selects it:

hosts/<host>/
├── default.nix
└── home/
    └── default.nix

Home module

Put this in home/default.nix:

{ pkgs, ... }:
{
  home.packages = [ pkgs.git ];

  home.file.".config/git/config".text = ''
    [init]
      defaultBranch = main
  '';
}

home.packages selects packages for this user's Home generation. home.file declares files relative to the user's home directory, so this file appears at /home/alice/.config/git/config. Its contents are generated in the Nix store and linked into place during Home activation.

System declaration

Add the following Home declaration to the existing host module at hosts/<host>/default.nix. Keep its other settings and imports.

{ ... }:
{
  homeEnvironment.users.alice = {
    enable = true;
    configurationPath = "/home/alice/copland-os";
    attribute = "hosts.<host>.homes.alice";
    modules = [ ./home ];
  };
}

Replace alice with your existing account name and <host> with the host's attribute name in the root evaluator. configurationPath points to your local Copland checkout, and attribute tells copland-home which Home generation to build from it.

The modules list selects the user's Home modules. They are evaluated separately from the system modules, so ./home belongs here rather than in the host's regular imports list. The user account itself remains declared through users.users.

Building and switching the system enables Copland Home for this user. A system switch automatically activates the Home generation selected by the system configuration, so no additional copland-home switch is needed. A generated OpenRC task handles Home activation after nix-daemon starts.

Use copland-home switch when you want to build and activate only the user environment without switching the whole system.

Configuration files

The following examples are three alternatives for the same Git configuration. Put a file named git.conf beside home/default.nix and choose one of the modules below instead of the earlier text declaration.

home/
├── default.nix
└── git.conf

Non-editable configuration

A Nix path copies the source into the Home generation. The installed configuration links to that read-only store copy.

{ pkgs, ... }:
{
  home.packages = [ pkgs.git ];
  home.file.".config/git/config".source = ./git.conf;
}

Edit git.conf in the checkout, then build and activate a new Home generation to apply the change. Generated files declared through text behave the same way.

Editable configuration

A string source links directly to the original file. Here, the path is relative to home.sourceRoot, which defaults to /home/alice/copland-os for the example user.

{ pkgs, ... }:
{
  home.packages = [ pkgs.git ];
  home.file.".config/git/config".source = "hosts/<host>/home/git.conf";
}

Replace <host> with your host directory name. Once activated, edits to that file are available without rebuilding Home, although the application may need to reload its configuration. The original file must remain available because this form has no store fallback.

Hybrid configuration

A Nix path with live = true combines direct editing with a store fallback. During activation, Copland Home chooses the checkout file if it exists and otherwise uses the copy saved in the generation.

{ pkgs, ... }:
{
  home.packages = [ pkgs.git ];
  home.file.".config/git/config" = {
    source = ./git.conf;
    live = true;
  };
}

With the checkout available, you can edit git.conf without rebuilding. The fallback contains the version from the last build, so build a new generation when you want to update that copy too. The choice of link is made during activation, not automatically when the checkout disappears.

Home commands

Run these commands as the user whose Home configuration you want to manage. They use the configurationPath and attribute from the system declaration above.

Build

build prepares a Home generation and prints its Nix store path. It does not change your installed files or select the generation for your Home profile.

copland-home build

Check

check builds the generation and checks its file sources and destination paths for conflicts. It does not activate the generation.

copland-home check

Switch

switch builds and activates the Home configuration without switching the system. For example, after changing the Git configuration in the non-editable example, run:

copland-home switch

Home updates its managed files and selects the new generation in your Home profile. A normal system switch already handles the Home generation selected by that system, so this command is only needed for a separate Home update.

Generations

generations lists the generations recorded in your Home profile and marks the current one.

copland-home generations

Rollback

rollback activates the previous available Home generation without rebuilding it. Use it to return to the packages and managed configuration from that generation.

copland-home rollback

Rollback does not undo edits to files in your checkout. Editable files, including hybrid files using their checkout source, still show the contents of those files.