FileRename

🚨	FileRename is still under development and in pre-release status.

Table of Contents

• About the Project
• Getting Started
  • Prerequisites
  • Installation
• How To Use
  • Examples
  • Available Templates/Transformation Rules
    • Regex Transformation Rule - <<R|{regular_expression}>>
    • Timestamp Transformation Rule - <<TS|{timestamp_pattern>>
    • File Creation Date Transformation Rule - <<CD|{timestamp_pattern}}>>
    • Enumeration Transformation Rule - <<E|{format_string_syntax}>>
• How to Extend the Ruleset

About the Project

Aim of this project is to provide a mapping solution between the various image naming patterns of mobile device and camera manufacturers. Since most manufacturers do not support defining a custom file naming pattern, having several different devices can lead to highly different file names for images that were e.g. taken in close temporal proximity.

The aims of this application are twofold:

• Firstly, the application should provide a command line based solution for this issue, especially with regards to different timestamp formats. This solution is intended to be run automatically, e.g. after importing images from a device or as cron job.

• Secondly, the application should allow extending and manipulating the ruleset for such transformations easily.

Getting Started

Prerequisites

This project requires

• Java Version 17

• Maven

Installation

To generate an executable jar using maven simply

1. Clone the repository

   git clone git@github.com:kocmana/filerename.git

2. Compile and package the application

   mvn clean package

3. Navigate to the /target folder and execute the filerename-with-dependencies.jar with one or several of the arguments described in the next section, eg:

   java -jar filerename-with-dependencies.jar -i "image<<TS|yyyyMMdd_HHmmss>>.jpg" -o "<<TS|yyyyMMdd_HHmmss>>" -d

How To Use

Several command line arguments can be used to customize the behavior of the application:

Usage: filerename [-hV] ([-p=<path>] [-r] -i=<inputTemplate>
                    -o=<outputTemplate> [-d] [-cp])...
      -cp, --copy     Define the operation to be performed. If set, files will
                        be copied instead of renamed.
  -d, --dryRun        Setting this parameter will only display how the file
                        names will be changed without performing any changes
  -h, --help          Show this help message and exit.
  -i, --input=<inputTemplate>
                      The pattern of the input file names
  -o, --output=<outputTemplate>
                      The pattern of the output file names
  -p, --path=<path>   The directory for the operation
  -r, --recursive     Include sub directories.
  -V, --version       Print version information and exit.

Examples

Single Task

java -jar filerename-with-dependencies.jar -i "image_<<TS|yyyyMMdd_HHmmssSSS>>.jpg" -o "<<TS|yyyy-MM-dd_HH-mm-ss>>.jpg" -d -cp

• -i/-o: Input and Output filename patterns

• -d: Dry run: This task will let you check if the result is what you expect it to be without performing any actual changes to the files specified

• -cp: This task will create copies of the specified files using their output filenames rather than renaming them.

Multiple Tasks

java -jar filerename-with-dependencies.jar -i "image_<<TS|yyyy-MM-dd>>.jpg" -o "<<TS|dd-MM-yyyy>>.jpg" -p "./user1/DCIM" -r -i "<<TS|yyyy-MM-dd_HHmmss>>.jpg" -o "<<TS|dd-MM-yyyy>>.jpg" -p "./user2/DCIM"

• -i/-o: Input and Output filename patterns for both tasks

• -p: Specify a path for the task, relative to the directory the jar is in

• -r: Include subdirectories

Available Templates/Transformation Rules

Regex Transformation Rule - <<R|{regular_expression}>>

This rule allows to define a regular expression against which the filenames are matched.

This can be used in two ways:

• Either only as part as the input pattern to match several files. Subsequently, other rules can be defined in the output pattern to modify these files:

  InputPattern	OutputPattern	Filename	Resulting Filename
  IMAGE_<<R|[0-9]{3}>>.jpg	picture-<<CD|yyyy-MM-dd>>.JPG	IMAGE001.jpg	picture-2020-10-21.JPG

• As part of both input and output pattern: This allows to shift a defined char sequence in many files following the same pattern to a different position if the output pattern.

  InputPattern	OutputPattern	Filename	Resulting Filename
  IMAGE_<<R|[0-9]{3}>>.jpg	<<R>>-picture.JPG	IMAGE_001.jpg	001-picture.JPG

Timestamp Transformation Rule - <<TS|{timestamp_pattern>>

This rule allows defining source and target timestamp patterns based on the Java API patterns for formatting and parsing date and time information.

Example:

InputPattern	OutputPattern	Filename	Resulting Filename
img<<TS|ddMMyyyyHHmmssSSS>>.jpg	image<<TS|yyyy-MM-dd_HHmmss>>.jpg	img20122021125401451.jpg	image2021-12-20_125401.jpg

File Creation Date Transformation Rule - <<CD|{timestamp_pattern}}>>

If no timestamp is available as part of the filename, the file creation date can be used instead.

If no timestamp_pattern is provided, ISO_DATE_TIME will be used per default.

👉	The creation date of a filename is not necessarily the date the file (e.g. picture) was originally created. It commonly indicates when a file was created on any given system instead.

Example:

InputPattern	OutputPattern	Filename	Resulting Filename
file<<R|[0-9]{5}>>.png	image_<<CD|yyyy-MM-dd_HHmmss>>.png	file00019.png	image_2021-12-20_125401.png

Enumeration Transformation Rule - <<E|{format_string_syntax}>>

This rule allows to add increasing numbers to the filename. Additional formatting arguments can be provided using the Java Format String syntax . If no formatting argument is provided (<<E>>) only the number itself will be used (synonymous with <<E|%d>>).

Example:

InputPattern	OutputPattern	Filename	Resulting Filename
birthday_<<R|(.+)>>.png	image_<<E|%02d>>.png	birthday_1999-12-7-127.png	image_01.png
birthday_<<R|(.+)>>.png	image_<<E>>.png	birthday_1999-12-7-127.png	image_1.png

How to Extend the Ruleset

New rules/patterns can be added easily:

1. You can implement the logic for the transformation rules using two approaches:

   1. Add a new transformation rule by implementing all required methods of the TransformationRule interface

   2. Add a new transformation rule by extending the AbstractTransformationRule class. This class provides several utility functions that allow you to focus on implementing the actual logic.

2. Add the generator function to the TransformationRuleFactoryConfiguration in the form of a TransformationRuleGenerator that consumes the input and output pattern provided as String and provides an Optional<TransformationRule> as result. Please take the contract of the API into consideration to ensure proper functionality:

   • return Optional.empty() if the pattern provided does not indicate that the rule is applicable to the task

   • return Optional.of(yourRuleInstance) in cases where the rule is applicable to the task

   • throw an IllegalArgumentException in cases where the input and/or output string does clearly indicate wrong input that can’t be parsed (e.g. image<<ddMMyyyy.jpg for a timestamp transformation rule)

🚨	Rules will be applied in parallel. Ensure sufficient atomicity where needed.

💡	Rules will be created once per task and hence share a common state which allows for the creation of rules that e.g. depend on the number of other invocations.