Skip to content

Fixes #12621 - Document behavior of wildcard matching when -Destination doesn't exist #12670

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 1 commit into from
Jan 17, 2026
Merged

Fixes #12621 - Document behavior of wildcard matching when -Destination doesn't exist #12670

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
28 changes: 24 additions & 4 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 @@ -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
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar error: "If the C:\Logfiles only contains" should be "If C:\Logfiles only contains" (remove "the" before the path). Paths used as subjects don't require the article "the" in this context.

Suggested change
> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
> If `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't

Copilot uses AI. Check for mistakes.
> 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.
Comment on lines +118 to +120
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation states "all files in C:\Logfiles are copied to C:\Drawings\Logs as a file" which is confusing and unclear. The phrase "copied to C:\Drawings\Logs as a file" doesn't make sense because multiple files cannot be copied to a single file path. The statement should clarify that each file except the last is overwritten by the next, resulting in only the last file being preserved, or describe the actual behavior more accurately.

Suggested change
> 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.
> If `C:\Logfiles` contains only files (no subdirectories) and `C:\Drawings\Logs` doesn't exist,
> each file in `C:\Logfiles` is copied in turn to the same destination path, `C:\Drawings\Logs`,
> so each copy overwrites the previous one. The resulting `C:\Drawings\Logs` file is a copy of
> the last file in the `C:\Logfiles` directory.

Copilot uses AI. Check for mistakes.

Comment on lines +118 to 121
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent reference: The sentence refers to "The C:\Drawings file" but previously mentions "C:\Drawings\Logs" as the destination. This creates confusion because C:\Drawings is described as a file rather than a directory. The sentence should clarify that when C:\Drawings\Logs doesn't exist, it's treated as a file path (not a directory), and explain the behavior more clearly.

Suggested change
> 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.
> If `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
> exist, the destination path is treated as a file name rather than a directory. A single file
> named `C:\Drawings\Logs` is created, and its contents are a copy of the last file in the
> `C:\Logfiles` directory that is processed.

Copilot uses AI. Check for mistakes.
### Example 4: Copy a file to the specified directory and rename the file

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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[]
Expand Down
30 changes: 25 additions & 5 deletions reference/7.4/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: 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:
Expand Down Expand Up @@ -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
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar error: "If the C:\Logfiles only contains" should be "If C:\Logfiles only contains" (remove "the" before the path). Paths used as subjects don't require the article "the" in this context.

Suggested change
> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
> If `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't

Copilot uses AI. Check for mistakes.
> 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.
Comment on lines +117 to +119
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent reference: The sentence refers to "The C:\Drawings file" but previously mentions "C:\Drawings\Logs" as the destination. This creates confusion because C:\Drawings is described as a file rather than a directory. The sentence should clarify that when C:\Drawings\Logs doesn't exist, it's treated as a file path (not a directory), and explain the behavior more clearly.

Suggested change
> 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.
> If `C:\Logfiles` contains only files and no subdirectories and `C:\Drawings\Logs` doesn't exist,
> `Copy-Item` treats `C:\Drawings\Logs` as the full path to a file, not a directory. All files in
> `C:\Logfiles` are copied in sequence, and the contents of the last file overwrite the previous
> content. The resulting `C:\Drawings\Logs` file contains the contents of the last file in the
> `C:\Logfiles` directory.

Copilot uses AI. Check for mistakes.

Comment on lines +117 to 120
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation states "all files in C:\Logfiles are copied to C:\Drawings\Logs as a file" which is confusing and unclear. The phrase "copied to C:\Drawings\Logs as a file" doesn't make sense because multiple files cannot be copied to a single file path. The statement should clarify that each file except the last is overwritten by the next, resulting in only the last file being preserved, or describe the actual behavior more accurately.

Suggested change
> 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.
> If `C:\Logfiles` contains only files and no subdirectories, and `C:\Drawings\Logs` doesn't
> exist, PowerShell treats `C:\Drawings\Logs` as a file path rather than a directory. Each file in
> `C:\Logfiles` is copied in turn to `C:\Drawings\Logs`, overwriting the previous one, so the final
> `C:\Drawings\Logs` file is a copy of the last file in the `C:\Logfiles` directory.

Copilot uses AI. Check for mistakes.
### Example 4: Copy a file to the specified directory and rename the file

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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[]
Expand Down
6 changes: 5 additions & 1 deletion reference/7.5/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: 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:
Expand Down Expand Up @@ -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
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar error: "If the C:\Logfiles only contains" should be "If C:\Logfiles only contains" (remove "the" before the path). Paths used as subjects don't require the article "the" in this context.

Suggested change
> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
> If `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't

Copilot uses AI. Check for mistakes.
> 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.
Comment on lines +117 to +119
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation states "all files in C:\Logfiles are copied to C:\Drawings\Logs as a file" which is confusing and unclear. The phrase "copied to C:\Drawings\Logs as a file" doesn't make sense because multiple files cannot be copied to a single file path. The statement should clarify that each file except the last is overwritten by the next, resulting in only the last file being preserved, or describe the actual behavior more accurately.

Suggested change
> 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.
> If `C:\Logfiles` contains only files (no subdirectories) and `C:\Drawings\Logs` doesn't
> exist, each file in `C:\Logfiles` is copied in turn to the same destination path,
> `C:\Drawings\Logs`. Each copy operation overwrites the previous one, so the resulting
> `C:\Drawings\Logs` file contains the contents of only the last file in the `C:\Logfiles`
> directory.

Copilot uses AI. Check for mistakes.

Comment on lines +117 to 120
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent reference: The sentence refers to "The C:\Drawings file" but previously mentions "C:\Drawings\Logs" as the destination. This creates confusion because C:\Drawings is described as a file rather than a directory. The sentence should clarify that when C:\Drawings\Logs doesn't exist, it's treated as a file path (not a directory), and explain the behavior more clearly.

Suggested change
> 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.
> If `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
> exist, `Copy-Item` treats `C:\Drawings\Logs` as a file path, not a directory. Each file from
> `C:\Logfiles` is copied in turn to `C:\Drawings\Logs`, so the `C:\Drawings\Logs` file ends up
> containing the contents of the last file in the `C:\Logfiles` directory.

Copilot uses AI. Check for mistakes.
### Example 4: Copy a file to the specified directory and rename the file

Expand Down
30 changes: 25 additions & 5 deletions reference/7.6/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: 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:
Expand Down Expand Up @@ -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
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar error: "If the C:\Logfiles only contains" should be "If C:\Logfiles only contains" (remove "the" before the path). Paths used as subjects don't require the article "the" in this context.

Suggested change
> If the `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't
> If `C:\Logfiles` only contains files and no subdirectories and `C:\Drawings\Logs` doesn't

Copilot uses AI. Check for mistakes.
> exist, all files in `C:\Logfiles` are copied to `C:\Drawings\Logs` as a file. The `C:\Drawings`
Comment on lines +117 to +118
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation states "all files in C:\Logfiles are copied to C:\Drawings\Logs as a file" which is confusing and unclear. The phrase "copied to C:\Drawings\Logs as a file" doesn't make sense because multiple files cannot be copied to a single file path. The statement should clarify that each file except the last is overwritten by the next, resulting in only the last file being preserved, or describe the actual behavior more accurately.

Suggested change
> 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`
> If `C:\Logfiles` contains only files (no subdirectories) and `C:\Drawings\Logs` doesn't
> exist, PowerShell treats `C:\Drawings\Logs` as the path to a single file. Each file from
> `C:\Logfiles` is copied to that same destination path in turn, so the final `C:\Drawings\Logs`

Copilot uses AI. Check for mistakes.
> file is a copy of the last file in the `C:\Logfiles` directory.
Comment on lines +117 to +119
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent reference: The sentence refers to "The C:\Drawings file" but previously mentions "C:\Drawings\Logs" as the destination. This creates confusion because C:\Drawings is described as a file rather than a directory. The sentence should clarify that when C:\Drawings\Logs doesn't exist, it's treated as a file path (not a directory), and explain the behavior more clearly.

Suggested change
> 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.
> If `C:\Logfiles` contains only files and no subdirectories and `C:\Drawings\Logs` doesn't
> exist, PowerShell treats `C:\Drawings\Logs` as the path of a single file in the `C:\Drawings`
> directory. All files in `C:\Logfiles` are copied, but the resulting `C:\Drawings\Logs` file
> contains the contents of the last file copied from the `C:\Logfiles` directory.

Copilot uses AI. Check for mistakes.

### Example 4: Copy a file to the specified directory and rename the file

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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[]
Expand Down