shell option for execFile and execFileSync in child_process module not documented

[mojavelinux]

• Version: 8.9.4
• Platform: n/a
• Subsystem: child_process

The shell option for the execFile and execFileSync functions in the child_process module is not documented. However, it clearly works, as this mocha/chai test proves:

const { execFile, execFileSync } = require('child_process')
const expect = require('chai').expect

const EXEC_OPTS = { encoding: 'utf8', shell: process.env.SHELL }

describe('execFile()', () => {
  it('should run command using specified shell', async () => {
    let fn
    try {
      const result = await new Promise((resolve, reject) => {
        execFile('ls', ['*'], EXEC_OPTS, (err, stdout) =>
          err ? reject(err) : resolve(stdout))
      })
      fn = () => result
    } catch (err) {
      fn = () => { throw err }
    }
    expect(fn).to.not.throw()
  })
})

describe('execFileSync()', () => {
  it('should run command using specified shell', () => {
    expect(() => execFileSync('ls', ['*'], EXEC_OPTS)).to.not.throw()
  })
})

I'm happy to add documentation for this option. I just need to know if this behavior is intention or whether it's the result of leaky internals.

[bnoordhuis]

I suppose it's undocumented because of this paragraph:

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

[mojavelinux]

I get that's the default behavior. But this function is still useful for executing in a shell because it accepts arguments as an array instead of a string as exec does. Depending on the circumstances, that can prove to be useful if the arguments are already prepared.

[jvelezpo]

I can work on it, and it will be my first issue and my first contribution to the core 😎