mirror of
https://github.com/nix-community/home-manager
synced 2024-12-04 17:09:47 +01:00
136 lines
3.5 KiB
Markdown
136 lines
3.5 KiB
Markdown
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:
|
||
|
||
```nix
|
||
{
|
||
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
|
||
|
||
```nix
|
||
{ 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.
|
||
|
||
[Nix]: https://nixos.org/nix/
|
||
[NixOS]: https://nixos.org/
|
||
[Nixpkgs]: https://nixos.org/nixpkgs/
|