diff --git a/reference/3.0/Microsoft.PowerShell.Management/Copy-Item.md b/reference/3.0/Microsoft.PowerShell.Management/Copy-Item.md index cc909ac97974..0562bd721964 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Copy-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 10/18/2018 +ms.date: 5/30/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -36,9 +36,9 @@ Copy-Item -LiteralPath [[-Destination] ] [-Container] [-Force The `Copy-Item` cmdlet copies an item from one location to another location in the same namespace. For instance, it can copy a file to a folder, but it cannot copy a file to a certificate drive. -This cmdlet does not cut or delete the items being copied. -The particular items that the cmdlet can copy depend on the PowerShell provider that exposes the item. -For instance, it can copy files and directories in a file system drive and registry keys and entries in the registry drive. +This cmdlet does not cut or delete the items being copied. The particular items that the cmdlet can +copy depend on the PowerShell provider that exposes the item. For instance, it can copy files and +directories in a file system drive and registry keys and entries in the registry drive. This cmdlet can copy and rename items in the same command. To rename an item, enter the new name in the value of the **Destination** parameter. @@ -48,7 +48,7 @@ To rename an item and not copy it, use the `Rename-Item` cmdlet. ### Example 1: Copy a file to the specified directory -This command copies the "mar1604.log.txt" file to the "C:\Presentation" directory. +This command copies the `mar1604.log.txt` file to the `C:\Presentation` directory. The command does not delete the original file. ```powershell @@ -58,17 +58,19 @@ Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation" ### Example 2: Copy the contents of a directory to another directory This command copies the entire contents of the "Logfiles" directory into the "Drawings" directory. -If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with their file trees intact. -The **Container** parameter is set to "true" by default. -This preserves the directory structure. ```powershell Copy-Item "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse ``` +If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with +their file trees intact. The **Container** parameter is set to "true" by default. + +This preserves the directory structure. + ### Example 3: Copy the contents of a directory to another directory and create the destination directory if it does not exist -This command copies the contents of the "C:\Logfiles" directory to the "C:\Drawings\Logs" directory. +This command copies the contents of the `C:\Logfiles` directory to the `C:\Drawings\Logs` directory. It creates the "\Logs" subdirectory if it does not already exist. ```powershell @@ -77,8 +79,10 @@ Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse ### Example 4: Copy a file to the specified directory and rename the file -This command uses the `Copy-Item` cmdlet to copy the "Get-Widget.ps1" script from the "\\\\Server01\Share" directory to the "\\\\Server12\ScriptArchive" directory. -As part of the copy operation, the command also changes the item name from "Get-Widget.ps1" to "Get-Widget.ps1.txt", so it can be attached to email messages. +This command uses the `Copy-Item` cmdlet to copy the `Get-Widget.ps1` script from the +`\\Server01\Share` directory to the `\\Server12\ScriptArchive` directory. +As part of the copy operation, the command also changes the item name from `Get-Widget.ps1` to +`Get-Widget.ps1.txt`, so it can be attached to email messages. ```powershell Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt" @@ -86,16 +90,28 @@ Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchi ## PARAMETERS -### -Credential +### -Container -Specifies a user account that has permission to perform this action. -The default is the current user. +Indicates that this cmdlet preserves container objects during the copy operation. -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 are prompted for a password. +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: True +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential -> [!WARNING] -> This parameter is not supported by any providers installed with Windows PowerShell. +> [!NOTE] +> This parameter is not supported by any providers installed with PowerShell. +> To impersonate another user, or elevate your credentials when running this cmdlet, +> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). ```yaml Type: PSCredential @@ -112,7 +128,9 @@ Accept wildcard characters: False ### -Destination Specifies the path to the new location. -To rename a copied item, include the new name in the value. +The default is the current directory. + +To rename the item being copied, specify a new name in the value of the **Destination** parameter. ```yaml Type: String @@ -128,10 +146,11 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -147,11 +166,11 @@ Accept wildcard characters: True ### -Filter -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 the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. +Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) +provider is the only installed PowerShell provider that supports the use of filters. You can find +the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). +Filters are more efficient than other parameters, because the provider applies them when the cmdlet +gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -167,7 +186,8 @@ Accept wildcard characters: True ### -Force -Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a read-only file or alias. +Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a +read-only file or alias. ```yaml Type: SwitchParameter @@ -176,17 +196,18 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -197,16 +218,17 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath -Specifies a path to the item. -Unlike the **Path** parameter, 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 PowerShell not to interpret any characters as escape sequences. +Specifies a path to one or more locations. 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 PowerShell not to interpret any characters +as escape sequences. + +For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md). ```yaml Type: String[] @@ -232,7 +254,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -240,6 +262,7 @@ Accept wildcard characters: False ### -Path Specifies, as a string array, the path to the items to copy. +Wildcard characters are permitted. ```yaml Type: String[] @@ -250,7 +273,7 @@ Required: True Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Recurse @@ -264,7 +287,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` diff --git a/reference/4.0/Microsoft.PowerShell.Management/Copy-Item.md b/reference/4.0/Microsoft.PowerShell.Management/Copy-Item.md index a503fe8d0370..fb97e7998bdf 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Copy-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 10/18/2018 +ms.date: 5/30/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -36,9 +36,9 @@ Copy-Item -LiteralPath [[-Destination] ] [-Container] [-Force The `Copy-Item` cmdlet copies an item from one location to another location in the same namespace. For instance, it can copy a file to a folder, but it cannot copy a file to a certificate drive. -This cmdlet does not cut or delete the items being copied. -The particular items that the cmdlet can copy depend on the PowerShell provider that exposes the item. -For instance, it can copy files and directories in a file system drive and registry keys and entries in the registry drive. +This cmdlet does not cut or delete the items being copied. The particular items that the cmdlet can +copy depend on the PowerShell provider that exposes the item. For instance, it can copy files and +directories in a file system drive and registry keys and entries in the registry drive. This cmdlet can copy and rename items in the same command. To rename an item, enter the new name in the value of the **Destination** parameter. @@ -48,7 +48,7 @@ To rename an item and not copy it, use the `Rename-Item` cmdlet. ### Example 1: Copy a file to the specified directory -This command copies the "mar1604.log.txt" file to the "C:\Presentation" directory. +This command copies the `mar1604.log.txt` file to the `C:\Presentation` directory. The command does not delete the original file. ```powershell @@ -58,17 +58,19 @@ Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation" ### Example 2: Copy the contents of a directory to another directory This command copies the entire contents of the "Logfiles" directory into the "Drawings" directory. -If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with their file trees intact. -The **Container** parameter is set to "true" by default. -This preserves the directory structure. ```powershell Copy-Item "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse ``` +If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with +their file trees intact. The **Container** parameter is set to "true" by default. + +This preserves the directory structure. + ### Example 3: Copy the contents of a directory to another directory and create the destination directory if it does not exist -This command copies the contents of the "C:\Logfiles" directory to the "C:\Drawings\Logs" directory. +This command copies the contents of the `C:\Logfiles` directory to the `C:\Drawings\Logs` directory. It creates the "\Logs" subdirectory if it does not already exist. ```powershell @@ -77,8 +79,10 @@ Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse ### Example 4: Copy a file to the specified directory and rename the file -This command uses the `Copy-Item` cmdlet to copy the "Get-Widget.ps1" script from the "\\\\Server01\Share" directory to the "\\\\Server12\ScriptArchive" directory. -As part of the copy operation, the command also changes the item name from "Get-Widget.ps1" to "Get-Widget.ps1.txt", so it can be attached to email messages. +This command uses the `Copy-Item` cmdlet to copy the `Get-Widget.ps1` script from the +`\\Server01\Share` directory to the `\\Server12\ScriptArchive` directory. +As part of the copy operation, the command also changes the item name from `Get-Widget.ps1` to +`Get-Widget.ps1.txt`, so it can be attached to email messages. ```powershell Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt" @@ -86,14 +90,10 @@ Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchi ### -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. -If you type a user name, you are prompted for a password. - -> [!WARNING] -> This parameter is not supported by any providers installed with Windows PowerShell. +> [!NOTE] +> This parameter is not supported by any providers installed with PowerShell. +> To impersonate another user, or elevate your credentials when running this cmdlet, +> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). ```yaml Type: PSCredential @@ -110,7 +110,9 @@ Accept wildcard characters: False ### -Destination Specifies the path to the new location. -To rename a copied item, include the new name in the value. +The default is the current directory. + +To rename the item being copied, specify a new name in the value of the **Destination** parameter. ```yaml Type: String @@ -126,10 +128,11 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -145,11 +148,11 @@ Accept wildcard characters: True ### -Filter -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 the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. +Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) +provider is the only installed PowerShell provider that supports the use of filters. You can find +the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). +Filters are more efficient than other parameters, because the provider applies them when the cmdlet +gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -165,7 +168,8 @@ Accept wildcard characters: True ### -Force -Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a read-only file or alias. +Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a +read-only file or alias. ```yaml Type: SwitchParameter @@ -174,17 +178,18 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -195,16 +200,17 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath -Specifies a path to the item. -Unlike the **Path** parameter, 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 PowerShell not to interpret any characters as escape sequences. +Specifies a path to one or more locations. 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 PowerShell not to interpret any characters +as escape sequences. + +For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md). ```yaml Type: String[] @@ -230,7 +236,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -238,6 +244,7 @@ Accept wildcard characters: False ### -Path Specifies, as a string array, the path to the items to copy. +Wildcard characters are permitted. ```yaml Type: String[] @@ -248,7 +255,7 @@ Required: True Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Recurse @@ -262,7 +269,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -320,7 +327,10 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +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 @@ -332,8 +342,8 @@ You can pipe a string that contains a path to this cmdlet. ### None or an object representing the copied item. -When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied item. -Otherwise, this cmdlet does not generate any output. +When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied +item. Otherwise, this cmdlet does not generate any output. ## NOTES diff --git a/reference/5.0/Microsoft.PowerShell.Management/Copy-Item.md b/reference/5.0/Microsoft.PowerShell.Management/Copy-Item.md index be8e685bea57..361d12cb6a87 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Copy-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 10/18/2018 +ms.date: 5/30/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -35,9 +35,9 @@ Copy-Item -LiteralPath [[-Destination] ] [-Container] [-Force The `Copy-Item` cmdlet copies an item from one location to another location in the same namespace. For instance, it can copy a file to a folder, but it cannot copy a file to a certificate drive. -This cmdlet does not cut or delete the items being copied. -The particular items that the cmdlet can copy depend on the PowerShell provider that exposes the item. -For instance, it can copy files and directories in a file system drive and registry keys and entries in the registry drive. +This cmdlet does not cut or delete the items being copied. The particular items that the cmdlet can +copy depend on the PowerShell provider that exposes the item. For instance, it can copy files and +directories in a file system drive and registry keys and entries in the registry drive. This cmdlet can copy and rename items in the same command. To rename an item, enter the new name in the value of the **Destination** parameter. @@ -47,7 +47,7 @@ To rename an item and not copy it, use the `Rename-Item` cmdlet. ### Example 1: Copy a file to the specified directory -This command copies the "mar1604.log.txt" file to the "C:\Presentation" directory. +This command copies the `mar1604.log.txt` file to the `C:\Presentation` directory. The command does not delete the original file. ```powershell @@ -57,17 +57,19 @@ Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation" ### Example 2: Copy the contents of a directory to another directory This command copies the entire contents of the "Logfiles" directory into the "Drawings" directory. -If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with their file trees intact. -The **Container** parameter is set to "true" by default. -This preserves the directory structure. ```powershell Copy-Item "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse ``` +If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with +their file trees intact. The **Container** parameter is set to "true" by default. + +This preserves the directory structure. + ### Example 3: Copy the contents of a directory to another directory and create the destination directory if it does not exist -This command copies the contents of the "C:\Logfiles" directory to the "C:\Drawings\Logs" directory. +This command copies the contents of the `C:\Logfiles` directory to the `C:\Drawings\Logs` directory. It creates the "\Logs" subdirectory if it does not already exist. ```powershell @@ -76,8 +78,10 @@ Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse ### Example 4: Copy a file to the specified directory and rename the file -This command uses the `Copy-Item` cmdlet to copy the "Get-Widget.ps1" script from the "\\\\Server01\Share" directory to the "\\\\Server12\ScriptArchive" directory. -As part of the copy operation, the command also changes the item name from "Get-Widget.ps1" to "Get-Widget.ps1.txt", so it can be attached to email messages. +This command uses the `Copy-Item` cmdlet to copy the `Get-Widget.ps1` script from the +`\\Server01\Share` directory to the `\\Server12\ScriptArchive` directory. +As part of the copy operation, the command also changes the item name from `Get-Widget.ps1` to +`Get-Widget.ps1.txt`, so it can be attached to email messages. ```powershell Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt" @@ -85,10 +89,12 @@ Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchi ### Example 5: Copy a file to a remote computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFu" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy "test.log" from the "D:\Folder001" folder to the "C:\Folder001_Copy" folder on the remote computer using the session information stored in the `$Session` variable. -This command does not delete the original file. +The second command uses the `Copy-Item` cmdlet to copy `test.log` from the `D:\Folder001` folder to +the `C:\Folder001_Copy` folder on the remote computer using the session information stored in the +`$Session` variable. This command does not delete the original file. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -97,10 +103,12 @@ Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $ ### Example 6: Copy the entire contents of a folder to a remote computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +`Contoso\PattiFul` and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the "D:\Folder002" folder to the "C:\Folder002_Copy" directory on the remote computer using the session information stored in the `$Session` variable. -The subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the `D:\Folder002` +folder to the `C:\Folder002_Copy` directory on the remote computer using the session information +stored in the `$Session` variable. The subfolders are copied with their file trees intact. ```powershell $Session = New-PSSession -ComputerName "Server02" -Credential "Contoso\PattiFul" @@ -109,11 +117,14 @@ Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session ### Example 7: Recursively copy the entire contents of a folder to a remote computer -The first command creates a session to the remote computer named Server01 with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named Server01 with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the "D:\Folder003" folder to the "C:\Folder003_Copy" directory on the remote computer using the session information stored in the `$Session` variable. -The subfolders are copied with their file trees intact. -Since this command uses the **Recurse** parameter, the operation creates the "Folder003_Copy" folder if it does not already exist. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the `D:\Folder003` +folder to the `C:\Folder003_Copy` directory on the remote computer using the session information +stored in the `$Session` variable. The subfolders are copied with their file trees intact. +Since this command uses the **Recurse** parameter, the operation creates the "Folder003_Copy" folder +if it does not already exist. ```powershell $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\PattiFul" @@ -122,10 +133,14 @@ Copy-Item "D:\Folder003\" -Destination "C:\Folder003_Copy\" -ToSession $Session ### Example 8: Copy a file to a remote computer and then rename the file -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy "scriptingexample.ps1" from the "D:\Folder004" folder to the "C:\Folder004_Copy" folder on the remote computer using the session information stored in the `$Session` variable. -As part of the copy operation, the command also changes the item name from "scriptingexample.ps1" to "scriptingexample_copy.ps1", so it can be attached to email messages. +The second command uses the `Copy-Item` cmdlet to copy `scriptingexample.ps1` from the +`D:\Folder004` folder to the "C:\Folder004_Copy" folder on the remote computer using the session +information stored in the `$Session` variable. +As part of the copy operation, the command also changes the item name from `scriptingexample.ps1` to +`scriptingexample_copy.ps1`, so it can be attached to email messages. This command does not delete the original file. ```powershell @@ -135,10 +150,12 @@ Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\sc ### Example 9: Copy a remote file to the local computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy test.log from the remote "C:\MyRemoteData\" to the local "D:\MyLocalData" folder using the session information stored in the `$Session` variable. -This command does not delete the original file. +The second command uses the `Copy-Item` cmdlet to copy test.log from the remote `C:\MyRemoteData\` +to the local `D:\MyLocalData` folder using the session information stored in the `$Session` +variable. This command does not delete the original file. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -147,10 +164,14 @@ Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession ### Example 10: Copy the entire contents of a remote folder to the local computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote "C:\MyRemoteData\scripts" folder to the local "D:\MyLocalData" folder using the session information stored in the `$Session` variable. -If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote +`C:\MyRemoteData\scripts` folder to the local `D:\MyLocalData` folder using the session information +stored in the `$Session` variable. +If the scripts folder contains files in subfolders, those subfolders are copied with their file +trees intact. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -159,10 +180,15 @@ Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession ### Example 11: Recursively copy the entire contents of a remote folder to the local computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote "C:\MyRemoteData\scripts" folder to the local "D:\MyLocalData\scripts" folder using the session information stored in the `$Session` variable. -Since this command uses the **Recurse** parameter, the operation creates the scripts folder if it does not already exist. If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote +`C:\MyRemoteData\scripts` folder to the local `D:\MyLocalData\scripts` folder using the session +information stored in the `$Session` variable. +Since this command uses the **Recurse** parameter, the operation creates the scripts folder if it +does not already exist. If the scripts folder contains files in subfolders, those subfolders are +copied with their file trees intact. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -198,21 +224,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: True Accept pipeline input: False 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. -If you type a user name, you are prompted for a password. - -> [!WARNING] -> This parameter is not supported by any providers installed with Windows PowerShell. +> [!NOTE] +> This parameter is not supported by any providers installed with PowerShell. +> To impersonate another user, or elevate your credentials when running this cmdlet, +> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). ```yaml Type: PSCredential @@ -229,7 +251,9 @@ Accept wildcard characters: False ### -Destination Specifies the path to the new location. -To rename a copied item, include the new name in the value. +The default is the current directory. + +To rename the item being copied, specify a new name in the value of the **Destination** parameter. ```yaml Type: String @@ -245,10 +269,11 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -264,11 +289,11 @@ Accept wildcard characters: True ### -Filter -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 the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. +Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) +provider is the only installed PowerShell provider that supports the use of filters. You can find +the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). +Filters are more efficient than other parameters, because the provider applies them when the cmdlet +gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -284,7 +309,8 @@ Accept wildcard characters: True ### -Force -Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a read-only file or alias. +Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a +read-only file or alias. ```yaml Type: SwitchParameter @@ -293,7 +319,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -301,7 +327,8 @@ Accept wildcard characters: False ### -FromSession Specifies the **PSSession** object from which a remote file is being copied. -When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the remote machine. +When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the +remote machine. ```yaml Type: PSSession @@ -317,10 +344,11 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -331,16 +359,17 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath -Specifies a path to the item. -Unlike the **Path** parameter, 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 PowerShell not to interpret any characters as escape sequences. +Specifies a path to one or more locations. 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 PowerShell not to interpret any characters +as escape sequences. + +For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md). ```yaml Type: String[] @@ -366,7 +395,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -374,6 +403,7 @@ Accept wildcard characters: False ### -Path Specifies, as a string array, the path to the items to copy. +Wildcard characters are permitted. ```yaml Type: String[] @@ -384,7 +414,7 @@ Required: True Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Recurse @@ -398,7 +428,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -406,7 +436,8 @@ Accept wildcard characters: False ### -ToSession Specifies the **PSSession** object to which a remote file is being copied. -When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the remote machine. +When you use this parameter, the **Path** and **LiteralPath** parameters refer to the local path on the +remote machine. ```yaml Type: PSSession @@ -457,7 +488,10 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +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 @@ -469,8 +503,8 @@ You can pipe a string that contains a path to this cmdlet. ### None or an object representing the copied item. -When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied item. -Otherwise, this cmdlet does not generate any output. +When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied +item. Otherwise, this cmdlet does not generate any output. ## NOTES diff --git a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md index b675117cb8ae..8945f1483a11 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 10/18/2018 +ms.date: 5/30/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -36,9 +36,9 @@ Copy-Item -LiteralPath [[-Destination] ] [-Container] [-Force The `Copy-Item` cmdlet copies an item from one location to another location in the same namespace. For instance, it can copy a file to a folder, but it cannot copy a file to a certificate drive. -This cmdlet does not cut or delete the items being copied. -The particular items that the cmdlet can copy depend on the PowerShell provider that exposes the item. -For instance, it can copy files and directories in a file system drive and registry keys and entries in the registry drive. +This cmdlet does not cut or delete the items being copied. The particular items that the cmdlet can +copy depend on the PowerShell provider that exposes the item. For instance, it can copy files and +directories in a file system drive and registry keys and entries in the registry drive. This cmdlet can copy and rename items in the same command. To rename an item, enter the new name in the value of the **Destination** parameter. @@ -48,7 +48,7 @@ To rename an item and not copy it, use the `Rename-Item` cmdlet. ### Example 1: Copy a file to the specified directory -This command copies the "mar1604.log.txt" file to the "C:\Presentation" directory. +This command copies the `mar1604.log.txt` file to the `C:\Presentation` directory. The command does not delete the original file. ```powershell @@ -58,17 +58,19 @@ Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation" ### Example 2: Copy the contents of a directory to another directory This command copies the entire contents of the "Logfiles" directory into the "Drawings" directory. -If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with their file trees intact. -The **Container** parameter is set to "true" by default. -This preserves the directory structure. ```powershell Copy-Item "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse ``` +If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with +their file trees intact. The **Container** parameter is set to "true" by default. + +This preserves the directory structure. + ### Example 3: Copy the contents of a directory to another directory and create the destination directory if it does not exist -This command copies the contents of the "C:\Logfiles" directory to the "C:\Drawings\Logs" directory. +This command copies the contents of the `C:\Logfiles` directory to the `C:\Drawings\Logs` directory. It creates the "\Logs" subdirectory if it does not already exist. ```powershell @@ -77,8 +79,10 @@ Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse ### Example 4: Copy a file to the specified directory and rename the file -This command uses the `Copy-Item` cmdlet to copy the "Get-Widget.ps1" script from the "\\\\Server01\Share" directory to the "\\\\Server12\ScriptArchive" directory. -As part of the copy operation, the command also changes the item name from "Get-Widget.ps1" to "Get-Widget.ps1.txt", so it can be attached to email messages. +This command uses the `Copy-Item` cmdlet to copy the `Get-Widget.ps1` script from the +`\\Server01\Share` directory to the `\\Server12\ScriptArchive` directory. +As part of the copy operation, the command also changes the item name from `Get-Widget.ps1` to +`Get-Widget.ps1.txt`, so it can be attached to email messages. ```powershell Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt" @@ -86,10 +90,12 @@ Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchi ### Example 5: Copy a file to a remote computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFu" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy "test.log" from the "D:\Folder001" folder to the "C:\Folder001_Copy" folder on the remote computer using the session information stored in the `$Session` variable. -This command does not delete the original file. +The second command uses the `Copy-Item` cmdlet to copy `test.log` from the `D:\Folder001` folder to +the `C:\Folder001_Copy` folder on the remote computer using the session information stored in the +`$Session` variable. This command does not delete the original file. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -98,10 +104,12 @@ Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $ ### Example 6: Copy the entire contents of a folder to a remote computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +`Contoso\PattiFul` and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the "D:\Folder002" folder to the "C:\Folder002_Copy" directory on the remote computer using the session information stored in the `$Session` variable. -The subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the `D:\Folder002` +folder to the `C:\Folder002_Copy` directory on the remote computer using the session information +stored in the `$Session` variable. The subfolders are copied with their file trees intact. ```powershell $Session = New-PSSession -ComputerName "Server02" -Credential "Contoso\PattiFul" @@ -110,11 +118,14 @@ Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session ### Example 7: Recursively copy the entire contents of a folder to a remote computer -The first command creates a session to the remote computer named Server01 with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named Server01 with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the "D:\Folder003" folder to the "C:\Folder003_Copy" directory on the remote computer using the session information stored in the `$Session` variable. -The subfolders are copied with their file trees intact. -Since this command uses the **Recurse** parameter, the operation creates the "Folder003_Copy" folder if it does not already exist. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the `D:\Folder003` +folder to the `C:\Folder003_Copy` directory on the remote computer using the session information +stored in the `$Session` variable. The subfolders are copied with their file trees intact. +Since this command uses the **Recurse** parameter, the operation creates the "Folder003_Copy" folder +if it does not already exist. ```powershell $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\PattiFul" @@ -123,10 +134,14 @@ Copy-Item "D:\Folder003\" -Destination "C:\Folder003_Copy\" -ToSession $Session ### Example 8: Copy a file to a remote computer and then rename the file -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy "scriptingexample.ps1" from the "D:\Folder004" folder to the "C:\Folder004_Copy" folder on the remote computer using the session information stored in the `$Session` variable. -As part of the copy operation, the command also changes the item name from "scriptingexample.ps1" to "scriptingexample_copy.ps1", so it can be attached to email messages. +The second command uses the `Copy-Item` cmdlet to copy `scriptingexample.ps1` from the +`D:\Folder004` folder to the "C:\Folder004_Copy" folder on the remote computer using the session +information stored in the `$Session` variable. +As part of the copy operation, the command also changes the item name from `scriptingexample.ps1` to +`scriptingexample_copy.ps1`, so it can be attached to email messages. This command does not delete the original file. ```powershell @@ -136,10 +151,12 @@ Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\sc ### Example 9: Copy a remote file to the local computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy test.log from the remote "C:\MyRemoteData\" to the local "D:\MyLocalData" folder using the session information stored in the `$Session` variable. -This command does not delete the original file. +The second command uses the `Copy-Item` cmdlet to copy test.log from the remote `C:\MyRemoteData\` +to the local `D:\MyLocalData` folder using the session information stored in the `$Session` +variable. This command does not delete the original file. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -148,10 +165,14 @@ Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession ### Example 10: Copy the entire contents of a remote folder to the local computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote "C:\MyRemoteData\scripts" folder to the local "D:\MyLocalData" folder using the session information stored in the `$Session` variable. -If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote +`C:\MyRemoteData\scripts` folder to the local `D:\MyLocalData` folder using the session information +stored in the `$Session` variable. +If the scripts folder contains files in subfolders, those subfolders are copied with their file +trees intact. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -160,10 +181,15 @@ Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession ### Example 11: Recursively copy the entire contents of a remote folder to the local computer -The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. +The first command creates a session to the remote computer named "Server01" with the credential of +"Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote "C:\MyRemoteData\scripts" folder to the local "D:\MyLocalData\scripts" folder using the session information stored in the `$Session` variable. -Since this command uses the **Recurse** parameter, the operation creates the scripts folder if it does not already exist. If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote +`C:\MyRemoteData\scripts` folder to the local `D:\MyLocalData\scripts` folder using the session +information stored in the `$Session` variable. +Since this command uses the **Recurse** parameter, the operation creates the scripts folder if it +does not already exist. If the scripts folder contains files in subfolders, those subfolders are +copied with their file trees intact. ```powershell $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" @@ -183,21 +209,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: True Accept pipeline input: False 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. -If you type a user name, you are prompted for a password. - -> [!WARNING] -> This parameter is not supported by any providers installed with Windows PowerShell. +> [!NOTE] +> This parameter is not supported by any providers installed with PowerShell. +> To impersonate another user, or elevate your credentials when running this cmdlet, +> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). ```yaml Type: PSCredential @@ -214,7 +236,9 @@ Accept wildcard characters: False ### -Destination Specifies the path to the new location. -To rename a copied item, include the new name in the value. +The default is the current directory. + +To rename the item being copied, specify a new name in the value of the **Destination** parameter. ```yaml Type: String @@ -230,10 +254,11 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -249,11 +274,11 @@ Accept wildcard characters: True ### -Filter -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 the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. +Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) +provider is the only installed PowerShell provider that supports the use of filters. You can find +the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). +Filters are more efficient than other parameters, because the provider applies them when the cmdlet +gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -269,7 +294,8 @@ Accept wildcard characters: True ### -Force -Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a read-only file or alias. +Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a +read-only file or alias. ```yaml Type: SwitchParameter @@ -278,7 +304,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -286,7 +312,8 @@ Accept wildcard characters: False ### -FromSession Specifies the **PSSession** object from which a remote file is being copied. -When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the remote machine. +When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the +remote machine. ```yaml Type: PSSession @@ -302,10 +329,11 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. -The value of this parameter qualifies the **Path** parameter. -Enter a path element or pattern, such as "*.txt". -Wildcard characters are permitted. +Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value +of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as +`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the +command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character +specifies the contents of the `C:\Windows` directory. ```yaml Type: String[] @@ -316,16 +344,17 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath -Specifies a path to the item. -Unlike the **Path** parameter, 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 PowerShell not to interpret any characters as escape sequences. +Specifies a path to one or more locations. 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 PowerShell not to interpret any characters +as escape sequences. + +For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md). ```yaml Type: String[] @@ -351,7 +380,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -359,6 +388,7 @@ Accept wildcard characters: False ### -Path Specifies, as a string array, the path to the items to copy. +Wildcard characters are permitted. ```yaml Type: String[] @@ -369,7 +399,7 @@ Required: True Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Recurse @@ -383,7 +413,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -391,7 +421,8 @@ Accept wildcard characters: False ### -ToSession Specifies the **PSSession** object to which a remote file is being copied. -When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the remote machine. +When you use this parameter, the **Path** and **LiteralPath** parameters refer to the local path on the +remote machine. ```yaml Type: PSSession @@ -424,6 +455,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -457,7 +489,10 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +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 @@ -469,8 +504,8 @@ You can pipe a string that contains a path to this cmdlet. ### None or an object representing the copied item. -When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied item. -Otherwise, this cmdlet does not generate any output. +When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied +item. Otherwise, this cmdlet does not generate any output. ## NOTES @@ -496,4 +531,6 @@ For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/a [Set-Item](Set-Item.md) -[Get-PSProvider](Get-PSProvider.md) \ No newline at end of file +[Get-PSProvider](Get-PSProvider.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Copy-Item.md b/reference/6/Microsoft.PowerShell.Management/Copy-Item.md index 3ba033bdcd0f..c53ce3ca1377 100644 --- a/reference/6/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Copy-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 5/14/2019 +ms.date: 5/30/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -208,7 +208,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: True Accept pipeline input: False Accept wildcard characters: False ``` @@ -303,7 +303,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -379,7 +379,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -412,7 +412,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ```