powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Rename-Item



NAME
Rename-Item

SYNOPSIS
Renames an item in a Windows PowerShell provider namespace.

SYNTAX
Rename-Item [-Path] [-NewName] [-Credential ] [-Force] [-PassThru] [-Confirm] [-Wha
tIf] [-UseTransaction] []


DESCRIPTION
The Rename-Item cmdlet changes the name of a specified item. This cmdlet does not affect the content of the item be
ing renamed.

You cannot use Rename-Item to move an item, such as by specifying a path along with the new name. To move and renam
e an item, use the Move-Item cmdlet.


PARAMETERS
-Credential
Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated
by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

This parameter is not supported by any providers installed with Windows PowerShell.

Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Force []
Allows the cmdlet to rename items that cannot otherwise be changed, such as hidden or read-only files or read-o
nly aliases or variables. The cmdlet cannot change constant aliases or variables. Implementation varies from pr
ovider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet canno
t override security restrictions.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-NewName
Specifies the new name of the item. Enter only a name, not a path and name. If you enter a path that is differe
nt from the path that is specified in the Path parameter, Rename-Item generates an error. To rename and move an
item, use the Move-Item cmdlet.

You cannot use wildcard characters in the value of NewName. To specify a name for multiple files, use the Repla
ce operator in a regular expression. For more information about the Replace operator, type "get-help about_comp
arison_operators". For a demonstration, see the examples.

Required? true
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-PassThru []
Passes an object representing the item to the pipeline. By default, this cmdlet does not generate any output.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Path
Specifies the path to the item to rename.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-Confirm []
Prompts you for confirmation before executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WhatIf []
Describes what would happen if you executed the command without actually executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
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.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.String
You can pipe a string that contains a path to Rename-Item.


OUTPUTS
None or an object representing the renamed item.
When you use the Passthru parameter, Rename-Item generates an object representing the renamed item. Otherwise,
this cmdlet does not generate any output.


NOTES


The Rename-Item cmdlet is designed to work with the data exposed by any provider. To list the providers availab
le in your session, type "Get-PsProvider". For more information, see about_Providers.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>rename-item -path c:\logfiles\daily_file.txt -newname monday_file.txt


Description
-----------
This command renames the file daily_file.txt to monday_file.txt.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>rename-item -path project.txt -newname d:\archive\old-project.txt

Rename-Item : Cannot rename because the target specified represents a path or device name.
At line:1 char:12
+ rename-item <<<< -path project.txt -newname d:\archive\old-project.txt
+ CategoryInfo : InvalidArgument: (:) [Rename-Item], PSArgumentException
+ FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.RenameItemCommand


C:\PS> move-item -path project.txt -destination d:\archive\old-project.txt
# Command succeeds


Description
-----------
This example shows that you cannot use the Rename-Item cmdlet to both rename and move an item. Specifically, you ca
nnot supply a path for the value of the NewName parameter, unless the path is identical to the path specified in th
e Path parameter. Otherwise, only a new name is permitted.

The first command uses the Rename-Item cmdlet to rename the project.txt file in the current directory to old-projec
t.txt in the D:\Archive directory. The result is the error shown in the output.

The second command shows the correct way to move and rename a file by using the Move-Item cmdlet. The Move-Item cmd
let lets you specify both a new path and a new name in the value of its Destination parameter.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>rename-item HKLM:\Software\MyCompany\Advertising -NewName Marketing


Description
-----------
This command uses the Rename-Item cmdlet to rename a registry key from Advertising to Marketing. When the command i
s complete, the key is renamed, but the registry entries in the key are unchanged.





-------------------------- EXAMPLE 4 --------------------------

C:\PS>get-childItem *.txt | rename-item -newname { $_.name -replace '\.txt','.log' }


Description
-----------
This example shows how to use the Replace operator to rename multiple files, even though the NewName parameter does
not accept wildcard characters.

This command renames all of the .txt files in the current directory to .log.

The command uses a Get-ChildItem cmdlet to get all of the files in the current directory that have a .txt file name
extension. Then, it uses the pipeline operator (|) to send the resulting files to the Rename-Item cmdlet.

In the Rename-Item command, the value of the NewName parameter is a script block that is executed before the value
is submitted to the NewName parameter.

In the script block, the $_ automatic variable represents each file object as it comes to the command through the p
ipeline. The command uses the dot format (.) to get the Name property of each file object. The Replace operator rep
laces the ".txt" file name extension of each file with ".log".

Because the Replace operator works with regular expressions, the dot preceding "txt" is interpreted to match any ch
aracter. To ensure that it matches only a dot (.), it is escaped with a backslash character (\). The backslash char
acter is not required in ".log" because it is a string, not a regular expression.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113382
about_Providers
Clear-Item
Invoke-Item
Move-Item
Rename-ItemProperty
Set-Item
New-Item
Remove-Item
Get-Item
Copy-Item