mirror of
https://github.com/nix-community/home-manager.git
synced 2025-11-08 11:36:05 +01:00
home-manager: avoid profile management during activation
This commit deprecates profile management from the activation script. The profile management is instead the responsibility of the driving software, for example, the `home-manager` tool in the case of standalone installs. The legacy behavior is still available for backwards compatibility but may be removed in the future. The new behavior resolves (or moves us closer to resolving) a number of long standing open issues: - `home-manager switch --rollback`, which performs a rollback to the previous Home Manager generation before activating. While it was previously possible to accomplish this by activating an old generation, it did always create a new profile generation. This option has been implemented as part of this commit. - `home-manager switch --specialisation NAME`, which switches to the named specialisation. While it was previously possible to accomplish this by manually running the specialisation activate script, it did always create a new profile generation. This option has been implemented as part of this commit. - `home-manager switch --test`, which activates the configuration but does not create a new profile generation. This option has _not_ been implemented here since it relies on the current configuration being activated on login, which we do not currently do. - When using the "Home Manager as a NixOS module" installation method we previously created an odd `home-manager` per-user "shadow profile" for the user. This is no longer necessary. This has been implemented as part of this commit. Fixes #3450
This commit is contained in:
Robert Helgesson
parent
e4bf85da68
commit
de448dcb57
21 changed files with 692 additions and 127 deletions
|
|
@ -28,6 +28,8 @@
|
|||
.Cm | packages
|
||||
.Cm | remove-generations Ar ID \&...
|
||||
.Cm | switch
|
||||
.Op Fl -rollback
|
||||
.Op Bro Fl c | Fl -specialisation Brc Ar NAME
|
||||
.Cm | uninstall
|
||||
.Brc
|
||||
.Op Fl A Ar attrPath
|
||||
|
|
@ -157,9 +159,18 @@ sub-command to find suitable generation numbers.
|
|||
.RE
|
||||
.Pp
|
||||
|
||||
.It Cm switch
|
||||
.It Cm switch Oo Fl -rollback Oc Oo Bro Fl c | Fl -specialisation Brc Ar NAME Oc
|
||||
.RS 4
|
||||
Build and activate the configuration\&.
|
||||
.sp
|
||||
If the
|
||||
.Fl -rollback
|
||||
option is given, then the build is not done, instead roll back to and
|
||||
activate the configuration prior to the current configuration\&.
|
||||
.sp
|
||||
If the
|
||||
.Fl -specialisation
|
||||
option is given, then the named specialisation is activated\&.
|
||||
.RE
|
||||
.Pp
|
||||
|
||||
|
|
|
|||
11
docs/manual/internals.md
Normal file
11
docs/manual/internals.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
# Home Manager Internals {#ch-internals}
|
||||
|
||||
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.
|
||||
|
||||
|
||||
```{=include=} sections
|
||||
internals/activation.md
|
||||
```
|
||||
40
docs/manual/internals/activation.md
Normal file
40
docs/manual/internals/activation.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Activation {#sec-internals-activation}
|
||||
|
||||
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
|
||||
{command}`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](#opt-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 {file}`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.
|
||||
|
|
@ -14,6 +14,7 @@ usage.md
|
|||
nix-flakes.md
|
||||
writing-modules.md
|
||||
contributing.md
|
||||
internals.md
|
||||
3rd-party.md
|
||||
faq.md
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,32 +1,45 @@
|
|||
# Rollbacks {#sec-usage-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
|
||||
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.
|
||||
|
||||
1. Run `home-manager generations` to determine which generation you
|
||||
wish to rollback to:
|
||||
::: {.example #ex-rollback-scenario}
|
||||
### Home Manager Rollback
|
||||
|
||||
``` shell
|
||||
$ 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
|
||||
…
|
||||
```
|
||||
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.
|
||||
|
||||
2. Copy the Nix store path of the generation you chose, e.g.,
|
||||
You can then run `home-manager switch --rollback` to recover your
|
||||
previous configuration, which includes the working version of the
|
||||
package.
|
||||
|
||||
/nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
|
||||
To see what happened above we can observe the list of Home Manager
|
||||
generations before and after the rollback:
|
||||
|
||||
for generation 763.
|
||||
``` shell
|
||||
$ 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
|
||||
…
|
||||
|
||||
3. Run the `activate` script inside the copied store path:
|
||||
$ home-manager switch --rollback
|
||||
Starting home manager activation
|
||||
…
|
||||
|
||||
``` shell
|
||||
$ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate
|
||||
Starting home manager activation
|
||||
…
|
||||
```
|
||||
$ home-manager generations
|
||||
2024-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation
|
||||
2024-01-03 10:29 : id 764 -> /nix/store/2wsmsliqr5yynqkdyjzb1y57pr5q2lsj-home-manager-generation (current)
|
||||
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
|
||||
…
|
||||
```
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -7,7 +7,46 @@ section is therefore not final.
|
|||
|
||||
This release has the following notable changes:
|
||||
|
||||
- No 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](#sec-internals-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](#sec-usage-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
|
||||
|
||||
``` nix
|
||||
home-manager.enableLegacyProfileManagement = true;
|
||||
```
|
||||
|
||||
to your configuration. This option is likely to be deprecated in the
|
||||
future.
|
||||
|
||||
## State Version Changes {#sec-release-25.11-state-version-changes}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue