rename 1.2

regex

Regular expression that matches source files which are to be renamed. Examples:

"(\w+).caf"
"IMG(\d\d\d\d\).[Jj][Pp][Ee]?[Gg]"
"([0-9]{2})-([0-9]{2})-([12][0-9]{3}).log"

The regular expression is global by default (e.g. writing "[0-9]" means "^[0-9]$"). This is to avoid accidental partial catches. If you want to match all files that start or end with a specific expression, add .* to the expression, e.g. ".*\.mp3" will match all files that end with .mp3. While that may seem a bit redundant, it’s on par with “explicit is better than inplicit” (see The Zen of Python). See also: -I.

Note: the regex is case-sensitive, also on case-preserving filesystems. If you wish to change that, use the -I option.

target

Name of the target file with references to regular expression groups caught in the source matches. References to groups are formed by a backslash character followed by he group number. Groups are indexed from 1. The group number can be contained within parentheses to disambiguate a reference followed by digits. Examples:

"\1.aiff"
"\(1)1337.zip"
"\3-\1-\2.log"

Automatic numbering can be introduced using a special \(index) reference. For example:

rename "IMG.*\.JPG" "Judy's Birthday \(index).jpg"

By default indexing starts with 1, increments with 1 and pads numbers with enough leading zeroes so that each filename uses the same amount of digits. This can be changed with the --index-first, --index-step, --index-digits and --index-pad-with options.

substring_from, substring_to

When using the “simple” mode (-s), these arguments provide the traditional search/replace pattern:

• substring_from is a simple (raw) substring that should be found within the filename

• substring_to is the replacement string

Both of these strings are raw, e.g. they don’t allow for any wildcards, regular expressions and whatnot. This is more-less compatible with behaviour of the existing rename tool from the util-linux-ng package. One obvious difference is that the file mask doesn’t use wildcards but regular expressions.

Example (translating underscores to spaces):

rename -s "_"  " "  ".*\.txt"

Note: substring_from is case-sensitive, also on case-preserving filesystems. If you wish to change that, use the -I option. substring_to is always case-sensitive.

-I, or –case-insensitive

When used, regexes work in a case-insensitive manner, e.g. "lib" will behave like "[Ll][Ii][Bb]". Group references still hold the original case.

-l, or –lower

When used, renamed filenames are transformed to lower-case. This does not affect the source regex used (i.e. it still matches in a case-sensitive manner, unless -I is used). See also: -U.

-q, or –quiet

When used, no error output is given. The status of invocation should be determined via the return code.

-s, or –simple

Invokes the “simple” mode. See: substring_from, substring_to.

-t, or –test

When used, the script will only fake renaming and verbosely state what it would do. Use this if you’re unsure of the effects your expression may cause.

-U, or –upper

When used, renamed filenames are transformed to upper-case. This does not affect the source regex used (i.e. it still matches in a case-sensitive manner, unless -I is used). See also: -l.

-v “except_regex”, or –except “except_regex”

When used, any filename matched by the original source regex will be also matched against the except_regex. In case there is a match, the filename is skipped. In other words, filenames that match except_regex will not be renamed.

The regular expression is local (e.g. writing "[0-3]" means “number 0-3 anywhere in the filename). This is to make the tool err on the side of caution by protecting from renaming too many files by accident when the user forgets to add dot-asterisk to -v. If you want to only match whole filenames, use the canonical global form (e.g. "^filename$"). See also: -I.

–index-first

When using the special \(index) reference, this option specifies what number will the first index be. Default: --index-first=1.

–index-step

When using the special \(index) reference, this option specifies what number will be added with each step to the first value. The specified number can be negative. Default: --index-step=1.

–index-digits

When using the special \(index) reference, this option specifies how many digits will be used in each reference. If a number has fewer digits, they will be prefixed by leading zeroes (or another character, see: --index-pad-with). A special value of auto can be used to automatically pad enough digits so that each filename has the same amount of them used. This is useful for ensuring your files will be sorted correctly even by dumb algorithms. Default: --index-digits=auto.

–index-pad-with

When using the special \(index) reference, this option specifies what character will be used for padding. Default: --index-pad-with=0.

–selftest

Runs internal unit tests of all functionality. Does actual renaming of a generated set of files in the specified directory. If no directory is passed, uses the temporary directory. Each test generates its own set of files.