From a72636bc4d904626373b822a7183d28119d4d8bc Mon Sep 17 00:00:00 2001
From: reillylm <reillylm@users.noreply.github.com>
Date: Fri, 16 Jan 2026 15:26:01 -0500
Subject: [PATCH] doc, child_process: clean up Windows example

In #53616, we added MJS snippets for the page. In the section about
Windows batch files, we also combined two previous snippets who
demonstrated the three ways of using `spawn`/`exec` described in the above
paragraph.

The first snippet showed the `spawn` of `cmd.exe` way:

https://github.com/nodejs/node/blob/dc74f17f6c37b1bb2d675216066238f33790ed29/doc/api/child_process.md?plain=1#L112-L114

The other snippet showed the `exec` and `spawn` with `shell: true`
ways:

https://github.com/nodejs/node/blob/dc74f17f6c37b1bb2d675216066238f33790ed29/doc/api/child_process.md?plain=1#L130-L132
https://github.com/nodejs/node/blob/dc74f17f6c37b1bb2d675216066238f33790ed29/doc/api/child_process.md?plain=1#L141

This makes these changes:

- remove the `// OR...` comment, since we only have one snippet now, so
  there's nothing to "or" with :)
- bring back the `spawn('cmd.exe')` example, which got lost in the
  shuffle
- reorder the examples to match the way they're presented in the
  paragraph
- remove the `exec` callback body, since the focus of the snippet is
  just the invocations of `spawn`/`exec`, not the usage of `exec`
  specifically
- split the prose of the three ways into a list so it's easier to read
---
 doc/api/child_process.md | 62 ++++++++++++++++++----------------------
 1 file changed, 28 insertions(+), 34 deletions(-)

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index e3273446c3e517..6818eec4594b25 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -118,51 +118,45 @@ operating systems (Unix, Linux, macOS) [`child_process.execFile()`][] can be
 more efficient because it does not spawn a shell by default. On Windows,
 however, `.bat` and `.cmd` files are not executable on their own without a
 terminal, and therefore cannot be launched using [`child_process.execFile()`][].
-When running on Windows, `.bat` and `.cmd` files can be invoked using
-[`child_process.spawn()`][] with the `shell` option set, with
-[`child_process.exec()`][], or by spawning `cmd.exe` and passing the `.bat` or
-`.cmd` file as an argument (which is what the `shell` option and
-[`child_process.exec()`][] do). In any case, if the script filename contains
-spaces it needs to be quoted.
+When running on Windows, `.bat` and `.cmd` files can be invoked by:
+
+* using [`child_process.spawn()`][] with the `shell` option set, or
+* using [`child_process.exec()`][], or
+* spawning `cmd.exe` and passing the `.bat` or `.cmd` file as an argument
+  (which is what the `shell` option and [`child_process.exec()`][] do).
+
+In any case, if the script filename contains spaces, it needs to be quoted.
 
 ```cjs
-// OR...
 const { exec, spawn } = require('node:child_process');
 
-exec('my.bat', (err, stdout, stderr) => {
-  if (err) {
-    console.error(err);
-    return;
-  }
-  console.log(stdout);
-});
+// 1. child_process.spawn() with the shell option set
+const myBat = spawn('my.bat', { shell: true });
 
-// Script with spaces in the filename:
-const bat = spawn('"my script.cmd" a b', { shell: true });
-// or:
-exec('"my script.cmd" a b', (err, stdout, stderr) => {
-  // ...
-});
+// 2. child_process.exec()
+exec('my.bat', (err, stdout, stderr) => { /* ... */ });
+
+// 3. spawning cmd.exe and passing the .bat or .cmd file as an argument
+const bat = spawn('cmd.exe', ['/c', 'my.bat']);
+
+// If the script filename contains spaces, it needs to be quoted
+exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });
 ```
 
 ```mjs
-// OR...
 import { exec, spawn } from 'node:child_process';
 
-exec('my.bat', (err, stdout, stderr) => {
-  if (err) {
-    console.error(err);
-    return;
-  }
-  console.log(stdout);
-});
+// 1. child_process.spawn() with the shell option set
+const myBat = spawn('my.bat', { shell: true });
 
-// Script with spaces in the filename:
-const bat = spawn('"my script.cmd" a b', { shell: true });
-// or:
-exec('"my script.cmd" a b', (err, stdout, stderr) => {
-  // ...
-});
+// 2. child_process.exec()
+exec('my.bat', (err, stdout, stderr) => { /* ... */ });
+
+// 3. spawning cmd.exe and passing the .bat or .cmd file as an argument
+const bat = spawn('cmd.exe', ['/c', 'my.bat']);
+
+// If the script filename contains spaces, it needs to be quoted
+exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });
 ```
 
 ### `child_process.exec(command[, options][, callback])`