File Stacker

A command-line tool that organizes files by grouping them based on their creation time and copying them into timestamped folders.

Description

File Stacker groups files with specified extensions by their creation time within a configurable tolerance window. Files created within the tolerance period are grouped together and copied into folders named with the start and end timestamps of that group.

This is particularly useful for organizing photos or files that were created in bursts (e.g., photo shoots, batch imports) where you want to keep related files together.

Installation

Using pip

pip install file-stacker

Using pipx (recommended for CLI tools)

pipx install file-stacker

Usage

Basic Usage

Stack files in the current directory with default settings (10 second tolerance, JPG and CR3 files):

file-stacker stack

Specify a Directory

Stack files in a specific directory:

file-stacker stack /path/to/directory

Custom Tolerance

Adjust the time tolerance window (in seconds):

file-stacker stack --tolerance 30

Custom File Extensions

Specify which file extensions to process:

file-stacker stack --extensions jpg png cr3 raw

Complete Example

Stack files in a directory with a 60-second tolerance, processing only RAW files:

file-stacker stack /path/to/photos --tolerance 60 --extensions cr3 raw

Options

• path: Directory path to stack (default: current directory .)
• --tolerance: Time difference in seconds to consider files as part of the same group (default: 10)
• --extensions: File extensions to group by (default: ["jpg", "cr3"])