Skip to content

Commit

Permalink
Adjust wording for usage of escape with exec (#1128)
Browse files Browse the repository at this point in the history
With v2, shell must always be truthy (actually, always `shell: true` is
even incorrect in general, because it should be the child_process
`shell` option value if present) so the removed statement is a bit
redundant. Instead, more direct language is introduced to indicate that
doing this should really be a last resort.

Also, move up the caveats to increase the likelihood of them being
noticed by the reader.
  • Loading branch information
ericcornelissen authored Aug 18, 2023
1 parent 7fba808 commit a86dcbb
Showing 1 changed file with 8 additions and 9 deletions.
17 changes: 8 additions & 9 deletions docs/recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,14 @@ try {
#### With `Shescape#escape`

If you find yourself in a situation where the inputted argument to `exec` cannot
be quoted, you can use `Shescape#escape` but must have `shell: true`.
be quoted, you can use `Shescape#escape` though this is not advised. This will
escape as much as possible - including whitespace in order to preserve it and
prevent argument splitting. This comes with some caveats:

- For all shells newlines (`\r?\n`) are always replaced by a single space.
- On Windows, cmd.exe does not support whitespace preservation. So, if argument
splitting is a concern, use `Shescape#quote` instead.
- On Windows, PowerShell will strip whitespace at the beginning of arguments.

> **Warning**: If possible, it is advised to rewrite your code so that you can
> use `Shescape#quote` as shown above. Or use a different function from the
Expand Down Expand Up @@ -174,14 +181,6 @@ exec(`echo Hello ${shescape.escape(userInput)}`, (error, stdout) => {
});
```

This will also escape whitespace in order to preserve it and prevent argument
splitting. Note that:

- For all shells newlines (`\r?\n`) are always replaced by a single space.
- On Windows, cmd.exe does not support whitespace preservation. So, if argument
splitting is a concern, use `Shescape#quote` instead.
- On Windows, PowerShell will strip whitespace at the beginning of arguments.

### [`execFile`] / [`execFileSync`]

#### `execFile(file, args, callback)`
Expand Down

0 comments on commit a86dcbb

Please sign in to comment.