Skip to content

11/05 PM Publish #8312

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

Merged
huypub merged 3 commits into from
Nov 5, 2021
Merged

11/05 PM Publish #8312

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
d76d19c
Fix description of final example (#8310)
sdwheeler Nov 5, 2021
760e027
Remove duplicate: AccessDBProviderSample03.cs (#8307)
matt9ucci Nov 5, 2021
8ef5ed4
Clarify input behaviors for Select-String (#8311)
sdwheeler Nov 5, 2021
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
67 changes: 55 additions & 12 deletions reference/5.1/Microsoft.PowerShell.Utility/Select-String.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.Utility.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Utility
ms.date: 10/04/2021
ms.date: 11/05/2021
online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/select-string?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Select-String
Expand Down Expand Up @@ -41,18 +41,16 @@ Select-String [-Pattern] <String[]> -LiteralPath <String[]> [-SimpleMatch] [-Cas

## Description

The `Select-String` cmdlet searches for text and text patterns in input strings and files. You can
use `Select-String` similar to `grep` in UNIX or `findstr.exe` in Windows.
The `Select-String` cmdlet uses regular expression matching to search for text patterns in input
strings and files. You can use `Select-String` similar to `grep` in UNIX or `findstr.exe` in
Windows.

`Select-String` is based on lines of text. By default, `Select-String` finds the first match in each
line and, for each match, it displays the file name, line number, and all text in the line
containing the match. You can direct `Select-String` to find multiple matches per line, display text
before and after the match, or display a Boolean value (True or False) that indicates whether a
match is found.

`Select-String` uses regular expression matching, but it can also perform a match that searches the
input for the text that you specify.

`Select-String` can display all the text matches or stop after the first match in each input file.
`Select-String` can be used to display all text that doesn't match the specified pattern.

Expand Down Expand Up @@ -133,10 +131,10 @@ example, the function only exists in the PowerShell session. When the PowerShell
the function is deleted. For more information, see [about_Functions](../Microsoft.PowerShell.Core/About/about_Functions.md).

```powershell
Function Search-Help
function Search-Help
{
$PSHelp = "$PSHOME\en-US\*.txt"
Select-String -Path $PSHelp -Pattern 'About_'
$PSHelp = "$PSHOME\en-US\*.txt"
Select-String -Path $PSHelp -Pattern 'About_'
}

Search-Help
Expand Down Expand Up @@ -313,6 +311,41 @@ line. The objects stored in the `$A` and `$B` variables are identical.
The `$B.Matches.Length` property increases because for each line, every occurrence of the pattern
**PowerShell** is counted.

### Example 10 - Convert pipeline objects to strings using `Out-String`

The `ToString()` result of the piped object isn't the same rich string representation produced by
PowerShell's formatting system. So, you may need to pipe the objects to `Out-String` first.

Piping to `Out-String` converts the formatted output into a single multi-line string object. This
means that when `Select-String` finds a match it outputs the whole multiline string.

```powershell
PS> $hash = @{
Name = 'foo'
Category = 'bar'
}

# !! NO output, due to .ToString() conversion
$hash | Select-String -Pattern 'foo'

# Out-String converts the output to a single multi-line string object
PS> $hash | Out-String | Select-String -Pattern 'foo'

Name Value
---- -----
Name foo
Category bar

# Out-String -Stream converts the output to a multiple single-line string objects
PS> $hash | Out-String -Steam | Select-String -Pattern 'foo'

Name foo
```

Piping to `Out-String -String` converts the formatted output into a multipel single-line string
objects. This means that when `Select-String` finds a match it outputs only the matching line.


## Parameters

### -AllMatches
Expand Down Expand Up @@ -639,15 +672,25 @@ the **Quiet** parameter, the output is a Boolean value indicating whether the pa

## Notes

`Select-String` is similar to **grep** in UNIX or **findstr.exe** in Windows.
`Select-String` is similar to `grep` in UNIX or `findstr.exe` in Windows.

The **sls** alias for the `Select-String` cmdlet was introduced in PowerShell 3.0.
The `sls` alias for the `Select-String` cmdlet was introduced in PowerShell 3.0.

> [!NOTE]
> According to [Approved Verbs for PowerShell Commands](/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands),
> According to
> [Approved Verbs for PowerShell Commands](/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands),
> the official alias prefix for `Select-*` cmdlets is `sc`, not `sl`. Therefore, the proper alias
> for `Select-String` should be `scs`, not `sls`. This is an exception to this rule.

When piping objects to `Select-String`:

- **FileInfo** objects are treated as a path to a file. When file paths are specified,
`Select-String` searches the contents of the file, not the `ToString()` representation of the
object.
- The `ToString()` result of the piped object isn't the same rich string representation produced by
PowerShell's formatting system. So, you may need to pipe the objects to `Out-String` first. For
more information, see Example 10.

To use `Select-String`, type the text that you want to find as the value of the **Pattern**
parameter. To specify the text to be searched, use the following criteria:

Expand Down
81 changes: 62 additions & 19 deletions reference/7.0/Microsoft.PowerShell.Utility/Select-String.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.Utility.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Utility
ms.date: 10/04/2021
ms.date: 11/05/2021
online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/select-string?view=powershell-7&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Select-String
Expand Down Expand Up @@ -65,18 +65,16 @@ Select-String [-Culture <String>] [-Pattern] <String[]> -LiteralPath <String[]>

## Description

The `Select-String` cmdlet searches for text and text patterns in input strings and files. You can
use `Select-String` similar to **grep** in UNIX or **findstr.exe** in Windows.
The `Select-String` cmdlet uses regular expression matching to search for text patterns in input
strings and files. You can use `Select-String` similar to `grep` in UNIX or `findstr.exe` in
Windows.

`Select-String` is based on lines of text. By default, `Select-String` finds the first match in each
line and, for each match, it displays the file name, line number, and all text in the line
containing the match. You can direct `Select-String` to find multiple matches per line, display text
before and after the match, or display a Boolean value (True or False) that indicates whether a
match is found.

`Select-String` uses regular expression matching, but it can also perform a match that searches the
input for the text that you specify.

`Select-String` can display all the text matches or stop after the first match in each input file.
`Select-String` can be used to display all text that doesn't match the specified pattern.

Expand Down Expand Up @@ -156,8 +154,8 @@ This example creates a function to search for a pattern in the PowerShell help f
example, the function only exists in the PowerShell session. When the PowerShell session is closed,
the function is deleted. For more information, see [about_Functions](../Microsoft.PowerShell.Core/About/about_Functions.md).

```
Function Search-Help
```powershell
function Search-Help
{
$PSHelp = "$PSHOME\en-US\*.txt"
Select-String -Path $PSHelp -Pattern 'About_'
Expand All @@ -167,10 +165,10 @@ Search-Help
```

```powershell
C:\Program Files\PowerShell\6\en-US\default.help.txt:67: The titles of conceptual topics begin with "About_".
C:\Program Files\PowerShell\6\en-US\default.help.txt:70: Get-Help About_<topic-name>
C:\Program Files\PowerShell\6\en-US\default.help.txt:93: Get-Help About_Modules : Displays help about PowerShell modules.
C:\Program Files\PowerShell\6\en-US\default.help.txt:97: about_Updatable_Help
C:\Program Files\PowerShell\7\en-US\default.help.txt:67: The titles of conceptual topics begin with "About_".
C:\Program Files\PowerShell\7\en-US\default.help.txt:70: Get-Help About_<topic-name>
C:\Program Files\PowerShell\7\en-US\default.help.txt:93: Get-Help About_Modules : Displays help about PowerShell modules.
C:\Program Files\PowerShell\7\en-US\default.help.txt:97: about_Updatable_Help
```

The function is created on the PowerShell command line. The `Function` command uses the name
Expand Down Expand Up @@ -280,9 +278,9 @@ $A
```

```Output
C:\Program Files\PowerShell\6\en-US\default.help.txt:3: PowerShell Help System
C:\Program Files\PowerShell\6\en-US\default.help.txt:6: Displays help about PowerShell cmdlets and concepts.
C:\Program Files\PowerShell\6\en-US\default.help.txt:9: PowerShell Help describes PowerShell cmdlets
C:\Program Files\PowerShell\7\en-US\default.help.txt:3: PowerShell Help System
C:\Program Files\PowerShell\7\en-US\default.help.txt:6: Displays help about PowerShell cmdlets and concepts.
C:\Program Files\PowerShell\7\en-US\default.help.txt:9: PowerShell Help describes PowerShell cmdlets
```

```powershell
Expand Down Expand Up @@ -338,6 +336,41 @@ line. The objects stored in the `$A` and `$B` variables are identical.
The `$B.Matches.Length` property increases because for each line, every occurrence of the pattern
**PowerShell** is counted.

### Example 10 - Convert pipeline objects to strings using `Out-String`

The `ToString()` result of the piped object isn't the same rich string representation produced by
PowerShell's formatting system. So, you may need to pipe the objects to `Out-String` first.

Piping to `Out-String` converts the formatted output into a single multi-line string object. This
means that when `Select-String` finds a match it outputs the whole multiline string.

```powershell
PS> $hash = @{
Name = 'foo'
Category = 'bar'
}

# !! NO output, due to .ToString() conversion
$hash | Select-String -Pattern 'foo'

# Out-String converts the output to a single multi-line string object
PS> $hash | Out-String | Select-String -Pattern 'foo'

Name Value
---- -----
Name foo
Category bar

# Out-String -Stream converts the output to a multiple single-line string objects
PS> $hash | Out-String -Steam | Select-String -Pattern 'foo'

Name foo
```

Piping to `Out-String -String` converts the formatted output into a multipel single-line string
objects. This means that when `Select-String` finds a match it outputs only the matching line.


## Parameters

### -AllMatches
Expand Down Expand Up @@ -741,7 +774,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable

### System.Management.Automation.PSObject

You can pipe any object that has a **ToString** method to `Select-String`.
You can pipe any object that has a `ToString()` method to `Select-String`.

## Outputs

Expand All @@ -753,15 +786,25 @@ If you use the **Raw** parameter, the output is a set of **String** objects that

## Notes

`Select-String` is similar to **grep** in UNIX or **findstr.exe** in Windows.
`Select-String` is similar to `grep` in UNIX or `findstr.exe` in Windows.

The **sls** alias for the `Select-String` cmdlet was introduced in PowerShell 3.0.
The `sls` alias for the `Select-String` cmdlet was introduced in PowerShell 3.0.

> [!NOTE]
> According to [Approved Verbs for PowerShell Commands](/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands),
> According to
> [Approved Verbs for PowerShell Commands](/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands),
> the official alias prefix for `Select-*` cmdlets is `sc`, not `sl`. Therefore, the proper alias
> for `Select-String` should be `scs`, not `sls`. This is an exception to this rule.

When piping objects to `Select-String`:

- **FileInfo** objects are treated as a path to a file. When file paths are specified,
`Select-String` searches the contents of the file, not the `ToString()` representation of the
object.
- The `ToString()` result of the piped object isn't the same rich string representation produced by
PowerShell's formatting system. So, you may need to pipe the objects to `Out-String` first. For
more information, see Example 10.

To use `Select-String`, type the text that you want to find as the value of the **Pattern**
parameter. To specify the text to be searched, use the following criteria:

Expand Down
Loading