Skip to content

(GH-8601) Clarify Include parameter for Copy-Item #8734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sdwheeler merged 3 commits into from
Apr 14, 2022
Merged

(GH-8601) Clarify Include parameter for Copy-Item #8734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8179369
(GH-8601) Clarify Include parameter for Copy-Item
michaeltlombardi Apr 13, 2022
fb9efa2
Apply suggestions from code review
sdwheeler Apr 14, 2022
0adb5d6
Added recurse example
sdwheeler Apr 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 137 additions & 23 deletions reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -252,6 +252,114 @@ 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: Using filters to copy items without recursion

This example shows the results using the **Include** parameter to select which items should 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`

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 `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 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
```

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.

### 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.

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`

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 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
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 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`

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
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
during recursion. This enables you to find, filter, and then copy items recursively.

## PARAMETERS

### -Container
Expand Down Expand Up @@ -310,11 +418,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[]
Expand All @@ -330,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
Expand Down Expand Up @@ -385,11 +496,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[]
Expand Down Expand Up @@ -476,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
Expand All @@ -494,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
Expand Down Expand Up @@ -542,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

Expand All @@ -562,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

Expand Down
Loading