Debugging

docs/api.md

@@ -1170,7 +1170,7 @@ _Default:_ `true` if the [`shell`](#optionsshell) option is `true`, `false` othe
 
 If `false`, escapes the command arguments on Windows.
 
-[More info.](windows.md#cmdexe-escaping)
+[More info.](windows.md#escaping)
 
 ## Verbose function
 

docs/windows.md

@@ -34,22 +34,33 @@ The default value for the [`stdin`](api.md#optionsstdin), [`stdout`](api.md#opti
 
 Instead of `'pipe'`, `'overlapped'` can be used instead to use [asynchronous I/O](https://learn.microsoft.com/en-us/windows/win32/fileio/synchronous-and-asynchronous-i-o) under-the-hood on Windows, instead of the default behavior which is synchronous. On other platforms, asynchronous I/O is always used, so `'overlapped'` behaves the same way as `'pipe'`.
 
-## Powershell
+## Escaping
 
-Windows typically requires files and arguments to be quoted when they contain spaces, tabs, backslashes or double quotes. Execa performs that quoting automatically.
+Windows requires files and arguments to be quoted when they contain spaces, tabs, backslashes or double quotes. Unlike Unix, this is needed even when no [shell](shell.md) is used.
 
-However, when using a [`cmd.exe`](https://en.wikipedia.org/wiki/Cmd.exe) shell (for example with the [`shell: true`](api.md#optionsshell) option), users must manually perform that quoting instead. It mostly involves double quoting arguments, and prepending double quotes with a backslash. The quoting rules are different from Unix shells.
+When not using any shell, Execa performs that quoting automatically. This ensures files and arguments are split correctly.
+
+```js
+await execa`npm run ${'task with space'}`;
+```
+
+When using a [shell](shell.md), the user must manually perform shell-specific quoting, on both Unix and Windows. When the [`shell`](api.md#optionsshell) option is `true`, [`cmd.exe`](https://en.wikipedia.org/wiki/Cmd.exe) is used on Windows and `sh` on Unix. Unfortunately both shells use different quoting rules. With `cmd.exe`, this mostly involves double quoting arguments and prepending double quotes with a backslash.
 
 ```js
 if (isWindows) {
-	await execa({shell: true})`npm run "task with space"`;
+	await execa({shell: true})`npm run ${'"task with space"'}`;
+} else {
+	await execa({shell: true})`npm run ${'\'task with space\''}`;
 }
 ```
 
-When using other Windows shells (such as Powershell), that `cmd.exe`-specific automatic quoting must be manually disabled using
-the [`windowsVerbatimArguments: true`](api.md#optionswindowsverbatimarguments) option.
+When using other Windows shells (such as Powershell or WSL), Execa performs `cmd.exe`-specific automatic quoting by default. This is a problem since Powershell uses different quoting rules. This can be disabled using the [`windowsVerbatimArguments: true`](api.md#optionswindowsverbatimarguments) option.
 
-Please note that the automatic quoting performed by `windowsVerbatimArguments: false` only helps with ensuring files and arguments are split correctly. It does not escape every possible `cmd.exe`-specific shell character. Therefore, to prevent against command injection, [`shell: false`](shell.md) should be used.
+```js
+if (isWindows) {
+	await execa({windowsVerbatimArguments: true})`wsl ...`;
+}
+```
 
 ## Console window