doc: clear up child_process command resolution

lundibundi · MylesBorins · commit af73ed632c78 · 2020-03-11T16:23:30.000-04:00
Fixes: #20605 Refs: libuv/libuv#1837 PR-URL: #32091 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Bartosz Sosnowski <bartosz@janeasystems.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
diff --git a/doc/api/child_process.md b/doc/api/child_process.md
@@ -33,6 +33,14 @@ process will block waiting for the pipe buffer to accept more data. This is
 identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`
 option if the output will not be consumed.
 
+The command lookup will be performed using `options.env.PATH` environment
+variable if passed in `options` object, otherwise `process.env.PATH` will be
+used. To account for the fact that Windows environment variables are
+case-insensitive Node.js will lexicographically sort all `env` keys and choose
+the first one case-insensitively matching `PATH` to perform command lookup.
+This may lead to issues on Windows when passing objects to `env` option that
+have multiple variants of `PATH` variable.
+
 The [`child_process.spawn()`][] method spawns the child process asynchronously,
 without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
 function provides equivalent functionality in a synchronous manner that blocks
