doc: note that path.normalize deviates from POSIX

PR-URL: #51513 Refs: #51345 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
nodejs · Feb 15, 2024 · 177e13c · 177e13c
1 parent a04aa36
commit 177e13c
Showing 1 changed file with 8 additions and 0 deletions.
diff --git a/doc/api/path.md b/doc/api/path.md
@@ -361,6 +361,14 @@ instance of the platform-specific path segment separator (`/` on POSIX and
 If the `path` is a zero-length string, `'.'` is returned, representing the
 current working directory.
 
+On POSIX, the types of normalization applied by this function do not strictly
+adhere to the POSIX specification. For example, this function will replace two
+leading forward slashes with a single slash as if it was a regular absolute
+path, whereas a few POSIX systems assign special meaning to paths beginning with
+exactly two forward slashes. Similarly, other substitutions performed by this
+function, such as removing `..` segments, may change how the underlying system
+resolves the path.
+
 For example, on POSIX:
 
 ```js