maxmustermann/PowerShell
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update pwsh -? output to match docs (#13748)

Browse source
This commit is contained in:
Sean Wheeler 2020-11-04 12:39:07 -06:00 committed by GitHub
parent 1d7a93c2e0
commit beb074d4a2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 112 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

167
src/Microsoft.PowerShell.ConsoleHost/resources/ManagedEntranceStrings.resx
View file

@ -153,8 +153,8 @@ Type 'help' to get help.</value>
[-EncodedCommand &lt;Base64EncodedCommand&gt;]
[-ExecutionPolicy &lt;ExecutionPolicy&gt;] [-InputFormat {Text | XML}]
[-Interactive] [-MTA] [-NoExit] [-NoLogo] [-NonInteractive] [-NoProfile]
[-OutputFormat {Text | XML}] [-SettingsFile &lt;filePath&gt;] [-STA] [-Version]
[-WindowStyle &lt;style&gt;] [-WorkingDirectory &lt;directoryPath&gt;]
[-OutputFormat {Text | XML}] [-SettingsFile &lt;filePath&gt;] [-SSHServerMode] [-STA]
[-Version] [-WindowStyle &lt;style&gt;] [-WorkingDirectory &lt;directoryPath&gt;]
pwsh[.exe] -h | -Help | -? | /?
@ -183,10 +183,11 @@ All parameters are case-insensitive.</value>
omitted. For example, the following command uses the All parameter of the
Get-Script.ps1 script file: "-File .\Get-Script.ps1 -All"
In rare cases, you might need to provide a Boolean value for a switch
parameter. To provide a Boolean value for a switch parameter in the value
of the File parameter, enclose the parameter name and value in curly
braces, such as the following: "-File .\Get-Script.ps1 {-All:$False}."
In rare cases, you might need to provide a BOOLEAN value for a switch
parameter. To provide a BOOLEAN value for a switch parameter in the value
of the FILE parameter, Use the parameter normally followed immediately by a
colon and the boolean value, such as the following:
"-File .\Get-Script.ps1 -All:$False".
Parameters passed to the script are passed as literal strings, after
interpretation by the current shell. For example, if you are in cmd.exe and
@ -197,7 +198,21 @@ All parameters are case-insensitive.</value>
cmd.exe results in the script receiving the literal string "$env:windir"
because it has no special meaning to the current cmd.exe shell. The
"$env:windir" style of environment variable reference can be used inside a
Command parameter, since there it will be interpreted as PowerShell code.
Command parameter, since there it is interpreted as PowerShell code.
Similarly, if you want to execute the same command from a Batch script,
you would use "%~dp0" instead of ".\" or "$PSScriptRoot" to represent the current
execution directory: "pwsh -File %~dp0test.ps1 -TestParam %windir%". If you
instead used ".\test.ps1", PowerShell would throw an error because it cannot
find the literal path ".\test.ps1".
When the script file invoked terminates with an exit command, the process
exit code is set to the numeric argument used with the exit command. With
normal termination, the exit code is always 0.
Similar to -Command, when a script-terminating error occurs, the exit code
is set to 1. However, unlike with -Command, when the execution is
interrupted with Ctrl-C the exit code is 0.
-Command | -c
@ -215,8 +230,7 @@ All parameters are case-insensitive.</value>
or parsed by the PowerShell host as a literal script block enclosed in
curly braces "{}", before being passed to pwsh.
pwsh -Command {Get-WinEvent -LogName security}
pwsh -Command {Get-WinEvent -LogName security}
In cmd.exe, there is no such thing as a script block (or ScriptBlock type),
so the value passed to Command will always be a string. You can write a
@ -224,7 +238,7 @@ All parameters are case-insensitive.</value>
behave exactly as though you typed it at a typical PowerShell prompt,
printing the contents of the script block back out to you.
A string passed to Command will still be executed as PowerShell, so the
A string passed to Command is still executed as PowerShell script, so the
script block curly braces are often not required in the first place when
running from cmd.exe. To execute an inline script block defined inside a
string, the call operator "&amp;" can be used:
@ -235,29 +249,39 @@ All parameters are case-insensitive.</value>
pwsh, because all arguments following it are interpreted as part of the
command to execute.
The results are returned to the parent shell as deserialized XML objects,
not live objects.
When called from within an existing PowerShell session, the results are
returned to the parent shell as deserialized XML objects, not live objects.
For other shells, the results are returned as strings.
If the value of Command is "-", the command text is read from standard
input. You must redirect standard input when using the Command parameter
with standard input. For example:
@'
"in"
@'
"in"
"hi" |
% { "$_ there" }
"hi" |
% { "$_ there" }
"out"
'@ | powershell -NoProfile -Command -
"out"
'@ | powershell -NoProfile -Command -
This example produces the following output:
"""Output
in
hi there
out
in
hi there
out
The process exit code is determined by status of the last (executed)
command within the script block. The exit code is 0 when $? is $true or 1
when $? is $false. If the last command is an external program or a
PowerShell script that explicitly sets an exit code other than 0 or 1, that
exit code is converted to 1 for process exit code. To preserve the specific
exit code, add exit $LASTEXITCODE to your command string or script block.
Similarly, the value 1 is returned when a script-terminating
(runspace-terminating) error, such as a throw or -ErrorAction Stop, occurs
or when execution is interrupted with Ctrl-C.
-ConfigurationName | -config
@ -275,34 +299,37 @@ All parameters are case-insensitive.</value>
predictable mechanism for connecting to other PowerShell instances.
Typically used with the CustomPipeName parameter on "Enter-PSHostProcess".
This parameter was introduced in PowerShell 6.2.
For example:
# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe
# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe
-EncodedCommand | -e | -ec
Accepts a base64-encoded string version of a command. Use this parameter to
submit commands to PowerShell that require complex quotation marks or curly
braces. The string must be formatted using UTF-16 character encoding.
Accepts a Base64-encoded string version of a command. Use this parameter to
submit commands to PowerShell that require complex, nested quoting. The
Base64 representation must be a UTF-16 encoded string.
For example:
$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand
$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand
-ExecutionPolicy | -ex | -ep
Sets the default execution policy for the current session and saves it in
the "$env:PSExecutionPolicyPreference" environment variable. This parameter
does not change the PowerShell execution policy that is set in the
registry.
the $env:PSExecutionPolicyPreference environment variable. This parameter
does not change the persistently configured execution policies.
This parameter only applies to Windows computers. The
$env:PSExecutionPolicyPreference environment variable does not exist on
non-Windows platforms.
-InputFormat | -inp | -if
@ -316,16 +343,37 @@ All parameters are case-insensitive.</value>
-Login | -l
On Linux and macOS, starts PowerShell as a login shell,
using /bin/sh to execute login profiles such as /etc/profile and ~/.profile.
On Windows, this switch does nothing.
On Linux and macOS, starts PowerShell as a login shell, using /bin/sh to
execute login profiles such as /etc/profile and ~/.profile. On Windows,
this switch does nothing.
Note that "-Login" is only supported as the first parameter to pwsh.
[!IMPORTANT] This parameter must come first to start PowerShell as a login
shell. The parameter is ignored if passed in any other position.
To set up pwsh as the login shell on UNIX-like operating systems:
- Verify that the full absolute path to pwsh is listed under /etc/shells
- This path is usually something like /usr/bin/pwsh on Linux or
/usr/local/bin/pwsh on macOS
- With some installation methods, this entry will be added
automatically at installation time
- If pwsh is not present in /etc/shells, use an editor to append the
path to pwsh on the last line. This requires elevated privileges to
edit.
- Use the chsh utility to set your current user's shell to pwsh:
chsh -s /usr/bin/pwsh
[!WARNING] Setting pwsh as the login shell is currently not supported on
Windows Subsystem for Linux (WSL), and attempting to set pwsh as the
login shell there may lead to being unable to start WSL interactively.
-MTA
Start the shell using a multi-threaded apartment.
Only available on Windows.
Start PowerShell using a multi-threaded apartment. This switch is only
available on Windows.
-NoExit | -noe
@ -335,15 +383,17 @@ All parameters are case-insensitive.</value>
-NoLogo | -nol
Hides the copyright banner at startup.
Hides the copyright banner at startup of interactive sessions.
-NonInteractive | -noni
Does not present an interactive prompt to the user.
Does not present an interactive prompt to the user. Any attempts to use
interactive features, like Read-Host or confirmation prompts, result in
statement-terminating errors.
-NoProfile | -nop
Does not load the PowerShell profile.
Does not load the PowerShell profiles.
-OutputFormat | -o | -of
@ -352,6 +402,10 @@ All parameters are case-insensitive.</value>
Example: "pwsh -o XML -c Get-Date"
When called withing a PowerShell session, you get deserialized objects as
output rather plain strings. When called from other shells, the output is
string data formatted as CLIXML text.
-SettingsFile | -settings
Overrides the system-wide "powershell.config.json" settings file for the
@ -363,10 +417,15 @@ All parameters are case-insensitive.</value>
Example: "pwsh -SettingsFile c:\myproject\powershell.config.json"
-SSHServerMode | -sshs
Used in sshd_config for running PowerShell as an SSH subsystem. It is not
intended or supported for any other use.
-STA
Start the shell using a single-threaded apartment. This is the default.
Only available on Windows.
Start PowerShell using a single-threaded apartment. This is the default.
This switch is only available on Windows.
-Version | -v
@ -379,17 +438,15 @@ All parameters are case-insensitive.</value>
-WorkingDirectory | -wd
Sets the initial working directory by executing
"Set-Location -LiteralPath &lt;path&gt;" at startup. Any valid PowerShell file
path is supported.
Sets the initial working directory by executing at startup. Any valid
PowerShell file path is supported.
To start PowerShell in your home directory, use: "pwsh -WorkingDirectory ~"
To start PowerShell in your home directory, use: pwsh -WorkingDirectory ~
-Help, -?, /?
Displays help for pwsh. If you are typing a pwsh command in PowerShell,
prepend the command parameters with a hyphen (-), not a forward slash (/).
You can use either a hyphen or forward slash in Cmd.exe.
</value>
</data>
</root>