diff --git a/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md b/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md index 8b4cc3a5f217..554bba446d1c 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Join-Path.md @@ -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] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## 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 @@ -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. @@ -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[] @@ -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 @@ -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 @@ -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) @@ -185,4 +250,8 @@ For more information, see about_Providers. [Test-Path](Test-Path.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file +[Get-PSProvider](Get-PSProvider.md) + +[Get-ChildItem](Get-ChildItem.md) + +[Get-PSDrive](Get-PSDrive.md) \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md b/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md index 284b23fa8a3c..208211b3d688 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Join-Path.md @@ -7,76 +7,120 @@ online version: http://go.microsoft.com/fwlink/p/?linkid=290508 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] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## 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. +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" +``` -### Example 2 +```output +path\childpath ``` -PS C:\> join-path c:\win* System* -resolve + +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 ``` -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. +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 +### Example 4: Use Join-Path with the Windows PowerShell registry provider + +```powershell +PS HKLM:\> Join-Path -Path System -ChildPath *ControlSet* -Resolve ``` -PS C:\> PS HKLM:\> join-path System *ControlSet* -resolve + +```output +HKLM:\System\ControlSet001 +HKLM:\System\CurrentControlSet ``` -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. +This command displays the registry keys in the `HKLM\System` registry subkey that include `ControlSet`. -### Example 4 +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 ``` -PS C:\> join-path -path C:, D:, E:, F: -childpath New + +```output +C:\New +D:\New +E:\New +F:\New ``` -This command uses Join-Path to combine multiple path roots with a child path. +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 -### Example 5 +```powershell +Get-PSDrive -PSProvider filesystem | ForEach-Object {$_.root} | Join-Path -ChildPath "Subdir" ``` -PS C:\> get-psdrive -psprovider filesystem | foreach {$_.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 @@ -87,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. @@ -107,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[] @@ -128,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 @@ -141,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 @@ -158,34 +209,36 @@ 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 @@ -197,4 +250,8 @@ For more information, see about_Providers. [Test-Path](Test-Path.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file +[Get-PSProvider](Get-PSProvider.md) + +[Get-ChildItem](Get-ChildItem.md) + +[Get-PSDrive](Get-PSDrive.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md b/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md index 58696a9d993e..2b3d64060e25 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Join-Path.md @@ -7,76 +7,120 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821599 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. ## SYNTAX -```powershell +``` Join-Path [-Path] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## 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: 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. +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 -### Example 2: Display files and folders by joining a path with a child path +```powershell +PS C:\> Join-Path -Path "path\" -ChildPath "\childpath" +``` + +```output +path\childpath ``` -PS C:\> Join-Path "C:\win*" "System*" -Resolve + +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 ``` 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. +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 -### Example 3: Use Join-Path with the Windows PowerShell registry provider +```powershell +PS HKLM:\> Join-Path -Path System -ChildPath *ControlSet* -Resolve ``` -PS C:\> -PS HKLM:\> Join-Path System *ControlSet* -Resolve + +```output +HKLM:\System\ControlSet001 +HKLM:\System\CurrentControlSet ``` -This command displays the registry keys in the HKLM\System registry subkey that include ControlSet. -The command shows how to use **Join-Path** with the Windows PowerShell registry provider. +This command displays the registry keys in the `HKLM\System` registry subkey that include `ControlSet`. -### Example 4: Combine multiple path roots with a child path +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 ``` -PS C:\> Join-Path -Path C:, D:, E:, F: -ChildPath New + +```output +C:\New +D:\New +E:\New +F:\New ``` -This command uses **Join-Path** to combine multiple path roots with a child path. +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 5: Combine the roots of a file system drive with a child path +### 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" ``` -PS C:\> Get-PSDrive -PSProvider filesystem | ForEach {$_.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-Object 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 the *Path* parameter. + +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 @@ -91,11 +135,12 @@ 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. +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. @@ -113,11 +158,12 @@ 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[] @@ -132,7 +178,11 @@ Accept wildcard characters: False ``` ### -Resolve -Indicates that this cmdlet 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 @@ -147,6 +197,7 @@ Accept wildcard characters: False ``` ### -UseTransaction + Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_Transactions. @@ -164,28 +215,30 @@ 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 this cmdlet. ## OUTPUTS ### System.String + 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. - 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. +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 diff --git a/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md b/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md index d05d34f2bf3c..6c319ba4a8bf 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Join-Path.md @@ -7,76 +7,120 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821599 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. ## SYNTAX -```powershell +``` Join-Path [-Path] [-ChildPath] [-Resolve] [-Credential ] [-UseTransaction] [] ``` ## 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: 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. +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 -### Example 2: Display files and folders by joining a path with a child path +```powershell +PS C:\> Join-Path -Path "path\" -ChildPath "\childpath" +``` + +```output +path\childpath ``` -PS C:\> Join-Path "C:\win*" "System*" -Resolve + +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 ``` 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. +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 -### Example 3: Use Join-Path with the Windows PowerShell registry provider +```powershell +PS HKLM:\> Join-Path -Path System -ChildPath *ControlSet* -Resolve ``` -PS C:\> -PS HKLM:\> Join-Path System *ControlSet* -Resolve + +```output +HKLM:\System\ControlSet001 +HKLM:\System\CurrentControlSet ``` -This command displays the registry keys in the HKLM\System registry subkey that include ControlSet. -The command shows how to use **Join-Path** with the Windows PowerShell registry provider. +This command displays the registry keys in the `HKLM\System` registry subkey that include `ControlSet`. -### Example 4: Combine multiple path roots with a child path +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 ``` -PS C:\> Join-Path -Path C:, D:, E:, F: -ChildPath New + +```output +C:\New +D:\New +E:\New +F:\New ``` -This command uses **Join-Path** to combine multiple path roots with a child path. +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 5: Combine the roots of a file system drive with a child path +### 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" ``` -PS C:\> Get-PSDrive -PSProvider filesystem | ForEach {$_.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-Object 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 the *Path* parameter. + +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 @@ -91,11 +135,12 @@ 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. +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. @@ -113,11 +158,12 @@ 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[] @@ -132,7 +178,11 @@ Accept wildcard characters: False ``` ### -Resolve -Indicates that this cmdlet 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 @@ -147,9 +197,10 @@ Accept wildcard characters: False ``` ### -UseTransaction + Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see about_Transactions. +For more information, see [about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: SwitchParameter @@ -164,28 +215,30 @@ 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 this cmdlet. ## OUTPUTS ### System.String + 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. - 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. +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 diff --git a/reference/6/Microsoft.PowerShell.Management/Join-Path.md b/reference/6/Microsoft.PowerShell.Management/Join-Path.md index 5046e4444b18..5603dd68e91f 100644 --- a/reference/6/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/6/Microsoft.PowerShell.Management/Join-Path.md @@ -7,74 +7,134 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821599 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. ## SYNTAX -```powershell +``` Join-Path [-Path] [-ChildPath] - [[-AdditionalChildPath] ] - [-Resolve] [-Credential ] [-UseTransaction] [] + [-Resolve] [-Credential ] [] ``` ## 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: Combine a path with a child path + ```powershell -Join-Path -Path "C:\win*" -ChildPath "System*" +PS C:\> Join-Path -Path "path" -ChildPath "childpath" +``` + +```output +path\childpath +``` + +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" +``` + +```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. +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 -### Example 2: Display files and folders by joining a path with a child path ```powershell Join-Path "C:\win*" "System*" -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. +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 -### Example 3: Use Join-Path with the Windows PowerShell registry provider ```powershell -HKLM:\> Join-Path System *ControlSet* -Resolve +PS HKLM:\> Join-Path -Path System -ChildPath *ControlSet* -Resolve +``` + +```output +HKLM:\System\ControlSet001 +HKLM:\System\CurrentControlSet ``` -This command displays the registry keys in the HKLM\System registry subkey that include ControlSet. -The command shows how to use **Join-Path** with the Windows PowerShell registry provider. +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 -### Example 4: 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. +```output +C:\New +D:\New +E:\New +F:\New +``` + +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 -### Example 5: Combine the roots of a file system drive with a child path ```powershell -Get-PSDrive -PSProvider filesystem | ForEach {$_.root} | Join-Path -ChildPath "Subdir" +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-Object 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. +### Example 7: Combine an indefinite number of paths + +```powershell +Join-Path a b c d e f g +``` + +```output +a\b\c\d\e\f\g +``` + +The `AdditionalChildPath` parameter allows the joining of an unlimited number of paths. + +In this example, no parameter names are used, thus "a" binds to `Path`, "b" to `ChildPath` and "c-g" to `AdditionalChildPath` + ## PARAMETERS ### -AdditionalChildPath -Specifies additional elements to append to the value of the *Path* parameter. + +Specifies additional elements to append to the value of the *Path* parameter. The `ChildPath` parameter is still mandatory and must be specified as well. + +This parameter is specified with the `ValueFromRemainingArguments` property which enables joining an indefinite number of paths. ```yaml Type: String[] @@ -89,9 +149,10 @@ Accept wildcard characters: False ``` ### -ChildPath -Specifies the elements to append to the value of the *Path* parameter. + +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 @@ -106,11 +167,12 @@ 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. +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. @@ -128,11 +190,12 @@ 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[] @@ -147,62 +210,49 @@ Accept wildcard characters: False ``` ### -Resolve -Indicates that this cmdlet displays the items that are referenced by the joined path. -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: +Indicates that this cmdlet should attempt to resolve the joined path from the current provider. -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see +- 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 Parameter Sets: (All) -Aliases: usetx +Aliases: Required: False Position: Named -Default value: False +Default value: None 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 this cmdlet. ## OUTPUTS ### System.String + 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. - 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. +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