RenameWand

File Renaming Tool. Free software written in Java.
Latest version: 2.2 (2007-12-09)

Simple command-line file and directory renamer. Use a friendly and intuitive but powerful syntax (like regex, only much easier) to rename files and directories. Perform string operations, arithmetic operations, enumerate files, insert timestamps, and more! Free software written in Java.

Brief Description

RenameWand is a simple command-line utility for renaming files or directories using an intuitive but powerful syntax. Perform string operations (e.g. case conversions, rearrangements of substrings), arithmetic operations (e.g. on the numbers in the filename), enumerate files (e.g. by name, size, time, or other attributes), insert timestamps, and many more file and system attributes with ease! RenameWand supports pattern matching using glob patterns and wildcards *, ?, [ ], and { }, as well as the <a> register capture group construct. Runs on any OS with the Java Runtime Environment (JRE 6+). RenameWand is free software written in Java and released under the GNU GPL license (version 3).

Main Features

  • Supports the common glob patterns and wildcards *, ?, [ ], and { } for matching filenames.

  • Use the <a> register capture group construct to capture strings of characters in the filename. For example, given the file "foo bar.txt", the source pattern "<a> <b>.<c>" would assign registers a ← "foo", b ← "bar", and c ← "txt".

  • Macros are defined for a variety of file and system attributes, such as file name (FN.*), file size (FS.*), file last-modified time (FT.*), current time (CT.*), system environment variables (ENV.*), and system properties (SYS.*).

  • A wide range of operations can be applied to registers and macros:

    • case conversions (e.g. *.upper, *.lower, *.title),
    • substring operations (e.g. myreg[1:3]),
    • arithmetic operations (e.g. a/(b-c)^d),
    • enumeration operations (e.g. #FT, #(myreg1+myreg2)), and more.

  • File rename operations are sequenced so that they are conflict-free, and temporary filenames are automatically used when necessary.

  • The user is given the option of undoing previous file rename operations, if a file rename operation is unsuccessful.

Screenshots

RenameWand screenshot Example of how to enumerate files, and rearrange and capitalize filenames, with a single command using RenameWand.

System Requirements

A Java Runtime Environment (JRE 6+) is required. The latest version of the JRE can be downloaded from http://java.sun.com/j2se.

License

RenameWand is released with source code under the GNU General Public License (version 3).

Installation & Execution

The RenameWand utility is downloaded as a single Zip file with the following contents:

  • RenameWand.jar – RenameWand executable JAR archive
  • readme.txt – Release notes
  • license.txt – License document (GNU GPLv3)
  • unix/RenameWand – Unix/Linux script for executing RenameWand
  • windows/RenameWand.bat – Windows batch file for executing RenameWand
  • src/ – Source files

No installation is necessary — just unzip the downloaded file and you are ready to go. Assuming that the executable JAR archive RenameWand.jar is in the current directory, simply execute the following at the command-line:

java -jar RenameWand.jar

Several pages of documentation (usage syntax, notes, and examples) should fill the screen. The use of the Windows batch file (windows/RenameWand.bat) or the Unix/Linux script (unix/RenameWand) is recommended because it enables you to simply execute RenameWand instead of java -jar RenameWand.jar. Further instructions are given in the respective files.

Source Code

Documentation

Usage Syntax

java -jar RenameWand.jar <switches> ["SourcePattern"] ["TargetPattern"]

For each file in the current directory with a name that matches ["SourcePattern"], rename it to ["TargetPattern"]. Patterns should be in quotes so that the shell passes them to RenameWand correctly. The user is prompted before files are renamed, and whenever errors occur. File rename operations are sequenced so that they are conflict-free, and temporary filenames are automatically used when necessary.

<Switches>
−r, −−recurse Recurse into subdirectories
−d, −−dirs Rename directories instead of files
−p, −−path Match ["SourcePattern"] against relative pathnames (e.g. "2007\Jan\Report.txt" instead of "Report.txt")
−l, −−lower Match ["SourcePattern"] against lower case names (e.g. "HelloWorld2007.JPG" → "helloworld2007.jpg")
−y, −−yes Automatically rename files without prompting
−s, −−simulate Simulate only; do not actually rename files
−i, −−ignorewarnings Ignore warnings; do not pause
−−skip Skip files that cannot be renamed successfully
−−undoall Undo all previous renames when a file cannot be renamed successfully
−−abort Abort subsequent renames when a file cannot be renamed successfully
["SourcePattern"]

Files with names matching ["SourcePattern"] are renamed.

This pattern string may contain literal (i.e. ordinary) characters and the following constructs (more details below):

  1. Glob patterns and wildcards, e.g. *, ?, [ ], { }
  2. Register capture groups, e.g. <a>, <5|song>, <2|@track>
  3. Special construct <...> that may involve macros, e.g. <FN.parent>, <CT.date>, <FS+FT.yyyy>

To use a construct symbol (e.g. [, {, ?) as a literal character, insert a backslash before it, e.g. use \[ for the literal character [. Use \\ for the literal backslash character \.

The file separator in Windows can be specified by \\ or /.

["TargetPattern"]

The target names of the matched files are specified by ["TargetPattern"].

This pattern string may contain literal (i.e. ordinary) characters and the special construct <...> that may involve registers and macros (more details below).

To use a construct symbol (e.g. <, >) as a literal character, insert a backslash before it, e.g. use \< for the literal character <. Use \\ for the literal backslash character \.

The file separator in Windows can be specified by \\ or /.

If the evaluated pattern string contains a file separator (e.g. / or \), then the target name is resolved with respect to the current directory; otherwise, the target name shares the same parent directory as the source file (i.e. the source is renamed "in place").

Glob Patterns & Wildcards

The four common glob patterns are supported in ["SourcePattern"]:

* Match a string of 0 or more characters
? Match exactly 1 character
[ ] Match exactly 1 character inside the brackets:
[abc] Match a, b, or c
[!abc] Match any character except a, b, or c (negation)
[a-z0-9] Match any character a through z, or 0 through 9, inclusive (range)
{ } Match exactly 1 comma-delimited string inside the braces:
{a,bc,def} Match either a, bc, or def
Register Capture Groups

Register capture groups are used in ["SourcePattern"] to capture a string of zero or more characters. A register name can contain only letters, digits, or underscores, but cannot begin with a digit.

<myreg> Capture a string of 0 or more characters
<@myreg> Capture a string of 0 or more digits
<n|myreg> Capture a string of exactly n characters
<n|@myreg> Capture a string of exactly n digits

Backreferences can be applied by reusing the register name, e.g. "<3|myreg><myreg>.txt" matches a filename that is a repetition of a three-character string, followed by the txt extension.

Special Constructs

Special constructs are supported in both ["SourcePattern"] and ["TargetPattern"]. In general, they take the form <length|expr>, where the expressions "length" and "expr" can involve registers, macros, and use operations involving arithmetic, substrings, and enumerations (more details below). Parentheses ( ) can be used to group values.

<expr> Insert the evaluated expression "expr" using as many characters as necessary
<length|expr> Insert the evaluated expression "expr" with padding:
If the evaluated expression is numeric, pad the number with leading zeros so that it occupies at least "length" characters;
if the evaluated expression is non-numeric, pad the string with trailing spaces so that it occupies at least "length" characters.
Arithmetic Operations

The standard arithmetic operations + - * / ^ are supported for numeric values; for non-numeric strings, + is interpreted as concatenation. The standard rules of operator precedence are observed. Values are automatically cast as integers before and after every operation.

For example, <a+b/(c-d)^(e*f)> evaluates an arithmetic expression involving registers a, b, c, d, e, and f.

Substring Operations

Substrings can be extracted from any value by inserting a comma-delimited list of indices and index ranges in brackets [ ] after the value.

Index 1 denotes the 1st character, index 2 the 2nd character, and so on.

Negative indices denote character positions counting from the end of the string, i.e. index -1 denotes the last character, index -2 the second-last character, and so on.

Index ranges are denoted using three parameters, e.g. 1:2:11 is equivalent to indices 1, 3, 5, ..., 11. The middle parameter is optional; it is assumed to be 1 if missing, e.g. 5:8 is equivalent to indices 5, 6, 7, 8.

myreg[1,5,3] Extract the 1st, 5th, and 3rd characters, in that order
myreg[2:6,1] Extract the 2nd through 6th characters, followed by the 1st character, in that order
myreg[1:2:-1] Extract the 1st, 3rd, 5th, ... characters
myreg[-1:1] Extract the last through first characters (effectively reverses the string)

Indices are automatically clipped if they are too big or small, e.g. if myreg is a 3-character string, then myreg[10] is equivalent to myreg[3].

Enumeration Operations

Matched files can be sorted by any value, and then numbered in sequence.

Numerical sorting is applied if all the values are numeric; otherwise, lexicographic sorting is applied.

The 1st file in the sorted sequence is assigned the number 1, the 2nd is assigned number 2, and so on; ties are broken arbitrarily.

#myreg Return the sequence number of the respective file when sorted in ascending order of the value in register myreg
#!myreg Return the sequence number of the respective file when sorted in descending order of the value in register myreg
@myreg Return the value in register myreg of the first file in the sequence sorted in ascending order
@!myreg Return the value in register myreg of the first file in the sequence sorted in descending order

The above operations apply to matched files enumerated locally within their respective subdirectories; to enumerate all matched files globally (i.e. when using the −−recurse switch), use ## instead of #, and @@ instead of @.

For example, to enumerate matched files locally and globally by their last-modified time, we can use the target pattern string "Local <2|#FT> of <2|RW.N> -vs- Global <2|##FT> of <2|RW.NN>.txt", where macros FT, RW.N, and RW.NN represent the last-modified time of the file, the number of local matched files, and the number of global matched files, respectively (more details below).

Arbitrary values such as arithmetic expressions and substrings can also be used for enumeration, e.g. <#(a*(b+c))>, <#(FN.name[1:3])>.

Macros

Macros are defined for a variety of file and system attributes, such as file name, file size, file last-modified time, current time, system environment variables, and system properties.

File Name
Example: "C:\Work\2007\Jan\Report.txt", with "C:\Work" as current directory

FN Filename ("Report.txt")
FN.ext File extension ("txt")
FN.name Base filename without extension ("Report")
FN.path Relative pathname ("2007\Jan\Report.txt")
FN.parent Parent directory ("Jan")
FN.parentpath Relative pathname of parent directory ("2007\Jan")

File Size (all values are cast as integers)

FS File size in bytes
FS.kB File size in kilobytes (2^10 bytes)
FS.MB File size in megabytes (2^20 bytes)
FS.GB File size in gigabytes (2^30 bytes)
FS.TB File size in terabytes (2^40 bytes)

File Last-Modified Time

FT Number of milliseconds since the epoch (January 1, 1970 00:00:00.000 GMT, Gregorian)
FT.date Date in the form yyyyMMdd
FT.time Time in the form HHmmss
FT.ap am/pm in lower case
FT.AP AM/PM in upper case

Date and time pattern letters from Java are also supported. Repeat letters to change the representation, e.g. FT.MMMM, FT.MMM, FT.MM could represent "April", "Apr", "4", respectively.

G Era designator
y Year
M Month in year
w Week in year
W Week in month
D Day in year
d Day in month
F Day of week in month
E Day in week
a AM/PM marker
H Hour in day (0-23)
k Hour in day (1-24)
K Hour in AM/PM (0-11)
h Hour in AM/PM (1-12)
m Minute in hour
s Second in minute
S Millisecond
z Time zone (general time zone)
Z Time zone (RFC 822 time zone)

Current Time

Macros for the current time are obtained by using CT instead of FT in the above macros for file last-modified time.

System Environment Variables

ENV.var System environment variable named "var"

System Properties
(see Java API for the full list)

SYS.os.name Operating system name
SYS.os.arch Operating system architecture
SYS.os.version Operating system version
SYS.file.separator File separator (e.g. "/" or "\")
SYS.path.separator Path separator (e.g. ":" or ";")
SYS.line.separator Line separator
SYS.user.name User's account name
SYS.user.home User's home directory
SYS.user.dir User's current working directory

Miscellaneous

RW.cd Full pathname of the current directory (e.g. "C:\Work")
RW.N Number of local matched files (i.e. in the file's subdirectory)
RW.NN Number of global matched files (i.e. in all subdirectories)
RW.random Generates a string of 10 random digits
Macro & Register Modifiers

To use the following modifiers, append a period followed by the modifier name to a macro or register name. Modifiers can also be chained, e.g. myreg.title.trim, FN.name.pascal.trim.

Example: "hello WORLD"

len Length of the string (11)
upper Convert to upper case ("HELLO WORLD")
lower Convert to lower case ("hello world")
capitalize Capitalize only the first character ("Hello world")
title Convert to title case ("Hello World")
camel Convert to camelCase ("helloWorld")
pascal Convert to PascalCase ("HelloWorld")
swapcase Swap the case ("HELLO world")
abbrev Abbreviate to initials ("h W")
reverse Reverse the string ("DLROW olleh")
trim Trim away whitespace on the left and right
ltrim Trim away whitespace on the left
rtrim Trim away whitespace on the right
delspace Delete whitespace in the string ("helloWORLD")
delextraspace Delete extra whitespace by replacing contiguous whitespace with a single space ("How   are  YOU" → "How are YOU")
delpunctuation Delete punctuation marks in the string
spaceout Space out words by inserting a space between connected words ("HowAreYou" → "How Are You")

Shortcut macros are defined for single-letter register names for convenience. Suppose we have the register "a"; then the following macros are automatically defined if there are no name clashes:

AA Convert to upper case (.upper)
aa Convert to lower case (.lower)
Aa Convert to title case (.title)
aA Swap the case (.swapcase)

Examples

  1. Convert the filename, less extension, to title case,
    e.g. "foo bar.txt" → "Foo Bar.txt":
    java -jar RenameWand.jar "<a>.<b>" "<Aa>.<b>"

  2. Convert disc and track numbers to a single number, and swap artist name with song name,
    e.g. "Disc 2 Track 5_SONG_ARTIST.mp3" → "015-Artist-Song.mp3":
    java -jar RenameWand.jar "Disc <@disc> Track <@track>_<song>_<artist>.mp3"
    "<3|10*(disc-1)+track>-<artist.title>-<song.title>.mp3"

  3. Insert the file date, and enumerate files by their last-modified time,
    e.g. "SCAN004001.jpg" → "doc20050512 (Page 01 of 42).jpg":
    java -jar RenameWand.jar "SCAN*.jpg"
    "doc<FT.date> (Page <2|#FT> of <2|RW.N>).jpg"

  4. Rename files into directories based on their names,
    e.g. "Daily Report May-28-2007.doc" → "2007/May/Daily Report 28.doc":
    java -jar RenameWand.jar "Daily Report <month>-<day>-<year>.doc"
    "<year>/<month>/Daily Report <day>.doc"

Feedback?

Comments, suggestions, and bug reports are welcomed! Please send any feedback you have about RenameWand to email address, or visit the RenameWand homepage at http://renamewand.sourceforge.net/ to post a message, bug report, or download the latest version of RenameWand.

SourceForge.net Logo