PowerShell v3 in a Year Day 11 Rename Item

Topic: Rename-Item
Alias: ri, ren

In cmd.exe the equivalent command to Rename-Item was simply ren. Nicely enough, ren still works as an alias for the Rename-Item cmdlet, but, there are a few more bells and whistles in PowerShell. For example, ren, in cmd.exe gives us this for help:

Renames a file or files.

RENAME [drive:][path]filename1 filename2.

REN [drive:][path]filename1 filename2.

Note that you cannot specify a new drive or path for your destination file.

Hardly the most verbose help Ive ever seen. In PowerShell, you get the following:

SYNOPSIS

    Renames an item in a Windows PowerShellprovider namespace.

SYNTAX

    Rename-Item[-Path] <String> [-NewName]<String>[-Credential <PSCredential>] [-Force[]][-PassThru []][-Confirm ]][-WhatIf []][-UseTransaction    []][]

    Rename-Item[-NewName] <String> [-Credential<PSCredential>][-Force ]][-PassThru[]]-LiteralPath <String> [-Confirm[]] [-WhatIf []][-UseTransaction []][]

DESCRIPTION

    The Rename-Item cmdletchanges thename ofa specifieditem. Thiscmdlet doesnot affectthe contentof theitem beingrenamed.

    You cannot useRename-Item tomove anitem,such asby specifyinga pathalong withthe newname. Tomove andrename anitem,use theMove-Item cmdlet. 

Somewhat more robust, but, still spare at times. To give insight into the main elements of the cmdlet, I will go through the parameters one by one.

-Path

Specifies thepath tothe itemto rename.

Required?                    true

Position?                    1

Default value

Accept pipelineinput?       true(ByValue, ByPropertyName)

Accept wildcardcharacters?  false

Path simply indicates the location of the item to be renamed. This cannot be omitted, unless you are passing items via the pipeline as it accepts pipeline input both ByValue and ByPropertyName. Quite simply, this tells me what I am renaming by file path.

-NewName

Specifies thenew nameof theitem. Enteronly aname,not apath andname. Ifyou entera paththat isdifferent fromthe path that is specified inthe Pathparameter,Rename-Item generatesan error.To renameand movean item, use the Move-Itemcmdlet.

You cannotuse wildcardcharacters inthe valueof NewName.To specifya namefor multiplefiles,use theReplace operatorin aregular expression.For moreinformation aboutthe Replaceoperator,type "get-help about_comparison_operators". For a demonstration,see theexamples.

Required?                    true

Position?                    2

Default value

Accept pipelineinput?       true(ByPropertyName)

Accept wildcardcharacters?  false

NewName is precisely what it indicates, the new name to be used in place of the old file name. As noted in the help, do not enter the path, merely the file name. Again, this is a required argument. One thing I have found here is to call various aspects of the original file name, such as basename, name, etc, with a pipelined object. This allows you to manipulate the file in clever ways at times. It takes a little experimentation to figure out just how to tweak things this way, but, it is a very useful technique. Take, for example, this scenario: I have a set of files in a directory for which I want to use the base name (that is the file name without the extension), but, I want to add in an incremented, zero-filled integer value along with a new extension. I might accomplish this as shown below:

$counter = 0;

Get-ChildItem -Path C:Directory* |

ForEach-Object {

    $Counter++;

    Rename-Item-Path $_.fullname -NewName ("$($_.BaseName)_{0:0000}.tif" -f $counter)

}

When this runs it will take a file name, lets say DCIM_1247.JPG, extract the basename (DCIM_1247), increment the counter to 1, then, pass the new integer value via the format specifier to the placeholder to generate a new file, DCIM_1247_0001.tif. This is a stilted example, but, can give an idea of how you can make some interesting manipulations in flight.

-Credential

Specifies auser accountthat haspermission toperform thisaction. Thedefault isthe currentuser.

Type auser name, such as "User01"or "Domain01User01", or enter a s.PSCredential object, such as one generated by the