Table of Contents
ca.desrt.dconf or dconf.service? Table of Contents
ca.desrt.dconf or dconf.service? List of Examples
This manual will eventually describe how to install, use, and extend Home Manager.
If you encounter problems then please reach out on the IRC channel #home-manager @@ -338,21 +338,35 @@ programs and service options – Emacs is
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.
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
Run home-manager generations to determine which generation you
-wish to rollback to:
$ 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
+When you perform a home-manager switch and discover a problem then
+it is possible to roll back to the previous version of your
+configuration using home-manager switch --rollback. This will turn
+the previous configuration into the current configuration.
Imagine you have just updated Nixpkgs and switched to a new Home +Manager configuration. You discover that a package update included in +your new configuration has a bug that was not present in the previous +configuration.
You can then run home-manager switch --rollback to recover your
+previous configuration, which includes the working version of the
+package.
To see what happened above we can observe the list of Home Manager +generations before and after the rollback:
$ home-manager generations
+2024-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation (current)
+2024-01-03 10:29 : id 764 -> /nix/store/2wsmsliqr5yynqkdyjzb1y57pr5q2lsj-home-manager-generation
+2024-01-01 12:21 : id 763 -> /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
+2023-12-29 21:03 : id 762 -> /nix/store/6c0k1r03fxckql4vgqcn9ccb616ynb94-home-manager-generation
+2023-12-25 18:51 : id 761 -> /nix/store/czc5y6vi1rvnkfv83cs3rn84jarcgsgh-home-manager-generation
…
-Copy the Nix store path of the generation you chose, e.g.,
/nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
-for generation 763.
Run the activate script inside the copied store path:
$ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate
+
+$ home-manager switch --rollback
Starting home manager activation
…
-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 @@ -952,6 +966,40 @@ use instead e.g.
$ nix build --refer
Some tests may be marked with enableLegacyIfd, those may be run by run with e.g.
$ nix-build --pure tests --arg enableLegacyIfd true -A build.mytest
This chapter collects some documentation about the internal workings +of Home Manager. The information here is mostly aimed to developers of +Home Manager and those who do non-trivial integration with Home +Manager.
Table of Contents
Activating a Home Manager configuration ensures that the built +configuration is introduced into the user’s environment. The +activation is performed by a suitably named script +activate. This script is generated as part of the +configuration build and is placed in the root of the build output.
The activation script is implemented in the Bash language and consists +of initialization code followed by a number of activation script +blocks. These blocks are specified using the +home.activation option. The blocks may have +dependencies among themselves and the generated activation script will +contain the blocks serialized such that the dependencies are +satisfied. A dependency cycle causes a failure when the configuration +is built.
Historically, the activation script has been responsible for creating
+a new generation of the home-manager Nix profile. The more modern
+way, however, is to let the activation driver – that is, the
+software calling the activation script – manage the profile. Indeed,
+in some cases we may not have a home-manager profile at all! This is
+the case when Home Manager is used as a NixOS or nix-darwin module, in
+these cases the system profile will contain references to the
+corresponding Home Manager configurations.
Note, to maintain backwards compatibility, the old activation script
+behavior is still the default. To choose the new mode of operation you
+have to call the activation script with the command line option
+--driver-version 1. The old behavior is available using
+--driver-version 0, or simply omit it entirely.
Unfortunately, driver software need to support both modes of operation
+for the time being since a user may wish to activate an old generation
+that contains an activation script that does not support
+--driver-version. To determine whether support is available, check
+the gen-version file in the configuration build output root.
+If the file is missing then the activation script does not support
+--driver-version. If the file exists and contains the integer 1 or
+higher, then --driver-version 1 is supported.
Here is a collection of tools and extensions that relate to Home Manager. Note, these are maintained outside the regular Home Manager flow so quality and support may vary wildly. If you encounter problems diff --git a/nix-darwin-options.xhtml b/nix-darwin-options.xhtml index 09f26f295..e84f30e67 100644 --- a/nix-darwin-options.xhtml +++ b/nix-darwin-options.xhtml @@ -27,6 +27,35 @@
home-manager.enableLegacyProfileManagement
+
+
+Whether to enable legacy profile (and garbage collection root)
+management during activation. When enabled, the Home Manager activation
+will produce a per-user home-manager Nix profile as well as a garbage
+collection root, just like in the standalone installation of Home
+Manager. Typically, this is not desired when Home Manager is embedded in
+the system configuration.
Type: +boolean
+ +Default:
+false
Declared by:
+
+
+<home-manager/nixos/common.nix>
+
+ |
home-manager.backupFileExtension
diff --git a/nixos-options.xhtml b/nixos-options.xhtml
index c89e0741a..a04ce676f 100644
--- a/nixos-options.xhtml
+++ b/nixos-options.xhtml
@@ -27,6 +27,35 @@
home-manager.enableLegacyProfileManagement
+
+
+Whether to enable legacy profile (and garbage collection root)
+management during activation. When enabled, the Home Manager activation
+will produce a per-user home-manager Nix profile as well as a garbage
+collection root, just like in the standalone installation of Home
+Manager. Typically, this is not desired when Home Manager is embedded in
+the system configuration.
Type: +boolean
+ +Default:
+false
Declared by:
+
+
+<home-manager/nixos/common.nix>
+
+ |
home-manager.backupFileExtension
diff --git a/release-notes.xhtml b/release-notes.xhtml
index 8bf2aaa9d..3f4603e84 100644
--- a/release-notes.xhtml
+++ b/release-notes.xhtml
@@ -26,7 +26,32 @@
Table of Contents
This section lists the release notes for stable versions of Home Manager and the current unstable version.
Table of Contents
This is the current unstable branch and the information in this -section is therefore not final.
This release has the following notable changes:
No changes.
This release has the following notable changes:
Updating the home-manager Nix profile inside the activation script
+now deprecated. The profile update is instead the responsibility of
+the software calling the activation script, such as the
+home-manager tool.
The legacy behavior remains the default for backwards compatibility +but may emit a deprecation warning in the future and in the longer +term removed all together. If you have developed tooling that +directly call the generated activation script, then you are +encouraged to adapt to the new behavior. See the +Activation section in the manual for +details on how to call the activation script.
The home-manager switch command now offers a --rollback option.
+When given, the switch performs a rollback to the Home Manager
+generation prior to the current before activating. While it was
+previously possible to accomplish this by manually activating an old
+generation, it always created a new profile generation. The new
+behavior mirrors the behavior of nixos-rebuild switch --rollback.
+See the Rollbacks section for more.
The home-manager switch command now offers a
+--specialisation NAME option. When given, the switch activates the
+named specialisation. While it was previously possible to accomplish
+this by manually running the specialisation activate script it was
+quite cumbersome and always created a new profile generation. The
+new behavior mirrors the behavior of nixos-rebuild switch --specialisation.
When using Home Manager as a NixOS or nix-darwin module we
+previously created an unnecessary home-manager per-user “shadow
+profile” for the user. This no longer happens. You can restore the
+old behavior by adding
home-manager.enableLegacyProfileManagement = true;
+to your configuration. This option is likely to be deprecated in the +future.
The state version in this release includes the changes below. These
changes are only active if the home.stateVersion option is set to
"25.11" or later.
No changes.