Skip to content

Closes #1490, #1612 - Updating Join-Path documentation #2623

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

Merged
merged 4 commits into from
Jun 27, 2018
Merged

Closes #1490, #1612 - Updating Join-Path documentation #2623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d5b9de9
Closes #1490, 1612 - Updating Join-Path documentation
bobbytreed Jun 27, 2018
f830768
removed broken link
bobbytreed Jun 27, 2018
0de208e
removed reference to -UseTransaction from v6
bobbytreed Jun 27, 2018
283da1a
removed reference to -UseTransaction from v6
bobbytreed Jun 27, 2018
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
163 changes: 116 additions & 47 deletions reference/3.0/Microsoft.PowerShell.Management/Join-Path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,68 +7,120 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113347
external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
title: Join-Path
---

# Join-Path

## SYNOPSIS

Combines a path and a child path into a single path.
The provider supplies the path delimiters.

## SYNTAX

```powershell
```
Join-Path [-Path] <String[]> [-ChildPath] <String>
[-Resolve] [-Credential <PSCredential>] [-UseTransaction] [<CommonParameters>]
```

## DESCRIPTION
The Join-Path cmdlet combines a path and child-path into a single path.

The `Join-Path` cmdlet combines a path and child-path into a single path.
The provider supplies the path delimiters.

## EXAMPLES

### Example 1
### Example 1: Combine a path with a child path

```powershell
PS C:\> Join-Path -Path "path" -ChildPath "childpath"
```
PS C:\> join-path -path c:\win* -childpath System*

```output
path\childpath
```

This command uses Join-Path to combine the "c:\Win*" path with the "System*" child path.
The Windows PowerShell file system provider, FileSystem joins the path and adds the "\" delimiter.
### Example 2
This command uses `Join-Path` to combine a path with a childpath.

Since the command is executed from the `FileSystem` provider, it provides the `\` delimiter to join the paths.

### Example 2: Combine paths that already contain directory separators

```powershell
PS C:\> Join-Path -Path "path\" -ChildPath "\childpath"
```
PS C:\> join-path c:\win* System* -resolve

```output
path\childpath
```

This command displays the files and folders that are referenced by joining the "c:\Win*" path and the "System*" child path.
It displays the same files and folders as Get-ChildItem, but it displays the fully qualified path to each item.
In this command, the Path and ChildPath optional parameter names are omitted.
### Example 3
Existing directory separators `\` and handled so there is only one separator between `Path` and `ChildPath`

### Example 3: Display files and folders by joining a path with a child path

```powershell
Join-Path "C:\win*" "System*" -Resolve
```
PS C:\> PS HKLM:\> join-path System *ControlSet* -resolve

This command displays the files and folders that are referenced by joining the C:\Win* path and the System* child path.
It displays the same files and folders as `Get-ChildItem`, but it displays the fully qualified path to each item.
In this command, the `Path` and `ChildPath` optional parameter names are omitted.

### Example 4: Use Join-Path with the Windows PowerShell registry provider

```powershell
PS HKLM:\> Join-Path -Path System -ChildPath *ControlSet* -Resolve
```

This command displays the registry keys in the HKLM\System registry subkey that include "ControlSet".
This example shows how to use Join-Path with the Windows PowerShell registry provider.
### Example 4
```output
HKLM:\System\ControlSet001
HKLM:\System\CurrentControlSet
```
PS C:\> join-path -path C:, D:, E:, F: -childpath New

This command displays the registry keys in the `HKLM\System` registry subkey that include `ControlSet`.

The `Resolve` parameter, attempts to resolve the joined path, including wildcards from the current provider path `HKLM:\`

### Example 5: Combine multiple path roots with a child path

```powershell
Join-Path -Path C:, D:, E:, F: -ChildPath New
```

This command uses Join-Path to combine multiple path roots with a child path.
### Example 5
```output
C:\New
D:\New
E:\New
F:\New
```
PS C:\> get-psdrive -psprovider filesystem | foreach {$_.root} | join-path -childpath Subdir

This command uses `Join-Path` to combine multiple path roots with a child path.

> [!NOTE]
> The Drives specified by `Path` must exist or the join of that entry will fail.

### Example 6: Combine the roots of a file system drive with a child path

```powershell
Get-PSDrive -PSProvider filesystem | ForEach-Object {$_.root} | Join-Path -ChildPath "Subdir"
```

```output
C:\Subdir
D:\Subdir
```

This command combines the roots of each Windows PowerShell file system drive in the console with the Subdir child path.

The command uses the Get-PSDrive cmdlet to get the Windows PowerShell drives supported by the FileSystem provider.
The ForEach statement selects only the Root property of the PSDriveInfo objects and combines it with the specified child path.
The command uses the `Get-PSDrive` cmdlet to get the Windows PowerShell drives supported by the FileSystem provider.
The `ForEach-Object` statement selects only the Root property of the `PSDriveInfo` objects and combines it with the specified child path.

The output shows that the Windows PowerShell drives on the computer included a drive mapped to the C:\Program Files directory.

## PARAMETERS

### -ChildPath
Specifies the elements to append to the value of Path.

Specifies the elements to append to the value of the `Path` parameter.
Wildcards are permitted.
The ChildPath parameter is required, although the parameter name ("ChildPath") is optional.
The `ChildPath` parameter is required, although the parameter name ("ChildPath") is optional.

```yaml
Type: String
Expand All @@ -79,15 +131,16 @@ Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True
Accept wildcard characters: False
```

### -Credential

Specifies a user account that has permission to perform this action.
The default is the current user.

Type a user name, such as "User01" or "Domain01\User01".
Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet.
Type a user name, such as User01 or Domain01\User01.
Or, enter a `PSCredential` object, such as one generated by the `Get-Credential` cmdlet.
If you type a user name, you will be prompted for a password.

This parameter is not supported by any providers installed with Windows PowerShell.
Expand All @@ -99,17 +152,18 @@ Aliases:

Required: False
Position: Named
Default value: Current user
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
```

### -Path

Specifies the main path (or paths) to which the child-path is appended.
Wildcards are permitted.

The value of Path determines which provider joins the paths and adds the path delimiters.
The Path parameter is required, although the parameter name ("Path") is optional.
The value of `Path` determines which provider joins the paths and adds the path delimiters.
The `Path` parameter is required, although the parameter name ("Path") is optional.

```yaml
Type: String[]
Expand All @@ -120,11 +174,15 @@ Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: True
Accept wildcard characters: False
```

### -Resolve
Displays the items that are referenced by the joined path.

Indicates that this cmdlet should attempt to resolve the joined path from the current provider.

- If wildcards are used, the cmdlet returns all paths that match the joined path.
- If **no** wildcards are used, the cmdlet will error if the path does not exist.

```yaml
Type: SwitchParameter
Expand All @@ -133,14 +191,15 @@ Aliases:

Required: False
Position: Named
Default value: False
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```

### -UseTransaction

Includes the command in the active transaction.
This parameter can only be used when a transaction is in progress.
This parameter is valid only when a transaction is in progress.
For more information, see about_Transactions.

```yaml
Expand All @@ -150,31 +209,37 @@ Aliases: usetx

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```

### CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md).

## INPUTS

### System.String
You can pipe a string that contains a path to Join-Path.

You can pipe a string that contains a path to this cmdlet.

## OUTPUTS

### System.String
Join-Path returns a string that contains the resulting path.

This cmdlet returns a string that contains the resulting path.

## NOTES
* The cmdlets that contain the Path noun (the Path cmdlets) 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.
The cmdlets that contain the Path noun (the Path cmdlets) 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.

The Join-Path 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.
You can use the path cmdlets with several providers, including the `FileSystem`, `Registry`, and `Certificate` providers.

This 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).

*
## RELATED LINKS

[Convert-Path](Convert-Path.md)
Expand All @@ -185,4 +250,8 @@ For more information, see about_Providers.

[Test-Path](Test-Path.md)

[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md)
[Get-PSProvider](Get-PSProvider.md)

[Get-ChildItem](Get-ChildItem.md)

[Get-PSDrive](Get-PSDrive.md)
Loading