diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-ChildItem.md b/reference/5.1/Microsoft.PowerShell.Management/Get-ChildItem.md index 61612aa3b1d8..ded907accc50 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-ChildItem.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-ChildItem.md @@ -33,44 +33,6 @@ Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] [] ``` -### Items (Default) - Certificate provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### LiteralItems - Certificate provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### Items (Default) - Filesystem provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - -### LiteralItems - FileSystem provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - ## DESCRIPTION The `Get-ChildItem` cmdlet gets the items in one or more specified locations. If the item is a @@ -81,9 +43,10 @@ of levels to recurse. `Get-ChildItem` doesn't display empty directories. When a `Get-ChildItem` command includes the **Depth** or **Recurse** parameters, empty directories aren't included in the output. -Locations are exposed to `Get-ChildItem` by PowerShell providers. A location can be a file system -directory, registry hive, or a certificate store. Some parameters are only available for a specific -provider. For more information, see +The `Get-ChildItem` cmdlet is designed to work with the items exposed by any provider. For example, +items can be a file system file or directory, registry hive, or a certificate store. To list the +providers available in your session, use the `Get-PSProvider` command. Some parameters are only +available for a specific provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## EXAMPLES @@ -125,7 +88,7 @@ as follows: - `s` (system) For more information about the mode flags, see -[about_Filesystem_Provider](../microsoft.powershell.core/about/about_filesystem_provider.md#attributes-flagsexpression). +[about_Filesystem_Provider](../Microsoft.PowerShell.Core/About/about_Filesystem_Provider.md#attributes-flagsexpression). ### Example 2: Get child item names in a directory @@ -347,8 +310,8 @@ authority. Get-ChildItem -Path Cert:\* -Recurse -CodeSigningCert ``` -For more information about the Certificate provider and the `Cert:` drive, -see [about_Certificate_Provider](../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md). +For more information about the Certificate provider and the `Cert:` drive, see +[about_Certificate_Provider](../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md). ### Example 8: Get items using the Depth parameter @@ -439,26 +402,27 @@ For example, to get non-system files (not directories) that are encrypted or com To find files and folders with commonly used attributes, use the **Attributes** parameter. Or, the parameters **Directory**, **File**, **Hidden**, **ReadOnly**, and **System**. -The **Attributes** parameter supports the following properties: - -- **Archive** -- **Compressed** -- **Device** -- **Directory** -- **Encrypted** -- **Hidden** -- **IntegrityStream** -- **Normal** -- **NoScrubData** -- **NotContentIndexed** -- **Offline** -- **ReadOnly** -- **ReparsePoint** -- **SparseFile** -- **System** -- **Temporary** - -For a description of these attributes, see the [FileAttributes Enumeration](/dotnet/api/system.io.fileattributes). +The **Attributes** parameter supports the following values: + +- `Archive` +- `Compressed` +- `Device` +- `Directory` +- `Encrypted` +- `Hidden` +- `IntegrityStream` +- `Normal` +- `NoScrubData` +- `NotContentIndexed` +- `Offline` +- `ReadOnly` +- `ReparsePoint` +- `SparseFile` +- `System` +- `Temporary` + +For a description of these attributes, see the [FileAttributes](xref:System.IO.FileAttributes) +enumeration. To combine attributes, use the following operators: @@ -754,7 +718,7 @@ Accept wildcard characters: False Allows the cmdlet to get items that otherwise can't be accessed by the user, such as hidden or system files. The **Force** parameter doesn't override security restrictions. Implementation varies -among providers. For more information, see +by provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml @@ -829,7 +793,8 @@ typed. No characters are interpreted as wildcards. If the path includes escape c it in single quotation marks. Single quotation marks tell PowerShell to not 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). > [!NOTE] > The **Include** and **Exclude** parameters have no effect when used with the **LiteralPath** @@ -867,8 +832,9 @@ Accept wildcard characters: False ### -Path -Specifies a path to one or more locations. Wildcards are accepted. The default location is the -current directory (`.`). +Specifies a path to one or more locations. If not specified, the default location is the current +directory (`.`). Wildcards are accepted. Use care when using the **Path** parameter with the +**Recurse** parameter. For more information, see the [NOTES](#notes) section of this article. ```yaml Type: System.String[] @@ -1047,12 +1013,33 @@ Windows PowerShell includes the following aliases for `Get-ChildItem`: - `dir` - `gci` -`Get-ChildItem` doesn't get hidden items by default. To get hidden items, use the **Force** -parameter. +**Recursion behavior with the Path parameter:** -The `Get-ChildItem` cmdlet is designed to work with the data exposed by any provider. To list the -providers available in your session, type `Get-PSProvider`. For more information, see -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +When you use `Get-ChildItem -Recurse` with the **Path** parameter, the cmdlet searches for the last +path component whether or not it's a wildcard pattern or a literal name. + +- If the last path component matches an existing immediate subdirectory of the target directory, the + cmdlet performs recursive enumeration on the matching directory. +- If the last path component doesn't match an existing immediate subdirectory of the target + directory, the cmdlet recursively searches the target directory's hierarchy for items that match + the last path component + +When you use `Get-ChildItem -Recurse` with the **Path** and **Name** parameters, the behavior +changes. The command searches for the last path component among the immediate child items of the +target directory. + +- If there is a match among the immediate child items, the cmdlet performs recursive enumeration on + the matching items. Wildcard matching happens only once, at the top level of the target directory. + The results are processed as if they had been individually passed to the **LiteralPath** + parameter. +- If the last path component doesn't match any items at the top level, an error occurs. + +You should avoid using the **Path** parameter with the **Recurse** parameter. For best results: + +- Use **LiteralPath** to specify the target directory to avoid triggering a recursive search for the + last path component. +- Use **Filter** or **Include** parameters to specify wildcard or literal patterns that should be + searched for in every level of the target directory's hierarchy. ## RELATED LINKS @@ -1060,7 +1047,7 @@ providers available in your session, type `Get-PSProvider`. For more information [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) -[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md) +[about_Quoting_Rules](../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md) [about_Registry_Provider](../Microsoft.PowerShell.Core/About/about_Registry_Provider.md) diff --git a/reference/7.4/Microsoft.PowerShell.Management/Get-ChildItem.md b/reference/7.4/Microsoft.PowerShell.Management/Get-ChildItem.md index 033e4783159d..b1591f9209b5 100644 --- a/reference/7.4/Microsoft.PowerShell.Management/Get-ChildItem.md +++ b/reference/7.4/Microsoft.PowerShell.Management/Get-ChildItem.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 08/09/2024 +ms.date: 02/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/get-childitem?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Get-ChildItem @@ -11,7 +11,6 @@ title: Get-ChildItem # Get-ChildItem ## SYNOPSIS - Gets the items and child items in one or more specified locations. ## SYNTAX @@ -32,44 +31,6 @@ Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] [] ``` -### Items (Default) - Certificate provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### LiteralItems - Certificate provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### Items (Default) - Filesystem provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - -### LiteralItems - FileSystem provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - ## DESCRIPTION The `Get-ChildItem` cmdlet gets the items in one or more specified locations. If the item is a @@ -80,9 +41,10 @@ of levels to recurse. `Get-ChildItem` doesn't display empty directories. When a `Get-ChildItem` command includes the **Depth** or **Recurse** parameters, empty directories aren't included in the output. -Locations are exposed to `Get-ChildItem` by PowerShell providers. A location can be a file system -directory, registry hive, or a certificate store. Some parameters are only available for a specific -provider. For more information, see +The `Get-ChildItem` cmdlet is designed to work with the items exposed by any provider. For example, +items can be a file system file or directory, registry hive, or a certificate store. To list the +providers available in your session, use the `Get-PSProvider` command. Some parameters are only +available for a specific provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## EXAMPLES @@ -124,7 +86,7 @@ as follows: - `s` (system) For more information about the mode flags, see -[about_Filesystem_Provider](../microsoft.powershell.core/about/about_filesystem_provider.md#attributes-flagsexpression). +[about_Filesystem_Provider](../Microsoft.PowerShell.Core/About/about_Filesystem_Provider.md#attributes-flagsexpression). ### Example 2: Get child item names in a directory @@ -346,8 +308,8 @@ authority. Get-ChildItem -Path Cert:\* -Recurse -CodeSigningCert ``` -For more information about the Certificate provider and the `Cert:` drive, -see [about_Certificate_Provider](../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md). +For more information about the Certificate provider and the `Cert:` drive, see +[about_Certificate_Provider](../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md). ### Example 8: Get items using the Depth parameter @@ -437,7 +399,7 @@ filesystem object returned by `Get-ChildItem` and is displayed in the default ou ```powershell PS D:\> New-Item -ItemType Junction -Name tmp -Target $env:TEMP -PS D:\> Get-ChildItem | Select-Object name,LinkTarget +PS D:\> Get-ChildItem | Select-Object name, LinkTarget Name LinkTarget ---- ---------- @@ -489,26 +451,27 @@ For example, to get non-system files (not directories) that are encrypted or com To find files and folders with commonly used attributes, use the **Attributes** parameter. Or, the parameters **Directory**, **File**, **Hidden**, **ReadOnly**, and **System**. -The **Attributes** parameter supports the following properties: - -- **Archive** -- **Compressed** -- **Device** -- **Directory** -- **Encrypted** -- **Hidden** -- **IntegrityStream** -- **Normal** -- **NoScrubData** -- **NotContentIndexed** -- **Offline** -- **ReadOnly** -- **ReparsePoint** -- **SparseFile** -- **System** -- **Temporary** - -For a description of these attributes, see the [FileAttributes Enumeration](/dotnet/api/system.io.fileattributes). +The **Attributes** parameter supports the following values: + +- `Archive` +- `Compressed` +- `Device` +- `Directory` +- `Encrypted` +- `Hidden` +- `IntegrityStream` +- `Normal` +- `NoScrubData` +- `NotContentIndexed` +- `Offline` +- `ReadOnly` +- `ReparsePoint` +- `SparseFile` +- `System` +- `Temporary` + +For a description of these attributes, see the [FileAttributes](xref:System.IO.FileAttributes) +enumeration. To combine attributes, use the following operators: @@ -796,7 +759,7 @@ Accept wildcard characters: False Allows the cmdlet to get items that otherwise can't be accessed by the user, such as hidden or system files. The **Force** parameter doesn't override security restrictions. Implementation varies -among providers. For more information, see +by provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml @@ -863,7 +826,8 @@ typed. No characters are interpreted as wildcards. If the path includes escape c it in single quotation marks. Single quotation marks tell PowerShell to not 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[] @@ -897,8 +861,9 @@ Accept wildcard characters: False ### -Path -Specifies a path to one or more locations. Wildcards are accepted. The default location is the -current directory (`.`). +Specifies a path to one or more locations. If not specified, the default location is the current +directory (`.`). Wildcards are accepted. Use care when using the **Path** parameter with the +**Recurse** parameter. For more information, see the [NOTES](#notes) section of this article. ```yaml Type: System.String[] @@ -1061,12 +1026,33 @@ PowerShell includes the following aliases for `Get-ChildItem`: - Windows: - `ls` -`Get-ChildItem` doesn't get hidden items by default. To get hidden items, use the **Force** -parameter. +**Recursion behavior with the Path parameter:** -The `Get-ChildItem` cmdlet is designed to work with the data exposed by any provider. To list the -providers available in your session, type `Get-PSProvider`. For more information, see -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +When you use `Get-ChildItem -Recurse` with the **Path** parameter, the cmdlet searches for the last +path component whether or not it's a wildcard pattern or a literal name. + +- If the last path component matches an existing immediate subdirectory of the target directory, the + cmdlet performs recursive enumeration on the matching directory. +- If the last path component doesn't match an existing immediate subdirectory of the target + directory, the cmdlet recursively searches the target directory's hierarchy for items that match + the last path component + +When you use `Get-ChildItem -Recurse` with the **Path** and **Name** parameters, the behavior +changes. The command searches for the last path component among the immediate child items of the +target directory. + +- If there is a match among the immediate child items, the cmdlet performs recursive enumeration on + the matching items. Wildcard matching happens only once, at the top level of the target directory. + The results are processed as if they had been individually passed to the **LiteralPath** + parameter. +- If the last path component doesn't match any items at the top level, an error occurs. + +You should avoid using the **Path** parameter with the **Recurse** parameter. For best results: + +- Use **LiteralPath** to specify the target directory to avoid triggering a recursive search for the + last path component. +- Use **Filter** or **Include** parameters to specify wildcard or literal patterns that should be + searched for in every level of the target directory's hierarchy. ## RELATED LINKS @@ -1074,7 +1060,7 @@ providers available in your session, type `Get-PSProvider`. For more information [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) -[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md) +[about_Quoting_Rules](../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md) [about_Registry_Provider](../Microsoft.PowerShell.Core/About/about_Registry_Provider.md) diff --git a/reference/7.5/Microsoft.PowerShell.Management/Get-ChildItem.md b/reference/7.5/Microsoft.PowerShell.Management/Get-ChildItem.md index eef880f55ba7..6ec1db30c09f 100644 --- a/reference/7.5/Microsoft.PowerShell.Management/Get-ChildItem.md +++ b/reference/7.5/Microsoft.PowerShell.Management/Get-ChildItem.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 08/09/2024 +ms.date: 02/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/get-childitem?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Get-ChildItem @@ -31,44 +31,6 @@ Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] [] ``` -### Items (Default) - Certificate provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### LiteralItems - Certificate provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### Items (Default) - Filesystem provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - -### LiteralItems - FileSystem provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - ## DESCRIPTION The `Get-ChildItem` cmdlet gets the items in one or more specified locations. If the item is a @@ -79,9 +41,10 @@ of levels to recurse. `Get-ChildItem` doesn't display empty directories. When a `Get-ChildItem` command includes the **Depth** or **Recurse** parameters, empty directories aren't included in the output. -Locations are exposed to `Get-ChildItem` by PowerShell providers. A location can be a file system -directory, registry hive, or a certificate store. Some parameters are only available for a specific -provider. For more information, see +The `Get-ChildItem` cmdlet is designed to work with the items exposed by any provider. For example, +items can be a file system file or directory, registry hive, or a certificate store. To list the +providers available in your session, use the `Get-PSProvider` command. Some parameters are only +available for a specific provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## EXAMPLES @@ -488,24 +451,24 @@ For example, to get non-system files (not directories) that are encrypted or com To find files and folders with commonly used attributes, use the **Attributes** parameter. Or, the parameters **Directory**, **File**, **Hidden**, **ReadOnly**, and **System**. -The **Attributes** parameter supports the following properties: - -- **Archive** -- **Compressed** -- **Device** -- **Directory** -- **Encrypted** -- **Hidden** -- **IntegrityStream** -- **Normal** -- **NoScrubData** -- **NotContentIndexed** -- **Offline** -- **ReadOnly** -- **ReparsePoint** -- **SparseFile** -- **System** -- **Temporary** +The **Attributes** parameter supports the following values: + +- `Archive` +- `Compressed` +- `Device` +- `Directory` +- `Encrypted` +- `Hidden` +- `IntegrityStream` +- `Normal` +- `NoScrubData` +- `NotContentIndexed` +- `Offline` +- `ReadOnly` +- `ReparsePoint` +- `SparseFile` +- `System` +- `Temporary` For a description of these attributes, see the [FileAttributes](xref:System.IO.FileAttributes) enumeration. @@ -796,7 +759,7 @@ Accept wildcard characters: False Allows the cmdlet to get items that otherwise can't be accessed by the user, such as hidden or system files. The **Force** parameter doesn't override security restrictions. Implementation varies -among providers. For more information, see +by provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml @@ -898,8 +861,9 @@ Accept wildcard characters: False ### -Path -Specifies a path to one or more locations. Wildcards are accepted. The default location is the -current directory (`.`). +Specifies a path to one or more locations. If not specified, the default location is the current +directory (`.`). Wildcards are accepted. Use care when using the **Path** parameter with the +**Recurse** parameter. For more information, see the [NOTES](#notes) section of this article. ```yaml Type: System.String[] @@ -1062,12 +1026,33 @@ PowerShell includes the following aliases for `Get-ChildItem`: - Windows: - `ls` -`Get-ChildItem` doesn't get hidden items by default. To get hidden items, use the **Force** -parameter. +**Recursion behavior with the Path parameter:** -The `Get-ChildItem` cmdlet is designed to work with the data exposed by any provider. To list the -providers available in your session, type `Get-PSProvider`. For more information, see -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +When you use `Get-ChildItem -Recurse` with the **Path** parameter, the cmdlet searches for the last +path component whether or not it's a wildcard pattern or a literal name. + +- If the last path component matches an existing immediate subdirectory of the target directory, the + cmdlet performs recursive enumeration on the matching directory. +- If the last path component doesn't match an existing immediate subdirectory of the target + directory, the cmdlet recursively searches the target directory's hierarchy for items that match + the last path component + +When you use `Get-ChildItem -Recurse` with the **Path** and **Name** parameters, the behavior +changes. The command searches for the last path component among the immediate child items of the +target directory. + +- If there is a match among the immediate child items, the cmdlet performs recursive enumeration on + the matching items. Wildcard matching happens only once, at the top level of the target directory. + The results are processed as if they had been individually passed to the **LiteralPath** + parameter. +- If the last path component doesn't match any items at the top level, an error occurs. + +You should avoid using the **Path** parameter with the **Recurse** parameter. For best results: + +- Use **LiteralPath** to specify the target directory to avoid triggering a recursive search for the + last path component. +- Use **Filter** or **Include** parameters to specify wildcard or literal patterns that should be + searched for in every level of the target directory's hierarchy. ## RELATED LINKS diff --git a/reference/7.6/Microsoft.PowerShell.Management/Get-ChildItem.md b/reference/7.6/Microsoft.PowerShell.Management/Get-ChildItem.md index 7e477497615d..7f300f3fc619 100644 --- a/reference/7.6/Microsoft.PowerShell.Management/Get-ChildItem.md +++ b/reference/7.6/Microsoft.PowerShell.Management/Get-ChildItem.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 08/09/2024 +ms.date: 02/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/get-childitem?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: Get-ChildItem @@ -11,7 +11,6 @@ title: Get-ChildItem # Get-ChildItem ## SYNOPSIS - Gets the items and child items in one or more specified locations. ## SYNTAX @@ -32,44 +31,6 @@ Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] [] ``` -### Items (Default) - Certificate provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### LiteralItems - Certificate provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-CodeSigningCert] [-DocumentEncryptionCert] [-SSLServerAuthentication] - [-DnsName ] [-Eku ] [-ExpiringInDays ] - [] -``` - -### Items (Default) - Filesystem provider - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - -### LiteralItems - FileSystem provider - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] - [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - ## DESCRIPTION The `Get-ChildItem` cmdlet gets the items in one or more specified locations. If the item is a @@ -80,9 +41,10 @@ of levels to recurse. `Get-ChildItem` doesn't display empty directories. When a `Get-ChildItem` command includes the **Depth** or **Recurse** parameters, empty directories aren't included in the output. -Locations are exposed to `Get-ChildItem` by PowerShell providers. A location can be a file system -directory, registry hive, or a certificate store. Some parameters are only available for a specific -provider. For more information, see +The `Get-ChildItem` cmdlet is designed to work with the items exposed by any provider. For example, +items can be a file system file or directory, registry hive, or a certificate store. To list the +providers available in your session, use the `Get-PSProvider` command. Some parameters are only +available for a specific provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## EXAMPLES @@ -124,7 +86,7 @@ as follows: - `s` (system) For more information about the mode flags, see -[about_Filesystem_Provider](../microsoft.powershell.core/about/about_filesystem_provider.md#attributes-flagsexpression). +[about_Filesystem_Provider](../Microsoft.PowerShell.Core/About/about_Filesystem_Provider.md#attributes-flagsexpression). ### Example 2: Get child item names in a directory @@ -346,8 +308,8 @@ authority. Get-ChildItem -Path Cert:\* -Recurse -CodeSigningCert ``` -For more information about the Certificate provider and the `Cert:` drive, -see [about_Certificate_Provider](../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md). +For more information about the Certificate provider and the `Cert:` drive, see +[about_Certificate_Provider](../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md). ### Example 8: Get items using the Depth parameter @@ -437,7 +399,7 @@ filesystem object returned by `Get-ChildItem` and is displayed in the default ou ```powershell PS D:\> New-Item -ItemType Junction -Name tmp -Target $env:TEMP -PS D:\> Get-ChildItem | Select-Object name,LinkTarget +PS D:\> Get-ChildItem | Select-Object name, LinkTarget Name LinkTarget ---- ---------- @@ -489,26 +451,27 @@ For example, to get non-system files (not directories) that are encrypted or com To find files and folders with commonly used attributes, use the **Attributes** parameter. Or, the parameters **Directory**, **File**, **Hidden**, **ReadOnly**, and **System**. -The **Attributes** parameter supports the following properties: - -- **Archive** -- **Compressed** -- **Device** -- **Directory** -- **Encrypted** -- **Hidden** -- **IntegrityStream** -- **Normal** -- **NoScrubData** -- **NotContentIndexed** -- **Offline** -- **ReadOnly** -- **ReparsePoint** -- **SparseFile** -- **System** -- **Temporary** - -For a description of these attributes, see the [FileAttributes Enumeration](/dotnet/api/system.io.fileattributes). +The **Attributes** parameter supports the following values: + +- `Archive` +- `Compressed` +- `Device` +- `Directory` +- `Encrypted` +- `Hidden` +- `IntegrityStream` +- `Normal` +- `NoScrubData` +- `NotContentIndexed` +- `Offline` +- `ReadOnly` +- `ReparsePoint` +- `SparseFile` +- `System` +- `Temporary` + +For a description of these attributes, see the [FileAttributes](xref:System.IO.FileAttributes) +enumeration. To combine attributes, use the following operators: @@ -796,7 +759,7 @@ Accept wildcard characters: False Allows the cmdlet to get items that otherwise can't be accessed by the user, such as hidden or system files. The **Force** parameter doesn't override security restrictions. Implementation varies -among providers. For more information, see +by provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml @@ -863,7 +826,8 @@ typed. No characters are interpreted as wildcards. If the path includes escape c it in single quotation marks. Single quotation marks tell PowerShell to not 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[] @@ -897,8 +861,9 @@ Accept wildcard characters: False ### -Path -Specifies a path to one or more locations. Wildcards are accepted. The default location is the -current directory (`.`). +Specifies a path to one or more locations. If not specified, the default location is the current +directory (`.`). Wildcards are accepted. Use care when using the **Path** parameter with the +**Recurse** parameter. For more information, see the [NOTES](#notes) section of this article. ```yaml Type: System.String[] @@ -1061,12 +1026,33 @@ PowerShell includes the following aliases for `Get-ChildItem`: - Windows: - `ls` -`Get-ChildItem` doesn't get hidden items by default. To get hidden items, use the **Force** -parameter. +**Recursion behavior with the Path parameter:** -The `Get-ChildItem` cmdlet is designed to work with the data exposed by any provider. To list the -providers available in your session, type `Get-PSProvider`. For more information, see -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +When you use `Get-ChildItem -Recurse` with the **Path** parameter, the cmdlet searches for the last +path component whether or not it's a wildcard pattern or a literal name. + +- If the last path component matches an existing immediate subdirectory of the target directory, the + cmdlet performs recursive enumeration on the matching directory. +- If the last path component doesn't match an existing immediate subdirectory of the target + directory, the cmdlet recursively searches the target directory's hierarchy for items that match + the last path component + +When you use `Get-ChildItem -Recurse` with the **Path** and **Name** parameters, the behavior +changes. The command searches for the last path component among the immediate child items of the +target directory. + +- If there is a match among the immediate child items, the cmdlet performs recursive enumeration on + the matching items. Wildcard matching happens only once, at the top level of the target directory. + The results are processed as if they had been individually passed to the **LiteralPath** + parameter. +- If the last path component doesn't match any items at the top level, an error occurs. + +You should avoid using the **Path** parameter with the **Recurse** parameter. For best results: + +- Use **LiteralPath** to specify the target directory to avoid triggering a recursive search for the + last path component. +- Use **Filter** or **Include** parameters to specify wildcard or literal patterns that should be + searched for in every level of the target directory's hierarchy. ## RELATED LINKS @@ -1074,7 +1060,7 @@ providers available in your session, type `Get-PSProvider`. For more information [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) -[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md) +[about_Quoting_Rules](../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md) [about_Registry_Provider](../Microsoft.PowerShell.Core/About/about_Registry_Provider.md)