fork/home-manager

git clone https://git.julia.blue/fork/home-manager

Robert HelgessonSwitch stable branch to release-23.0533ccc5c2

master
8.3 KiB252 linesraw
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.
51  home.username = "jdoe";
52  home.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.
62  home.stateVersion = "23.05";
63
64  # Let Home Manager install and manage itself.
65  programs.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.
85  home.username = "jdoe";
86  home.homeDirectory = "/home/jdoe";
87
88  # Packages that should be installed to the user profile.
89  home.packages = [                               <1>
90    pkgs.htop
91    pkgs.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.
102  home.stateVersion = "23.05";
103
104  # Let Home Manager install and manage itself.
105  programs.home-manager.enable = true;
106
107  programs.emacs = {                              <2>
108    enable = true;
109    extraPackages = epkgs: [
110      epkgs.nix-mode
111      epkgs.magit
112    ];
113  };
114
115  services.gpg-agent = {                          <3>
116    enable = true;
117    defaultCacheTtl = 1800;
118    enableSshSupport = 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
186  programs.git = {
187    enable = true;
188    userName = "Jane Doe";
189    userEmail = "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
217  services.xserver.enable = true;
218
219  # …
220}
221----
222
223in your system configuration and
224
225[source,nix]
226----
227{
228  # …
229
230  xsession.enable = true;
231  xsession.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----