4 files changed, 91 insertions, 4 deletions
diff --git a/lib/path/default.nix b/lib/path/default.nix
index a4a08668ae62e..936e9b0302534 100644
--- a/lib/path/default.nix
+++ b/lib/path/default.nix
@@ -7,6 +7,7 @@ let
     isPath
     split
     match
+    typeOf
     ;
 
   inherit (lib.lists)
@@ -18,6 +19,7 @@ let
     all
     concatMap
     foldl'
+    take
     ;
 
   inherit (lib.strings)
@@ -100,6 +102,22 @@ let
     # An empty string is not a valid relative path, so we need to return a `.` when we have no components
     (if components == [] then "." else concatStringsSep "/" components);
 
+  # Type: Path -> { root :: Path, components :: [ String ] }
+  #
+  # Deconstruct a path value type into:
+  # - root: The filesystem root of the path, generally `/`
+  # - components: All the path's components
+  #
+  # This is similar to `splitString "/" (toString path)` but safer
+  # because it can distinguish different filesystem roots
+  deconstructPath =
+    let
+      recurse = components: base:
+        # If the parent of a path is the path itself, then it's a filesystem root
+        if base == dirOf base then { root = base; inherit components; }
+        else recurse ([ (baseNameOf base) ] ++ components) (dirOf base);
+    in recurse [];
+
 in /* No rec! Add dependencies on this file at the top. */ {
 
   /* Append a subpath string to a path.
@@ -108,6 +126,12 @@ in /* No rec! Add dependencies on this file at the top. */ {
     More specifically, it checks that the first argument is a [path value type](https://nixos.org/manual/nix/stable/language/values.html#type-path"),
     and that the second argument is a valid subpath string (see `lib.path.subpath.isValid`).
 
+    Laws:
+
+    - Not influenced by subpath normalisation
+
+        append p s == append p (subpath.normalise s)
+
     Type:
       append :: Path -> String -> Path
 
@@ -149,6 +173,51 @@ in /* No rec! Add dependencies on this file at the top. */ {
           ${subpathInvalidReason subpath}'';
     path + ("/" + subpath);
 
+  /*
+  Whether the first path is a component-wise prefix of the second path.
+
+  Laws:
+
+  - `hasPrefix p q` is only true if `q == append p s` for some subpath `s`.
+
+  - `hasPrefix` is a [non-strict partial order](https://en.wikipedia.org/wiki/Partially_ordered_set#Non-strict_partial_order) over the set of all path values
+
+  Type:
+    hasPrefix :: Path -> Path -> Bool
+
+  Example:
+    hasPrefix /foo /foo/bar
+    => true
+    hasPrefix /foo /foo
+    => true
+    hasPrefix /foo/bar /foo
+    => false
+    hasPrefix /. /foo
+    => true
+  */
+  hasPrefix =
+    path1:
+    assert assertMsg
+      (isPath path1)
+      "lib.path.hasPrefix: First argument is of type ${typeOf path1}, but a path was expected";
+    let
+      path1Deconstructed = deconstructPath path1;
+    in
+      path2:
+      assert assertMsg
+        (isPath path2)
+        "lib.path.hasPrefix: Second argument is of type ${typeOf path2}, but a path was expected";
+      let
+        path2Deconstructed = deconstructPath path2;
+      in
+        assert assertMsg
+        (path1Deconstructed.root == path2Deconstructed.root) ''
+          lib.path.hasPrefix: Filesystem roots must be the same for both paths, but paths with different roots were given:
+              first argument: "${toString path1}" with root "${toString path1Deconstructed.root}"
+              second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
+        take (length path1Deconstructed.components) path2Deconstructed.components == path1Deconstructed.components;
+
+
   /* Whether a value is a valid subpath string.
 
   - The value is a string
diff --git a/lib/path/tests/default.nix b/lib/path/tests/default.nix
index 9a31e42828f48..6b8e515f43304 100644
--- a/lib/path/tests/default.nix
+++ b/lib/path/tests/default.nix
@@ -24,8 +24,9 @@ pkgs.runCommand "lib-path-tests" {
   export TEST_LIB=$PWD/lib
 
   echo "Running unit tests lib/path/tests/unit.nix"
-  nix-instantiate --eval lib/path/tests/unit.nix \
-    --argstr libpath "$TEST_LIB"
+  nix-instantiate --eval --show-trace \
+    --argstr libpath "$TEST_LIB" \
+    lib/path/tests/unit.nix
 
   echo "Running property tests lib/path/tests/prop.sh"
   bash lib/path/tests/prop.sh ${toString seed}
diff --git a/lib/path/tests/prop.sh b/lib/path/tests/prop.sh
index d6021cfcd5fe2..f321fdf1cf450 100755
--- a/lib/path/tests/prop.sh
+++ b/lib/path/tests/prop.sh
@@ -74,7 +74,7 @@ fi
 
 # Precalculate all normalisations with a single Nix call. Calling Nix for each
 # string individually would take way too long
-nix-instantiate --eval --strict --json \
+nix-instantiate --eval --strict --json --show-trace \
     --argstr libpath "$TEST_LIB" \
     --argstr dir "$tmp/strings" \
     "$SCRIPT_DIR"/prop.nix \
diff --git a/lib/path/tests/unit.nix b/lib/path/tests/unit.nix
index 61c4ab4d6f2ee..9c5b752cf64a3 100644
--- a/lib/path/tests/unit.nix
+++ b/lib/path/tests/unit.nix
@@ -3,7 +3,7 @@
 { libpath }:
 let
   lib = import libpath;
-  inherit (lib.path) append subpath;
+  inherit (lib.path) hasPrefix append subpath;
 
   cases = lib.runTests {
     # Test examples from the lib.path.append documentation
@@ -40,6 +40,23 @@ let
       expected = false;
     };
 
+    testHasPrefixExample1 = {
+      expr = hasPrefix /foo /foo/bar;
+      expected = true;
+    };
+    testHasPrefixExample2 = {
+      expr = hasPrefix /foo /foo;
+      expected = true;
+    };
+    testHasPrefixExample3 = {
+      expr = hasPrefix /foo/bar /foo;
+      expected = false;
+    };
+    testHasPrefixExample4 = {
+      expr = hasPrefix /. /foo;
+      expected = true;
+    };
+
     # Test examples from the lib.path.subpath.isValid documentation
     testSubpathIsValidExample1 = {
       expr = subpath.isValid null;