rtRenameFiles Version 1.00 Documentation
Overview
Quick Start
Tips & Tricks
Argument Reference
Overview
rtRenameFiles is a Windows command line utility that provides a fast and intuitive way to rename files in bulk.
Quick Start
The first step to renaming files is to determine which files will be renamed. To do this, we use the -file-mask argument.
Example:
rtrenamefiles -file-mask *.jpg
This will rename all files ending in ".jpg".
The new name that will be assigned to each file is determined by a "File Name Template".
For example, this file name template:
{FileTitle}_{YearCreated4}-{MonthCreated2}-{DayCreated2}.{FileExt}
might result in this new file name:
Payroll_2010-02-28.qbk
For more information, see the documentation for the -file-name-template argument.
Common Usage Examples
Rename all jpg files to their creation date
rtrenamefiles -file-mask *.jpg -file-name-template {YearCreated4}-{MonthCreated2}-{DayCreated2}.{FileExt}
Results
123.jpg -> 2010-02-28.jpg
Add a leading underscore to all file names
rtrenamefiles -file-mask *.* -file-name-template _{FileName}
Results
archive.doc -> _archive.doc
Number files sequentially based on file creation date
First, rename files according to their file creation date/time:
rtrenamefiles -file-mask *.* -file-name-template {YearCreated4}-{MonthCreated2}-{DayCreated2}_{HourCreatedMil2}-{MinuteCreated2}-{SecondCreated2}.{FileExt}
Next, rename files using the serial number token.
rtrenamefiles -file-mask *.* -file-name-template {SerialNum}.{FileExt}
Tips & Tricks
This section contains various information to help you use this program effectively.
Command Line Arguments with Spaces
If you need to supply a command line argument that contains spaces, you can surround the argument with double-quotes.
Example:
rtrenamefiles -file-name-template "{FileTitle} {YearCreated}.{FileExt}"
In this example, the quotes are necessary because the argument contains spaces. If the quotes were not supplied, then {YearCreated}.{FileExt} would be considered a new argument, which would generate an error message.
Argument Reference
-file-mask <string>
This is a standard DOS-type file mask (a.k.a. "File Skeleton") that determines which files will be renamed. This is the only required argument.
In a file mask, there are two wildcard characters:
- * - Represents any number of characters (zero or more)
- ? - Represents any single character
Examples:
- *.jpg - Matches all files ending in ".jpg".
- 0100_*.* - Matches all files beginning with "0100_" and having any file extension.
- IMG_*.jpg - Matches all files beginning with "IMG_" and having the file extention ".jpg".
-file-name-template <string>
Overview
This argument determines the new name assigned to files (i.e. - what files are renamed to).
<string> is a template consisting of literal characters and tokens. Tokens are surrounded by curly braces.
Tokens are expanded into information derived from the source file. For example, the {YearCreated4} token expands to "2010" if the current file was created in 2010.
Example: If <string> is:
MyFile_{YearCreated4}-{MonthCreated2}-{DayCreated2}.{FileExt}
Assuming the file creation date is February 28, 2010, the file will be renamed to:
MyFile_2010-02-28.jpg
Default Value
If not specified, <string> defaults to:
{YearModified4}-{MonthModified2}-{DayModified2}_
{HourModifiedMil2}-{MinuteModified2}-{SecondModified2}.{FileExt}
Token Reference
{DayCreated} {DayCreated1} {DayCreated2}
{DayCreatedAbbr3} {DayCreatedAbbr3UC} {DayCreatedAbbr3LC} {DayCreatedAbbr3PC}
{DayCreatedName} {DayCreatedNameUC} {DayCreatedNameLC} {DayCreatedNamePC}
{DayModified} {DayModified1} {DayModified2}
{DayModifiedAbbr3} {DayModifiedAbbr3UC} {DayModifiedAbbr3LC} {DayModifiedAbbr3PC}
{DayModifiedName} {DayModifiedNameUC} {DayModifiedNameLC} {DayModifiedNamePC}
{DayAccessed} {DayAccessed1} {DayAccessed2}
{DayAccessedAbbr3} {DayAccessedAbbr3UC} {DayAccessedAbbr3LC} {DayAccessedAbbr3PC}
{DayAccessedName} {DayAccessedNameUC} {DayAccessedNameLC} {DayAccessedNamePC}
These tokens return the day the file was created, last modified (written), or last accessed (read).
Tokens ending in 1 (like {DayCreated1}) return the day of the month as a number. If the number contains a single digit, then a single digit is returned. If the number contains 2 digits, then two digits are returned.
Example: The 3rd day of the month is represented by 3
Example: The 10th day of the month is represented by 10
Tokens ending in 2 (like {DayCreated2}) return the day of the month as a two-digit number. If the number contains a single digit, then the value is padded with a single zero on the left.
Example: The 3rd day of the month is represented by 03
Example: The 10th day of the month is represented by 10
Tokens containing Abbr3 (like {DayCreatedAbbr3}) return the 3-character abbreviation of the day.
Example: Monday is represented by Mon
Example: Friday is represented by Fri
Tokens containing Name (like {DayCreatedName}) return the full name of the day.
Example: Monday is represented by Monday
Example: Friday is represented by Friday
Tokens ending in UC (like {DayCreatedNameUC}) return their value in upper-case.
Example: {DayCreatedNameUC} may return MONDAY
Tokens ending in LC (like {DayCreatedNameLC}) return their value in lower-case.
Example: {DayCreatedNameLC} may return monday
Tokens ending in PC (like {DayCreatedNamePC}) return their value in proper-case.
Example: {DayCreatedNamePC} may return Monday
{FileDir} {FileDirUC} {FileDirLC}
Returns the path of the file's containing directory.
{FileDir} returns the value in its original case.
{FileDirUC} returns the value in upper case.
{FileDirLC} returns the value in lower case.
Examples: Using this file: C:\Documents\MyFile.doc
{FileDir} returns C:\Documents
{FileDirUC} returns C:\DOCUMENTS
{FileDirLC} returns c:\documents
Note: A trailing slash is never included in the returned value.
{FileExt} {FileExtUC} {FileExtLC} {FileExtPC}
Returns the extension of the file. This is the file name without the file title.
{FileExt} returns the value in its original case.
{FileExtUC} returns the value in upper case.
{FileExtLC} returns the value in lower case.
{FileExtPC} returns the value in proper case (the first character is capitalized).
Examples: Using this file: C:\Documents\MyFile.dOc
{FileExt} returns dOc
{FileExtUC} returns DOC
{FileExtLC} returns doc
{FileExtPC} returns Doc
{FileName} {FileNameUC} {FileNameLC} {FileNamePC}
Returns the name of the file. This includes the file title and extension.
{FileName} returns the value in its original case.
{FileNameUC} returns the value in upper case.
{FileNameLC} returns the value in lower case.
{FileNamePC} returns the value in proper case (the first character is capitalized).
Examples: Using this file: C:\Documents\MyFile.dOc
{FileName} returns MyFile.dOc
{FileNameUC} returns MYFILE.DOC
{FileNameLC} returns myfile.doc
{FileNamePC} returns Myfile.Doc
{FileSize}
Returns the size of the file, in bytes.
Example: This file: C:\Documents\MyFile.doc may return 12585
{FileTitle} {FileTitleUC} {FileTitleLC} {FileTitlePC}
Returns the title of the file. This is the file name without the file extension.
{FileTitle} returns the value in its original case.
{FileTitleUC} returns the value in upper case.
{FileTitleLC} returns the value in lower case.
{FileTitlePC} returns the value in proper case (the first character is capitalized).
Examples: Using this file: C:\Documents\MyFile.dOc
{FileName} returns MyFile
{FileNameUC} returns MYFILE
{FileNameLC} returns myfile
{FileNamePC} returns Myfile
{HourCreated} {HourCreated1} {HourCreated2}
{HourCreatedMil} {HourCreatedMil1} {HourCreatedMil2}
{HourModified} {HourModified1} {HourModified2}
{HourModifiedMil} {HourModifiedMil1} {HourModifiedMil2}
{HourAccessed} {HourAccessed1} {HourAccessed2}
{HourAccessedMil} {HourAccessedMil1} {HourAccessedMil2}
These tokens return the hour the file was created, last modified (written), or last accessed (read).
Tokens ending in 1 (like {HourCreated1}) return the hour as a number. If the number contains a single digit, then a single digit is returned. If the number contains 2 digits, then two digits are returned.
Example: 3 is represented by 3
Example: 10 is represented by 10
Tokens ending in 2 (like {HourCreated2}) return the hour as a two-digit number. If the number contains a single digit, then the value is padded with a single zero on the left.
Example: 3 is represented by 03
Example: 10 is represented by 10
Tokens containing Mil (like {HourCreatedMil1}) return the hour in military (24-hour) time.
Examples:
Using {HourCreatedMil} and {HourCreatedMil1}, 3am is represented by 3
Using {HourCreatedMil} and {HourCreatedMil1}, 3pm is represented by 15
Using {HourCreatedMil2}, 3am is represented by 03
Using {HourCreatedMil2}, 3pm is represented by 15
{MeridianCreated} {MeridianCreatedUC} {MeridianCreatedLC}
{MeridianCreated1} {MeridianCreated1UC} {MeridianCreated1LC}
{MeridianCreated2} {MeridianCreated2UC} {MeridianCreated2LC}
{MeridianModified} {MeridianModifiedUC} {MeridianModifiedLC}
{MeridianModified1} {MeridianModified1UC} {MeridianModified1LC}
{MeridianModified2} {MeridianModified2UC} {MeridianModified2LC}
{MeridianAccessed} {MeridianAccessedUC} {MeridianAccessedLC}
{MeridianAccessed1} {MeridianAccessed1UC} {MeridianAccessed1LC}
{MeridianAccessed2} {MeridianAccessed2UC} {MeridianAccessed2LC}
These tokens return the meridian ("am" or "pm") on which the file was created, last modified (written), or last accessed (read).
Tokens ending in 1 (like {MeridianCreated1}) return the meridian as 1 character.
Example: AM is represented by A
Example: PM is represented by P
Tokens ending in 2 (like {MeridianCreated2}) and tokens ending in a non-numeric value (like {MeridianCreated}) return the meridian as 2 characters.
Example: AM is represented by AM
Example: PM is represented by PM
Tokens ending in UC (like {MeridianCreatedUC}) return their value in upper-case.
Example: {MeridianCreatedUC} may return AM
Tokens ending in LC (like {MeridianCreatedLC}) return their value in lower-case.
Example: {MeridianCreatedLC} may return am
{MinuteCreated} {MinuteCreated1} {MinuteCreated2}
{MinuteModified} {MinuteModified1} {MinuteModified2}
{MinuteAccessed} {MinuteAccessed1} {MinuteAccessed2}
These tokens return the minute the file was created, last modified (written), or last accessed (read).
Tokens ending in 1 (like {MinuteCreated1}) and tokens ending in a non-numeric value (like {MinuteCreated}) return the minute as 1 or 2 digits, as required by the value being displayed.
Example: 3 is represented by 3
Example: 10 is represented by 10
Tokens ending in 2 (like {MinuteCreated2}) return the minute as a two-digit number. If the number contains a single digit, then the number is padded with a single zero on the left.
Example: 3 is represented by 03
Example: 10 is represented by 10
{MonthCreated} {MonthCreated1} {MonthCreated2}
{MonthCreatedAbbr3} {MonthCreatedAbbr3UC} {MonthCreatedAbbr3LC} {MonthCreatedAbbr3PC}
{MonthCreatedName} {MonthCreatedNameUC} {MonthCreatedNameLC} {MonthCreatedNamePC}
{MonthModified} {MonthModified1} {MonthModified2}
{MonthModifiedAbbr3} {MonthModifiedAbbr3UC} {MonthModifiedAbbr3LC} {MonthModifiedAbbr3PC}
{MonthModifiedName} {MonthModifiedNameUC} {MonthModifiedNameLC} {MonthModifiedNamePC}
{MonthAccessed} {MonthAccessed1} {MonthAccessed2}
{MonthAccessedAbbr3} {MonthAccessedAbbr3UC} {MonthAccessedAbbr3LC} {MonthAccessedAbbr3PC}
{MonthAccessedName} {MonthAccessedNameUC} {MonthAccessedNameLC} {MonthAccessedNamePC}
These tokens return the month the file was created, last modified (written), or last accessed (read).
Tokens ending in 1 (like {MonthCreated1}) return the month of the year as a number. If the number contains a single digit, then a single digit is returned. If the number contains 2 digits, then two digits are returned.
Example: March is represented by 3
Example: October is represented by 10
Tokens ending in 2 (like {MonthCreated2}) return the month of the year as a two-digit number. If the number contains a single digit, then the value is padded with a single zero on the left.
Example: March is represented by 03
Example: October is represented by 10
Tokens containing Abbr3 (like {MonthCreatedAbbr3}) return the 3-character abbreviation of the month.
Example: March is represented by Mar
Example: October is represented by Oct
Tokens containing Name (like {MonthCreatedName}) return the full name of the month.
Example: March is represented by March
Example: October is represented by October
Tokens ending in UC (like {MonthCreatedNameUC}) return their value in upper-case.
Example: {MonthCreatedNameUC} may return MARCH
Tokens ending in LC (like {MonthCreatedNameLC}) return their value in lower-case.
Example: {MonthCreatedNameLC} may return march
Tokens ending in PC (like {MonthCreatedNamePC}) return their value in proper-case.
Example: {MonthCreatedNamePC} may return March
{SecondCreated} {SecondCreated1} {SecondCreated2}
{SecondModified} {SecondModified1} {SecondModified2}
{SecondAccessed} {SecondAccessed1} {SecondAccessed2}
These tokens return the second the file was created, last modified (written), or last accessed (read).
Tokens ending in 1 (like {SecondCreated1}) and tokens ending in a non-numeric value (like {SecondCreated}) return the second as 1 or 2 digits, as required by the value being displayed.
Example: 3 is represented by 3
Example: 10 is represented by 10
Tokens ending in 2 (like {SecondCreated2}) return the second as a two-digit number. If the number contains a single digit, then the number is padded with a single zero on the left.
Example: 3 is represented by 03
Example: 10 is represented by 10
{YearCreated} {YearCreated4} {YearCreated2}
{YearModified} {YearModified4} {YearModified2}
{YearAccessed} {YearAccessed4} {YearAccessed2}
Returns the year the file was created, last modified (written), or last accessed (read).
{YearCreated} and {YearCreated4} returns the value in 4 characters.
Example: 2010
{YearCreated2} returns the value in 2 characters.
Example: The year 2010 is represented with: 10
-no-rename
When this argument is present, no files will be renamed. The program will still display the name of each file being renamed along with each resulting new file name.
This is useful for testing the -file-mask and -file-name-template arguments before actually renaming files.
-serial-num-format <string>
When the {SerialNum} token is used, this argument determines how the serial number will be formatted.
This string we pass to this argument is called the mask.
<string> may contain up to 18 digit-formatting digits on either side of a decimal point. The mask may not contain literal characters unless each character is preceded with a backslash (\) escape character, or the literal characters are enclosed in quotes.
Digit placeholders in a mask do not have to be contiguous. This allows you to format a single number into multiple displayed parts.
Example: 00\:00\:00 may return 12:34:56
The following table explains the characters you can use to create masks.
Empty String
No formatting takes place. No leading space is applied to positive numbers.
0 (zero)
This is a digit placeholder. The program will insert a digit or 0 in that position.
If {SerialNum} contains a digit in the position where the 0 appears in this mask, that digit is returned. Otherwise, zero ("0") is returned.
If {SerialNum} has fewer digits than there are zeros (on either side of the decimal point), leading or trailing zeros are added.
If {SerialNum} has more digits to the right of the decimal point than there are zeros to the right of the decimal point in the format expression, the number is rounded to as many decimal places as there are zeros in the mask.
If {SerialNum} has more digits to the left of the decimal point than there are zeros to the left of the decimal point in the mask, the extra digits are displayed without truncation.
If {SerialNum} is negative, the negation symbol will be treated as a decimal digit. Therefore, care should be exercised when displaying negative values with this placeholder style.
Example: Padding with leading zeros:
If {SerialNum} = 123 and <string> = 000000, then the result is 000123.
# (number sign)
This is a digit placeholder.
If {SerialNum} contains a digit for this position, the program replaces this placeholder with a digit, nothing, or a user-specified character. Unlike the 0 digit placeholder, if the numeric value has fewer digits than there are # characters on either side of the decimal placeholder, The program will either:
1. Omit this character position from the final formatted string, or
2.
Substitute a user-specified replacement character if one has been defined (see the asterisk (*) character for more information).
To specify leading spaces, prefix the mask with "* " (asterisk followed by a space).
Examples:
No leading spaces and trailing spaces: ####.### returns 0.75
Up to 3 Leading spaces before decimal: * ##.### returns 0.75
Using asterisks for padding characters: *=##.### returns ===0.75=
Return a string that is larger than the number of characters in the mask:
#.# returns 999999.9
. (period)
This is a decimal placeholder. This determines the position of the decimal point.
If any numeric field is specified to the left of the decimal point, at least one digit will always result, even if only a zero. The zero is not considered to be a "leading" zero if it is the only digit to the left of the decimal.
Placing more than one period character in <string> will produce undefined results.
% (percent)
This is a percentage placeholder. The program multiplies {SerialNum} by 100, and adds a trailing percent symbol.
Example: 0.0% returns 20.0%
, (comma)
This is a thousand separator. This is used to separate thousands from hundreds within a number that has four or more digits to the left of the decimal point.
In order to be recognized as a format character, the comma must be placed immediately after a digit placeholder character (also see restrictions below).
Examples:
#, returns 1,234,567
#,.00 returns 12,345.00
#.00, returns 12,345.00
$00,000.00 returns $01,212.46
0, returns 1,234,567
*x (asterisk)
This is a digit placeholder and fill-character. This instructs {SerialNum} to insert a digit or character "x" in that position. If there is a digit in {SerialNum} at the position where the * appears in <string>, that digit is used; otherwise, the "x" character is used (where "x" represents your own choice of character).
Examples:
The *x specifier acts as two digit (#) fields:
$**####,.00 returns $**9,999.90
$*=###0,.00# returns $=====0.00=
$* ####0,.00 returns $ 0.00
E- e- E+ e+
This is scientific format. The program will use scientific notation in the formatted output.
Use E- or e- to place a minus sign in front of negative exponents.
Use E+ or e+ to place a minus sign in front of negative exponents and a plus sign in front of non-negative exponents.
In order to be recognized as a format sequence, the E-, e-, E+, or e+ must be placed between two digit placeholder characters.
Examples:
0.0E-## returns 1.0E2
0.0E-## returns -1.0E2
0.0E+## returns 1.0E+2
0.0E+## returns -1.0E+2
0.0e+## returns 1.0e-1
" (double-quote)
This is a quoted string. The program treats all characters between opening and closing double-quotes as-is, without interpreting them as digit placeholders or format characters. Also see backslash.
Note: When a double-quote is the first character in <string>, the operating system interprets this as the beginning of a double-quote-enclosed argument (or argument attribute) being passed to the program. Therefore, this double-quote is stripped before being seen by the program. So, be sure not to begin <string> with a double-quote.
Examples:
0000"_Widgets" returns 0001_Widgets
Note: The underscore is necessary. If it was omitted, then everything after 0000 would be seen as the next program argument.
_"Total:"0000 returns 0001_Widgets
Note: The underscore is necessary. If it was omitted, the program would only see Total: as the value being passed to <string>.
\x (backslash)
This is an escaped character prefix. The program treats the character "x" immediately following the backslash (\) as a literal character rather than a digit placeholder or a formatting character.
Many characters in a mask have a special meaning and cannot be used as literal characters unless they are preceded by a backslash. The backslash itself is not returned.
To return a backslash, use two backslashes (\\).
To return a literal double-quote, use \".
To simplify the mask string for common numeric formats, FORMAT$ permits the dollar symbol, the left and right parenthesis symbols, the plus and minus symbols, and the space character to pass through from the mask string the formatted output string, without requiring an escape (\) prefix character.
Examples:
00\N00 returns 00N01
Note: The backslash makes the following character ("N") act like a double-quoted literal.
$0000 returns $0001
Note: Certain characters, including the dollar-sign, do not require a leading backslash.
0000% returns 0100%
Note: Certain characters, including the percent-sign, do not require a leading backslash. Also note that the percent sign automatically causes the value to be multiplied by 100.
-serial-num-start <number>
When the {SerialNum} token is used, this argument determines what the starting number is.
<number> can be negative, positive, or zero. It must be convertable to a long integer or an error message will be displayed and no files will be renamed.
<number> defaults to 1 if not specified.
Example:
rtrenamefiles -file-mask *.jpg -file-name-template {SerialNum}.{FileExt} -serial-num-start 17
Result:
qwert.jpg -> 17.jpg
asdfl.jpg -> 18.jpg
kjlkf.jpg -> 19.jpg
-serial-num-step <number>
When the {SerialNum} token is used, this argument determines what the step value is. This is the number that is added to the most recently used serial number for each subsequent file name.
<number> must be convertable to a long integer or an error message will be displayed and no files will be renamed.
<number> defaults to 1 if not specified.
Example:
rtrenamefiles -file-mask *.jpg -file-name-template {SerialNum}.{FileExt} -serial-num-step 2
Result:
qwert.jpg -> 1.jpg
asdfl.jpg -> 3.jpg
kjlkf.jpg -> 5.jpg
-sleep-time <number>
This is the number of milliseconds that the program sleeps between file rename operations. This makes it possible to rename a large number of files without using up too much CPU power.
<number> must be convertable to a long integer and must be zero or positive or an error message will be displayed and no files will be renamed.
<number> defaults to 0 if not specified.
Example:
rtrenamefiles -file-mask *.jpg -sleep-time 500
Results:
The program releases control of the CPU for 500 milliseconds (½ second) after each subsequent file is renamed.
-usage
This displays simple usage information.
If this flag is used, all arguments are ignored and usage information is displayed.
-verbosity <number>
This determines how verbose (talkative) the program is.
<number> must be convertable to a long integer and must be a valid value or an error message will be displayed and no files will be renamed.
<number> defaults to 2 if not specified.
Following are the value values:
"0" Nothing is displayed at all.
"1" Displays only the list of files being renamed and relevant error messages.
"2" Displays the current settings followed by the list of files being renamed followed by statistic and a final success or error message. Relevant error message are also displayed.
Note: When <number> is 0, pressing Ctrl-C ends the program immediately. No confirmation message is displayed.
-version
This causes rtRenameFiles to display the current version.
If this flag is specified, all arguments are ignored (except -usage) and the current version is displayed instead.
If -usage and -version is used at the same time, -version is ignored and -usage takes precedence.
Example:
rtrenamefiles -version
Result:
1.0
|