rename-file-by-time-info

This is a CLI tool to rename files under a folder, according to the time that the file is born. That is, I want the file to be named by the time it's original copy is created.

This information does not exist in the metadata of most files, and the best guess would be the file's modified timestamp (mtime), assuming that the file has not been changed since it was created. For many media files, we have more information thanks to the Exif metadata inside these files. Devices (e.g. camera) creating these media files will usually store the timestamp of file creation in the Exif metadata, and it remains unchanged after normal media editing operations (e.g. Photoshop). Thus, we can extract this value and use it to name the media file.

This tool heavily relies on ExifTool to extract Exif metadata from media files. Thus, it is basically a wrapper of ExifTool. You have to download ExifTool yourself and add it to the search paths of executables, so that this tool can also executable ExifTool to obtained the extracted Exif metadata. If ExifTool does not exist on the system, this tool can only handle a few image types by extracting Exif metadata using the Python Pillow library.

Get Started

Windows

1. Download Exiftool Windows executable and rename the extracted executable from "exiftool(-k).exe" to "exiftool.exe".
2. Add the directory of "exiftool.exe" to "System Properties --> Advanced --> Environment Variables --> User variables --> Path".
3. Open terminal and run "exiftool -ver" to make sure comand "exiftool" is found by the system.
4. Download the latest version of this tool from the GitHub Releases page.
5. Extract this tool from the downloaded archive (e.g. rename_files-1.0.0-windows-amd64.tar.gz) and add the directory of "rename_files.exe" to "System Properties --> Advanced --> Environment Variables --> User variables --> Path".
6. Open terminal and run "rename_files --version" to make sure command "rename_files" is found by the system.

Usage

rename_files [global_options] <subcommand> [subcommand_options] <target_directory>

subcommand should be either general or media. global_options are optional arguments that are universal across subcommands. subcommand_options are optional arguments that are specific to that subcommand. target_directory is the path to the directory that this command going to work on.

Basic Usage

• Run rename_files general . to rename all files under the current directory, according to their modified timestamp.
• Run rename_files media . to renames supported media files under the current directory, according to datetime information embedded in their metadata. Whether a file will be treated as a media file is defined in the configuration file. See section supported_file_extensions for more details.

Available Arguments

help

To get runtime help:

rename_files --help

version

To show the version of the tool:

rename_files --version

config-file

To specify the configuration file to be used (rather than loading configurations from config.json):

rename_files --config-file <file-path> <subcommand> [subcommand_options] <target_directory>

general

Use this subcommand to rename any files in a folder. Options for this subcommand are listed below:

option	meaning	example
-r	Rename files recursively
--forced-offset-time	Specify a target timezone if the timezone of the timestamps used to rename the files are not what you expect.	--forced-offset-time +08:00
--forced-date	Specify the date of the files if the date information used to rename the files are not what you expect.	--forced-date 2023-09-25
--exif-offset-time	Specify the timezone of datetime data in Exif metadata if timezone information does not exist in the metadata.	--exif-offset-time -04:00
--skip-files-with-formatted-names	Specify this option so that files with name matching the naming format will be skipped. See section configuration for more details.
--skip-media-files	Specify this option so that files with extensions specified in configuration file will be skipped.

media

Use this subcommand to rename media files. Options for this subcommand are listed below:

option	meaning	example
-r	Refer to here
--forced-offset-time	Refer to here
--forced-date	Refer to here
--exif-offset-time	Refer to here
--skip-files-with-formatted-names	Refer to here
--use-exiftool-on-images or --no-use-exiftool-on-images	Specify either of these options to override this field in the configuration file.

Configurations

After extracting this tool from the archive, you can find the JSON configuration file "config.json" along with the "rename_files.exe" executable. Configurable options are listed below.

file_naming_format

Use format codes to specify the format of the file name.

general_file

The following is the list of format codes available when parsing normal files (using the general sub-command).

Directive	Meaning
%Y	4-digit representation of the year.
%y	2-digit representation of the year within a century.
%m	2-digit representation of the month
%d	2-digit representation of the day of the month.
%H	2-digit representation of the hour (24-hour clock).
%M	2-digit representation of the minute.
%S	2-digit representation of the second.
%z	UTC offset in the form ±HHMM
%{ms}	3-digit representation of the millisecond.
%%	A literal '%' character.

media_file

Apart from the format codes available when parsing normal files, the following has listed additional format codes available when parsing media files (using the media sub-command).

Directive	Meaning	Remarks
%{dtt}	A string to indicate what the date and time information in the file name is representing.
%{et}	A string to indicate whether the media file has been edited before.

supported_file_extensions

This section specifies the types of media files supported by different libraries used in this tool. You can remove items from the list if you do not want those types of files to be renamed when you using the media sub-command. Extensions in the list are case-insensitive.

exiftool

Specify the types of media files that will be passed to Exiftool for metadata extraction. Noted that image file extensions are located at a list separated from the video and audio file extensions.

pillow

Specify the types of media files that will be passed to Python Pillow for metadata extraction.

ignored_file_extensions

File with extension specified in this list will not be renamed by this tool.

media

DateAndTimeType

This field maps the DateAndTimeType to a string that will be shown on the file name if you use the %{dtt} format code when parsing media files. DateAndTimeType is an enumeration with the following members:

Member	Meaning
AUTHENTIC	The date and time information extracted from the metadata of the file is representing the actual time that the media (image, video or audio) is generated.
BEST	The earliest date and time information that can be found from the metadata of the file, but not necessarily the time that the media (image, video or audio) is generated.
CURATED	The date and time information is a hard-coded value. That is, the information is not retrieved from the metadata of the file.

EditType

This field maps the EditType to a string that will be shown on the file name if you use the %{et} format code when parsing media files. EditType is an enumeration with the following members:

Member	Meaning
ORIGINAL	It is likely that the file is an original copy of the media.
EDITED	It is likely that the file has been altered by editors (e.g. Photoshop)

editing_softwares_keywords

How this tool determine whether a media file has been edited is by finding the name of the editing softwares in the metadata of the file. Usually, a media file exported from an editing software will have it name embedded in the metadata of the file. This list specifies the texts that this tool will look for to determine whether the file is an exported file of an editing software.

use_exiftool_on_images

By default, extraction of metadata from images is performed by Exiftool. However, the use of Exiftool in this tool has not been optimized in terms of speed. If all the types of files you want to process can be handled by Python Pillow, you may want to choose not to use Exiftool on images by specifying "use_exiftool_on_images": false.

debug_mode

Setting it to true will output more logs.

Development

Distribute

1. pip install .[dist]
2. python -O distribute.py
3. Distributable generated can be found in dist.

License

This project is licensed under the terms of the MIT license.