fork/home-manager
git clone https://git.julia.blue/fork/home-manager
33ccc5c2
master
1[[ch-usage]] 2== Using Home Manager 3 4Your use of Home Manager is centered around the configuration file, 5which is typically found at `~/.config/home-manager/home.nix` in the standard installation 6or `~/.config/home-manager/flake.nix` in a Nix flake based installation. 7 8[ NOTE ] 9The default configuration used to be placed in `~/.config/nixpkgs`¸ 10so you may see references to that elsewhere. 11The old directory still works but Home Manager will print a warning message when used. 12 13This configuration file can be _built_ and _activated_. 14 15Building a configuration produces a directory in the Nix store that contains all files and programs that should be available in your home directory and Nix user profile, respectively. The build step also checks that the configuration is valid and it will fail with an error if you, for example, assign a value to an option that does not exist or assign a value of the wrong type. Some modules also have custom assertions that perform more detailed, module specific, checks. 16 17Concretely, if your configuration contains 18 19[ source,nix ] 20programs.emacs.enable = "yes"; 21 22then building it, for example using `home-manager build`, will result in an error message saying something like 23 24[ source,console ] 25---- 26$ home-manager build 27error: A definition for option `programs.emacs.enable' is not of type `boolean'. Definition values: 28- In `/home/jdoe/.config/home-manager/home.nix': "yes" 29(use '--show-trace' to show detailed location information) 30---- 31 32The message indicates that you must provide a Boolean value for this option, that is, either `true` or `false`. The documentation of each option will state the expected type, for <<opt-programs.emacs.enable>> you will see ``Type: boolean''. You there also find information about the default value and a description of the option. You can find the complete option documentation in <<ch-options>> or directly in the terminal by running 33 34[ source,console ] 35man home-configuration.nix 36 37Once a configuration is successfully built, it can be activated. The activation performs the steps necessary to make the files, programs, and services available in your user environment. The `home-manager switch` command performs a combined build and activation. 38 39[[sec-usage-configuration]] 40=== Configuration Example 41 42A fresh install of Home Manager will generate a minimal `~/.config/home-manager/home.nix` file containing something like 43 44[ source,nix ] 45---- 46{ config, pkgs, ... }: 47 48{ 49# Home Manager needs a bit of information about you and the 50# paths it should manage. 51home.username = "jdoe"; 52home.homeDirectory = "/home/jdoe"; 53 54# This value determines the Home Manager release that your 55# configuration is compatible with. This helps avoid breakage 56# when a new Home Manager release introduces backwards 57# incompatible changes. 58# 59# You can update Home Manager without changing this value. See 60# the Home Manager release notes for a list of state version 61# changes in each release. 62home.stateVersion = "23.05"; 63 64# Let Home Manager install and manage itself. 65programs.home-manager.enable = true; 66} 67---- 68 69You can use this as a base for your further configurations. 70 71[ NOTE ] 72If you are not very familiar with the Nix language and NixOS modules then it is encouraged to start with small and simple changes. As you learn you can gradually grow the configuration with confidence. 73 74As an example, let us expand the initial configuration file to also install the htop and fortune packages, install Emacs with a few extra packages available, and enable the user gpg-agent service. 75 76To satisfy the above setup we should elaborate the `home.nix` file as follows: 77 78[ source,nix ] 79---- 80{ config, pkgs, ... }: 81 82{ 83# Home Manager needs a bit of information about you and the 84# paths it should manage. 85home.username = "jdoe"; 86home.homeDirectory = "/home/jdoe"; 87 88# Packages that should be installed to the user profile. 89home.packages = [ <1> 90pkgs.htop 91pkgs.fortune 92]; 93 94# This value determines the Home Manager release that your 95# configuration is compatible with. This helps avoid breakage 96# when a new Home Manager release introduces backwards 97# incompatible changes. 98# 99# You can update Home Manager without changing this value. See 100# the Home Manager release notes for a list of state version 101# changes in each release. 102home.stateVersion = "23.05"; 103 104# Let Home Manager install and manage itself. 105programs.home-manager.enable = true; 106 107programs.emacs = { <2> 108enable = true; 109extraPackages = epkgs: [ 110epkgs.nix-mode 111epkgs.magit 112]; 113}; 114 115services.gpg-agent = { <3> 116enable = true; 117defaultCacheTtl = 1800; 118enableSshSupport = true; 119}; 120} 121---- 122<1> Nixpkgs packages can be installed to the user profile using <<opt-home.packages>>. 123<2> The option names of a program module typically start with `programs.<package name>`. 124<3> Similarly, for a service module, the names start with `services.<package name>`. Note in some cases a package has both programs _and_ service options – Emacs is such an example. 125 126To activate this configuration you can run 127 128[ source,console ] 129home-manager switch 130 131or if you are not feeling so lucky, 132 133[ source,console ] 134home-manager build 135 136which will create a `result` link to a directory containing an 137activation script and the generated home directory files. 138 139[[sec-usage-rollbacks]] 140=== Rollbacks 141 142While the `home-manager` tool does not explicitly support rollbacks at the moment it is relatively easy to perform one manually. The steps to do so are 143 1441. Run `home-manager generations` to determine which generation you wish to rollback to: 145+ 146[ source,console ] 147---- 148$ home-manager generations 1492018-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation 1502018-01-03 10:29 : id 764 -> /nix/store/2wsmsliqr5yynqkdyjzb1y57pr5q2lsj-home-manager-generation 1512018-01-01 12:21 : id 763 -> /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation 1522017-12-29 21:03 : id 762 -> /nix/store/6c0k1r03fxckql4vgqcn9ccb616ynb94-home-manager-generation 1532017-12-25 18:51 : id 761 -> /nix/store/czc5y6vi1rvnkfv83cs3rn84jarcgsgh-home-manager-generation 154… 155---- 156 1572. Copy the Nix store path of the generation you chose, e.g., 158+ 159---- 160/nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation 161---- 162+ 163for generation 763. 164 1653. Run the `activate` script inside the copied store path: 166+ 167[ source,console ] 168---- 169$ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate 170Starting home manager activation 171… 172---- 173 174[[sec-usage-dotfiles]] 175=== Keeping your ~ safe from harm 176 177To configure programs and services Home Manager must write various things to your home directory. To prevent overwriting any existing files when switching to a new generation, Home Manager will attempt to detect collisions between existing files and generated files. If any such collision is detected the activation will terminate before changing anything on your computer. 178 179For example, suppose you have a wonderful, painstakingly created `~/.config/git/config` and add 180 181[ source,nix ] 182---- 183{ 184# … 185 186programs.git = { 187enable = true; 188userName = "Jane Doe"; 189userEmail = "jane.doe@example.org"; 190}; 191 192# … 193} 194---- 195 196to your configuration. Attempting to switch to the generation will then result in 197 198[ source,console ] 199---- 200$ home-manager switch 201… 202Activating checkLinkTargets 203Existing file '/home/jdoe/.config/git/config' is in the way 204Please move the above files and try again 205---- 206 207[[sec-usage-graphical]] 208=== Graphical services 209 210Home Manager includes a number of services intended to run in a graphical session, for example `xscreensaver` and `dunst`. Unfortunately, such services will not be started automatically unless you let Home Manager start your X session. That is, you have something like 211 212[ source,nix ] 213---- 214{ 215# … 216 217services.xserver.enable = true; 218 219# … 220} 221---- 222 223in your system configuration and 224 225[ source,nix ] 226---- 227{ 228# … 229 230xsession.enable = true; 231xsession.windowManager.command = "…"; 232 233# … 234} 235---- 236 237in your Home Manager configuration. 238 239[[sec-updating]] 240=== Updating 241 242If you have installed Home Manager using the Nix channel method 243then updating Home Manager is done by first updating the channel. 244You can then switch to the updated Home Manager environment. 245 246[ source,console ] 247---- 248$ nix-channel --update 249… 250unpacking channels... 251$ home-manager switch 252----