media-stow

Context and purpose

media-stow is a command-line tool for organising large local archives of photos, videos, and audio. Instead of trusting filenames or directory locations, it compares file content, making cases such as identical files with different names easier to handle reliably.

The tool treats archiving as more than copying. Validating the target structure, finding duplicates, separating common files between directories, and comparing earlier operations all belong to the same workspace.

How it works

An initial synchronisation places source files into a category- and extension-based target structure, then creates a JSON index describing the result. Later synchronisations compare the disk with that index to identify new, missing, or misplaced files.

The dedup command groups files with equal SHA-256 hashes. Verify checks the structure of the sorted archive and can compare it with a source directory while producing a report. Extract-common and compare commands analyse shared or changed content between directories and operation records.

System design

The application is a single .NET console program that chooses commands through CommandRegistry. Each command owns its workflow, while hashing, file access, terminal logging, and user confirmation remain shared services.

Models represent the media index, file records, summaries, and verification reports. Category and filter configuration centralises the rules that decide where files belong, avoiding different commands interpreting the same media rules independently.

Key technical decisions

HashService reads each file as a stream and calculates SHA-256. Equality therefore is not inferred from a name, timestamp, or size: it establishes that two files contain the same bytes. For large archives, the cost is balanced by limiting parallel work to processor capacity.

Indexes and reports are first written to a temporary target and then moved to their final name. This reduces the chance of a partially written JSON file being treated as valid state by a later synchronisation. Commands that change files ask for explicit confirmation, and sync and dedup provide a preview mode.

Validation and limits

The tool provides operational visibility through accessibility checks, structural verification, and JSON reports. However, the repository has no separate automated test project, so it does not offer automated proof that every file-moving or deletion scenario is safe.

Equal hashes do not mean files are visually similar. A re-encoded or edited photo is treated as different content. Hashing requires reading every file, so large archives have expected disk-access and time costs. Preview mode and backups should be used before operating on real media.