From 87c2a931be4412e567beb3d6d049b7ac37806017 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 19 Jan 2024 15:18:37 -0600 Subject: [PATCH 1/2] (GH-10742) Update `Test-Path` for 7.5 This change: - Updates the example for using the **OlderThan** and **NewerThan** parameters to show using them for a date range in 7.5. - Updates the description for the parameters to clarify the prior limitation on using them with the **PathType** parameter, each other, and directories. - Resolves #10742 - Fixes AB#201369 --- .../Test-Path.md | 32 ++++++++++++++++--- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md index e4c366b3217a..47adcc6ce66c 100644 --- a/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md @@ -159,15 +159,17 @@ Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerS False ``` -### Example 6: Test if a file is newer than a specified date +### Example 6: Test if a file is in a date range -This command uses the **NewerThan** dynamic parameter to determine whether the "PowerShell.exe" file -on the computer is newer than "July 13, 2009". +This command uses the **NewerThan** and **OlderThan** dynamic parameters to determine whether the +`pwsh.exe` file on the computer is newer than `July 13, 2009` and older than last week. -The NewerThan parameter works only in file system drives. +The **NewerThan** and **OlderThan** parameters only work in file system drives. ```powershell -Test-Path $pshome\pwsh.exe -NewerThan "July 13, 2009" +Get-Command pwsh | + Select-Object -ExpandProperty Path | + Test-Path -NewerThan "July 13, 2009" -OlderThan (Get-Date).AddDays(-7) ``` ```Output @@ -328,6 +330,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- The **OlderThan** parameter when used with this parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **OlderThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -349,6 +361,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- This parameter when used with the **NewerThan** parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **NewerThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). From 3aceca25c9f14f2292f4911959458d1c752b8bb8 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 19 Jan 2024 15:26:21 -0600 Subject: [PATCH 2/2] (MAINT) Fix lint warnings + sync updates --- .../Test-Path.md | 109 +++++++++++------- .../Test-Path.md | 105 ++++++++++------- .../Test-Path.md | 105 ++++++++++------- .../Test-Path.md | 105 ++++++++++------- .../Test-Path.md | 81 ++++++------- 5 files changed, 295 insertions(+), 210 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Test-Path.md b/reference/5.1/Microsoft.PowerShell.Management/Test-Path.md index 060315767e30..1495c67c8c7b 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Test-Path.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: 02/16/2023 +ms.date: 01/19/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Test-Path @@ -48,11 +48,11 @@ Test-Path -LiteralPath [-Filter ] [-Include ] [-Exc ## DESCRIPTION -The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$True` if all -elements exist and `$False` if any are missing. It can also tell whether the path syntax is valid +The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$true` if all +elements exist and `$false` if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element. If the **Path** is a -whitespace or empty string, then `$False` is returned. If the **Path** is `$null`, array of `$null` -or empty array, a non-terminating error is returned. +whitespace or empty string, then the cmdlet returns `$false`. If the **Path** is `$null`, an array +of `$null` or an empty array, the cmdlet returns a non-terminating error. ## EXAMPLES @@ -66,9 +66,9 @@ Test-Path -Path "C:\Documents and Settings\DavidC" True ``` -This command checks whether all elements in the path exist, that is, the `C:` directory, the +This command checks whether all elements in the path exist, including the `C:` directory, the `Documents and Settings` directory, and the `DavidC` directory. If any are missing, the cmdlet -returns `$False`. Otherwise, it returns `$True`. +returns `$false`. Otherwise, it returns `$true`. ### Example 2: Test the path of a profile @@ -91,11 +91,12 @@ True These commands test the path of the PowerShell profile. The first command determines whether all elements in the path exist. The second command determines -whether the syntax of the path is correct. In this case, the path is `$False`, but the syntax is -correct `$True`. These commands use `$profile`, the automatic variable that points to the location -for the profile, even if the profile does not exist. +whether the syntax of the path is correct. In this case, the path is `$false`, but the syntax is +correct `$true`. These commands use `$profile`, the automatic variable that points to the location +for the profile, even if the profile doesn't exist. -For more information about automatic variables, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +For more information about automatic variables, see +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ### Example 3: Check whether there are any files besides a specified type @@ -115,10 +116,9 @@ path is enclosed in quotation marks. The asterisk at the end of the path indicat the Commercial Building directory. With long paths, such as this one, type the first few letters of the path, and then use the TAB key to complete the path. -The command specifies the **Exclude** parameter to specify files that will be omitted from the -evaluation. +The command specifies the **Exclude** parameter to specify files to omit from the evaluation. -In this case, because the directory contains only .dwg files, the result is `$False`. +In this case, because the directory contains only .dwg files, the result is `$false`. ### Example 4: Check for a file @@ -131,19 +131,19 @@ True ``` This command checks whether the path stored in the `$profile` variable leads to a file. In this -case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$True`. +case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$true`. ### Example 5: Check paths in the Registry These commands use `Test-Path` with the PowerShell registry provider. The first command tests whether the registry path of the **Microsoft.PowerShell** registry key is -correct on the system. If PowerShell is installed correctly, the cmdlet returns `$True`. +correct on the system. If PowerShell is installed correctly, the cmdlet returns `$true`. > [!IMPORTANT] -> `Test-Path` does not work correctly with all PowerShell providers. For example, you can use +> `Test-Path` doesn't work correctly with all PowerShell providers. For example, you can use > `Test-Path` to test the path of a registry key, but if you use it to test the path of a registry -> entry, it always returns `$False`, even if the registry entry is present. +> entry, it always returns `$false`, even if the registry entry is present. ```powershell Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" @@ -163,8 +163,8 @@ False ### Example 6: Test if a file is newer than a specified date -This command uses the **NewerThan** dynamic parameter to determine whether the "PowerShell.exe" file -on the computer is newer than "July 13, 2009". +This command uses the **NewerThan** dynamic parameter to determine whether the `PowerShell.exe` +file on the computer is newer than `July 13, 2009`. The NewerThan parameter works only in file system drives. @@ -179,7 +179,7 @@ True ### Example 7: Test a path with null as the value The error returned for `null`, array of `null` or empty array is a non-terminating error. It can be -suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases which +suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases that return the `NullPathNotPermitted` error. ```powershell @@ -199,9 +199,9 @@ At line:1 char:11 ### Example 8: Test a path with whitespace as the value -When a whitespace string is provided for the the **Path** parameter, it returns **True**. When an -empty string is provided, `Test-Path` returns an error. The following example shows whitespace and -empty string. +When a whitespace string is provided for the **Path** parameter, it returns `$true`. When an empty +string is provided, `Test-Path` returns an error. The following example shows whitespace and empty +string. ```powershell Test-Path ' ' @@ -242,7 +242,7 @@ Accept wildcard characters: False ### -Exclude Specifies items that this cmdlet omits. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -260,8 +260,8 @@ Accept wildcard characters: True Specifies a filter in the format or language of the provider. The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends -on the provider. Filters are more efficient than other parameters, because the provider applies them -when it retrieves the objects instead of having PowerShell filter the objects after they are +on the provider. Filters are more efficient than other parameters, because the provider applies +them when it retrieves the objects instead of having PowerShell filter the objects after they're retrieved. ```yaml @@ -279,7 +279,7 @@ Accept wildcard characters: True ### -Include Specifies paths that this cmdlet tests. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -296,7 +296,7 @@ Accept wildcard characters: True ### -IsValid Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the -path exist. This cmdlet returns `$True` if the path syntax is valid and `$False` if it is not. +path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. ```yaml Type: System.Management.Automation.SwitchParameter @@ -313,9 +313,9 @@ Accept wildcard characters: False ### -LiteralPath Specifies a path to be tested. Unlike **Path**, the value of the **LiteralPath** parameter is used -exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes -characters that could be interpreted by PowerShell as escape sequences, you must enclose the path in -single quote so that they won't be interpreted. +exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes +characters that could be interpreted by PowerShell as escape sequences, you must enclose the path +in single quote so that they won't be interpreted. ```yaml Type: System.String[] @@ -335,6 +335,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- The **OlderThan** parameter when used with this parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **OlderThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -356,6 +366,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- This parameter when used with the **NewerThan** parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **NewerThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -390,24 +410,24 @@ Accept wildcard characters: True ### -PathType -Specifies the type of the final element in the path. This cmdlet returns `$True` if the element is -of the specified type and `$False` if it is not. The acceptable values for this parameter are: +Specifies the type of the final element in the path. This cmdlet returns `$true` if the element is +of the specified type and `$false` if it's not. The acceptable values for this parameter are: - `Container` - An element that contains other elements, such as a directory or registry key. -- `Leaf` - An element that does not contain other elements, such as a file. +- `Leaf` - An element that doesn't contain other elements, such as a file. - `Any` - Either a container or a leaf. Tells whether the final element in the path is of a particular type. > [!CAUTION] > -> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are -> specified together, the `Test-Path` cmdlet ignores the **PathType** switch and only -> validates the syntactic path without validating the path type. +> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are specified +> together, the `Test-Path` cmdlet ignores the **PathType** switch and only validates the syntactic +> path without validating the path type. > > According to [issue #8607](https://github.com/PowerShell/PowerShell/issues/8607), fixing this > behavior may be a breaking change in a future version, where the **IsValid** and **PathType** -> switches belong to separate parameter sets, and thus, cannot be used together avoiding this +> switches belong to separate parameter sets, and thus, can't be used together avoiding this > confusion. ```yaml @@ -461,14 +481,15 @@ The cmdlet returns a **Boolean** value. ## NOTES -The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return -the names in a concise format that all PowerShell providers can interpret. They are designed for use -in programs and scripts where you want to display all or part of a path name in a particular format. -Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path +The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path and return the +names in a concise format that all PowerShell providers can interpret. They're designed for use in +programs and scripts where you want to display all or part of a path in a particular format. Use +them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. The `Test-Path` 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). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/7.2/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.2/Microsoft.PowerShell.Management/Test-Path.md index e14b73c01376..a839196bdb8d 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Test-Path.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: 02/16/2023 +ms.date: 01/19/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Test-Path @@ -46,11 +46,11 @@ Test-Path -LiteralPath [-Filter ] [-Include ] [-Exc ## DESCRIPTION -The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$True` if all -elements exist and `$False` if any are missing. It can also tell whether the path syntax is valid +The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$true` if all +elements exist and `$false` if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element. If the **Path** is a -whitespace or empty string, then `$False` is returned. If the **Path** is `$null`, array of `$null` -or empty array, a non-terminating error is returned. +whitespace or empty string, then the cmdlet returns `$false`. If the **Path** is `$null`, an array +of `$null` or an empty array, the cmdlet returns a non-terminating error. ## EXAMPLES @@ -64,9 +64,9 @@ Test-Path -Path "C:\Documents and Settings\DavidC" True ``` -This command checks whether all elements in the path exist, that is, the `C:` directory, the +This command checks whether all elements in the path exist, including the `C:` directory, the `Documents and Settings` directory, and the `DavidC` directory. If any are missing, the cmdlet -returns `$False`. Otherwise, it returns `$True`. +returns `$false`. Otherwise, it returns `$true`. ### Example 2: Test the path of a profile @@ -89,11 +89,12 @@ True These commands test the path of the PowerShell profile. The first command determines whether all elements in the path exist. The second command determines -whether the syntax of the path is correct. In this case, the path is `$False`, but the syntax is -correct `$True`. These commands use `$profile`, the automatic variable that points to the location -for the profile, even if the profile does not exist. +whether the syntax of the path is correct. In this case, the path is `$false`, but the syntax is +correct `$true`. These commands use `$profile`, the automatic variable that points to the location +for the profile, even if the profile doesn't exist. -For more information about automatic variables, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +For more information about automatic variables, see +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ### Example 3: Check whether there are any files besides a specified type @@ -113,10 +114,9 @@ path is enclosed in quotation marks. The asterisk at the end of the path indicat the Commercial Building directory. With long paths, such as this one, type the first few letters of the path, and then use the TAB key to complete the path. -The command specifies the **Exclude** parameter to specify files that will be omitted from the -evaluation. +The command specifies the **Exclude** parameter to specify files to omit from the evaluation. -In this case, because the directory contains only .dwg files, the result is `$False`. +In this case, because the directory contains only .dwg files, the result is `$false`. ### Example 4: Check for a file @@ -129,19 +129,19 @@ True ``` This command checks whether the path stored in the `$profile` variable leads to a file. In this -case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$True`. +case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$true`. ### Example 5: Check paths in the Registry These commands use `Test-Path` with the PowerShell registry provider. The first command tests whether the registry path of the **Microsoft.PowerShell** registry key is -correct on the system. If PowerShell is installed correctly, the cmdlet returns `$True`. +correct on the system. If PowerShell is installed correctly, the cmdlet returns `$true`. > [!IMPORTANT] -> `Test-Path` does not work correctly with all PowerShell providers. For example, you can use +> `Test-Path` doesn't work correctly with all PowerShell providers. For example, you can use > `Test-Path` to test the path of a registry key, but if you use it to test the path of a registry -> entry, it always returns `$False`, even if the registry entry is present. +> entry, it always returns `$false`, even if the registry entry is present. ```powershell Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" @@ -161,8 +161,8 @@ False ### Example 6: Test if a file is newer than a specified date -This command uses the **NewerThan** dynamic parameter to determine whether the "PowerShell.exe" file -on the computer is newer than "July 13, 2009". +This command uses the **NewerThan** dynamic parameter to determine whether the `pwsh.exe` file on +the computer is newer than `July 13, 2009`. The NewerThan parameter works only in file system drives. @@ -177,7 +177,7 @@ True ### Example 7: Test a path with null as the value The error returned for `null`, array of `null` or empty array is a non-terminating error. It can be -suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases which +suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases that return the `NullPathNotPermitted` error. ```powershell @@ -197,7 +197,7 @@ At line:1 char:11 ### Example 8: Test a path with whitespace as the value -When a whitespace string is provided for the **Path** parameter, it returns **False**. This is a +When a whitespace string is provided for the **Path** parameter, it returns `$false`. This is a change from Windows PowerShell 5.1. When an empty string is provided, `Test-Path` returns an error. The following example shows whitespace and empty string. @@ -235,7 +235,7 @@ Accept wildcard characters: False ### -Exclude Specifies items that this cmdlet omits. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -253,8 +253,8 @@ Accept wildcard characters: True Specifies a filter in the format or language of the provider. The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends -on the provider. Filters are more efficient than other parameters, because the provider applies them -when it retrieves the objects instead of having PowerShell filter the objects after they are +on the provider. Filters are more efficient than other parameters, because the provider applies +them when it retrieves the objects instead of having PowerShell filter the objects after they're retrieved. ```yaml @@ -272,7 +272,7 @@ Accept wildcard characters: True ### -Include Specifies paths that this cmdlet tests. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -289,7 +289,7 @@ Accept wildcard characters: True ### -IsValid Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the -path exist. This cmdlet returns `$True` if the path syntax is valid and `$False` if it is not. +path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. ```yaml Type: System.Management.Automation.SwitchParameter @@ -306,9 +306,9 @@ Accept wildcard characters: False ### -LiteralPath Specifies a path to be tested. Unlike **Path**, the value of the **LiteralPath** parameter is used -exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes -characters that could be interpreted by PowerShell as escape sequences, you must enclose the path in -single quote so that they won't be interpreted. +exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes +characters that could be interpreted by PowerShell as escape sequences, you must enclose the path +in single quote so that they won't be interpreted. ```yaml Type: System.String[] @@ -328,6 +328,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- The **OlderThan** parameter when used with this parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **OlderThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -349,6 +359,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- This parameter when used with the **NewerThan** parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **NewerThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -383,24 +403,24 @@ Accept wildcard characters: True ### -PathType -Specifies the type of the final element in the path. This cmdlet returns `$True` if the element is -of the specified type and `$False` if it is not. The acceptable values for this parameter are: +Specifies the type of the final element in the path. This cmdlet returns `$true` if the element is +of the specified type and `$false` if it's not. The acceptable values for this parameter are: - `Container` - An element that contains other elements, such as a directory or registry key. -- `Leaf` - An element that does not contain other elements, such as a file. +- `Leaf` - An element that doesn't contain other elements, such as a file. - `Any` - Either a container or a leaf. Tells whether the final element in the path is of a particular type. > [!CAUTION] > -> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are -> specified together, the `Test-Path` cmdlet ignores the **PathType** switch and only -> validates the syntactic path without validating the path type. +> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are specified +> together, the `Test-Path` cmdlet ignores the **PathType** switch and only validates the syntactic +> path without validating the path type. > > According to [issue #8607](https://github.com/PowerShell/PowerShell/issues/8607), fixing this > behavior may be a breaking change in a future version, where the **IsValid** and **PathType** -> switches belong to separate parameter sets, and thus, cannot be used together avoiding this +> switches belong to separate parameter sets, and thus, can't be used together avoiding this > confusion. ```yaml @@ -437,14 +457,15 @@ The cmdlet returns a **Boolean** value. ## NOTES -The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return -the names in a concise format that all PowerShell providers can interpret. They are designed for use -in programs and scripts where you want to display all or part of a path name in a particular format. -Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path +The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path and return the +names in a concise format that all PowerShell providers can interpret. They're designed for use in +programs and scripts where you want to display all or part of a path in a particular format. Use +them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. The `Test-Path` 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). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/7.3/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.3/Microsoft.PowerShell.Management/Test-Path.md index 71b538af6104..75f271b5eed1 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Test-Path.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: 02/16/2023 +ms.date: 01/19/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Test-Path @@ -46,11 +46,11 @@ Test-Path -LiteralPath [-Filter ] [-Include ] [-Exc ## DESCRIPTION -The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$True` if all -elements exist and `$False` if any are missing. It can also tell whether the path syntax is valid +The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$true` if all +elements exist and `$false` if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element. If the **Path** is a -whitespace or empty string, then `$False` is returned. If the **Path** is `$null`, array of `$null` -or empty array, a non-terminating error is returned. +whitespace or empty string, then the cmdlet returns `$false`. If the **Path** is `$null`, an array +of `$null` or an empty array, the cmdlet returns a non-terminating error. ## EXAMPLES @@ -64,9 +64,9 @@ Test-Path -Path "C:\Documents and Settings\DavidC" True ``` -This command checks whether all elements in the path exist, that is, the `C:` directory, the +This command checks whether all elements in the path exist, including the `C:` directory, the `Documents and Settings` directory, and the `DavidC` directory. If any are missing, the cmdlet -returns `$False`. Otherwise, it returns `$True`. +returns `$false`. Otherwise, it returns `$true`. ### Example 2: Test the path of a profile @@ -89,11 +89,12 @@ True These commands test the path of the PowerShell profile. The first command determines whether all elements in the path exist. The second command determines -whether the syntax of the path is correct. In this case, the path is `$False`, but the syntax is -correct `$True`. These commands use `$profile`, the automatic variable that points to the location -for the profile, even if the profile does not exist. +whether the syntax of the path is correct. In this case, the path is `$false`, but the syntax is +correct `$true`. These commands use `$profile`, the automatic variable that points to the location +for the profile, even if the profile doesn't exist. -For more information about automatic variables, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +For more information about automatic variables, see +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ### Example 3: Check whether there are any files besides a specified type @@ -113,10 +114,9 @@ path is enclosed in quotation marks. The asterisk at the end of the path indicat the Commercial Building directory. With long paths, such as this one, type the first few letters of the path, and then use the TAB key to complete the path. -The command specifies the **Exclude** parameter to specify files that will be omitted from the -evaluation. +The command specifies the **Exclude** parameter to specify files to omit from the evaluation. -In this case, because the directory contains only .dwg files, the result is `$False`. +In this case, because the directory contains only .dwg files, the result is `$false`. ### Example 4: Check for a file @@ -129,19 +129,19 @@ True ``` This command checks whether the path stored in the `$profile` variable leads to a file. In this -case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$True`. +case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$true`. ### Example 5: Check paths in the Registry These commands use `Test-Path` with the PowerShell registry provider. The first command tests whether the registry path of the **Microsoft.PowerShell** registry key is -correct on the system. If PowerShell is installed correctly, the cmdlet returns `$True`. +correct on the system. If PowerShell is installed correctly, the cmdlet returns `$true`. > [!IMPORTANT] -> `Test-Path` does not work correctly with all PowerShell providers. For example, you can use +> `Test-Path` doesn't work correctly with all PowerShell providers. For example, you can use > `Test-Path` to test the path of a registry key, but if you use it to test the path of a registry -> entry, it always returns `$False`, even if the registry entry is present. +> entry, it always returns `$false`, even if the registry entry is present. ```powershell Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" @@ -161,8 +161,8 @@ False ### Example 6: Test if a file is newer than a specified date -This command uses the **NewerThan** dynamic parameter to determine whether the "PowerShell.exe" file -on the computer is newer than "July 13, 2009". +This command uses the **NewerThan** dynamic parameter to determine whether the `pwsh.exe` file on +the computer is newer than `July 13, 2009`. The NewerThan parameter works only in file system drives. @@ -177,7 +177,7 @@ True ### Example 7: Test a path with null as the value The error returned for `null`, array of `null` or empty array is a non-terminating error. It can be -suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases which +suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases that return the `NullPathNotPermitted` error. ```powershell @@ -197,7 +197,7 @@ At line:1 char:11 ### Example 8: Test a path with whitespace as the value -When a whitespace string is provided for the the **Path** parameter, it returns **False**. This is a +When a whitespace string is provided for the **Path** parameter, it returns `$false`. This is a change from Windows PowerShell 5.1. When an empty string is provided, `Test-Path` returns an error. The following example shows whitespace and empty string. @@ -235,7 +235,7 @@ Accept wildcard characters: False ### -Exclude Specifies items that this cmdlet omits. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -253,8 +253,8 @@ Accept wildcard characters: True Specifies a filter in the format or language of the provider. The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends -on the provider. Filters are more efficient than other parameters, because the provider applies them -when it retrieves the objects instead of having PowerShell filter the objects after they are +on the provider. Filters are more efficient than other parameters, because the provider applies +them when it retrieves the objects instead of having PowerShell filter the objects after they're retrieved. ```yaml @@ -272,7 +272,7 @@ Accept wildcard characters: True ### -Include Specifies paths that this cmdlet tests. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -289,7 +289,7 @@ Accept wildcard characters: True ### -IsValid Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the -path exist. This cmdlet returns `$True` if the path syntax is valid and `$False` if it is not. +path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. ```yaml Type: System.Management.Automation.SwitchParameter @@ -306,9 +306,9 @@ Accept wildcard characters: False ### -LiteralPath Specifies a path to be tested. Unlike **Path**, the value of the **LiteralPath** parameter is used -exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes -characters that could be interpreted by PowerShell as escape sequences, you must enclose the path in -single quote so that they won't be interpreted. +exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes +characters that could be interpreted by PowerShell as escape sequences, you must enclose the path +in single quote so that they won't be interpreted. ```yaml Type: System.String[] @@ -328,6 +328,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- The **OlderThan** parameter when used with this parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **OlderThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -349,6 +359,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- This parameter when used with the **NewerThan** parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **NewerThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -383,24 +403,24 @@ Accept wildcard characters: True ### -PathType -Specifies the type of the final element in the path. This cmdlet returns `$True` if the element is -of the specified type and `$False` if it is not. The acceptable values for this parameter are: +Specifies the type of the final element in the path. This cmdlet returns `$true` if the element is +of the specified type and `$false` if it's not. The acceptable values for this parameter are: - `Container` - An element that contains other elements, such as a directory or registry key. -- `Leaf` - An element that does not contain other elements, such as a file. +- `Leaf` - An element that doesn't contain other elements, such as a file. - `Any` - Either a container or a leaf. Tells whether the final element in the path is of a particular type. > [!CAUTION] > -> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are -> specified together, the `Test-Path` cmdlet ignores the **PathType** switch and only -> validates the syntactic path without validating the path type. +> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are specified +> together, the `Test-Path` cmdlet ignores the **PathType** switch and only validates the syntactic +> path without validating the path type. > > According to [issue #8607](https://github.com/PowerShell/PowerShell/issues/8607), fixing this > behavior may be a breaking change in a future version, where the **IsValid** and **PathType** -> switches belong to separate parameter sets, and thus, cannot be used together avoiding this +> switches belong to separate parameter sets, and thus, can't be used together avoiding this > confusion. ```yaml @@ -437,14 +457,15 @@ The cmdlet returns a **Boolean** value. ## NOTES -The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return -the names in a concise format that all PowerShell providers can interpret. They are designed for use -in programs and scripts where you want to display all or part of a path name in a particular format. -Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path +The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path and return the +names in a concise format that all PowerShell providers can interpret. They're designed for use in +programs and scripts where you want to display all or part of a path in a particular format. Use +them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. The `Test-Path` 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). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/7.4/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.4/Microsoft.PowerShell.Management/Test-Path.md index 49cea5d28947..39a2191a0109 100644 --- a/reference/7.4/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/7.4/Microsoft.PowerShell.Management/Test-Path.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: 02/16/2023 +ms.date: 01/19/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Test-Path @@ -46,11 +46,11 @@ Test-Path -LiteralPath [-Filter ] [-Include ] [-Exc ## DESCRIPTION -The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$True` if all -elements exist and `$False` if any are missing. It can also tell whether the path syntax is valid +The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$true` if all +elements exist and `$false` if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element. If the **Path** is a -whitespace or empty string, then `$False` is returned. If the **Path** is `$null`, array of `$null` -or empty array, a non-terminating error is returned. +whitespace or empty string, then the cmdlet returns `$false`. If the **Path** is `$null`, an array +of `$null` or an empty array, the cmdlet returns a non-terminating error. ## EXAMPLES @@ -64,9 +64,9 @@ Test-Path -Path "C:\Documents and Settings\DavidC" True ``` -This command checks whether all elements in the path exist, that is, the `C:` directory, the +This command checks whether all elements in the path exist, including the `C:` directory, the `Documents and Settings` directory, and the `DavidC` directory. If any are missing, the cmdlet -returns `$False`. Otherwise, it returns `$True`. +returns `$false`. Otherwise, it returns `$true`. ### Example 2: Test the path of a profile @@ -89,11 +89,12 @@ True These commands test the path of the PowerShell profile. The first command determines whether all elements in the path exist. The second command determines -whether the syntax of the path is correct. In this case, the path is `$False`, but the syntax is -correct `$True`. These commands use `$profile`, the automatic variable that points to the location -for the profile, even if the profile does not exist. +whether the syntax of the path is correct. In this case, the path is `$false`, but the syntax is +correct `$true`. These commands use `$profile`, the automatic variable that points to the location +for the profile, even if the profile doesn't exist. -For more information about automatic variables, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +For more information about automatic variables, see +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ### Example 3: Check whether there are any files besides a specified type @@ -113,10 +114,9 @@ path is enclosed in quotation marks. The asterisk at the end of the path indicat the Commercial Building directory. With long paths, such as this one, type the first few letters of the path, and then use the TAB key to complete the path. -The command specifies the **Exclude** parameter to specify files that will be omitted from the -evaluation. +The command specifies the **Exclude** parameter to specify files to omit from the evaluation. -In this case, because the directory contains only .dwg files, the result is `$False`. +In this case, because the directory contains only .dwg files, the result is `$false`. ### Example 4: Check for a file @@ -129,19 +129,19 @@ True ``` This command checks whether the path stored in the `$profile` variable leads to a file. In this -case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$True`. +case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$true`. ### Example 5: Check paths in the Registry These commands use `Test-Path` with the PowerShell registry provider. The first command tests whether the registry path of the **Microsoft.PowerShell** registry key is -correct on the system. If PowerShell is installed correctly, the cmdlet returns `$True`. +correct on the system. If PowerShell is installed correctly, the cmdlet returns `$true`. > [!IMPORTANT] -> `Test-Path` does not work correctly with all PowerShell providers. For example, you can use +> `Test-Path` doesn't work correctly with all PowerShell providers. For example, you can use > `Test-Path` to test the path of a registry key, but if you use it to test the path of a registry -> entry, it always returns `$False`, even if the registry entry is present. +> entry, it always returns `$false`, even if the registry entry is present. ```powershell Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" @@ -161,8 +161,8 @@ False ### Example 6: Test if a file is newer than a specified date -This command uses the **NewerThan** dynamic parameter to determine whether the "PowerShell.exe" file -on the computer is newer than "July 13, 2009". +This command uses the **NewerThan** dynamic parameter to determine whether the `pwsh.exe` file on +the computer is newer than `July 13, 2009`. The NewerThan parameter works only in file system drives. @@ -177,7 +177,7 @@ True ### Example 7: Test a path with null as the value The error returned for `null`, array of `null` or empty array is a non-terminating error. It can be -suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases which +suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases that return the `NullPathNotPermitted` error. ```powershell @@ -197,7 +197,7 @@ At line:1 char:11 ### Example 8: Test a path with whitespace as the value -When a whitespace string is provided for the the **Path** parameter, it returns **False**. This is a +When a whitespace string is provided for the **Path** parameter, it returns `$false`. This is a change from Windows PowerShell 5.1. When an empty string is provided, `Test-Path` returns an error. The following example shows whitespace and empty string. @@ -235,7 +235,7 @@ Accept wildcard characters: False ### -Exclude Specifies items that this cmdlet omits. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -253,8 +253,8 @@ Accept wildcard characters: True Specifies a filter in the format or language of the provider. The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends -on the provider. Filters are more efficient than other parameters, because the provider applies them -when it retrieves the objects instead of having PowerShell filter the objects after they are +on the provider. Filters are more efficient than other parameters, because the provider applies +them when it retrieves the objects instead of having PowerShell filter the objects after they're retrieved. ```yaml @@ -272,7 +272,7 @@ Accept wildcard characters: True ### -Include Specifies paths that this cmdlet tests. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -289,7 +289,7 @@ Accept wildcard characters: True ### -IsValid Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the -path exist. This cmdlet returns `$True` if the path syntax is valid and `$False` if it is not. +path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. ```yaml Type: System.Management.Automation.SwitchParameter @@ -306,9 +306,9 @@ Accept wildcard characters: False ### -LiteralPath Specifies a path to be tested. Unlike **Path**, the value of the **LiteralPath** parameter is used -exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes -characters that could be interpreted by PowerShell as escape sequences, you must enclose the path in -single quote so that they won't be interpreted. +exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes +characters that could be interpreted by PowerShell as escape sequences, you must enclose the path +in single quote so that they won't be interpreted. ```yaml Type: System.String[] @@ -328,6 +328,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- The **OlderThan** parameter when used with this parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **OlderThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -349,6 +359,16 @@ This is a dynamic parameter made available by the **FileSystem** provider. Specify a time as a **DateTime** object. +Before PowerShell 7.5, the cmdlet ignores: + +- This parameter when you specify **PathType** as any value other than `Any`. +- This parameter when used with the **NewerThan** parameter. +- This parameter when **Path** points to a directory. + +Starting with PowerShell 7.5, you can use this parameter with any value for the **PathType** +parameter, to test a date range with the **NewerThan** parameter, and to test the age of +directories. + For more information, see [about_FileSystem_Provider](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md). @@ -383,24 +403,24 @@ Accept wildcard characters: True ### -PathType -Specifies the type of the final element in the path. This cmdlet returns `$True` if the element is -of the specified type and `$False` if it is not. The acceptable values for this parameter are: +Specifies the type of the final element in the path. This cmdlet returns `$true` if the element is +of the specified type and `$false` if it's not. The acceptable values for this parameter are: - `Container` - An element that contains other elements, such as a directory or registry key. -- `Leaf` - An element that does not contain other elements, such as a file. +- `Leaf` - An element that doesn't contain other elements, such as a file. - `Any` - Either a container or a leaf. Tells whether the final element in the path is of a particular type. > [!CAUTION] > -> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are -> specified together, the `Test-Path` cmdlet ignores the **PathType** switch and only -> validates the syntactic path without validating the path type. +> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are specified +> together, the `Test-Path` cmdlet ignores the **PathType** switch and only validates the syntactic +> path without validating the path type. > > According to [issue #8607](https://github.com/PowerShell/PowerShell/issues/8607), fixing this > behavior may be a breaking change in a future version, where the **IsValid** and **PathType** -> switches belong to separate parameter sets, and thus, cannot be used together avoiding this +> switches belong to separate parameter sets, and thus, can't be used together avoiding this > confusion. ```yaml @@ -437,14 +457,15 @@ The cmdlet returns a **Boolean** value. ## NOTES -The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return -the names in a concise format that all PowerShell providers can interpret. They are designed for use -in programs and scripts where you want to display all or part of a path name in a particular format. -Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path +The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path and return the +names in a concise format that all PowerShell providers can interpret. They're designed for use in +programs and scripts where you want to display all or part of a path in a particular format. Use +them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. The `Test-Path` 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). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md index 47adcc6ce66c..459a6798e794 100644 --- a/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/7.5/Microsoft.PowerShell.Management/Test-Path.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: 02/16/2023 +ms.date: 01/19/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Test-Path @@ -46,11 +46,11 @@ Test-Path -LiteralPath [-Filter ] [-Include ] [-Exc ## DESCRIPTION -The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$True` if all -elements exist and `$False` if any are missing. It can also tell whether the path syntax is valid +The `Test-Path` cmdlet determines whether all elements of the path exist. It returns `$true` if all +elements exist and `$false` if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element. If the **Path** is a -whitespace or empty string, then `$False` is returned. If the **Path** is `$null`, array of `$null` -or empty array, a non-terminating error is returned. +whitespace or empty string, then the cmdlet returns `$false`. If the **Path** is `$null`, an array +of `$null` or an empty array, the cmdlet returns a non-terminating error. ## EXAMPLES @@ -64,9 +64,9 @@ Test-Path -Path "C:\Documents and Settings\DavidC" True ``` -This command checks whether all elements in the path exist, that is, the `C:` directory, the +This command checks whether all elements in the path exist, including the `C:` directory, the `Documents and Settings` directory, and the `DavidC` directory. If any are missing, the cmdlet -returns `$False`. Otherwise, it returns `$True`. +returns `$false`. Otherwise, it returns `$true`. ### Example 2: Test the path of a profile @@ -89,11 +89,12 @@ True These commands test the path of the PowerShell profile. The first command determines whether all elements in the path exist. The second command determines -whether the syntax of the path is correct. In this case, the path is `$False`, but the syntax is -correct `$True`. These commands use `$profile`, the automatic variable that points to the location -for the profile, even if the profile does not exist. +whether the syntax of the path is correct. In this case, the path is `$false`, but the syntax is +correct `$true`. These commands use `$profile`, the automatic variable that points to the location +for the profile, even if the profile doesn't exist. -For more information about automatic variables, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +For more information about automatic variables, see +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ### Example 3: Check whether there are any files besides a specified type @@ -113,10 +114,9 @@ path is enclosed in quotation marks. The asterisk at the end of the path indicat the Commercial Building directory. With long paths, such as this one, type the first few letters of the path, and then use the TAB key to complete the path. -The command specifies the **Exclude** parameter to specify files that will be omitted from the -evaluation. +The command specifies the **Exclude** parameter to specify files to omit from the evaluation. -In this case, because the directory contains only .dwg files, the result is `$False`. +In this case, because the directory contains only .dwg files, the result is `$false`. ### Example 4: Check for a file @@ -129,19 +129,19 @@ True ``` This command checks whether the path stored in the `$profile` variable leads to a file. In this -case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$True`. +case, because the PowerShell profile is a `.ps1` file, the cmdlet returns `$true`. ### Example 5: Check paths in the Registry These commands use `Test-Path` with the PowerShell registry provider. The first command tests whether the registry path of the **Microsoft.PowerShell** registry key is -correct on the system. If PowerShell is installed correctly, the cmdlet returns `$True`. +correct on the system. If PowerShell is installed correctly, the cmdlet returns `$true`. > [!IMPORTANT] -> `Test-Path` does not work correctly with all PowerShell providers. For example, you can use +> `Test-Path` doesn't work correctly with all PowerShell providers. For example, you can use > `Test-Path` to test the path of a registry key, but if you use it to test the path of a registry -> entry, it always returns `$False`, even if the registry entry is present. +> entry, it always returns `$false`, even if the registry entry is present. ```powershell Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" @@ -179,7 +179,7 @@ True ### Example 7: Test a path with null as the value The error returned for `null`, array of `null` or empty array is a non-terminating error. It can be -suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases which +suppress by using `-ErrorAction SilentlyContinue`. The following example shows all cases that return the `NullPathNotPermitted` error. ```powershell @@ -199,7 +199,7 @@ At line:1 char:11 ### Example 8: Test a path with whitespace as the value -When a whitespace string is provided for the the **Path** parameter, it returns **False**. This is a +When a whitespace string is provided for the **Path** parameter, it returns `$false`. This is a change from Windows PowerShell 5.1. When an empty string is provided, `Test-Path` returns an error. The following example shows whitespace and empty string. @@ -237,7 +237,7 @@ Accept wildcard characters: False ### -Exclude Specifies items that this cmdlet omits. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -255,8 +255,8 @@ Accept wildcard characters: True Specifies a filter in the format or language of the provider. The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends -on the provider. Filters are more efficient than other parameters, because the provider applies them -when it retrieves the objects instead of having PowerShell filter the objects after they are +on the provider. Filters are more efficient than other parameters, because the provider applies +them when it retrieves the objects instead of having PowerShell filter the objects after they're retrieved. ```yaml @@ -274,7 +274,7 @@ Accept wildcard characters: True ### -Include Specifies paths that this cmdlet tests. The value of this parameter qualifies the **Path** -parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. +parameter. Enter a path element or pattern, such as `*.txt`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -291,7 +291,7 @@ Accept wildcard characters: True ### -IsValid Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the -path exist. This cmdlet returns `$True` if the path syntax is valid and `$False` if it is not. +path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. ```yaml Type: System.Management.Automation.SwitchParameter @@ -308,9 +308,9 @@ Accept wildcard characters: False ### -LiteralPath Specifies a path to be tested. Unlike **Path**, the value of the **LiteralPath** parameter is used -exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes -characters that could be interpreted by PowerShell as escape sequences, you must enclose the path in -single quote so that they won't be interpreted. +exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes +characters that could be interpreted by PowerShell as escape sequences, you must enclose the path +in single quote so that they won't be interpreted. ```yaml Type: System.String[] @@ -405,24 +405,24 @@ Accept wildcard characters: True ### -PathType -Specifies the type of the final element in the path. This cmdlet returns `$True` if the element is -of the specified type and `$False` if it is not. The acceptable values for this parameter are: +Specifies the type of the final element in the path. This cmdlet returns `$true` if the element is +of the specified type and `$false` if it's not. The acceptable values for this parameter are: - `Container` - An element that contains other elements, such as a directory or registry key. -- `Leaf` - An element that does not contain other elements, such as a file. +- `Leaf` - An element that doesn't contain other elements, such as a file. - `Any` - Either a container or a leaf. Tells whether the final element in the path is of a particular type. > [!CAUTION] > -> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are -> specified together, the `Test-Path` cmdlet ignores the **PathType** switch and only -> validates the syntactic path without validating the path type. +> Up to PowerShell version 6.1.2, when the **IsValid** and **PathType** switches are specified +> together, the `Test-Path` cmdlet ignores the **PathType** switch and only validates the syntactic +> path without validating the path type. > > According to [issue #8607](https://github.com/PowerShell/PowerShell/issues/8607), fixing this > behavior may be a breaking change in a future version, where the **IsValid** and **PathType** -> switches belong to separate parameter sets, and thus, cannot be used together avoiding this +> switches belong to separate parameter sets, and thus, can't be used together avoiding this > confusion. ```yaml @@ -459,14 +459,15 @@ The cmdlet returns a **Boolean** value. ## NOTES -The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return -the names in a concise format that all PowerShell providers can interpret. They are designed for use -in programs and scripts where you want to display all or part of a path name in a particular format. -Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path +The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path and return the +names in a concise format that all PowerShell providers can interpret. They're designed for use in +programs and scripts where you want to display all or part of a path in a particular format. Use +them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. The `Test-Path` 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). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS