From 81793693345aa8b23a1063e3b31d034a5ae9c468 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 13 Apr 2022 00:01:00 -0500 Subject: [PATCH 1/3] (GH-8601) Clarify Include parameter for Copy-Item Prior to this commit, the documentation for the Include parameter of the Copy-Item cmdlet was unclear. This commit clarifies its functionality and adds a new example to show how it is used and where its behavior might be otherwise surprising. --- .../Copy-Item.md | 103 +++++++++++++++-- .../Copy-Item.md | 103 +++++++++++++++-- .../Copy-Item.md | 104 ++++++++++++++++-- .../Copy-Item.md | 104 ++++++++++++++++-- .../Copy-Item.md | 104 ++++++++++++++++-- 5 files changed, 460 insertions(+), 58 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md index ab4594eaecda..fd10833bc07a 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -252,6 +252,85 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Limit the files copied from a wildcard-specified path into the current folder + +This example shows how to limit the files copied from a wildcard-matching path into the current +folder using the **Include** parameter. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths which end in `.txt`. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +```powershell +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> Remove-Item .\* +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName +C:\temp\tree\examples +C:\temp\tree\example.txt +``` + +The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from +`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. + +The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** +parameter's filter is applied only to the items resolved from the wildcard specified in the +**Path**. + +The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to +`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter +specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items +are copied. + +### Example 14: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\out\example_1.txt +C:\temp\out\example_2.txt +C:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -310,11 +389,12 @@ Accept wildcard characters: False ### -Exclude -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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -385,11 +465,12 @@ 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. 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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] diff --git a/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md index 0e980d95546b..5b5a589e92db 100644 --- a/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,85 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Limit the files copied from a wildcard-specified path into the current folder + +This example shows how to limit the files copied from a wildcard-matching path into the current +folder using the **Include** parameter. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths which end in `.txt`. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +```powershell +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> Remove-Item .\* +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName +C:\temp\tree\examples +C:\temp\tree\example.txt +``` + +The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from +`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. + +The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** +parameter's filter is applied only to the items resolved from the wildcard specified in the +**Path**. + +The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to +`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter +specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items +are copied. + +### Example 14: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\out\example_1.txt +C:\temp\out\example_2.txt +C:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +387,12 @@ Accept wildcard characters: False ### -Exclude -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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -383,11 +463,12 @@ 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. 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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] diff --git a/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md index e3387e65b32a..65104298c4a2 100644 --- a/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,85 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Limit the files copied from a wildcard-specified path into the current folder + +This example shows how to limit the files copied from a wildcard-matching path into the current +folder using the **Include** parameter. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths which end in `.txt`. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +```powershell +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> Remove-Item .\* +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName +C:\temp\tree\examples +C:\temp\tree\example.txt +``` + +The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from +`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. + +The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** +parameter's filter is applied only to the items resolved from the wildcard specified in the +**Path**. + +The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to +`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter +specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items +are copied. + +### Example 14: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\out\example_1.txt +C:\temp\out\example_2.txt +C:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +387,12 @@ Accept wildcard characters: False ### -Exclude -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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -383,11 +463,12 @@ 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. 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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -566,4 +647,3 @@ available in your session, type `Get-PSProvider`. For more information, see [abo [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) - diff --git a/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md index 14ea5e14dd4d..e9a60f08f026 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,85 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Limit the files copied from a wildcard-specified path into the current folder + +This example shows how to limit the files copied from a wildcard-matching path into the current +folder using the **Include** parameter. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths which end in `.txt`. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +```powershell +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> Remove-Item .\* +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName +C:\temp\tree\examples +C:\temp\tree\example.txt +``` + +The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from +`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. + +The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** +parameter's filter is applied only to the items resolved from the wildcard specified in the +**Path**. + +The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to +`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter +specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items +are copied. + +### Example 14: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\out\example_1.txt +C:\temp\out\example_2.txt +C:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +387,12 @@ Accept wildcard characters: False ### -Exclude -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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -383,11 +463,12 @@ 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. 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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -566,4 +647,3 @@ available in your session, type `Get-PSProvider`. For more information, see [abo [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) - diff --git a/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md index f34c15530341..000546419587 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 08/25/2020 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,85 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Limit the files copied from a wildcard-specified path into the current folder + +This example shows how to limit the files copied from a wildcard-matching path into the current +folder using the **Include** parameter. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths which end in `.txt`. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +```powershell +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> Remove-Item .\* +PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\test\out\example.txt + +PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName +C:\temp\tree\examples +C:\temp\tree\example.txt +``` + +The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from +`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. + +The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** +parameter's filter is applied only to the items resolved from the wildcard specified in the +**Path**. + +The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to +`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter +specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items +are copied. + +### Example 14: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This list shows the existing folder structure of the path to the files to be copied: + +- `C:\temp\tree\examples` +- `C:\temp\tree\example.ps1` +- `C:\temp\tree\example.txt` +- `C:\temp\tree\examples\example_1.txt` +- `C:\temp\tree\examples\example_2.txt` + +To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item +PS C:\temp\test> (Get-ChildItem).FullName +C:\temp\out\example_1.txt +C:\temp\out\example_2.txt +C:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +387,12 @@ Accept wildcard characters: False ### -Exclude -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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -383,11 +463,12 @@ 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. 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. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -566,4 +647,3 @@ available in your session, type `Get-PSProvider`. For more information, see [abo [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) - From fb9efa2849870c195f3271bdeeb01203f9ded493 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Apr 2022 08:57:02 -0500 Subject: [PATCH 2/3] Apply suggestions from code review --- .../5.1/Microsoft.PowerShell.Management/Copy-Item.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md index fd10833bc07a..b8b8ddb62406 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -257,7 +257,8 @@ the same name are overwritten in the destination folder. This example shows how to limit the files copied from a wildcard-matching path into the current folder using the **Include** parameter. -This list shows the existing folder structure of the path to the files to be copied: +The following list shows the existing folder structure of the path to the files to be copied: + - `C:\temp\tree\examples` - `C:\temp\tree\example.ps1` @@ -267,7 +268,8 @@ This list shows the existing folder structure of the path to the files to be cop In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the -files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items +files and folders that match `C:\temp\tree\*`. The **Include** parameter filters the list of items + to process, limiting the operation to only those paths which end in `.txt`. > [!NOTE] @@ -309,7 +311,8 @@ resolved for a wildcard-specifying **Path**, the **Include** parameter can't be files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you want to copy and pass those items to `Copy-Item`. -This list shows the existing folder structure of the path to the files to be copied: +The following list shows the existing folder structure of the path to the files to be copied: + - `C:\temp\tree\examples` - `C:\temp\tree\example.ps1` From 0adb5d6a14e435afb42fa7c110f952ebccd07c88 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Apr 2022 09:43:42 -0500 Subject: [PATCH 3/3] Added recurse example --- .../Copy-Item.md | 154 +++++++++++------- .../Copy-Item.md | 147 ++++++++++------- .../Copy-Item.md | 147 ++++++++++------- .../Copy-Item.md | 147 ++++++++++------- .../Copy-Item.md | 147 ++++++++++------- 5 files changed, 452 insertions(+), 290 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md index b8b8ddb62406..6e448c48bd52 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -252,58 +252,81 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. -### Example 13: Limit the files copied from a wildcard-specified path into the current folder +### Example 13: Using filters to copy items without recursion -This example shows how to limit the files copied from a wildcard-matching path into the current -folder using the **Include** parameter. +This example shows the results using the **Include** parameter to select which items should be +copied. -The following list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: - -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the -files and folders that match `C:\temp\tree\*`. The **Include** parameter filters the list of items +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. -to process, limiting the operation to only those paths which end in `.txt`. +```powershell +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` -> [!NOTE] -> The behavior of the **Exclude** parameter is the same as described in this example, except that -> it limits the operation to only those paths which do not match the pattern. +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. -```powershell -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +### Example 15: Using filters to copy items with recursion -PS C:\temp\test> Remove-Item .\* -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +This example shows the results using the **Include** parameter to select which items should be +copied. -PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName -C:\temp\tree\examples -C:\temp\tree\example.txt -``` +This example uses the following folder structure containing the files to be copied: -The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from -`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** -parameter's filter is applied only to the items resolved from the wildcard specified in the -**Path**. +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. -The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to -`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter -specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items -are copied. +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. -### Example 14: Limit the files to recursively copy from a wildcard-specified path +### Example 15: Limit the files to recursively copy from a wildcard-specified path This example shows how to limit the files recursively copied from a wildcard-matching path into another folder. Example 13 shows that, because the **Include** parameter only filters on the paths @@ -311,24 +334,27 @@ resolved for a wildcard-specifying **Path**, the **Include** parameter can't be files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you want to copy and pass those items to `Copy-Item`. -The following list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` - -To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** parameters and pipe the results to `Copy-Item`. ```powershell -PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\out\example_1.txt -C:\temp\out\example_2.txt -C:\temp\out\example.txt +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt ``` Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered @@ -413,11 +439,13 @@ Accept wildcard characters: True ### -Filter -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're 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're retrieved. ```yaml Type: System.String @@ -560,8 +588,7 @@ Accept wildcard characters: False ### -ToSession Specifies the **PSSession** object to which a remote file is being copied. When you use this -parameter, the **Destination** parameter refers to the local path on the remote -machine. +parameter, the **Destination** parameter refers to the local path on the remote machine. ```yaml Type: System.Management.Automation.Runspaces.PSSession @@ -578,7 +605,8 @@ 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](../Microsoft.PowerShell.Core/About/about_Transactions.md). +in progress. For more information, see +[about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: System.Management.Automation.SwitchParameter @@ -626,9 +654,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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -646,7 +675,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES 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). +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/7.0/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md index 5b5a589e92db..f20e84ea2bbd 100644 --- a/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md @@ -250,56 +250,81 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. -### Example 13: Limit the files copied from a wildcard-specified path into the current folder +### Example 13: Using filters to copy items without recursion -This example shows how to limit the files copied from a wildcard-matching path into the current -folder using the **Include** parameter. +This example shows the results using the **Include** parameter to select which items should be +copied. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the -files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items -to process, limiting the operation to only those paths which end in `.txt`. - -> [!NOTE] -> The behavior of the **Exclude** parameter is the same as described in this example, except that -> it limits the operation to only those paths which do not match the pattern. +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. ```powershell -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` -PS C:\temp\test> Remove-Item .\* -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. -PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName -C:\temp\tree\examples -C:\temp\tree\example.txt -``` +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. -The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from -`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. +This example uses the following folder structure containing the files to be copied: -The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** -parameter's filter is applied only to the items resolved from the wildcard specified in the -**Path**. +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to -`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter -specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items -are copied. +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. -### Example 14: Limit the files to recursively copy from a wildcard-specified path +### Example 15: Limit the files to recursively copy from a wildcard-specified path This example shows how to limit the files recursively copied from a wildcard-matching path into another folder. Example 13 shows that, because the **Include** parameter only filters on the paths @@ -307,23 +332,27 @@ resolved for a wildcard-specifying **Path**, the **Include** parameter can't be files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you want to copy and pass those items to `Copy-Item`. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** parameters and pipe the results to `Copy-Item`. ```powershell -PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\out\example_1.txt -C:\temp\out\example_2.txt -C:\temp\out\example.txt +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt ``` Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered @@ -408,11 +437,13 @@ Accept wildcard characters: True ### -Filter -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're 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're retrieved. ```yaml Type: System.String @@ -604,9 +635,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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -624,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES 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). +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/7.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md index 65104298c4a2..711c295f96c5 100644 --- a/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -250,56 +250,81 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. -### Example 13: Limit the files copied from a wildcard-specified path into the current folder +### Example 13: Using filters to copy items without recursion -This example shows how to limit the files copied from a wildcard-matching path into the current -folder using the **Include** parameter. +This example shows the results using the **Include** parameter to select which items should be +copied. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the -files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items -to process, limiting the operation to only those paths which end in `.txt`. - -> [!NOTE] -> The behavior of the **Exclude** parameter is the same as described in this example, except that -> it limits the operation to only those paths which do not match the pattern. +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. ```powershell -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` -PS C:\temp\test> Remove-Item .\* -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. -PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName -C:\temp\tree\examples -C:\temp\tree\example.txt -``` +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. -The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from -`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. +This example uses the following folder structure containing the files to be copied: -The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** -parameter's filter is applied only to the items resolved from the wildcard specified in the -**Path**. +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to -`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter -specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items -are copied. +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. -### Example 14: Limit the files to recursively copy from a wildcard-specified path +### Example 15: Limit the files to recursively copy from a wildcard-specified path This example shows how to limit the files recursively copied from a wildcard-matching path into another folder. Example 13 shows that, because the **Include** parameter only filters on the paths @@ -307,23 +332,27 @@ resolved for a wildcard-specifying **Path**, the **Include** parameter can't be files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you want to copy and pass those items to `Copy-Item`. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** parameters and pipe the results to `Copy-Item`. ```powershell -PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\out\example_1.txt -C:\temp\out\example_2.txt -C:\temp\out\example.txt +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt ``` Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered @@ -408,11 +437,13 @@ Accept wildcard characters: True ### -Filter -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're 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're retrieved. ```yaml Type: System.String @@ -604,9 +635,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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -624,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES 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). +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/7.2/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md index e9a60f08f026..b8ef709fb407 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md @@ -250,56 +250,81 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. -### Example 13: Limit the files copied from a wildcard-specified path into the current folder +### Example 13: Using filters to copy items without recursion -This example shows how to limit the files copied from a wildcard-matching path into the current -folder using the **Include** parameter. +This example shows the results using the **Include** parameter to select which items should be +copied. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the -files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items -to process, limiting the operation to only those paths which end in `.txt`. - -> [!NOTE] -> The behavior of the **Exclude** parameter is the same as described in this example, except that -> it limits the operation to only those paths which do not match the pattern. +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. ```powershell -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` -PS C:\temp\test> Remove-Item .\* -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. -PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName -C:\temp\tree\examples -C:\temp\tree\example.txt -``` +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. -The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from -`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. +This example uses the following folder structure containing the files to be copied: -The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** -parameter's filter is applied only to the items resolved from the wildcard specified in the -**Path**. +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to -`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter -specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items -are copied. +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. -### Example 14: Limit the files to recursively copy from a wildcard-specified path +### Example 15: Limit the files to recursively copy from a wildcard-specified path This example shows how to limit the files recursively copied from a wildcard-matching path into another folder. Example 13 shows that, because the **Include** parameter only filters on the paths @@ -307,23 +332,27 @@ resolved for a wildcard-specifying **Path**, the **Include** parameter can't be files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you want to copy and pass those items to `Copy-Item`. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** parameters and pipe the results to `Copy-Item`. ```powershell -PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\out\example_1.txt -C:\temp\out\example_2.txt -C:\temp\out\example.txt +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt ``` Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered @@ -408,11 +437,13 @@ Accept wildcard characters: True ### -Filter -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're 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're retrieved. ```yaml Type: System.String @@ -604,9 +635,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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -624,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES 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). +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/7.3/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md index 000546419587..026bd20df688 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md @@ -250,56 +250,81 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. -### Example 13: Limit the files copied from a wildcard-specified path into the current folder +### Example 13: Using filters to copy items without recursion -This example shows how to limit the files copied from a wildcard-matching path into the current -folder using the **Include** parameter. +This example shows the results using the **Include** parameter to select which items should be +copied. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the -files and folders which match `C:\temp\tree\*`. The **Include** parameter filters the list of items -to process, limiting the operation to only those paths which end in `.txt`. - -> [!NOTE] -> The behavior of the **Exclude** parameter is the same as described in this example, except that -> it limits the operation to only those paths which do not match the pattern. +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. ```powershell -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` -PS C:\temp\test> Remove-Item .\* -PS C:\temp\test> Copy-Item -Path C:\temp\tree\* -Include *.txt -Recurse -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\test\out\example.txt +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. -PS C:\temp\test> (Get-Item -Path C:\temp\tree*).FullName -C:\temp\tree\examples -C:\temp\tree\example.txt -``` +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. -The first call to `Copy-Item` is non-recursive. It copies the only the `example.txt` file from -`C:\temp\tree` as the **Include** parameter filtered out both `examples` and `example.txt`. +This example uses the following folder structure containing the files to be copied: -The second call to `Copy-Item` is recursive and has the same result. This is because the **Include** -parameter's filter is applied only to the items resolved from the wildcard specified in the -**Path**. +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -The call to `Get-Item` shows the files and folders that the **Include** parameter in the calls to -`Copy-Item` filters against. In those results, the only string that matches the `*.txt` filter -specified for the **Include** parameter is `C:\temp\tree\example.txt`. This ensures no other items -are copied. +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. -### Example 14: Limit the files to recursively copy from a wildcard-specified path +### Example 15: Limit the files to recursively copy from a wildcard-specified path This example shows how to limit the files recursively copied from a wildcard-matching path into another folder. Example 13 shows that, because the **Include** parameter only filters on the paths @@ -307,23 +332,27 @@ resolved for a wildcard-specifying **Path**, the **Include** parameter can't be files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you want to copy and pass those items to `Copy-Item`. -This list shows the existing folder structure of the path to the files to be copied: +This example uses the following folder structure containing the files to be copied: -- `C:\temp\tree\examples` -- `C:\temp\tree\example.ps1` -- `C:\temp\tree\example.txt` -- `C:\temp\tree\examples\example_1.txt` -- `C:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` -To copy all the `example*.txt` files, use `Get-ChildItem` with the **Recurse** and **Filter** +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** parameters and pipe the results to `Copy-Item`. ```powershell -PS C:\temp\test> Get-ChildItem -Path C:\temp\tree -Recurse -Filter *.txt | Copy-Item -PS C:\temp\test> (Get-ChildItem).FullName -C:\temp\out\example_1.txt -C:\temp\out\example_2.txt -C:\temp\out\example.txt +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt ``` Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered @@ -408,11 +437,13 @@ Accept wildcard characters: True ### -Filter -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're 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're retrieved. ```yaml Type: System.String @@ -604,9 +635,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](https://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](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -624,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES 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). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS