Duplicate File Audit — Personal Python Demo

Personal demonstration — no client engagement. All sample files are synthetic.

A Python standard-library command-line tool inspects a stable local folder and produces a JSON report of duplicate file candidates. It groups files by size, then streams matching-size candidates through SHA-256 in chunks of at most 1 MiB. Unique-size files need no content read. The tool reads files; it does not delete, move or deduplicate them.

The report includes sorted relative paths, sizes, hashes, skipped symbolic links and per-path errors. Unreadable candidates produce a partial report and a non-zero exit status. The synthetic example contains five files: two matching 34-byte files, a different file with the same size, and two empty files. The report correctly separates the different-content file.

Verified with 10 automated tests covering matching bytes under different names, equal-size different content, empty files, symbolic links, invalid roots, permission failures, deterministic JSON, unchanged input contents, unique-size optimization and changes detected before hashing.

Scope and limits: macOS/Linux with O_NOFOLLOW support, a stable directory tree and path metadata held in memory. SHA-256 is the duplicate criterion; no second byte-by-byte comparison is performed. Hard links appear as separate paths, so a duplicate group does not imply that deleting a path would free its full size. This is an audit report, not a deletion recommendation or a filesystem snapshot.

Source code, tests, synthetic examples and run notes are available. The cover is an original text/diagram illustration of the verified example, not a client screenshot.