Photo Organizer

Photo Organizer is a Python script that sorts photos from a source directory into a target directory based on their creation date. The script can organize photos into year, month, and optionally day subfolders. It also supports explicitly choosing whether to copy or move files, recursive directory traversal, filtering by file extensions, and excluding files using regex patterns.

Features

• Organize photos into year/month/day folders based on creation date
• Explicitly copy or move files from the source to the target directory (--copy or --move, one required)
• Recursively traverse directories
• Filter files by specified extensions
• Exclude files from processing using regex patterns
• Verbose logging for detailed information
• Flexible folder structure with optional top‑level year‑month folders

Usage

Prerequisites

• Python 3.x

Installation

Install the package using pip:

pip install photo-organizer

Alternatively, use it with Docker:

docker run -ti \
    -v <your-photo-source-directory>:/source \
    -v <your-photo-target-directory>:/target \
    ghcr.io/Supporterino/photo-organizer:latest /source /target

Running the Script

photo-organizer [-h] [-r] [-d] [-e [ENDINGS ...]] [-v]
                 [-c | -m] [--no-year] [--exclude EXCLUDE_PATTERN]
                 source target

Arguments

• SOURCE_DIRECTORY – The source directory containing the photos
• TARGET_DIRECTORY – The target directory where the photos will be organized

Options

NOTE: One of -c/--copy or -m/--move must be supplied. If neither is provided, the script will warn and exit.

Examples

Move all files from source to target, organizing by year and month:

photo-organizer --move /path/to/source /path/to/target

Move all files recursively and organize by year/month/day:

photo-organizer --move -r -d /path/to/source /path/to/target

Copy only .jpg and .png files:

photo-organizer -c -e .jpg .png /path/to/source /path/to/target

Exclude files matching a specific regex pattern:

photo-organizer --exclude "^ignore|\.tmp$" /path/to/source /path/to/target

Enable verbose logging:

photo-organizer -vv --move /path/to/source /path/to/target

Move photos to top‑level year‑month folders without a year parent folder:

photo-organizer --no-year --move /path/to/source /path/to/target

Combine options to copy .jpg and .png files recursively into daily folders with verbose logging:

photo-organizer -c -r -d -e .jpg .png -vv /path/to/source /path/to/target

Development

To contribute to this project, follow these steps:

1. Clone the repository.
2. Install dependencies.
3. Make your changes and add tests.
4. Submit a pull request.

Logging

The script uses Python's logging module to provide detailed information about the operations performed. By default, the logging level is set to WARNING. Use the -v or --verbose flag to enable INFO level logging and -vv for DEBUG level logging for more detailed output.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your changes. Ensure that your code adheres to the existing coding standards and includes appropriate tests.

License

This project is licensed under the MIT License. See the LICENSE file for details.