cataloguer 2.2

Description:

cataloguer 2.2

Media cataloguer
Organize your media files using your preferred directory structure.

Do you have pictures taken from different devices?
Do you want control over your file system?
Do you wish to unify all your media files and remove duplicates?

If you reply affirmative to any of the previous questions, this tool could be right for you too.
This tool helps you to unify and organise your media files using your own rules.
It also deals with duplicates, so you don't have to.
Disclaimer
Per design, this command line interface tool only deletes duplicate files to avoid any risk of losing data.
Features

Move, copy, sort or delete duplicates operations
User-friendly console output
Obscure creation date detection
Custom folder structure definition
Duplication detection
Does not alter existing files

Requirements

Python 3.9 or higher

Installation
pip install cataloguer

Usage
$ cataloguer --help

Usage: cataloguer [OPTIONS] COMMAND [ARGS]...

Command line interface.
All [OPTIONS] can be passed as environment variables with the "CATALOGUER_" prefix.
file arguments accept file names and a special value "-" to indicate stdin or stdout

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --verbose -v Enables verbose mode. Disabled by default │
│ --format-pattern TEXT Pattern template. e.g. %Y/%m/{file} │
│ --unknown-format-pattern TEXT Pattern template fallback when date cannot get extracted │
│ --interactive/--no-interactive Disables confirmation prompts. Enabled by default │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ copy Copy files. In case of duplicates will take the shortest name. │
│ create-catalogue Creates a new catalogue. │
│ delete-catalogue Deletes a catalogue. No files are affected. │
│ delete-duplicates Delete duplicates. │
│ inspect Inspects a path or a catalogue │
│ move Move files. In case of duplicates will take the shortest name. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Quickstart
We are going to start creating a new directory media:
mkdir media

We are going to create a new catalogue named local_media which is going to get store on the newly created media directory.
We specify our format pattern so photos are group by year and a subgroup of month:
cataloguer create-catalogue local_media ./media --format-pattern %Y/%m/{file}

Now, we add some photos from an old storage drive:
cataloguer copy /mnt/hdd/old_photos local_media

Later on, we decided we want to reorganize our local home folder, but we are not sure of how many files are
going to be affected, so we run the command in dry-run mode:
cataloguer move ~/ local_media --dry-run

After seeing the output, we decided to just reorganize our Pictures:
cataloguer move ~/Pictures/ local_media

To get a summary of our catalogue we run:
cataloguer inspect local_media

Options
format-pattern accepts the following patterns

Common date codes:

%d: Day of the month as number
%m: Month as number
%Y: Year as number
%A: Weekday name
%B: Month name
other format codes specified here


/ Specifies a new folder
{media_type}: Detected file type (image, video)
{media_format}: Detected file format (jpeg, tiff, png, gif, mp4 ...)
{file} Original filename (photo.jpg)
{file_name} Filename without the extension (photo)
{file_extension} Filename extension (jpg)
{relative_path} Relative path to the source directory

Advance usage:
unknown-format-pattern Accepts the same variables as format-pattern but date patterns
are resolved using the current date since it was not possible to recover the creation date of the file.
This can be useful to not leave files behind.
Variables can also be specified as environment variables, using a CATALOGUER_ prefix. e.g:
export CATALOGUER_FORMAT_PATTERN=%Y/%m/{file}

CATALOGUER_STORAGE_LOCATION Accepts any path. That location will store metadata.
By default, it will create a .catalogues in the user's home directory.
Examples:
Pattern to fix file extensions keeping the folder structure:
cataloguer --format-pattern {relative_path}/{file_name}.{media_format} sort ./target/

TODO list

Video support