Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

6/21/2023 PM Publish #10188

Merged
merged 3 commits into from
Jun 21, 2023
Merged

6/21/2023 PM Publish #10188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c1cc469
Update about_Pipeline_Chain_Operators.md (#10182)
mubed Jun 21, 2023
69d9270
Update install instructions (#10184)
sdwheeler Jun 21, 2023
1a2c1a6
Update defaults for Head and Tail parameters (#10185)
sdwheeler Jun 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 79 additions & 50 deletions reference/5.1/Microsoft.PowerShell.Management/Get-Content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Management
ms.date: 12/12/2022
ms.date: 06/21/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/get-content?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Get-Content
Expand Down Expand Up @@ -37,7 +37,7 @@ Get-Content [-ReadCount <Int64>] [-TotalCount <Int64>] [-Tail <Int32>] -LiteralP

The `Get-Content` cmdlet gets the content of the item at the location specified by the path, such as
the text in a file or the content of a function. For files, the content is read one line at a time
and returns a collection of objects, each of which represents a line of content.
and returns a collection of objects, each representing a line of content.

Beginning in PowerShell 3.0, `Get-Content` can also get a specified number of lines from the
beginning or end of an item.
Expand All @@ -47,7 +47,7 @@ beginning or end of an item.
### Example 1: Get the content of a text file

This example gets the content of a file in the current directory. The `LineNumbers.txt` file
contains 100 lines in the format, **This is Line X** and is used in several examples.
has 100 lines in the format, **This is Line X** and is used in several examples.

```powershell
1..100 | ForEach-Object { Add-Content -Path .\LineNumbers.txt -Value "This is line $_." }
Expand All @@ -70,9 +70,8 @@ PowerShell console.

### Example 2: Limit the number of lines Get-Content returns

This command gets the first five lines of a file. The **TotalCount** parameter is used to gets the
first five lines of content. This example uses the `LineNumbers.txt` file that was created in
Example 1.
This command gets the first five lines of a file. The **TotalCount** parameter gets the first five
lines of content. This example uses the `LineNumbers.txt` referenced in Example 1.

```powershell
Get-Content -Path .\LineNumbers.txt -TotalCount 5
Expand All @@ -90,7 +89,7 @@ This is Line 5

This command gets a specific number of lines from a file and then displays only the last line of
that content. The **TotalCount** parameter gets the first 25 lines of content. This example uses the
`LineNumbers.txt` file that was created in Example 1.
`LineNumbers.txt` file referenced in Example 1.

```powershell
(Get-Content -Path .\LineNumbers.txt -TotalCount 25)[-1]
Expand Down Expand Up @@ -118,9 +117,9 @@ Get-Item -Path .\LineNumbers.txt | Get-Content -Tail 1
This is Line 100
```

This example uses the `Get-Item` cmdlet to demonstrate that you can pipe files into the
`Get-Content` parameter. The **Tail** parameter gets the last line of the file. This method is
faster than retrieving all of the lines and using the `[-1]` index notation.
This example uses the `Get-Item` cmdlet to demonstrate that you can pipe files to `Get-Content`. The
**Tail** parameter gets the last line of the file. This method is faster than retrieving all the
lines in a variable and using the `[-1]` index notation.

### Example 5: Get the content of an alternate data stream

Expand All @@ -147,17 +146,42 @@ Length : 44
```

```powershell
# Retrieve the content of the primary, or $DATA stream.
Get-Content -Path .\Stream.txt -Stream $DATA
# Retrieve the content of the primary stream.
# Note the single quotes to prevent variable substitution.
Get-Content -Path .\Stream.txt -Stream ':$DATA'
```

```Output
This is the content of the Stream.txt file
```

```powershell
# Alternative way to get the same content.
Get-Content -Path .\Stream.txt -Stream ""
# The primary stream doesn't need to be specified to get the primary stream of the file.
# This gets the same data as the prior two examples.
Get-Content -Path .\Stream.txt
```

```Output
This is the content of the Stream.txt file
```

```powershell
# The primary stream doesn't need to be specified to get the primary stream of the file.
# This gets the same data as the prior two examples.
Get-Content -Path .\Stream.txt
```

```powershell
# Use the Stream parameter of Add-Content to create a new Stream containing sample content.
Add-Content -Path .\Stream.txt -Stream NewStream -Value 'Added a stream named NewStream to Stream.txt'
$addContentSplat = @{
Path = '.\Stream.txt'
Stream = 'NewStream'
Value = 'Added a stream named NewStream to Stream.txt'
}
Add-Content @addContentSplat
# Use Get-Item to verify the stream was created.
Get-Item -Path .\Stream.txt -Stream *
```
Expand Down Expand Up @@ -195,15 +219,14 @@ Added a stream named NewStream to Stream.txt

The **Stream** parameter is a dynamic parameter of the
[FileSystem provider](../microsoft.powershell.core/about/about_filesystem_provider.md#stream-string).
By default `Get-Content` only retrieves data from the default, or `:$DATA` stream. **Streams** can be
used to store hidden data such as attributes, security settings, or other data.
By default `Get-Content` only retrieves data from the default, or `:$DATA` stream. **Streams** can
be used to store hidden data such as attributes, security settings, or other data.

### Example 6: Get raw content

The commands in this example get the contents of a file as one string, instead of an array of
strings. By default, without the **Raw** dynamic parameter, content is returned as an array of
newline-delimited strings. This example uses the `LineNumbers.txt` file that was created in Example
1.
newline-delimited strings. This example uses the `LineNumbers.txt` file referenced in Example 1.

```powershell
$raw = Get-Content -Path .\LineNumbers.txt -Raw
Expand Down Expand Up @@ -257,9 +280,9 @@ PowerShell as `[System.Object[]]`.
### -Credential

> [!NOTE]
> This parameter is not supported by any providers installed with PowerShell.
> To impersonate another user, or elevate your credentials when running this cmdlet,
> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md).
> This parameter isn't supported by any providers installed with PowerShell. To impersonate another
> user, or elevate your credentials when running this cmdlet, use
> [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md).
```yaml
Type: System.Management.Automation.PSCredential
Expand All @@ -277,9 +300,9 @@ Accept wildcard characters: False
Specifies the delimiter that `Get-Content` uses to divide the file into objects while it reads. The
default is `\n`, the end-of-line character. When reading a text file, `Get-Content` returns a
collection of string objects, each of which ends with an end-of-line character. When you enter a
delimiter that does not exist in the file, `Get-Content` returns the entire file as a single,
undelimited object.
collection of string objects, each ending with an end-of-line character. When you enter a delimiter
that doesn't exist in the file, `Get-Content` returns the entire file as a single, undelimited
object.

You can use this parameter to split a large file into smaller files by specifying a file separator,
as the delimiter. The delimiter is preserved (not discarded) and becomes the last item in each file
Expand All @@ -291,7 +314,7 @@ cmdlet. This parameter works only in file system drives.
> [!NOTE]
> Currently, when the value of the **Delimiter** parameter is an empty string, `Get-Content` does
> not return anything. This is a known issue. To force `Get-Content` to return the entire file as
> a single, undelimited string. Enter a value that does not exist in the file.
> a single, undelimited string. Enter a value that doesn't exist in the file.

```yaml
Type: System.String
Expand Down Expand Up @@ -351,8 +374,7 @@ Accept wildcard characters: False
Specifies, as a string array, an item or items that this cmdlet excludes in the operation.
The value of this parameter qualifies the **Path** parameter.

Enter a path element or pattern, such as `*.txt`.
Wildcard characters are permitted.
Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted.

The **Exclude** parameter is effective only when the command includes the contents of an item,
such as `C:\Windows\*`, where the wildcard character specifies the contents of the `C:\Windows`
Expand All @@ -372,11 +394,13 @@ Accept wildcard characters: True

### -Filter

Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md)
provider is the only installed PowerShell provider that supports the use of filters. You can find
the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md).
Filters are more efficient than other parameters, because the provider applies them when the cmdlet
gets the objects rather than having PowerShell filter the objects after they are retrieved.
Specifies a filter to qualify the **Path** parameter. The
[FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the only
installed PowerShell provider that supports the use of filters. You can find the syntax for the
**FileSystem** filter language in
[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient
than other parameters, because the provider applies them when the cmdlet gets the objects rather
than having PowerShell filter the objects after they're retrieved.

```yaml
Type: System.String
Expand All @@ -392,8 +416,8 @@ Accept wildcard characters: True

### -Force

**Force** will override a read-only attribute or create directories to complete a file path. The
**Force** parameter does not attempt to change file permissions or override security restrictions.
**Force** can override a read-only attribute or create directories to complete a file path. The
**Force** parameter doesn't attempt to change file permissions or override security restrictions.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand Down Expand Up @@ -429,12 +453,13 @@ Accept wildcard characters: True

### -LiteralPath

Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is
Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it's
typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose
it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters
as escape sequences.

For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
For more information, see
[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).

```yaml
Type: System.String[]
Expand Down Expand Up @@ -490,9 +515,9 @@ Accept wildcard characters: False
### -ReadCount

Specifies how many lines of content are sent through the pipeline at a time. The default value is 1.
A value of 0 (zero) sends all of the content at one time.
A value of 0 (zero) sends all the content at one time.

This parameter does not change the content displayed, but it does affect the time it takes to
This parameter doesn't change the content displayed, but it does affect the time it takes to
display the content. As the value of **ReadCount** increases, the time it takes to return the first
line increases, but the total time for the operation decreases. This can make a perceptible
difference in large items.
Expand All @@ -512,11 +537,12 @@ Accept wildcard characters: False
### -Stream

Gets the contents of the specified alternate NTFS file stream from the file. Enter the stream name.
Wildcards are not supported.
Wildcards aren't supported.

**Stream** is a dynamic parameter that the **FileSystem** provider adds to the `Get-Content` cmdlet.
This parameter works only in file system drives on Windows systems. This parameter was introduced in
Windows PowerShell 3.0.
This parameter works only in file system drives on Windows systems.

This parameter was introduced in Windows PowerShell 3.0.

```yaml
Type: System.String
Expand All @@ -533,7 +559,10 @@ Accept wildcard characters: False
### -Tail

Specifies the number of lines from the end of a file or other item. You can use the **Tail**
parameter name or its alias, **Last**. This parameter was introduced in PowerShell 3.0.
parameter name or its alias, **Last**. Negative values cause the cmdlet to return the entire
contents.

This parameter was introduced in PowerShell 3.0.

```yaml
Type: System.Int32
Expand All @@ -549,8 +578,8 @@ Accept wildcard characters: False

### -TotalCount

Specifies the number of lines from the beginning of a file or other item. The default is -1 (all
lines).
Specifies the number of lines from the beginning of a file or other item. Negative values cause the
cmdlet to return the entire contents.

You can use the **TotalCount** parameter name or its aliases, **First** or **Head**.

Expand All @@ -561,7 +590,7 @@ Aliases: First, Head
Required: False
Position: Named
Default value: -1
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
```
Expand All @@ -587,11 +616,10 @@ Accept wildcard characters: False

Keeps the file open after all existing lines have been output. While waiting, `Get-Content` checks
the file once each second and outputs new lines if present. You can interrupt **Wait** by pressing
**CTRL+C**. Waiting also ends if the file gets deleted, in which case a non-terminating error is
reported.
**CTRL+C**. Waiting also ends if the file gets deleted, which also causes a non-terminating error.

**Wait** is a dynamic parameter that the FileSystem provider adds to the `Get-Content` cmdlet. This
parameter works only in file system drives. **Wait** cannot be combined with **Raw**.
parameter works only in file system drives. **Wait** can't be combined with **Raw**.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand All @@ -607,9 +635,10 @@ Accept wildcard characters: False

### CommonParameters

This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`,
`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`,
`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
-WarningAction, and -WarningVariable. For more information, see
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

Expand Down
38 changes: 21 additions & 17 deletions reference/7.2/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes chaining pipelines with the `&&` and `||` operators in PowerShell.
Locale: en-US
ms.date: 12/08/2022
ms.date: 06/21/2023
online version: https://learn.microsoft.com/powershell/module/psscheduledjob/about/about_pipeline_chain_operators?view=powershell-7.2&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about Pipeline Chain Operators
Expand All @@ -17,10 +17,8 @@ Describes chaining pipelines with the `&&` and `||` operators in PowerShell.

Beginning in PowerShell 7, PowerShell implements the `&&` and `||` operators to
conditionally chain pipelines. These operators are known in PowerShell as
_pipeline chain operators_, and are similar to
[AND-OR lists](https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_03)
in POSIX shells like bash, zsh and sh, as well as
[conditional processing symbols](/previous-versions/windows/it-pro/windows-xp/bb490954(v=technet.10)#using-multiple-commands-and-conditional-processing-symbols)
_pipeline chain operators_, and are similar to [AND-OR lists][05] in POSIX
shells like bash, zsh and sh, as well as [conditional processing symbols][01]
in the Windows Command Shell (cmd.exe).

The `&&` operator executes the right-hand pipeline, if the left-hand pipeline
Expand Down Expand Up @@ -152,11 +150,10 @@ semicolons (`;`). This means that pipelines within a pipeline chain can be
individually redirected, and that entire pipeline chains can be backgrounded,
assigned to variables, or separated as statements.

To use lower precedence syntax within a pipeline chain,
consider the use of parentheses `(...)`.
Similarly, to embed a statement within a pipeline chain,
a subexpression `$(...)` can be used.
This can be useful for combining native commands with control flow:
To use lower precedence syntax within a pipeline chain, consider the use of
parentheses `(...)`. Similarly, to embed a statement within a pipeline chain, a
subexpression `$(...)` can be used. This can be useful for combining native
commands with control flow:

```powershell
foreach ($file in 'file1','file2','file3')
Expand All @@ -172,15 +169,15 @@ file2
Found file2
```

As of PowerShell 7, the behaviour of these syntaxes has been changed
so that `$?` is set as expected when a command succeeds or fails
within parentheses or a subexpression.
As of PowerShell 7, the behaviour of these syntaxes has been changed so that
`$?` is set as expected when a command succeeds or fails within parentheses or
a subexpression.

Like most other operators in PowerShell, `&&` and `||` are also
_left-associative_, meaning they group from the left. For example:

```powershell
Get-ChildItem -Path ./file.txt |
Get-ChildItem -Path ./file.txt ||
Write-Error "file.txt doesn't exist" &&
Get-Content -Raw ./file.txt
```
Expand Down Expand Up @@ -312,6 +309,13 @@ deemed to have failed after generating the non-terminating error.

## See also

- [about_Automatic_Variables](about_Automatic_Variables.md)
- [about_Operators](about_Operators.md)
- [about_Pipelines](about_Pipelines.md)
- [about_Automatic_Variables][02]
- [about_Operators][03]
- [about_Pipelines][04]

<!-- link references -->
[01]: /previous-versions/windows/it-pro/windows-xp/bb490954(v=technet.10)#using-multiple-commands-and-conditional-processing-symbols
[02]: about_Automatic_Variables.md
[03]: about_Operators.md
[04]: about_Pipelines.md
[05]: https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_03
Loading