Phockup

Media sorting tool to organize photos and videos from your camera in folders by year, month and day.

How it works

The software will collect all files from the input directory and copy them to the output directory without changing the files content. It will only rename the files and place them in the proper directory for year, month and day.

All files which are not images or videos or those which do not have creation date information will be placed in a directory called unknown without file name change. By doing this you can be sure that the input directory can be safely deleted after the successful process completion because all files from the input directory have a copy in the output directory.

If the target file already exists, its checksum is compared with the source to determine if it is a duplicate. If the checksums are different, we do not have a duplicate and the target filename will be suffixed with a number, for example "-1". If the checksums match, the copy operation will be skipped.

Installation

Docker

The docker container supports two operation modes. The first allows for a single execution of phockup. In this mode, the container will be stopped after the execution is complete. The second mode allows for execution in intervals. In this mode, the container will continue running until the user decides to stop it.

Single execution mode

In this mode, all phockup parameters need to be passed as direct parameters within the docker run command. As you define a complete set of phockup parameters for this execution mode, this includes the paths to the input and output folders within the container. To execute phockup only once, use the following command:

docker run -v ~/Pictures:/mnt ivandokov/phockup:latest /mnt/input /mnt/output [PHOCKUP ARGUMENTS]

Continuous execution mode

In this mode, all relevant settings are defined through environment variables and volume mappings. The folders where phockup moves files are always /mnt/input and /mnt/output within the container and can not be changed. You can of course map any folder on your host system to those folders within the container.

The -v ~/Pictures/input:/mnt/input part of the command mounts your ~/Pictures/input directory to /mnt/input inside the container. The same is done for the output folder. You can pass any absolute path to be mounted to the container and later on be used as paths for the phockup command. The example above provides your ~/Pictures/input as INPUTDIR and ~/Pictures/output as OUTPUDIR. You can pass additional arguments through the OPTIONS environment variable.

To keep the container running and execute phockup in intervals, use the following command:

docker run -v ~/Pictures/input:/mnt/input -v ~/Pictures/output:/mnt/output -e "CRON=* * * * *" -e "OPTIONS=[PHOCKUP ARGUMENTS]" ivandokov/phockup:latest

This will execute phockup once every minute (as defined by the value of the CRON environment variable). However, the container will not spawn a new phockup process if another phockup process is still running. You can define other intervals for execution using the usual cron syntax. If you want to pass further arguments to phockup, use the OPTIONS environment variable. In this execution mode, phockup will always use the directories mounted to /mnt/input and /mnt/output and ignore arguments passed in the style of the single execution mode.

Mac

Requires Homebrew

brew tap ivandokov/homebrew-contrib
brew install phockup

Linux (snap)

Requires snapd

sudo snap install phockup

Note: snap applications can access files only in your home and /media directories for security reasons. If your media files are not located in these directories you should use the installation method below. If your files are in /media you should run the following command to allow access:

sudo snap connect phockup:removable-media

Linux (without snap)

If you are using distro which doesn't support snapd or you don't want to download the snap you can use the following commands to download the source and set it up

sudo apt-get install python3 libimage-exiftool-perl -y
curl -L https://github.com/ivandokov/phockup/archive/latest.tar.gz -o phockup.tar.gz
tar -zxf phockup.tar.gz
sudo mv phockup-* /opt/phockup
cd /opt/phockup
pip3 install -r requirements.txt
sudo ln -s /opt/phockup/phockup.py /usr/local/bin/phockup

Linux (AUR)

If you are an arch user you can install from the aur.

For example using yay:

yay -S phockup

Windows

• Download and install latest stable Python 3
• Download Phockup's latest release and extract the archive
• Download exiftool from the official website and extract the archive
• Rename exiftool(-k).exe to exiftool.exe
• Move exiftool.exe to phockup folder
• Open Command Prompt and cd to phockup folder
• Use the command below (use phockup.py instead of phockup)

Usage

Organize photos from one directory into another

phockup INPUTDIR OUTPUTDIR

INPUTDIR is the directory where your photos are located. OUTPUTDIR is the directory where your sorted photos will be stored. It could be a new not existing directory.

Example:

phockup ~/Pictures/camera ~/Pictures/sorted

Version

If you want to view the version of phockup use the flag -v | --version.

Date format

If you want to change the output directories date format you can do it by passing the format as -d | --date argument. You can choose different year format (e.g. 17 instead of 2017) or decide to skip the day directories and have all photos sorted in year/month.

Supported formats:
    YYYY - 2016, 2017 ...
    YY   - 16, 17 ...
    MM   - 07, 08, 09 ...
    M    - July, August, September ...
    m    - Jul, Aug, Sept ...
    DD   - 27, 28, 29 ... (day of month)
    DDD  - 123, 158, 365 ... (day of year)
    U    - 00, 01, 53 ... (week of the year, Sunday first day of week)
    W    - 00, 01, 53 ... (week of the year, Monday first day of week)

Example:
    YYYY/MM/DD -> 2011/07/17
    YYYY/M/DD  -> 2011/July/17
    YYYY/m/DD  -> 2011/Jul/17
    YY/m-DD    -> 11/Jul-17
    YYYY/U     -> 2011/30
    YYYY/W     -> 2011/28

Prefix/Suffix

In order to support both aggregation and finer granularity of files sorted, you can specify a prefix or suffix (or both) to aid in storing files in directories beyond strictly date.

NOTE: Prefixes and suffixes will also apply to the 'unknown' folder to isolate files that cannot be processed into their respective folders. This creates a bit more chaos for 'unknown' files, but should allow them to be managed by whomever they "belong" to.

Prefix

--output-prefix flag can be used to specify a directory to be appended to the OUTPUTDIR, and thus prepended to the date.

For example:

phockup ~/Pictures/camera /mnt/sorted --output_prefix=nikon

would place files in folders similar to:

/mnt/sorted/nikon/2011/07/17
/mnt/sorted/nikon/unknown

While it may seem to be redundant with OUTPUTDIR, this flag is intended to add support for more cleanly determining the output directory at run-time via environment variable expansion (i.e. use $USER, %USERNAME%, $HOSTNAME, etc. to aggregate files)

For example:

phockup ~/Pictures/camera /mnt/sorted --output_prefix=$USER

would yield an output directory of

/mnt/sorted/ivandokov/2011/07/17
/mnt/sorted/ivandokov/unknown

This allows the same script to be deployed to multiple users/machines and allows sorting into their respective top level directories.

Suffix

--output-suffix flag can be used to specify a directory within the target date directory for a file. This allows files to be sorted in their respective date/time folders while additionally adding a directory based on the suffix value for additional metadata.

For example:

phockup ~/Pictures/DCIM/NIKOND40 /mnt/sorted --output_suffix=nikon
phockup ~/Pictures/DCIM/100APPLE /mnt/sorted --output_suffix=iphone

This would allow files to be stored in the following structure:

/mnt/sorted/2011/07/17/nikon/DCS_0001.NEF
...
/mnt/sorted/2011/07/17/nikon/DCS_0099.NEF
/mnt/sorted/unknown/nikon/

/mnt/sorted/2011/07/17/iphone/ABIL6163.HEIC
...
/mnt/sorted/2011/07/17/iphone/YZYE9497.HEIC
/mnt/sorted/unknown/iphone/

The output suffix also allows for environment variable expansion (e.g. $USER, $HOSTNAME, %USERNAME%, etc.) allowing dynamic folders to represent additional metadata about the images.

For example:

phockup ~/Pictures/ /mnt/sorted --output_suffix=$HOSTNAME

or

phockup ~/Pictures/ /mnt/sorted --output_suffix=$USER

could be used to sort images based on the source computer or user, perventing hetrogenous collections of images from disparate sources saving to the same central respository.

The two options above can be used to help sort/store images

Limit files processed by date

--from-date flag can be used to limit the operations to the files that are newer than the provided date (inclusive). The date must be specified i