Skip to content

Commit

Permalink
doc: revise introductory child_process text
Browse files Browse the repository at this point in the history
This consolidates information about Windows environment variables and
has a few other smaller improvements (punctuation, present tense, etc.).

Co-authored-by: Shelley Vohr <codebytere@gmail.com>

PR-URL: #35296
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
  • Loading branch information
Trott committed Sep 25, 2020
1 parent 785a5f9 commit 52dd524
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 16 deletions.
31 changes: 15 additions & 16 deletions doc/api/child_process.md
Expand Up @@ -6,7 +6,7 @@
<!-- source_link=lib/child_process.js -->

The `child_process` module provides the ability to spawn child processes in
The `child_process` module provides the ability to spawn subprocesses in
a manner that is similar, but not identical, to popen(3). This capability
is primarily provided by the [`child_process.spawn()`][] function:

Expand All @@ -28,24 +28,23 @@ ls.on('close', (code) => {
```

By default, pipes for `stdin`, `stdout`, and `stderr` are established between
the parent Node.js process and the spawned child. These pipes have
limited (and platform-specific) capacity. If the child process writes to
stdout in excess of that limit without the output being captured, the child
process will block waiting for the pipe buffer to accept more data. This is
the parent Node.js process and the spawned subprocess. These pipes have
limited (and platform-specific) capacity. If the subprocess writes to
stdout in excess of that limit without the output being captured, the
subprocess blocks 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.

On Windows Node.js will sanitize the `env` by removing case-insensitive
duplicates. Only first (in lexicographic order) entry will be passed to the
child process.
The command lookup is performed using the `options.env.PATH` environment
variable if it is in the `options` object. Otherwise, `process.env.PATH` is
used.

On Windows, environment variables are case-insensitive. Node.js
lexicographically sorts the `env` keys and uses the first one that
case-insensitively matches. Only first (in lexicographic order) entry will be
passed to the subprocess. This may lead to issues on Windows when passing
objects to `env` option that have multiple variants of the same key, such as
`PATH` and `Path`.

The [`child_process.spawn()`][] method spawns the child process asynchronously,
without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
Expand Down
8 changes: 8 additions & 0 deletions doc/guides/collaborator-guide.md
Expand Up @@ -469,6 +469,12 @@ code. If you wish to create the token yourself in advance, see

### Technical HOWTO

Infrequently, it is necessary to manually perform the steps required to land a
pull request rather than rely on `git-node`.

<details>
<summary>Manual landing steps</summary>

Clear any `am`/`rebase` that might already be underway:

```text
Expand Down Expand Up @@ -626,6 +632,8 @@ your pull request shows the purple merged status,
add the "Landed in \<commit hash>..\<commit hash>" comment if you added
more than one commit.

</details>

### Troubleshooting

Sometimes, when running `git push upstream master`, you might get an error
Expand Down

0 comments on commit 52dd524

Please sign in to comment.