Document behavior of wildcard matching when -Destination doesn't exist (#12670)

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md

@@ -114,6 +114,10 @@ Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse
 > trees, are copied to the new destination directory. For example:
 >
 > `Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings\Logs" -Recurse`
+>
+> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
+> exist, all files in `C:\Logfiles` are copied to `C:\Drawings\Logs` as a file. The `C:\Drawings`
+> file is a copy of the last file in the `C:\Logfiles` directory.
 
 ### Example 4: Copy a file to the specified directory and rename the file
 
@@ -123,7 +127,11 @@ operation, the command changes the item name from `Get-Widget.ps1` to `Get-Widge
 can be safely attached to email messages.
 
 ```powershell
-Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
+$copyParams = @{
+    Path        = "\\Server01\Share\Get-Widget.ps1"
+    Destination = "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
+}
+Copy-Item @copyParams
 ```
 
 ### Example 5: Copy a file to a remote computer
@@ -181,7 +189,12 @@ The `Copy-Item` cmdlet copies `scriptingexample.ps1` from the `D:\Folder004` fol
 
 ```powershell
 $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
-Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\scriptingexample_copy.ps1" -ToSession $Session
+$copyParams = @{
+    Path        = "D:\Folder004\scriptingexample.ps1"
+    Destination = "C:\Folder004_Copy\scriptingexample_copy.ps1"
+    ToSession   = $Session
+}
+Copy-Item @copyParams
 ```
 
 ### Example 9: Copy a remote file to the local computer
@@ -226,7 +239,13 @@ copied with their file trees intact.
 
 ```powershell
 $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
-Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\scripts" -FromSession $Session -Recurse
+$copyParams = @{
+    Path        = "C:\MyRemoteData\scripts"
+    Destination = "D:\MyLocalData\scripts"
+    FromSession = $Session
+    Recurse     = $true
+}
+Copy-Item @copyParams
 ```
 
 ### Example 12: Recursively copy files from a folder tree into the current folder
@@ -541,7 +560,8 @@ typed. No characters are interpreted as wildcards. If the path includes escape c
 it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters
 as escape sequences.
 
-For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
+For more information, see
+[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
 
 ```yaml
 Type: System.String[]

reference/7.4/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: 11/04/2024
+ms.date: 01/17/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 aliases:
@@ -113,6 +113,10 @@ Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse
 > trees, are copied to the new destination directory. For example:
 >
 > `Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings\Logs" -Recurse`
+>
+> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
+> exist, all files in `C:\Logfiles` are copied to `C:\Drawings\Logs` as a file. The `C:\Drawings`
+> file is a copy of the last file in the `C:\Logfiles` directory.
 
 ### Example 4: Copy a file to the specified directory and rename the file
 
@@ -122,7 +126,11 @@ operation, the command changes the item name from `Get-Widget.ps1` to `Get-Widge
 can be safely attached to email messages.
 
 ```powershell
-Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
+$copyParams = @{
+    Path        = "\\Server01\Share\Get-Widget.ps1"
+    Destination = "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
+}
+Copy-Item @copyParams
 ```
 
 ### Example 5: Copy a file to a remote computer
@@ -180,7 +188,12 @@ The `Copy-Item` cmdlet copies `scriptingexample.ps1` from the `D:\Folder004` fol
 
 ```powershell
 $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
-Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\scriptingexample_copy.ps1" -ToSession $Session
+$copyParams = @{
+    Path        = "D:\Folder004\scriptingexample.ps1"
+    Destination = "C:\Folder004_Copy\scriptingexample_copy.ps1"
+    ToSession   = $Session
+}
+Copy-Item @copyParams
 ```
 
 ### Example 9: Copy a remote file to the local computer
@@ -225,7 +238,13 @@ copied with their file trees intact.
 
 ```powershell
 $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
-Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\scripts" -FromSession $Session -Recurse
+$copyParams = @{
+    Path        = "C:\MyRemoteData\scripts"
+    Destination = "D:\MyLocalData\scripts"
+    FromSession = $Session
+    Recurse     = $true
+}
+Copy-Item @copyParams
 ```
 
 ### Example 12: Recursively copy files from a folder tree into the current folder
@@ -540,7 +559,8 @@ typed. No characters are interpreted as wildcards. If the path includes escape c
 it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters
 as escape sequences.
 
-For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
+For more information, see
+[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
 
 ```yaml
 Type: System.String[]

reference/7.5/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: 11/04/2024
+ms.date: 01/17/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.5&WT.mc_id=ps-gethelp
 schema: 2.0.0
 aliases:
@@ -113,6 +113,10 @@ Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse
 > trees, are copied to the new destination directory. For example:
 >
 > `Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings\Logs" -Recurse`
+>
+> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
+> exist, all files in `C:\Logfiles` are copied to `C:\Drawings\Logs` as a file. The `C:\Drawings`
+> file is a copy of the last file in the `C:\Logfiles` directory.
 
 ### Example 4: Copy a file to the specified directory and rename the file
 

reference/7.6/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: 11/04/2024
+ms.date: 01/17/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.6&WT.mc_id=ps-gethelp
 schema: 2.0.0
 aliases:
@@ -113,6 +113,10 @@ Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse
 > trees, are copied to the new destination directory. For example:
 >
 > `Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings\Logs" -Recurse`
+>
+> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
+> exist, all files in `C:\Logfiles` are copied to `C:\Drawings\Logs` as a file. The `C:\Drawings`
+> file is a copy of the last file in the `C:\Logfiles` directory.
 
 ### Example 4: Copy a file to the specified directory and rename the file
 
@@ -122,7 +126,11 @@ operation, the command changes the item name from `Get-Widget.ps1` to `Get-Widge
 can be safely attached to email messages.
 
 ```powershell
-Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
+$copyParams = @{
+    Path        = "\\Server01\Share\Get-Widget.ps1"
+    Destination = "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
+}
+Copy-Item @copyParams
 ```
 
 ### Example 5: Copy a file to a remote computer
@@ -180,7 +188,12 @@ The `Copy-Item` cmdlet copies `scriptingexample.ps1` from the `D:\Folder004` fol
 
 ```powershell
 $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
-Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\scriptingexample_copy.ps1" -ToSession $Session
+$copyParams = @{
+    Path        = "D:\Folder004\scriptingexample.ps1"
+    Destination = "C:\Folder004_Copy\scriptingexample_copy.ps1"
+    ToSession   = $Session
+}
+Copy-Item @copyParams
 ```
 
 ### Example 9: Copy a remote file to the local computer
@@ -225,7 +238,13 @@ copied with their file trees intact.
 
 ```powershell
 $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
-Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\scripts" -FromSession $Session -Recurse
+$copyParams = @{
+    Path        = "C:\MyRemoteData\scripts"
+    Destination = "D:\MyLocalData\scripts"
+    FromSession = $Session
+    Recurse     = $true
+}
+Copy-Item @copyParams
 ```
 
 ### Example 12: Recursively copy files from a folder tree into the current folder
@@ -540,7 +559,8 @@ typed. No characters are interpreted as wildcards. If the path includes escape c
 it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters
 as escape sequences.
 
-For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
+For more information, see
+[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
 
 ```yaml
 Type: System.String[]