From 2dedeb55b2c140d9a123ae931588e8903fe202ef Mon Sep 17 00:00:00 2001
From: Vinicius Deolindo <git@vini.cat>
Date: Wed, 11 Feb 2026 12:09:58 -0300
Subject: [PATCH] man: make `package` nullable and default to `null` on darwin

---
 docs/release-notes/rl-2605.md                 |  6 ++++++
 modules/programs/man.nix                      | 21 ++++++++++++++++---
 tests/modules/programs/man/default.nix        |  6 ++++++
 .../man/no-caches-without-package.nix         | 19 +++++++++++++++++
 .../programs/man/no-package-on-darwin.nix     | 12 +++++++++++
 5 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 tests/modules/programs/man/no-caches-without-package.nix
 create mode 100644 tests/modules/programs/man/no-package-on-darwin.nix

diff --git a/docs/release-notes/rl-2605.md b/docs/release-notes/rl-2605.md
index 848802dd..020e95f5 100644
--- a/docs/release-notes/rl-2605.md
+++ b/docs/release-notes/rl-2605.md
@@ -36,3 +36,9 @@ changes are only active if the `home.stateVersion` option is set to
   you had the key `XDG_DESKTOP_DIR` before, you should now use the key
   `DESKTOP`. Home Manager 26.05 introduced a warning when the `XDG_<name>_DIR`
   form is used.
+
+- The [](#opt-programs.man.package) option now defaults to `null` on
+  Darwin because the GNU `man` from nixpkgs ships `apropos`/`man -k`
+  and `whatis`/`man -f` binaries that don't work on Darwin. Nix-installed
+  manual pages still work with macOS's built-in `man` via
+  [](#opt-home.extraOutputsToInstall).
diff --git a/modules/programs/man.nix b/modules/programs/man.nix
index 3b41eb34..dc062e39 100644
--- a/modules/programs/man.nix
+++ b/modules/programs/man.nix
@@ -21,7 +21,18 @@ in
         '';
       };
 
-      package = lib.mkPackageOption pkgs "man" { };
+      package = mkOption {
+        type = with types; nullOr package;
+        default =
+          if pkgs.stdenv.isDarwin && lib.versionAtLeast config.home.stateVersion "26.05" then
+            null
+          else
+            pkgs.man;
+        defaultText = lib.literalExpression ''
+          if pkgs.stdenv.isDarwin && lib.versionAtLeast config.home.stateVersion "26.05" then null else pkgs.man
+        '';
+        description = "The {command}`man` package to use.";
+      };
 
       extraConfig = mkOption {
         type = types.lines;
@@ -51,11 +62,15 @@ in
   };
 
   config = lib.mkIf cfg.enable {
-    home.packages = [ cfg.package ];
+    warnings = lib.optional (
+      cfg.generateCaches && cfg.package == null
+    ) "programs.man.generateCaches has no effect when programs.man.package is null";
+
+    home.packages = lib.optional (cfg.package != null) cfg.package;
     home.extraOutputsToInstall = [ "man" ];
 
     # This is mostly copy/pasted/adapted from NixOS' documentation.nix.
-    home.file = lib.mkIf cfg.generateCaches {
+    home.file = lib.mkIf (cfg.generateCaches && cfg.package != null) {
       ".manpath".text =
         let
           # Generate a directory containing installed packages' manpages.
diff --git a/tests/modules/programs/man/default.nix b/tests/modules/programs/man/default.nix
index 2e9d340f..9b066db7 100644
--- a/tests/modules/programs/man/default.nix
+++ b/tests/modules/programs/man/default.nix
@@ -1,4 +1,10 @@
+{ lib, pkgs, ... }:
+
 {
   man-apropos = ./apropos.nix;
   man-no-manpath = ./no-manpath.nix;
+  man-no-caches-without-package = ./no-caches-without-package.nix;
+}
+// lib.optionalAttrs pkgs.stdenv.hostPlatform.isDarwin {
+  man-no-package-on-darwin = ./no-package-on-darwin.nix;
 }
diff --git a/tests/modules/programs/man/no-caches-without-package.nix b/tests/modules/programs/man/no-caches-without-package.nix
new file mode 100644
index 00000000..6ec8b4a7
--- /dev/null
+++ b/tests/modules/programs/man/no-caches-without-package.nix
@@ -0,0 +1,19 @@
+{
+  config = {
+    home.stateVersion = "26.05";
+
+    programs.man = {
+      enable = true;
+      package = null;
+      generateCaches = true;
+    };
+
+    test.asserts.warnings.expected = [
+      "programs.man.generateCaches has no effect when programs.man.package is null"
+    ];
+
+    nmt.script = ''
+      assertPathNotExists home-files/.manpath
+    '';
+  };
+}
diff --git a/tests/modules/programs/man/no-package-on-darwin.nix b/tests/modules/programs/man/no-package-on-darwin.nix
new file mode 100644
index 00000000..7ec15a0e
--- /dev/null
+++ b/tests/modules/programs/man/no-package-on-darwin.nix
@@ -0,0 +1,12 @@
+{
+  config = {
+    home.stateVersion = "26.05";
+
+    programs.man.enable = true;
+
+    nmt.script = ''
+      assertPathNotExists home-path/bin/man
+      assertPathNotExists home-files/.manpath
+    '';
+  };
+}