Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

(GH-10742) Update Test-Path for 7.5 #10812

Merged
merged 3 commits into from
Jan 22, 2024
Merged

(GH-10742) Update Test-Path for 7.5 #10812

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87c2a93
(GH-10742) Update `Test-Path` for 7.5
michaeltlombardi Jan 19, 2024
3aceca2
(MAINT) Fix lint warnings + sync updates
michaeltlombardi Jan 19, 2024
d211a7a
Merge branch 'main' into ab-201369/main/test-path-7.5
sdwheeler Jan 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 65 additions & 44 deletions reference/5.1/Microsoft.PowerShell.Management/Test-Path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Management
ms.date: 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
Expand Down Expand Up @@ -48,11 +48,11 @@ Test-Path -LiteralPath <string[]> [-Filter <string>] [-Include <string[]>] [-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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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"
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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 ' '
Expand Down Expand Up @@ -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[]
Expand All @@ -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
Expand All @@ -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[]
Expand All @@ -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
Expand All @@ -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[]
Expand All @@ -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).

Expand All @@ -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).

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
Loading