Prerequisites
Version
7.2
Link to affected document
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2
Description of the documentation error
It seems that -- has a special meaning of "end-of-parameters" and therefore gets swallowed on its first occurrence. This seems to be the case when invoking CmdLets or external scripts. External applications seem not to be affected, but there are indiciations that in the past they were.
For example, Write-Output a -- b -- c will print a b -- c (swallowing the first --) while cmd.exe /c echo a -- b -- c will print a -- b -- c.
I was unable to find any sort of documentation about this behavior. The only reference I found (cited in other posts about this issue on the Internet) is a third-party book ("Windows PowerShell in Action" by Bruce Payette). See this Stack Overflow answer.
The fact that this is not well-known, not documented and apparently also version-dependent makes "mysterious" issues appear, and makes it hard to reliably predict the behavior of some commands. What led me to opening this issue was this seemingly odd problem that turned out to be related to certain npm versions creating an npm.ps1 file additionally to npm.cmd which would then behave differently when invoked as something like npm run test -- --value 10 (and I later found that others had the same issue in the past too).
(Note: There is also --%, which is documented but seems to behave in yet another way...)
Suggested fix
I'd suggest to add documentation about -- to the "Parsing" docs page (and perhaps also to "Parameters"), including a comparison between -- and --%, under what circumstances -- does or doesn't have special behavior, how to work around it if it's causing a problem and perhaps also version differences, if any.
Prerequisites
Version
7.2
Link to affected document
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2
Description of the documentation error
It seems that
--has a special meaning of "end-of-parameters" and therefore gets swallowed on its first occurrence. This seems to be the case when invoking CmdLets or external scripts. External applications seem not to be affected, but there are indiciations that in the past they were.For example,
Write-Output a -- b -- cwill printab--c(swallowing the first--) whilecmd.exe /c echo a -- b -- cwill printa -- b -- c.I was unable to find any sort of documentation about this behavior. The only reference I found (cited in other posts about this issue on the Internet) is a third-party book ("Windows PowerShell in Action" by Bruce Payette). See this Stack Overflow answer.
The fact that this is not well-known, not documented and apparently also version-dependent makes "mysterious" issues appear, and makes it hard to reliably predict the behavior of some commands. What led me to opening this issue was this seemingly odd problem that turned out to be related to certain npm versions creating an
npm.ps1file additionally tonpm.cmdwhich would then behave differently when invoked as something likenpm run test -- --value 10(and I later found that others had the same issue in the past too).(Note: There is also
--%, which is documented but seems to behave in yet another way...)Suggested fix
I'd suggest to add documentation about
--to the "Parsing" docs page (and perhaps also to "Parameters"), including a comparison between--and--%, under what circumstances--does or doesn't have special behavior, how to work around it if it's causing a problem and perhaps also version differences, if any.