Format Operator

Format Operator

Contents

• Description
• Usage
• Examples

Description

The format operator enables control over how filenames are renamed. By default without --format being invoked, an implicit format of "$d"is used. $d is a required format specifier which signifies where the numerical pattern should be placed in the output filenames. This leads to plain integer filenames such as 2.png, 05.mkv, etc. The format operator can customize the output filenames by controlling what goes around the $d format specifier. Optionally, strings can be captured from filenames through a regex statement parameter and used in the output filename.

Usage

-f foo
--format foo
-f foo bar
--format foo bar

• where foo is a string of the custom output format which must contain the format specifier $d (indicates where to substitute the numbering pattern). If bar is provided, additional format specifiers of $1, $2, etc should be included (see below for more information).
• where bar is an optional string regex statement which should contain regex capture groups. Each captured group is substituted back into the format foo, replacing format specifiers $1, $2, etc in order of which they are captured. For example bar of "(Apple) Pear (Banana)" would encourage usage of format specifier $1 (Apple) and $2 (Banana) in the foo argument in order for them to be substituted properly. See Examples for more detailed use-cases.

Examples

The following files are used for the examples below

1 - The Beatles - A Hard Day's Night.mp3

5 - John Lennon - Woman.mp3

7 - The Beatles - Can't Buy Me Love.mp3

Example 1

Static format, only one format parameter is required. Format specifier $d must be included (escape character may be required based on your terminal).

renamer . --format "My Music #\$d"

My Music #1.mp3
My Music #5.mp3
My Music #7.mp3

Example 2

Dynamic format, both parameters required. -f may be used instead of --format. Only one capture group, so format specifier $1 should be included. Regex statement captures characters before the file extension and after the last - character. Format specifier $1 substitutes that content into the output file name.

renamer . -f "\$d - \$1" ".*\-\s(.+)\..*"

1 - A Hard Day's Night.mp3
5 - Woman.mp3
7 - Can't Buy Me Love.mp3

Example 3

Multiple capture groups can be used, provided multitple numerical format specifiers are included in the first parameter. Ordering of numerical format specifiers is irrelevant.

renamer . -f "\$2 - \$1 #\$d" "[\d\-\s]+(.+)[\s\-]{3,}(.+)\..*"

A Hard Day's Night - The Beatles #1.mp3
Woman - John Lennon #5.mp3
Can't Buy Me Love - The Beatles #7.mp3