bug: (xdg.configFile.)<name>.recursive = true doesn't work as documented

[Andrew15-5]

Are you following the right branch?

• My Nixpkgs and Home Manager versions are in sync

Is there an existing issue for this?

• I have searched the existing issues

Issue description

https://nix-community.github.io/home-manager/options.xhtml#opt-xdg.configFile._name_.onChange:

Shell commands to run when file has changed between generations. The script will be run after the new files have been linked into place.

Note, this code is always run when recursive is enabled.

I tried that last perk with NixOS 25.05 (nixpkgs unstable) and home-manager master, but it doesn't work.

xdg.configFile."file-immutable.yaml" = {
  recursive = true;
  text = ''
    a: 1
    b:
      ba: "iea"
      bb: 657
    c: 3
  '';
  onChange = ''
    config_dir=''${XDG_CONFIG_HOME:-$HOME/.config}
    file="$config_dir/file.yaml"
    source="$config_dir/file-immutable.yaml"
    if [ -s "$file" ]; then
      ${pkgs.yq-go}/bin/yq ea -i 'select(fi == 1) * select(fi == 0)' \
        "$file" "$source"
    else
      install -m 644 "$source" "$file"
    fi
  '';
};

I tried to run the same config multiple times and the fact that I used recursive = true; did not make the onChange script run, It only was run when text was changed.

Another example:

xdg.configFile."zellij" = {
  recursive = true;
  source = ./config;
};

https://nix-community.github.io/home-manager/options.xhtml#opt-xdg.configFile._name_.recursive:

If the file source is a directory, then this option determines whether the directory should be recursively linked to the target location. This option has no effect if the source is a file.

If false (the default) then the target will be a symbolic link to the source directory. If true then the target will be a directory structure matching the source’s but whose leafs are symbolic links to the files of the source directory.

This supposed to link all internal files separately, but it still links the whole directory, same way if I don't use recursive = true;.

Both use cases say to me that the recursive state is ignored, which is why none of its functionality is working.

This is very useful for debugging onChange code (when creating new stuff), but of course it has many other advantages, and yet I can't take advantage of any of that. :/

Maintainer CC

@emilazy @rycee

System information

- system: `"x86_64-linux"`
 - host os: `Linux 6.12.11, NixOS, 25.05 (Warbler), 25.05.20250129.9d3ae80`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.24.12`
 - nixpkgs: `/nix/store/pgg4vm83q0kr4hxzcwhdgdiv2yfnh3dw-source`

[ayyess]

Probably relates to

This option has no effect if the source is a file.

[Andrew15-5]

The quoted sentence is from paragraph about recursive linking, so it has no effect on that behavior. But from the onChange documentation it explicitly only talks about files and that it will always run off recusive is enabled without any exception.

This actually says to me that the documentation is poorly written as it can cause confusion and misunderstanding, like what you've quoted. It should be more explicit what "no effect" means exactly (it should have an effect if onChange is set) and what happens if source is a directory (instead of a file) and onChange is set. I'm guessing it's exactly the same as with file, but not explicitly mentioned.

But I think it's more important to address the main issue first and only then improve the documentation according to the revised behavior.