nix/2.home-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: move usage section to chapter in manual

Browse source 
Also expand the chapter in various ways.
This commit is contained in:
Robert Helgesson 2021-11-14 00:12:54 +01:00
parent 426830a174
commit 0f5d93119c
No known key found for this signature in database
GPG key ID: 36BDAA14C2797E89
3 changed files with 229 additions and 185 deletions
Download patch file Download diff file Expand all files Collapse all files

187
README.md
View file

@ -132,191 +132,7 @@ checkout of the repository then you can use the
`programs.home-manager.path` option to specify the absolute path to
the repository.
Usage
-----
Home Manager is typically managed through the `home-manager` tool.
This tool can, for example, apply configurations to your home
directory, list user packages installed by the tool, and list the
configuration generations.
As an example, let us expand the initial configuration file from the
installation above to install the htop and fortune packages, install
Emacs with a few extra packages enabled, install Firefox with
smooth scrolling disabled, and enable the user gpg-agent service.
To satisfy the above setup we should elaborate the
`~/.config/nixpkgs/home.nix` file as follows:
```nix
{ pkgs, ... }:
{
home.packages = [
pkgs.htop
pkgs.fortune
];
programs.emacs = {
enable = true;
extraPackages = epkgs: [
epkgs.nix-mode
epkgs.magit
];
};
programs.firefox = {
enable = true;
profiles = {
myprofile = {
settings = {
"general.smoothScroll" = false;
};
};
};
};
services.gpg-agent = {
enable = true;
defaultCacheTtl = 1800;
enableSshSupport = true;
};
programs.home-manager = {
enable = true;
path = "…";
};
}
```
To activate this configuration you can then run
```shell
home-manager switch
```
or if you are not feeling so lucky,
```shell
home-manager build
```
which will create a `result` link to a directory containing an
activation script and the generated home directory files.
Documentation of available configuration options, including
descriptions and usage examples, is available in the [Home Manager
manual][configuration options] or offline by running
```shell
man home-configuration.nix
```
Rollbacks
---------
While 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
1. Run `home-manager generations` to determine which generation you
wish to rollback to:
```console
$ home-manager generations
2018-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation
2018-01-03 10:29 : id 764 -> /nix/store/2wsmsliqr5yynqkdyjzb1y57pr5q2lsj-home-manager-generation
2018-01-01 12:21 : id 763 -> /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
2017-12-29 21:03 : id 762 -> /nix/store/6c0k1r03fxckql4vgqcn9ccb616ynb94-home-manager-generation
2017-12-25 18:51 : id 761 -> /nix/store/czc5y6vi1rvnkfv83cs3rn84jarcgsgh-home-manager-generation
…
```
2. Copy the Nix store path of the generation you chose, e.g.,
/nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
for generation 763.
3. Run the `activate` script inside the copied store path:
```console
$ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate
Starting home manager activation
…
```
Keeping your ~ safe from harm
-----------------------------
To 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.
For example, suppose you have a wonderful, painstakingly created
`~/.config/git/config` and add
```nix
{
# …
programs.git = {
enable = true;
userName = "Jane Doe";
userEmail = "jane.doe@example.org";
};
# …
}
```
to your configuration. Attempting to switch to the generation will
then result in
```console
$ home-manager switch
…
Activating checkLinkTargets
Existing file '/home/jdoe/.config/git/config' is in the way
Please move the above files and try again
```
Graphical services
------------------
Home 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
```nix
{
# …
services.xserver.enable = true;
# …
}
```
in your system configuration and
```nix
{
# …
xsession.enable = true;
xsession.windowManager.command = "…";
# …
}
```
in your Home Manager configuration.
Once installed you can now read the [usage section][manual usage] of the manual.
Nix Flakes
----------
@ -409,6 +225,7 @@ an issue.
[nixosAllowedUsers]: https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers
[Z shell]: http://zsh.sourceforge.net/
[manual]: https://nix-community.github.io/home-manager/
[manual usage]: https://nix-community.github.io/home-manager/#ch-usage
[configuration options]: https://nix-community.github.io/home-manager/options.html
[#home-manager]: https://webchat.oftc.net/?channels=home-manager
[OFTC]: https://oftc.net/