From 83e64a37f782e37c1dd1c999e37fcbab911cb55b Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Wed, 1 Apr 2026 12:11:00 -0500 Subject: [PATCH] (AB-538640) Clarify behavior of `Rename-Item` when new name item exists --- .../5.1/Microsoft.PowerShell.Management/Rename-Item.md | 9 +++++++-- .../7.4/Microsoft.PowerShell.Management/Rename-Item.md | 9 +++++++-- .../7.5/Microsoft.PowerShell.Management/Rename-Item.md | 9 +++++++-- .../7.6/Microsoft.PowerShell.Management/Rename-Item.md | 9 +++++++-- 4 files changed, 28 insertions(+), 8 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Rename-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Rename-Item.md index 203561c775b7..bb11359ad037 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Rename-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Rename-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/2026 +ms.date: 04/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/rename-item?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -40,6 +40,10 @@ content of the item being renamed. You can't use `Rename-Item` to move an item, such as by specifying a path together with the new name. To move and rename an item, use the `Move-Item` cmdlet. +You can't use `Rename-Item` to replace an existing item, such as renaming `log_new.txt` to +`log_current.txt` when `log_current.txt` already exists. To replace an existing item, use the +`Move-Item` cmdlet with the **Force** parameter. + ## EXAMPLES ### Example 1: Rename a file @@ -152,7 +156,8 @@ or read-only aliases or variables. The cmdlet can't change constant aliases or v Implementation varies from provider to provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). -Even using the **Force** parameter, the cmdlet can't override security restrictions. +Even using the **Force** parameter, the cmdlet can't override security restrictions or replace an +existing item at the destination name specified by **NewName**. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.4/Microsoft.PowerShell.Management/Rename-Item.md b/reference/7.4/Microsoft.PowerShell.Management/Rename-Item.md index 4c3378863393..c7893e004488 100644 --- a/reference/7.4/Microsoft.PowerShell.Management/Rename-Item.md +++ b/reference/7.4/Microsoft.PowerShell.Management/Rename-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/2026 +ms.date: 04/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/rename-item?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -39,6 +39,10 @@ content of the item being renamed. You can't use `Rename-Item` to move an item, such as by specifying a path together with the new name. To move and rename an item, use the `Move-Item` cmdlet. +You can't use `Rename-Item` to replace an existing item, such as renaming `log_new.txt` to +`log_current.txt` when `log_current.txt` already exists. To replace an existing item, use the +`Move-Item` cmdlet with the **Force** parameter. + ## EXAMPLES ### Example 1: Rename a file @@ -151,7 +155,8 @@ or read-only aliases or variables. The cmdlet can't change constant aliases or v Implementation varies from provider to provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). -Even using the **Force** parameter, the cmdlet can't override security restrictions. +Even using the **Force** parameter, the cmdlet can't override security restrictions or replace an +existing item at the destination name specified by **NewName**. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.5/Microsoft.PowerShell.Management/Rename-Item.md b/reference/7.5/Microsoft.PowerShell.Management/Rename-Item.md index 7feebaf8be12..8301804fcf0a 100644 --- a/reference/7.5/Microsoft.PowerShell.Management/Rename-Item.md +++ b/reference/7.5/Microsoft.PowerShell.Management/Rename-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/2026 +ms.date: 04/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/rename-item?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -39,6 +39,10 @@ content of the item being renamed. You can't use `Rename-Item` to move an item, such as by specifying a path together with the new name. To move and rename an item, use the `Move-Item` cmdlet. +You can't use `Rename-Item` to replace an existing item, such as renaming `log_new.txt` to +`log_current.txt` when `log_current.txt` already exists. To replace an existing item, use the +`Move-Item` cmdlet with the **Force** parameter. + ## EXAMPLES ### Example 1: Rename a file @@ -151,7 +155,8 @@ or read-only aliases or variables. The cmdlet can't change constant aliases or v Implementation varies from provider to provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). -Even using the **Force** parameter, the cmdlet can't override security restrictions. +Even using the **Force** parameter, the cmdlet can't override security restrictions or replace an +existing item at the destination name specified by **NewName**. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.6/Microsoft.PowerShell.Management/Rename-Item.md b/reference/7.6/Microsoft.PowerShell.Management/Rename-Item.md index edb88048ed10..a74bf7f2c7a9 100644 --- a/reference/7.6/Microsoft.PowerShell.Management/Rename-Item.md +++ b/reference/7.6/Microsoft.PowerShell.Management/Rename-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/2026 +ms.date: 04/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/rename-item?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -39,6 +39,10 @@ content of the item being renamed. You can't use `Rename-Item` to move an item, such as by specifying a path together with the new name. To move and rename an item, use the `Move-Item` cmdlet. +You can't use `Rename-Item` to replace an existing item, such as renaming `log_new.txt` to +`log_current.txt` when `log_current.txt` already exists. To replace an existing item, use the +`Move-Item` cmdlet with the **Force** parameter. + ## EXAMPLES ### Example 1: Rename a file @@ -151,7 +155,8 @@ or read-only aliases or variables. The cmdlet can't change constant aliases or v Implementation varies from provider to provider. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). -Even using the **Force** parameter, the cmdlet can't override security restrictions. +Even using the **Force** parameter, the cmdlet can't override security restrictions or replace an +existing item at the destination name specified by **NewName**. ```yaml Type: System.Management.Automation.SwitchParameter