home-manager/README.md

Home Manager using Nix

This project provides a basic system for managing a user environment using the Nix package manager together with the Nix libraries found in Nixpkgs. Before attempting to use Home Manager please read the warning below.

Words of warning

This project is in early development! I personally use it to manage several user configurations but it may fail catastrophically for you. So beware!

To configure programs and services the Home Manager must write various things to your home directory and possibly overwrite files you have previously created. For example, if you use Home Manager to install and configure Git then your ~/.gitconfig will be replaced by a link to a configuration generated by Home Manager:

$ ls -gG ~/.gitconfig
lrwxrwxrwx 1 73 Jan  8 21:59 /home/rycee/.gitconfig -> /nix/store/pk7g12816avnxyhnkbdhqhnlzrw7fsga-home-manager-files/.gitconfig

So, if you already have a wonderful, painstakingly created ~/.gitconfig it will be gone. Home Manager will not attempt to backup the previous ~/.gitconfig file.

Further, Home Manager has only ever been used on NixOS version 16.09 (the stable version), it may or may not work on other Linux distributions and NixOS versions.

Finally, the home-manager tool does not support rollbacks at the moment so if your home directory gets messed up you'll have to fix it yourself.

Now when your expectations have been built up and you are eager to try all this out you can go ahead and read the rest of this text.

Installation

Currently the easiest way to install Home Manager is as follows:

1. Make sure you have a working Nix installation.

2. Clone the Home Manager repository into the ~/.nixpkgs directory:

   $ git clone https://github.com/rycee/home-manager ~/.nixpkgs/home-manager
   

3. Add Home Manager to your user's Nixpkgs, for example by adding it to the packageOverrides section in your ~/.nixpkgs/config.nix file:

   {
     packageOverrides = pkgs: rec {
       home-manager = import ./home-manager { inherit pkgs; };
     };
   }
   

4. Install the home-manager package:

   $ nix-env -f '<nixpkgs>' -iA home-manager
   installing ‘home-manager’
   

Usage

The home-manager package installs a tool that is conveniently called home-manager. This tool can apply configurations to your home directory, list user packages installed by the tool, and list the configuration generations.

As an example, let us set up a very simple configuration that installs the htop and fortune packages, installs Emacs with a few extra packages enabled, installs Firefox with Adobe Flash enabled, and enables the user gpg-agent service.

First create a file ~/.nixpkgs/home.nix containing

{ pkgs }:

{
  home.packages = [
    pkgs.htop
    pkgs.fortune
  ];

  programs.emacs = {
    enable = true;
    extraPackages = epkgs: [
      epkgs.nix-mode
      epkgs.magit
    ];
  };

  programs.firefox = {
    enable = true;
    enableAdobeFlash = true;
  };

  services.gpg-agent = {
    enable = true;
    defaultCacheTtl = 1800;
    enableSshSupport = true;
  };
}

To activate this configuration you can then run

$ home-manager switch

or if you are not feeling so lucky,

$ home-manager build

which will create a result link to a directory containing an activation script and the generated home directory files.