From 08bcd70ecbc0c067a1ce71699c85256c625630ed Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Dec 2025 22:15:45 +0100
Subject: [PATCH 1/2] doc: builtins.path: link to content-address docs for hash
 methods

The sha256 parameter documentation said "file at the path" but it
works with directories too (using NAR hashing). Link to the
content-address documentation instead of duplicating information.
---
 src/libexpr/primops.cc | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index 98b4c129627..bcdd77eaa7d 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -3002,16 +3002,19 @@ static RegisterPrimOp primop_path({
 
         - recursive\
           When `false`, when `path` is added to the store it is with a
-          flat hash, rather than a hash of the NAR serialization of the
-          file. Thus, `path` must refer to a regular file, not a
+          [flat hash](@docroot@/store/file-system-object/content-address.md#serial-flat),
+          rather than a hash of the
+          [NAR serialization](@docroot@/store/file-system-object/content-address.md#serial-nix-archive)
+          of the file. Thus, `path` must refer to a regular file, not a
           directory. This allows similar behavior to `fetchurl`. Defaults
           to `true`.
 
         - sha256\
-          When provided, this is the expected hash of the file at the
-          path. Evaluation fails if the hash is incorrect, and
-          providing a hash allows `builtins.path` to be used even when the
-          `pure-eval` nix config option is on.
+          When provided, this is the expected
+          [content hash](@docroot@/store/file-system-object/content-address.md)
+          of the path. Evaluation fails if the hash is incorrect,
+          and providing a hash allows `builtins.path` to be used even
+          when the `pure-eval` nix config option is on.
     )",
     .fun = prim_path,
 });

From 0068d58b18ab13a809a3692085961efaf91fcb72 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Dec 2025 22:16:54 +0100
Subject: [PATCH 2/2] tests: builtins.path: add explicit directory hash test

Add a test case that explicitly demonstrates NAR hashing of a directory
without using a filter. Add comments to clarify what each test case is
testing (NAR vs flat hashing).
---
 tests/functional/lang/eval-okay-path.exp | 2 +-
 tests/functional/lang/eval-okay-path.nix | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/tests/functional/lang/eval-okay-path.exp b/tests/functional/lang/eval-okay-path.exp
index 635e2243a2a..2698f2f18ce 100644
--- a/tests/functional/lang/eval-okay-path.exp
+++ b/tests/functional/lang/eval-okay-path.exp
@@ -1 +1 @@
-[ "/nix/store/ya937r4ydw0l6kayq8jkyqaips9c75jm-output" "/nix/store/m7y372g6jb0g4hh1dzmj847rd356fhnz-output" ]
+[ "/nix/store/ya937r4ydw0l6kayq8jkyqaips9c75jm-output" "/nix/store/m7y372g6jb0g4hh1dzmj847rd356fhnz-output" "/nix/store/a517xfygy9w2q5i3c2dbm50sw4p70b4c-output" ]
diff --git a/tests/functional/lang/eval-okay-path.nix b/tests/functional/lang/eval-okay-path.nix
index b8b48aae1a6..64b5486b616 100644
--- a/tests/functional/lang/eval-okay-path.nix
+++ b/tests/functional/lang/eval-okay-path.nix
@@ -1,4 +1,5 @@
 [
+  # NAR hash of directory with filter
   (builtins.path {
     path = ./.;
     filter = path: _: baseNameOf path == "data";
@@ -6,10 +7,17 @@
     sha256 = "1yhm3gwvg5a41yylymgblsclk95fs6jy72w0wv925mmidlhcq4sw";
     name = "output";
   })
+  # Flat hash of file
   (builtins.path {
     path = ./data;
     recursive = false;
     sha256 = "0k4lwj58f2w5yh92ilrwy9917pycipbrdrr13vbb3yd02j09vfxm";
     name = "output";
   })
+  # NAR hash of directory (recursive = true is the default)
+  (builtins.path {
+    path = ./dir1;
+    sha256 = "02vlkcjkl1rvy081n6d40qi73biv2w4b9x9biklay4ncgk77zr1f";
+    name = "output";
+  })
 ]