Copy-Item -Include -Recurse needs clarification and examples

[SteveL-MSFT]

Prerequisites

• Write a descriptive title.
• Search the existing issues.
• I am reporting the documentation problem for version of PowerShell I am using.

Version

5.1, 7.0, 7.1, 7.2, 7.3 (preview)

Link to affected document

https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.2

Description of the documentation error

The -Include parameter of Copy-Item says: "The value of this parameter qualifies the Path parameter." This is not clear to the user where they expect -Include to filter the results, but instead is a filter on the -Path globbing. As discussed in this issue by the Cmdlets WG PowerShell/PowerShell#16219, we believe more clarification is needed as well as some specific examples showing that -Include filters against -Path (while Copy-item does what users expect which is -Include filters on the results).

Suggested fix

Change "The value of this parameter qualifies the Path parameter." to "The value of this parameter qualifies the Path parameter. This means that -Include filters against the globbing (wildcard matching) result of -Path and not against the final results. This may be unexpected behavior when used with -Recurse as it only filters against the top level results and not the recursive results."

Add examples showing that -Path example* -Include *.txt -Recurse would only match example*.txt and not files within the example* folders that end in .txt.

[sdwheeler]

@SteveL-MSFT There are 37 cmdlets that have -include and -exclude. Does this behavior apply to all of these cmdlets? What about the behavior of -exclude?