Split-Path

 

SYNOPSIS

Returns the specified part of a path.

 

SYNTAX

Split-Path [-path] <string[]> [-parent] [-resolve] [-credential <PSCredential>] [-literalPath <string[]>] [<CommonParameters>]

 

Split-Path [-path] <string[]> [[-qualifier]] [-resolve] [-credential <PSCredential>] [-literalPath <string[]>] [<CommonParameters>]

 

Split-Path [-path] <string[]> [-noQualifier] [-resolve] [-credential <PSCredential>] [-literalPath <string[]>] [<CommonParameters>]

 

Split-Path [-path] <string[]> [-leaf] [-resolve] [-credential <PSCredential>] [-literalPath <string[]>] [<CommonParameters>]

 

Split-Path [-path] <string[]> [-isAbsolute] [-resolve] [-credential <PSCredential>] [-literalPath <string[]>] [<CommonParameters>]

 

DETAILED DESCRIPTION

The Split-Path cmdlet returns only the specified path of a path, such as the parent directory, a child directory, or a file name. You can use this cmdlet to display or submit only a selected part of a path in a script or application.

 

PARAMETERS

 

-path <string[]>

Specifies the paths to be split. Wildcards are permitted. If the path includes spaces, enclose it in quotation marks.

 

Required?

true

Position?

1

Default value

N/A - The path must be specified

Accept pipeline input?  

true (ByValue, ByPropertyName)

Accept wildcard characters? 

true

 

-qualifier <SwitchParameter>

Returns only the qualifier of the specified path. For the FileSystem or registry providers, the qualifier is the drive of the provider path, such as C: or HKCU:.

 

Required?

false

Position?

2

Default value

False

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

-parent <SwitchParameter>

Returns only the parent containers of the item or container specified by the path. For example, in the path "C:\Test\Logs\Pass1.log", it returns "C:\Test\Logs". Parent is the default split location parameter.

 

Required?

false

Position?

named

Default value

True

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

-leaf <SwitchParameter>

Returns only the last item or container in the path. For example, in the path "C:\Test\Logs\Pass1.log", it returns only "Pass1.log".

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

-noQualifier <SwitchParameter>

Returns the path without the qualifier. For the FileSystem or registry providers, the qualifier is the drive of the provider path, such as C: or HKCU:. For example, in the path  "C:\Test\Logs\Pass1.log", it returns only "\Test\Logs\Pass1.log".

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

-isAbsolute <SwitchParameter>

Returns TRUE if the path is absolute and FALSE if it is relative. An absolute path has a length greater than zero and does not use "." to indicate the current path.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-resolve <SwitchParameter>

Displays the items that are referenced by the path that remains after the split.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-credential <PSCredential>

Uses a credential to validate access to the resource. <Credential> represents a user-name, such as "User01" or "Domain01\User01", or a PSCredential object, such as the one retrieved by using the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter appears, but it is not supported in any Windows PowerShell core cmdlets or providers.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

-literalPath <string[]>

Specifies the paths to be split. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

RETURN TYPE

Strings

 

NOTES

 

For more information, type "Get-Help Split-Path -detailed". For technical information, type "Get-Help Split-Path -full".

 

The split location parameters -- Qualifier, Parent, Leaf, and NoQualifier -- are exclusive. You can use only one in each command.

 

The path cmdlets (*-path) manipulate path names and return the names in a concise format that all Windows 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 like you would use Dirname, Normpath, Realpath, Join, or other path manipulators.

 

You can use the path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers.

 

When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

EXAMPLE 1

 

split-path "HKCU:\Software\Microsoft" -qualifier

 

This command returns only the qualifier (the drive) of the path.

 

HKCU:

 

EXAMPLE 2

 

split-path "C:\Test\Logs\*.log" -leaf -resolve

 

This command displays the files that are reference by the split path. Because this path is split to the last item (the "leaf) only the file names of the paths are displayed.

 

Pass1.log

Pass2.log

...

 

EXAMPLE 3

 

split-path "C:\WINDOWS\system32\WindowsPowerShell\V1.0\about_*.txt"

 

This command returns only the parent containers of the path. Because it doesn't include any parameters to specify the split, Split-Path uses the split location default, which is Parent.

 

C:\WINDOWS\system32\WindowsPowerShell

 

EXAMPLE 4

 

split-path ".\My Pictures\*.jpg"

 

This command determines if the path is relative or absolute. In this case, because the path is relative to the current directory, which is represented by a dot (.), it returns FALSE ($false).

 

False

 

EXAMPLE 5

 

cd (split-path $profile)

 

This command changes to the directory that contains the Windows PowerShell profile. "CD" is an alias for the Set-Locationcmdlet, which changes the current directory. The command in parentheses uses the Split-Path cmdlet to return only the parent of the path stored in the built-in $Profile variable. (The Parent parameter is the default split location parameter, so you can omit it from the command.) The parentheses direct Windows PowerShell to execute the command first. This is a handy way to navigate to a directory with a long path name.

 

PS C:\Documents and Settings\NicoleH\My Documents\PSConfiguration>

 

RELATED LINKS

Test-Path

Convert-Path

Resolve-Path

Join-Path

about_namespace