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) diff --git a/reference/docs-conceptual/learn/shell/creating-profiles.md b/reference/docs-conceptual/learn/shell/creating-profiles.md index 526f39419b23..0c631483bf00 100644 --- a/reference/docs-conceptual/learn/shell/creating-profiles.md +++ b/reference/docs-conceptual/learn/shell/creating-profiles.md @@ -2,7 +2,7 @@ description: > This article explains how to use your profile to save preferred PowerShell settings and optimize your shell experience. -ms.date: 09/04/2024 +ms.date: 02/26/2025 title: Customizing your shell environment --- # Customizing your shell environment @@ -10,11 +10,11 @@ title: Customizing your shell environment A PowerShell profile is a script that runs when PowerShell starts. You can use the profile to customize the environment. You can: -- add aliases, functions, and variables -- load modules -- create PowerShell drives -- run arbitrary commands -- and change preference settings +- Add aliases, functions, and variables +- Load modules +- Create PowerShell drives +- Run arbitrary commands +- Change preference settings Putting these settings in your profile ensures that they're available whenever you start PowerShell on your system. @@ -39,32 +39,47 @@ properties of `$PROFILE`. - **CurrentUserCurrentHost** You can create profile scripts that run for all users or just one user, the **CurrentUser**. -**CurrentUser** profiles are stored in the user's home directory. - -There are also profiles that run for all PowerShell hosts or specific hosts. The profile script -for each PowerShell host has a name unique for that host. For example, the filename for the standard -Console Host on Windows or the default terminal application on other platforms is -`Microsoft.PowerShell_profile.ps1`. For Visual Studio Code (VS Code), the filename is -`Microsoft.VSCode_profile.ps1`. - -For more information, see [about_Profiles][2]. +**CurrentUser** profiles are stored under the user's home directory path. The location varies +depending on the operating system and the version of PowerShell you use. By default, referencing the `$PROFILE` variable returns the path to the "Current User, Current Host" profile. The other profiles path can be accessed through the properties of the `$PROFILE` variable. -For example: +The following command shows the default profile locations on Windows. ```powershell -PS> $PROFILE -C:\Users\user1\Documents\PowerShell\Microsoft.PowerShell_profile.ps1 -PS> $PROFILE.AllUsersAllHosts -C:\Program Files\PowerShell\7\profile.ps1 +PS> $PROFILE | Select-Object * +AllUsersAllHosts : C:\Program Files\PowerShell\7\profile.ps1 +AllUsersCurrentHost : C:\Program Files\PowerShell\7\Microsoft.PowerShell_profile.ps1 +CurrentUserAllHosts : C:\Users\username\Documents\PowerShell\profile.ps1 +CurrentUserCurrentHost : C:\Users\username\Documents\PowerShell\Microsoft.PowerShell_profile.ps1 +Length : 69 ``` +The following command shows the default profile locations on Ubuntu Linux. + +```powershell +$PROFILE | Select-Object * + +AllUsersAllHosts : /opt/microsoft/powershell/7/profile.ps1 +AllUsersCurrentHost : /opt/microsoft/powershell/7/Microsoft.PowerShell_profile.ps1 +CurrentUserAllHosts : /home/username/.config/powershell/profile.ps1 +CurrentUserCurrentHost : /home/username/.config/powershell/Microsoft.PowerShell_profile.ps1 +Length : 67 +``` + +There are also profiles that run for all PowerShell hosts or specific hosts. The profile script for +each PowerShell host has a name unique for that host. For example, the filename for the standard +Console Host on Windows or the default terminal application on other platforms is +`Microsoft.PowerShell_profile.ps1`. For Visual Studio Code (VS Code), the filename is +`Microsoft.VSCode_profile.ps1`. + +For more information, see [about_Profiles][2]. + ## How to create your personal profile When you first install PowerShell on a system, the profile script files and the directories they -belong to don't exist. The following command creates the "Current User, Current Host" -profile script file if it doesn't exist. +belong to don't exist. The following command creates the "Current User, Current Host" profile script +file if it doesn't exist. ```powershell if (!(Test-Path -Path $PROFILE)) { @@ -73,14 +88,14 @@ if (!(Test-Path -Path $PROFILE)) { ``` The **Force** parameter of `New-Item` cmdlet creates the necessary folders when they don't exist. -Once you have created the script file, you can use your favorite editor to customize your shell +After you create the script file, you can use your favorite editor to customize your shell environment. ## Adding customizations to your profile The previous articles talked about using [tab completion][3], [command predictors][4], and [aliases][5]. These articles showed the commands used to load the required modules, create custom -completers, define keybindings, and other settings. These are the kinds of customizations that you +completers, define key bindings, and other settings. These are the kinds of customizations that you want to have available in every PowerShell interactive session. The profile script is the place for these settings. @@ -163,11 +178,11 @@ Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock This profile script provides examples for the following customization: - Adds two new [PSDrives][7] for the other root registry hives. -- Creates a [customized prompt][8] that changes if you are running in an elevated session. -- Configures **PSReadLine** and adds keybinding. The color settings use the [$PSStyle][9] feature to - define the ANSI color settings. -- Adds tab completion for the [dotnet CLI][10] tool. The tool provides parameters to help resolve the - command-line arguments. The script block for [Register-ArgumentCompleter][11] uses that +- Creates a [customized prompt][8] that changes if you're running in an elevated session. +- Configures **PSReadLine** and adds key binding. The color settings use the [$PSStyle][9] feature + to define the ANSI color settings. +- Adds tab completion for the [dotnet CLI][10] tool. The tool provides parameters to help resolve + the command-line arguments. The script block for [Register-ArgumentCompleter][11] uses that feature to provide the tab completion.