home-manager

Manage user configuration declaratively with Nix

TLDR

Build the configuration defined in ~/.config/nixpkgs/home.nix without applying it

$ home-manager build

Build and apply (switch to) the new configuration

$ home-manager switch

Roll back to a previous configuration generation

$ home-manager rollback

List all existing configuration generations

$ home-manager generations

When using flakes, run any operation that requires nix to run (build, switch, news) by passing the path to the flake

$ home-manager [command] --flake [path/to/flake]

build
    Builds the Home Manager environment but does not activate it.

switch
    Builds and activates the Home Manager environment, making changes live.

dry-build
    Shows what would be built without actually building it. Useful for debugging.

edit
    Opens the Home Manager configuration file in your editor.

version
    Displays the Home Manager version.

help
    Displays help information about Home Manager or a specific command.

options
    Lists available options for Home Manager configuration.

rollback
    Rollback to previous Home Manager configuration.

DESCRIPTION

Home Manager is a tool for managing a user environment using the Nix package manager.
It allows users to declaratively manage their dotfiles, install software packages, and configure services that run within their user session.
This allows for reproducible and easily manageable user configurations. Instead of manually editing configuration files and installing packages, you define your desired state in a Nix expression, and Home Manager ensures that your system matches that state. This configuration is stored in a file (often `~/.config/nixpkgs/home.nix` or a similar location) that can be version controlled.
Home Manager handles symlinking files into the user's home directory and setting environment variables, and automatically managing dependencies between packages and configurations.

CAVEATS

Home Manager requires the Nix package manager to be installed. Using experimental features may require specific Nix configuration.

CONFIGURATION

The primary configuration file is typically located at `~/.config/nixpkgs/home.nix`. This file contains the Nix expression that defines your desired user environment. You can use Nix's functional programming features to create complex and modular configurations.

ACTIVATION

The `home-manager switch` command activates the changes defined in your configuration file. This involves creating symbolic links, setting environment variables, and running any necessary scripts.

HISTORY

Home Manager was created to provide a declarative way to manage user environments with Nix. It has evolved significantly since its inception, adding support for more and more packages and configuration options. It has gained popularity as a convenient alternative to manual dotfile management, especially within the Nix community.