child_process.exec/execFile docs have some inconsistencies and inaccuracies #32524

I don't have time to fix this now, but while looking at sec issues related to these APIs, I found some oddities.

https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback says

shell | If true, runs command inside of a shell.

But execFile() doesn't have a command argument... this was pasted from exec(), it seems. Probably what happens is that if there is a shell, then file and args are all concatenated together, ' ' seperated, and passed to the shell.

Since the shell option AFAICT ends up following the same path as from exec(), it suggests that the exec docs:

shell Shell to execute the command with. See Shell Requirements and Default Windows Shell. Default: '/bin/sh' on Unix, process.env.ComSpec on Windows.

are incomplete, probably false would work just fine as an arg there, making exec() behave exactly like execFile().

This seems to be a bit legacy as well:

The child_process.execFile() function is similar to child_process.exec() except that it does not spawn a shell by default. Rather, the specified executable file is spawned directly as a new process making it slightly more efficient than child_process.exec().

Now that both exec and execFile() have a shell, differing only be the default value, its probably more accurate to say the difference is that one takes an array of strings as an argument execFile(file, argv, .. and the other takes a single string exec(command, ...).

The text following is now wrong:

The same options as child_process.exec() are supported. Since a shell is not spawned, behaviors such as I/O redirection and file globbing are not supported.

It can't both support the same options, and not support some of the options.

It should probably say "If a shell is ..." (only one word different, but its important).

exec should probably have docs saying the same thing, shell behaviours are not supported when shell is false.

And execFile() should probably include the warnings from exec about how shell special chars vary by platform.

Some of these issues are shared with the "sync" versions of the APIs.