Document the specific constraints of the stop-parsing symbol (--%)

[mklement0]

It is worth clarifying the following limitations, notably the one with respect to what causes --% to stop parsing (see PowerShell/PowerShell#12975):

• --% supports only one command, which an unquoted |, || or && on the same line, if present, implicitly ends; this allows you to pipe / chain such a command to / with other commands.

  • However, using ; in order to unconditionally place another command on the same line is not supported; the ; is passed through verbatim.

  • --% reads (at most) to the end of the line so spreading a command across multiple lines with line-continuation chars. is NOT supported

• Other than %...% environment-variable references, you cannot embed any other dynamic elements in the command; that is, you cannot embed regular PowerShell variable references or expressions.

  • Escaping % characters as %% (the way you can do inside batch files) is not supported; %<name>% tokens are invariably expanded, if <name> refers to a defined environment variable (if not, the token is passed through as-is).

• You cannot use stream redirections (e.g., >file.txt), because they are passed verbatim, as arguments to the target command.

  • For stdout output you can work around that by appending | Set-Content file.txt instead, but there is no direct PowerShell workaround for stderr output.

  • However, if you invoke your command via cmd, you can let cmd handle the (stderr) redirection (e.g., cmd --% /c nosuch 2>file.txt)

#4963 discusses why, specifically, --% is virtually useless on Unix-like platforms (the about_Parsing topic now mentions that, but just in the abstract ("The stop-parsing symbol only intended for use on Windows platforms.")).

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: b60e729-d3a7-bf51-c945-ff5ef5f4d570
• Version Independent ID: b9957906-f58b-86de-7907-cc2f94174af3
• Content: about_Parsing - PowerShell
• Content Source: reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md
• Product: powershell
• GitHub Login: @SteveL-MSFT
• Microsoft Alias: slee

[sdwheeler]

Adding links to related issues:

• Document the need for additional \-escaping of double quotes (") when calling external programs #2361 Document the need for additional -escaping of double quotes (") when calling external programs
• Introduce a conceptual help topic about calling external programs (native applications) #5152 Introduce a conceptual help topic about calling external programs (native applications)