# CleanGallery (CLI prototype)

CleanGallery is a working prototype of a multi-target, read-only
duplicate-waste audit tool: point it at several directories, network
shares, or user-profile folders at once and it scans each one
independently for exact duplicate files, then prints (and can export to
CSV) a ranked report showing how much disk space each target could
reclaim, worst offender first, plus a fleet-wide total. It exists so an
IT admin managing many shares/profiles can quickly answer "where should I
focus cleanup effort first?" instead of eyeballing folders one at a time.
It differs from the sibling tool DupePilot, which is single-target and
interactive: you point DupePilot at one folder and it walks you through
quarantining/deleting the duplicates it finds there. CleanGallery does
not do any of that by design - it is audit-only, with no quarantine,
apply, or cleanup action of any kind, because its job is the fleet-wide
survey, not the per-folder surgery. The intended workflow is to run
CleanGallery across your shares to find the worst offender, then run
DupePilot against that one target to actually clean it up. Centralized
deployment, policy-based scheduling, and multi-seat licensing from the
full CleanGallery product concept are on the roadmap and not part of
this CLI prototype - see ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o cleangallery .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o cleangallery.exe .
    GOOS=darwin  GOARCH=arm64 go build -o cleangallery .

## Usage

    cleangallery audit <target1> [<target2> ...] [flags]

Each <target> is an INDEPENDENT scan root. CleanGallery runs the same
size-bucket-then-SHA-256 exact-duplicate detection technique as DupePilot
separately within each target and does NOT merge targets together: a
file that is byte-for-byte identical between target1 and target2 is NOT
counted as a duplicate for this tool's purposes, because the question
CleanGallery answers is "how much duplicate waste exists inside THIS
share/profile", not "what's globally unique across my whole fleet". This
is a deliberate scoping choice, not an oversight - a naive global merge-
and-dedupe would answer a different (and less useful, for triage
purposes) question.

For each target, CleanGallery computes:
  - duplicate set count: how many distinct groups of identical files
    exist in that target
  - reclaimable bytes: sum over all duplicate groups in that target of
    (group file size) x (group member count - 1) - i.e. the bytes you'd
    get back by keeping one copy of each duplicated file and deleting
    the rest

Flags:
  --min-size <bytes>   Ignore files smaller than this many bytes when
                        looking for duplicates (default 1). Useful for
                        skipping tiny files (icons, empty placeholders)
                        that aren't worth reporting.
  --csv <file>          Write a per-target summary CSV to <file>, with
                        one row per target: path, duplicate_set_count,
                        reclaimable_bytes, human_readable_size. Fields
                        containing commas or other special characters
                        are quoted per standard CSV rules, so target
                        paths with spaces or commas are safe. This is
                        the summary view, meant for a spreadsheet.
  --json                Print a structured JSON report instead of the
                        plain-text table. Includes everything the CSV
                        has plus full per-target duplicate-set detail
                        (every group's size, SHA-256, member count, and
                        the full list of file paths in that group), so
                        a downstream tool can act on the exact files
                        involved, not just the summary numbers.
  -h, --help            Show help.

The plain-text summary table and the CSV/JSON exports are all sorted by
reclaimable bytes descending (worst offender first), followed by a
fleet-wide total across every target scanned in that invocation.

CleanGallery never writes to, moves, renames, or deletes anything in any
target directory - it only reads file metadata and file contents to
compute hashes. The only file it ever writes is the optional --csv
report file you point it at.

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds -
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.