The Start-Process topic contains incorrect and misleading information about use on Unix-like platforms

[mklement0]

The Start-Process topic currently states with respect to Unix-like platforms:

When using PowerShell Core on Linux, to open a new process within a new window (similar to the default behavior when using Start-Process in Windows), run the cmdlet with the -UseNewEnvironment -Wait parameters. This is done to prevent the new process from blocking PowerShell's control of keyboard input.

This is incorrect and misleading:

• Only Linux is mentioned, but special considerations equally apply to all Unix-like platforms, notably including macOS

• Creating a new window is fundamentally unsupported on Unix-like platforms (macOS and Linux).

• -Wait is only needed if you're launching a terminal-based (non-GUI) utility (to prevent the keyboard / output issue), as opposed to asynchronously launching a GUI, such as gedit, which is the other legitimate use case.

  • However, the only reason to run a terminal-based utility with Start-Process -Wait to begin with is in the unusual event that you want to ignore the current process' environment and start with a fresh one via -UseNewEnvironment - without that, the utility can just be invoked directly (which makes the invocation implicitly synchronous and also keeps the new process' standard streams connected to PowerShell's).
    • As an aside: -UseNewEnvironment is currently broken: see Start-Process -UseNewEnvironment provides an environment that is missing crucial standard environment variables while not supporting passing a new environment PowerShell/PowerShell#4671

In short, on Unix-like platforms:

• -NoNewWindow is invariably implied - you'll never get a new terminal window.
• Use Start-Process only in these scenarios:
  • If you want to launch a GUI application that has a blocking CLI (e.g., gedit, firefox) asynchronously - typical only on Linux.
  • If you want to launch a terminal-based utility with -UseNewEnvironment in order to start with a fresh environment.
    • With utilities that produce output / require user interaction, this then also requires use of -Wait to prevent keyboard-control issues and/or preventing output from arriving asynchronously.
    • Note that with -Wait output will print synchronously to the terminal, but due to the process not being connected to PowerShell's streams you won't able to capture or suppress it - which is a price you invariably pay in general when you use Start-Process.

Version(s) of document impacted

• Impacts 6.next document
• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

Reason(s) for not selecting all version of documents

• The documented feature was introduced in selected version of PowerShell
• This issue only shows up in selected version of the document