depot/third_party/home-manager/docs/release-notes/rl-2003.md

Release 20.03

The 20.03 release branch became the stable branch in April, 2020.

Highlights

This release has the following notable changes:

• Assigning a list to the home.file, xdg.dataFile options is now deprecated and will produce a warning message if used. Specifically, if your configuration currently contains something like

  home.file = [
    {
      target = ".config/foo.txt";
      text = "bar";
    }
  ]
  

  then it should be updated to instead use the equivalent attribute set form

  home.file = {
    ".config/foo.txt".text = "bar";
  }
  

  Support for the list form will be removed in Home Manager version 20.09.

• The lib function attribute given to modules is now enriched with an attribute hm containing extra library functions specific for Home Manager. More specifically, lib.hm is now the same as config.lib and should be the preferred choice since it is more robust.

  Therefore, if your configuration makes use of, for example, config.lib.dag to create activation script blocks, it is recommended to change to lib.hm.dag.

  Note, in the unlikely case that you are

  • using Home Manager's NixOS or nix-darwin module,

  • have made your own Home Manager module containing an top-level option named config or options, and

  • assign to this option in your system configuration inside a plain attribute set, i.e., without a function argument,

  then you must update your configuration to perform the option assignment inside a config attribute. For example, instead of

  home-manager.users.jane = { config = "foo"; };
  

  use

  home-manager.users.jane = { config.config = "foo"; };
  

• The services.compton module has been deprecated and instead the new module services.picom should be used. This is because Nixpkgs no longer packages compton, and instead packages the (mostly) compatible fork called picom.

• The list form of the programs.ssh.matchBlocks option has been deprecated and configurations requiring match blocks in a defined order should switch to using DAG entries instead. For example, a configuration

  programs.ssh.matchBlocks = [
    {
      host = "alpha.foo.com";
      user = "jd";
    }
    {
      host = "*.foo.com";
      user = "john.doe";
    }
  ];
  

  can be expressed along the lines of

  programs.ssh.matchBlocks = {
    "*.example.com" = {
      user = "john.doe";
    }
    "alpha.example.com" = lib.hm.dag.entryBefore ["*.example.com"] {
      user = "jd";
    }
  };
  

  Support for the list form will be removed in Home Manager version 20.09.

State Version Changes

The state version in this release includes the changes below. These changes are only active if the home.stateVersion option is set to "20.03" or later.

• The programs.zsh.history.path option is no longer prepended by $HOME, which allows specifying absolute paths, for example, using the xdg module. Also, the default value is fixed to $HOME/.zsh_history and dotDir path is not prepended to it anymore.

• The newsboat module will now default in displaying queries before urls in its main window. This makes sense in the case when one has a lot of URLs and few queries.