One of the biggest obstacles to getting started with Windows Powershell is learning how to use the output of the Get-Help cmdlet. At first glance, an absolute mess of output is given that can be confusing. Once you know how to parse the output of this command, learning how to use new cmdlets is pretty straightforward.
Before getting started, you will want to run the following command to make sure you have updated help files:
> Update-Help
By default, Windows does not come with help files stored locally for Powershell cmdlets, so you will need to run this command at least once to get everything downloaded. If you have done this previously, you can still run this to fetch updates.
If you want to run this task in the background in powershell, you can do so by using this command:
> Start-Job -scriptblock {update-help}
This starts a background job for the task, and you can check the status of background jobs using:
> Get-Job
Let's run the following command to get some sample help output:
> Get-Help Get-Help
There are 3 main sections of the output that will give us useful info:
The Synopsis and Description sections are useful and straightforward, so our focus will be on the Syntax portion.
The basic structure of the syntax section is:
> Get-Help Get-Help -Parameter Name
As seen in the screenshot above, there are six sets of parameters listed that look mostly identical. The most important thing to understand here is that each of the 6 sets of parameters is exclusive. You cannot mix parameters from different sets in a single command (unless that parameter appears in both sets).
For example, the first set contains the -Detailed parameter, but not the -Examples parameter. The second set contains -Examples, but not -Detailed. So the following command is not valid:
> Get-Help Get-Help -Detailed -Examples
You will get an error that looks like this:
By contrast, choosing only parameters from a single set will provide valid output. The following command is valid since both are included in a single parameter grouping from above:
> Get-Help Get-Help -Detailed -Category All
So to summarize, use the Syntax section to help forming a valid command, but only use parameters from a single set from the Syntax section to avoid errors.
That's all well and good, but what do any of these parameters actually do? Annoyingly, the default output of Get-Help does not actually tell us what any of the parameters do. You need the following parameter:
> Get-Help Get-Help -Detailed
Notice that this provides another section which tells us what all of these parameters actually do:
This output will provide a detailed description of every command parameter. Since this seems (to me) to be the most useful part of the help documentation, I have no idea why it is not included by default. In any case, this output will help you sort out which parameters you need.
The -Detailed parameter will also display examples of the command being used. If you want to display these examples without all of the other detail included, you can use:
> Get-Help Get-Help -Examples
