11.4 Invoking guix home

Once you have written a home environment declaration (see Declaring the Home Environment, it can be instantiated using the guix home command. The synopsis is:

guix home options… action file

file must be the name of a file containing a home-environment declaration. action specifies how the home environment is instantiated, but there are few auxiliary actions which don’t instantiate it. Currently the following values are supported:

search

Display available home service type definitions that match the given regular expressions, sorted by relevance:

$ guix home search shell
name: home-shell-profile
location: gnu/home/services/shells.scm:73:2
extends: home-files
description: Create `~/.profile', which is used for environment initialization
+ of POSIX compatible login shells.  Can be extended with a list of strings or
+ gexps.
relevance: 6

name: home-zsh-plugin-manager
location: gnu/home/services/shellutils.scm:28:2
extends: home-zsh home-profile
description: Install plugins in profile and configure Zsh to load them.
relevance: 1

name: home-zsh-direnv
location: gnu/home/services/shellutils.scm:69:2
extends: home-profile home-zsh
description: Enables `direnv' for `zsh'.  Adds hook to `.zshrc' and installs a
+ package in the profile.
relevance: 1

name: home-zsh-autosuggestions
location: gnu/home/services/shellutils.scm:43:2
extends: home-zsh-plugin-manager home-zsh
description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and
+ sets reasonable default values for some plugin's variables to improve perfomance
+ and adjust behavior: `(history completion)' is set for strategy, manual rebind
+ and async are enabled.
relevance: 1

name: home-zsh
location: gnu/home/services/shells.scm:236:2
extends: home-files home-profile
description: Install and configure Zsh.
relevance: 1

name: home-bash
location: gnu/home/services/shells.scm:388:2
extends: home-files home-profile
description: Install and configure Bash.
relevance: 1

…

As for guix package --search, the result is written in recutils format, which makes it easy to filter the output (see GNU recutils databases in GNU recutils manual).

reconfigure

Build the home environment described in file, and switch to it. Switching means that the activation script will be evaluated and (in basic scenario) symlinks to configuration files generated from home-environment declaration will be created in ~. If the file with the same path already exists in home folder it will be moved to ~/TIMESTAMP-guix-home-legacy-configs-backup, where TIMESTAMP is a current UNIX epoch time.

Note: It is highly recommended to run guix pull once before you run guix home reconfigure for the first time (see Invoking guix pull).

This effects all the configuration specified in file. The command starts Shepherd services specified in file that are not currently running; if a service is currently running, this command will arrange for it to be upgraded the next time it is stopped (e.g. by herd stop X or herd restart X).

This command creates a new generation whose number is one greater than the current generation (as reported by guix home list-generations). If that generation already exists, it will be overwritten. This behavior mirrors that of guix package (see Invoking guix package).

Upon completion, the new home is deployed under ~/.guix-home. This directory contains provenance meta-data: the list of channels in use (see Channels) and file itself, when available. You can view the provenance information by running:

guix home describe

This information is useful should you later want to inspect how this particular generation was built. In fact, assuming file is self-contained, you can later rebuild generation n of your home environment with:

guix time-machine \
  -C /var/guix/profiles/per-user/USER/guix-home-n-link/channels.scm -- \
  home reconfigure \
  /var/guix/profiles/per-user/USER/guix-home-n-link/configuration.scm

You can think of it as some sort of built-in version control! Your home is not just a binary artifact: it carries its own source.

switch-generation

Switch to an existing home generation. This action atomically switches the home profile to the specified home generation.

The target generation can be specified explicitly by its generation number. For example, the following invocation would switch to home generation 7:

guix home switch-generation 7

The target generation can also be specified relative to the current generation with the form +N or -N, where +3 means “3 generations ahead of the current generation,” and -1 means “1 generation prior to the current generation.” When specifying a negative value such as -1, you must precede it with -- to prevent it from being parsed as an option. For example:

guix home switch-generation -- -1

This action will fail if the specified generation does not exist.

roll-back

Switch to the preceding home generation. This is the inverse of reconfigure, and it is exactly the same as invoking switch-generation with an argument of -1.

delete-generations

Delete home generations, making them candidates for garbage collection (see Invoking guix gc, for information on how to run the “garbage collector”).

This works in the same way as ‘guix package --delete-generations’ (see --delete-generations). With no arguments, all home generations but the current one are deleted:

guix home delete-generations

You can also select the generations you want to delete. The example below deletes all the home generations that are more than two months old:

guix home delete-generations 2m

build

Build the derivation of the home environment, which includes all the configuration files and programs needed. This action does not actually install anything.

describe

Describe the current home generation: its file name, as well as provenance information when available.

list-generations

List a summary of each generation of the home environment available on disk, in a human-readable way. This is similar to the --list-generations option of guix package (see Invoking guix package).

Optionally, one can specify a pattern, with the same syntax that is used in guix package --list-generations, to restrict the list of generations displayed. For instance, the following command displays generations that are up to 10 days old:

$ guix home list-generations 10d

import

Generate a home environment from the packages in the default profile and configuration files found in the user’s home directory. The configuration files will be copied to the specified directory, and a home-configuration.scm will be populated with the home environment. Note that not every home service that exists is supported (see Home Services).

$ guix home import ~/guix-config
guix home: '/home/alice/guix-config' populated with all the Home configuration files

options can contain any of the common build options (see Common Build Options). In addition, options can contain one of the following:

--expression=expr

-e expr

Consider the home-environment expr evaluates to. This is an alternative to specifying a file which evaluates to a home environment.