unofficial mirror of guix-patches@gnu.org 
 help / color / mirror / code / Atom feed
* [bug#50313] [PATCH] doc: Add Guix Home documentation.
@ 2021-09-01  8:47 Andrew Tropin
  2021-09-01 10:12 ` Oleg Pykhalov
  2021-09-01 11:57 ` [bug#50313] [PATCH] " Xinglu Chen
  0 siblings, 2 replies; 7+ messages in thread
From: Andrew Tropin @ 2021-09-01  8:47 UTC (permalink / raw)
  To: 50313

[-- Attachment #1: Type: text/plain, Size: 29780 bytes --]

* doc/guix.texi: Add Guix Home documentation.
* doc/he-config-bare-bones.texi: Add home-environment example configuration.
---
Reread and updated documentation for Guix Home to reflect latest changes,
still a subject for review and proofreading.  Combined all changes into one
commit.  Sections about Mcron and Shepherd (which are not in wip-guix-home
yet) contains only placeholders, will be updated with patches for related home
services.  There is no section about Gradual Migration to Guix Home and
Invoking guix home's subsection about 'guix home import' subcommand yet, they
are planned, but probably will come later.

 doc/guix.texi | 687 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 687 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 2b8448c856..8a50678a80 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -96,6 +96,7 @@ Copyright @copyright{} 2021 Domagoj Stolfa@*
 Copyright @copyright{} 2021 Hui Lu@*
 Copyright @copyright{} 2021 pukkamustard@*
 Copyright @copyright{} 2021 Alice Brenon@*
+Copyright @copyright{} 2021 Andrew Tropin@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -167,6 +168,7 @@ Weblate} (@pxref{Translating Guix}).
 * Programming Interface::       Using Guix in Scheme.
 * Utilities::                   Package management commands.
 * System Configuration::        Configuring the operating system.
+* Home Configuration::          Configuring the home environment.
 * Documentation::               Browsing software user manuals.
 * Installing Debugging Files::  Feeding the debugger.
 * Security Updates::            Deploying security fixes quickly.
@@ -328,6 +330,10 @@ System Configuration
 * Running Guix in a VM::        How to run Guix System in a virtual machine.
 * Defining Services::           Adding new service definitions.
 
+Home Environment Configuration
+
+* Invoking guix home::          Instantiating a home environment configuration.
+
 Services
 
 * Base Services::               Essential system services.
@@ -35090,6 +35096,687 @@ system:
 This service represents PID@tie{}1.
 @end defvr
 
+@node Home Configuration
+@chapter Home Configuration
+@cindex home configuration
+Guix supports declarative configuration of @dfn{home environment} by
+utilizing the configuration mechanism described in the previous chapter
+(@pxref{Defining Services}), but for user's home. It works both on Guix
+System and foreign distros and allows users to declare all the packages
+that should be installed and configured for the user.  After that, such
+a @dfn{home configuration} can be @dfn{instantiated} by an unprivileged
+user with the @command{guix home} command (@pxref{Invoking guix home}).
+@c Maybe later, it will be possible to make home configuration a part of
+@c system configuration to make everything managed by guix system.
+
+User's home environment usually consists of three basic parts: software,
+configuration and state.  Software in mainstream distros are usually
+installed system-wide, but with GNU Guix most software packages can be
+installed on a per-user basis without needing root privileges, and are
+thus considered part of the user’s @dfn{home environment}.  Packages on
+their own not very useful in many cases, because often they require some
+additional configuration, usually config files that reside in
+@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) or other
+directories.  Everything else can be considered state, like media files,
+application databases, and logs.
+
+Using Guix for managing home environments provides a number of
+advantages:
+
+@itemize
+
+@item All software can be configured in one language (Guile Scheme),
+this gives users to ability to share values between configurations of
+different programs and other benifits.
+
+@item A well-defined home environment is self-contained and can be
+created in a declarative and reproducible way.  There is no need to grab
+external binaries or manually edit some configuration file.
+
+@item After every @command{guix home reconfigure} invocation, a new home
+environment generation will be created.  This means that users can
+rollback to a previous home environment generation so they don’t have to
+worry about breaking their configuration.
+
+@item It is possible to manage stateful data with Guix Home, this
+includes the ability to automatically clone Git repositories on the
+initial setup of the machine, and periodically running commands like
+@command{rsync} to sync data with another host.  This functionality is
+still in an experimental stage, though.
+
+@end itemize
+
+@menu
+* Declaring the Home Environment::  Customizing your Home.
+* Configuring the Shell::     Enabling home environment.
+* Home Services::             Specifying home services.
+* Invoking guix home::        Instantiating a home configuration.
+@end menu
+
+@node Declaring the Home Environment
+@section Declaring the Home Environment
+The home environment is configured by providing @code{home-environment}
+declaration in a file that can be passed to the @command{guix home}
+command (@pxref{Invoking guix home}).  A simple setup can include Bash
+and custom text configuration, like in the example below.  Don't be
+afraid to declare home environment parts, which overlaps with your
+current dotfiles, before installing any configuration files Guix Home
+will back up existing config files to a separate place in the home
+folder.
+
+@quotation Note
+It is highly recommended that you manage your shell or shells with Guix
+Home, because it will make sure that all the necessary scripts are
+sourced by shell configuration file.  Otherwise you will need to do it
+manually. (@pxref{Configuring the Shell}).
+@end quotation
+
+@findex home-environment
+@lisp
+@include he-config-bare-bones.texi
+@end lisp
+
+The @code{packages} field should be self-explanatory, it will install
+the list of packages into the user's profile.  The most important field
+is @code{services}, it contains a list of @dfn{home services}, which are
+the basic building blocks of a home environment.
+
+There is no daemon (at least not necessary) related to home service,
+it's just an element that is used to declare part of home environment
+and extend other parts of it.  The extension mechanism discussed in the
+previous chapter (@pxref{Defining Services}) should not be confused with
+@ref{Shepherd Services}.  Using this extension mechanism and some Scheme
+code that glues things together gives a lot of freedom in declaring of
+very custom home environments.
+
+@node Configuring the Shell
+@section Configuring the Shell
+This section is safe to skip if your shell or shells are managed by
+Guix Home.  Otherwise, read it carefully.
+
+There are a few scripts that must be evaluated by a login shell to
+activate the home environment.  The shell startup files only read by
+login shells often have @code{profile} suffix.  For more information
+about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
+Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
+Reference Manual}.
+
+The first script is @file{setup-environment}, which sets all the
+necessary environment variables (including variables declared by user)
+and the second one is @file{on-first-login}, which starts Shepherd for
+the current user and performs actions declared by other home services
+extending @code{home-run-on-first-login-service-type}.
+
+Guix Home will always create @file{~/.profile}, which contains the
+following lines:
+
+@example
+HOME_ENVIRONMENT=$HOME/.guix-home
+. $HOME_ENVIRONMENT/setup-environment
+$HOME_ENVIRONMENT/on-first-login
+@end example
+
+That makes POSIX compliant login shells activate the home environment.
+However, in most cases this file won't be read by most modern shells,
+because they are run in non POSIX mode by default and have their own
+@file{*profile} startup files.  For example Bash will prefer
+@file{~/.bash_profile} in case it exists and only if it doesn't will it
+fallback to @file{~/.profile}.  Zsh (if no additional options specified)
+will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist.
+
+To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
+@code{source ~/profile} to the startup file for the login shell.  In
+case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
+@file{~/.zprofile}.
+
+@quotation Note
+This step is only required if your shell is NOT managed by Guix Home.
+Otherwise, everything will be done automatically.
+@end quotation
+
+@node Home Services
+@section Home Services
+@cindex home services
+
+A @dfn{home service} is not necessarily something that has a daemon and
+is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
+Manual}), in most cases it doesn't.  It's a simple building block of
+home environment, often declaring a set of packages to be installed in
+the home environment profile, a set of config files to be symlinked into
+@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and
+environment variables to be set by a login shell.
+
+There is a service extension mechanism (@pxref{Service Composition}),
+which allows home services to extend other home services and utilize
+capabilities they provide, for example: declare mcron jobs
+(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
+Service}, declare daemons by extending @ref{Shepherd Home Service}, add
+commands, which will be invoked on by the Bash by extending
+@ref{Shells Home Services, @code{home-bash-service-type}}.
+
+The good way to discover avaliable home services is using the
+@command{guix home search} command (@pxref{Invoking guix home}).  After
+the required home services are found, include its module with the
+@code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
+guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
+directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
+Guile Reference Manual}) and declare a home service using the
+@code{service} function, or extend a service type by declaring a new
+service with the @code{simple-service} procedure from @code{(gnu
+services)}.
+
+@menu
+* Essential Home Services::  Environment variables, packages, on-* scripts.
+* Shells: Shells Home Services.          POSIX shells, Bash, Zsh.
+* Mcron: Mcron Home Service.             Scheduled User's Job Execution.
+* Shepherd: Shepherd Home Service.       Managing User's Daemons.
+@end menu
+@c In addition to that Home Services can provide
+
+@node Essential Home Services
+@subsection Essential Home Services
+There are a few essential services defined in @code{(gnu
+home-services)}, they are mostly for internal use and are required to
+build a home environment, but some of them will be useful for the end
+user.
+
+@cindex environment variables
+
+@defvr {Scheme Variable} home-environment-variables-service-type
+The service of this type will be instantiated by every home environment
+automatically by default, there is no need to define it, but someone may
+want to extend it with a list of pairs to set some environment
+variables.
+
+@lisp
+(list ("ENV_VAR1" . "value1")
+      ("ENV_VAR2" . "value2"))
+@end lisp
+
+The easiest way to extend service type, without defining new service
+type is to use the @code{simple-service} helper from @code{(gnu
+services)}.
+
+@lisp
+(simple-service 'some-useful-env-vars-service
+		home-environment-variables-service-type
+		`(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
+                  ("SHELL" . ,(file-append zsh "/bin/zsh"))
+                  ("USELESS_VAR" . #f)
+                  ("_JAVA_AWT_WM_NONREPARENTING" . #t)))
+@end lisp
+
+If you include such service to you home environment definition, it will
+add the following content to the @file{setup-environment} script (which
+is expected to be sourced by the login shell):
+
+@example
+export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst
+export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh
+export _JAVA_AWT_WM_NONREPARENTING
+@end example
+
+@quotation Note
+Make sure that module @code{(gnu packages shells)} is imported with
+@code{use-modules} or any other way, this namespace contains definition
+of @code{zsh} packages, which is used in the example above.
+@end quotation
+
+
+The key of the association list (@pxref{Association Lists, alists,
+Association Lists, guile, The GNU Guile Reference manual}) is always a
+string, the value can be a string, string-valued gexp
+(@pxref{G-Expressions}) file-like object (@pxref{G-Expressions,
+file-like object}) or boolean. For gexps, the variable will be set to
+the value of the gexp; for file-like objects, it will be set to the path
+of the file in the store (@pxref{The Store}); for @code{#t}, it will
+export the variable without any value; and for @code{#f}, it will omit
+variable.
+
+@end defvr
+
+@defvr {Scheme Variable} home-profile-service-type
+The service of this type will be instantiated by every home environment
+automatically, there is no need to define it, but you may want to extend
+it with a list of packages if you want to install additional packages
+into your profile.  Other services, which need to make some programs
+avaliable to the user will also extend this service type.
+
+The extension value is just a list of packages:
+
+@lisp
+(list htop vim emacs)
+@end lisp
+
+The same approach as @code{simple-service} (@pxref{Service Reference,
+simple-service}) for @code{home-environment-variables-service-type} can
+be used here, too.  Make sure that modules containing the specified
+packages are imported with @code{use-modules}.  To find a package or
+information about its module use @command{guix search} (@pxref{Invoking
+guix package}).  Alternatively, @code{specification->package} can be
+used to get the package record from string without importing related
+module.
+@end defvr
+
+There are few more essential services, but users are not expected to
+extend them.
+
+@defvr {Scheme Variable} home-service-type
+The root of home services DAG, it generates a folder, which later will be
+symlinked to @file{~/.guix-home}, it contains configurations,
+profile with binaries and libraries, and some necessary scripts to glue
+things together.
+@end defvr
+
+@defvr {Scheme Variable} home-run-on-first-login-service-type
+The service of this type generates a Guile script, which is expected to
+be executed by the login shell.  It is only executed if the special flag
+file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
+redundant executions of the script if multiple login shells are spawned.
+
+It Can be extended with a gexp.  However, to autostart an application,
+users SHOULD NOT use this service, in most cases it's better to extend
+@code{home-shpeherd-service-type} with a Shepherd service
+(@pxref{Shepherd Services}), or extend the shell's startup file with
+required command using the appropriate service type.
+@end defvr
+
+@defvr {Scheme Variable} home-activation-service-type
+The service of this type generates a guile script, which runs on every
+@command{guix home reconfigure} invocation or any other action, which
+leads to activation of home environment.
+@end defvr
+
+@node Shells Home Services
+@subsection Shells
+
+@cindex shell
+@cindex login shell
+@cindex interactive shell
+@cindex bash
+@cindex zsh
+
+Shells play a quite important role in the environment initialization
+process, you can configure them manually as described in section
+@ref{Configuring the Shell}, but the recommended way is to use home services
+listed below.  It's both easier and more reliable.
+
+Each home environment instantiates
+@code{home-shell-profile-service-type}, which creates a
+@file{~/.profile} startup file for all POSIX-compatible shells.  This
+file contains all the necessary steps to properly initialize the
+environment, but many modern shells like Bash or Zsh prefer their own
+startup files, that's why the respective home services
+(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
+that @file{~/.profile} is sourced by @file{~/.bash_profile} and
+@file{~/.zprofile}, respectively.
+
+@subsubheading Shell Profile Service
+
+Available @code{home-shell-profile-configuration} fields are:
+
+@deftypevr {@code{home-shell-profile-configuration} parameter} text-config profile
+@code{home-shell-profile} is instantiated automatically by
+@code{home-environment}, DO NOT create this service manually, it can
+only be extended.
+
+@code{profile} is a list of strings or gexps, which will go to
+@file{~/.profile}.  By default @file{~/.profile} contains the
+initialization code, which have to be evaluated by login shell to make
+home-environment's profile avaliable to the user, but other commands can
+be added to the file if it is really necessary.
+
+In most cases shell's configuration files are preferred places for
+user's customizations.  Extend home-shell-profile service only if you
+really know what you do.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@subsubheading Bash Home Service
+
+Available @code{home-bash-configuration} fields are:
+
+@deftypevr {@code{home-bash-configuration} parameter} package package
+The Bash package to use.
+
+@end deftypevr
+
+@deftypevr {@code{home-bash-configuration} parameter} boolean guix-defaults?
+Add sane defaults like reading @file{/etc/bashrc}, coloring output for
+@code{ls} provided by guix to @file{.bashrc}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{home-bash-configuration} parameter} text-config bash-profile
+List of strings or gexps, which will be added to @file{.bash_profile}.
+Used for executing user's commands at start of login shell (In most
+cases the shell started on tty just after login).  @file{.bash_login}
+won't be ever read, because @file{.bash_profile} always present.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{home-bash-configuration} parameter} text-config bashrc
+List of strings or gexps, which will be added to @file{.bashrc}.  Used
+for executing user's commands at start of interactive shell (The shell
+for interactive usage started by typing @code{bash} or by terminal app
+or any other program).
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{home-bash-configuration} parameter} text-config bash-logout
+List of strings or gexps, which will be added to @file{.bash_logout}.
+Used for executing user's commands at the exit of login shell.  It won't
+be read in some cases (if the shell terminates by exec'ing another
+process for example).
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@subsubheading Zsh Home Service
+
+Available @code{home-zsh-configuration} fields are:
+
+@deftypevr {@code{home-zsh-configuration} parameter} package package
+The Zsh package to use.
+
+@end deftypevr
+
+@deftypevr {@code{home-zsh-configuration} parameter} boolean xdg-flavor?
+Place all the configs to @file{$XDG_CONFIG_HOME/zsh}.  Makes
+@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
+Shell startup process will continue with
+@file{$XDG_CONFIG_HOME/zsh/.zshenv}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{home-zsh-configuration} parameter} text-config zshenv
+List of strings or gexps, which will be added to @file{.zshenv}.  Used
+for setting user's shell environment variables.  Must not contain
+commands assuming the presence of tty or producing output.  Will be read
+always.  Will be read before any other file in @env{ZDOTDIR}.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{home-zsh-configuration} parameter} text-config zprofile
+List of strings or gexps, which will be added to @file{.zprofile}.  Used
+for executing user's commands at start of login shell (In most cases the
+shell started on tty just after login).  Will be read before
+@file{.zlogin}.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{home-zsh-configuration} parameter} text-config zshrc
+List of strings or gexps, which will be added to @file{.zshrc}.  Used
+for executing user's commands at start of interactive shell (The shell
+for interactive usage started by typing @code{zsh} or by terminal app or
+any other program).
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogin
+List of strings or gexps, which will be added to @file{.zlogin}.  Used
+for executing user's commands at the end of starting process of login
+shell.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogout
+List of strings or gexps, which will be added to @file{.zlogout}.  Used
+for executing user's commands at the exit of login shell.  It won't be
+read in some cases (if the shell terminates by exec'ing another process
+for example).
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@node Mcron Home Service
+@subsection Scheduled User's Job Execution
+
+@cindex cron
+@cindex mcron
+@cindex scheduling jobs
+
+mcron info here
+
+@node Shepherd Home Service
+@subsection Managing User's Daemons
+shepherd info here
+
+@node Invoking guix home
+@section Invoking @code{guix home}
+
+Once you have written a home environment declaration (@pxref{Declaring
+the Home Environment,,,,}, it can be @dfn{instantiated} using the
+@command{guix home} command.  The synopsis is:
+
+@example
+guix home @var{options}@dots{} @var{action} @var{file}
+@end example
+
+@var{file} must be the name of a file containing a
+@code{home-environment} declaration.  @var{action} specifies how the
+home environment is instantiated, but there are few auxuliary actions,
+which don't instantiate it.  Currently the following values are
+supported:
+
+@table @code
+@item search
+Display available home service type definitions that match the given
+regular expressions, sorted by relevance:
+
+@cindex shell
+@cindex shell-profile
+@cindex bash
+@cindex zsh
+@example
+$ 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
+
+@dots{}
+@end example
+
+As for @command{guix package --search}, the result is written in
+@code{recutils} format, which makes it easy to filter the output
+(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
+
+@item reconfigure
+Build the home environment described in @var{file}, and switch to it.
+Switching means that activation script will be evaluated and (in basic
+scenario) symlinks to configuration files generated from
+@code{home-environment} declaration will be created in @file{~}.  If the
+file with the same path already exists in home folder it will be moved
+to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP
+is a current UNIX epoch time.
+
+@c @footnote{This action (and the related actions
+@c @code{switch-generation} and @code{roll-back}) are usable after home
+@c environmet initialized.}.
+
+@quotation Note
+It is highly recommended to run @command{guix pull} once before you run
+@command{guix home reconfigure} for the first time (@pxref{Invoking guix
+pull}).
+@end quotation
+
+This effects all the configuration specified in @var{file}.
+The command starts shepherd services specified in @var{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
+@code{herd stop X} or @code{herd restart X}).
+
+This command creates a new generation whose number is one greater than
+the current generation (as reported by @command{guix home
+list-generations}).  If that generation already exists, it will be
+overwritten.  This behavior mirrors that of @command{guix package}
+(@pxref{Invoking guix package}).
+
+@cindex provenance tracking, of the home environment
+Upon completion, the new home is deployed under @file{~/.guix-home}.
+This directory contains @dfn{provenance meta-data}: the list of channels
+in use (@pxref{Channels}) and @var{file} itself, when available.  You
+can view it by running:
+
+@example
+guix home describe
+@end example
+
+This information is useful should you later want to inspect how this
+particular generation was built.  In fact, assuming @var{file} is
+self-contained, you can later rebuild generation @var{n} of your
+home environment with:
+
+@example
+guix time-machine \
+  -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
+  home reconfigure \
+  /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm
+
+@end example
+
+You can think of it as some sort of built-in version control!  Your
+home is not just a binary artifact: @emph{it carries its own source}.
+@c @xref{Service Reference, @code{provenance-service-type}}, for more
+@c information on provenance tracking.
+
+@item switch-generation
+@cindex home generations
+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:
+
+@example
+guix home switch-generation 7
+@end example
+
+The target generation can also be specified relative to the current
+generation with the form @code{+N} or @code{-N}, where @code{+3} means
+``3 generations ahead of the current generation,'' and @code{-1} means
+``1 generation prior to the current generation.''  When specifying a
+negative value such as @code{-1}, you must precede it with @code{--} to
+prevent it from being parsed as an option.  For example:
+
+@example
+guix home switch-generation -- -1
+@end example
+
+This action will fail if the specified generation does not exist.
+
+@item roll-back
+@cindex rolling back
+Switch to the preceding home generation.  This is the inverse
+of @command{reconfigure}, and it is exactly the same as invoking
+@command{switch-generation} with an argument of @code{-1}.
+
+@item delete-generations
+@cindex deleting home generations
+@cindex saving space
+Delete home generations, making them candidates for garbage collection
+(@pxref{Invoking guix gc}, for information on how to run the ``garbage
+collector'').
+
+This works in the same way as @samp{guix package --delete-generations}
+(@pxref{Invoking guix package, @option{--delete-generations}}).  With no
+arguments, all home generations but the current one are deleted:
+
+@example
+guix home delete-generations
+@end example
+
+You can also select the generations you want to delete.  The example below
+deletes all the home generations that are more than two month old:
+
+@example
+guix home delete-generations 2m
+@end example
+
+@item build
+Build the derivation of the home environment, which includes all the
+configuration files and programs needed.  This action does not actually
+install anything.
+
+@item describe
+Describe the current home generation: its file name, as well as
+provenance information when available.
+
+@item 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
+@option{--list-generations} option of @command{guix package}
+(@pxref{Invoking guix package}).
+
+Optionally, one can specify a pattern, with the same syntax that is used
+in @command{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:
+
+@example
+$ guix home list-generations 10d
+@end example
+
+@end table
 
 @node Documentation
 @chapter Documentation
-- 
2.33.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

^ permalink raw reply related	[flat|nested] 7+ messages in thread
end of thread, other threads:[~2021-09-03  7:22 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-09-01  8:47 [bug#50313] [PATCH] doc: Add Guix Home documentation Andrew Tropin
2021-09-01 10:12 ` Oleg Pykhalov
2021-09-01 13:32   ` [bug#50313] [PATCH v2] " Andrew Tropin
2021-09-01 15:10     ` bug#50313: " Oleg Pykhalov
2021-09-03  7:21       ` [bug#50313] " Andrew Tropin
2021-09-01 11:57 ` [bug#50313] [PATCH] " Xinglu Chen
2021-09-01 13:28   ` Andrew Tropin

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).