🗂️ DiskShelf

Catalog your external drives on macOS — scan once, find any file across every disk, even offline.

A single, private, read-only catalog of all your external drives.
Plug a drive in, scan it once, and browse its entire file tree — sizes, folders, previews, everything — long after you've unplugged it and put it back on the shelf.

---

Note

A personal tool, shared as-is. 🛠️ I built DiskShelf to catalog my own pile of external drives, and use it daily. It works well and is safe by design (see below), but it's an early, un-notarized build shared modestly — no roadmap, no promises.

✨ What it does

If you're a video editor, photographer, or anyone with a drawer full of HDDs, DiskShelf answers the question "which drive is that file on?" — without plugging in all of them.

🔎 Find a file across every drive — global search (⇧⌘F) spans all scanned drives at once, even disconnected ones. Each result shows which numbered drive it lives on.	🔌 Browse offline — folders, sizes, dates and structure stay available after the drive is unplugged. Scan once; the catalog is yours.

• 🔢 Number your drives — if your HDDs are physically labeled, assign the same number in the app. It shows up everywhere and in every export.
• 🖼️ Media previews (opt-in) — small photo/video thumbnails that stay visible offline. Off by default to keep the app tiny (~15–30 MB per 1,000 previews); generate them per-drive on demand.
• 🧮 Space planner — "I need 500 GB free on this drive." A deterministic bin-packing algorithm picks exactly what to move where, respecting free space and a safety margin on each destination. Instant, reproducible, fully offline — it only ever suggests; it never moves your files.
• ♻️ Duplicate finder — spot the same project sitting on several drives (matched by name + size). "Reveal copies in Finder" opens every mounted copy at once, one window per folder.
• 📤 Export everything — the whole catalog to CSV, Markdown, or JSON for dashboards, backups, or feeding an AI agent.

🔒 Safety first — this is the whole point

DiskShelf is built around a single promise: it never writes to the drives it scans.

• A scan is only directory enumeration + attribute reads. There is no write, move, or delete call aimed at a scanned volume anywhere in the code.
• The space planner only produces a plan — you carry out any moves yourself.
• No networking code at all — nothing leaves your Mac. The catalog lives locally in ~/Library/Application Support/DiskShelf/.
• Drives are opened read-only through standard macOS mechanisms.
• The invariant is pinned by an automated test (testScanLeavesVolumeUntouched): a volume's files, sizes and dates must be byte-for-byte identical before and after a scan.

See SECURITY.md for the full model.

📥 Install

1. Download DiskShelf-v1.3.0.dmg from Releases and open it.
2. Drag DiskShelf onto the Applications folder (the window shows an arrow).
3. Allow the first launch. The build isn't notarized yet, so macOS blocks it — it's safe (read-only, no networking). Two ways to allow it:
   • Most reliable (macOS Sequoia & Tahoe) — run this once in Terminal, then open the app normally:

     xattr -dr com.apple.quarantine /Applications/DiskShelf.app

     It just clears the "downloaded from the internet" flag; it doesn't modify the app.
   • Via Settings (older macOS) — after macOS blocks it, open System Settings → Privacy & Security, scroll to the bottom, and click "Open Anyway", then confirm. On Tahoe this button is often hidden, so use the Terminal method above.
4. On the first scan, macOS asks for read-only access to removable volumes — that's the standard system prompt.

Full step-by-step is inside the DMG as "How to install.txt".

Requires macOS 13 (Ventura) or newer • Apple Silicon & Intel.

🛠️ Build from source

Needs Xcode or Command Line Tools with Swift 5.9+.

git clone https://github.com/Dato241/DiskShelf.git && cd DiskShelf
swift test          # 20+ tests: scanner, planner, exports, live disk-image integration
./build_app.sh --install   # build + install to /Applications and launch
./Scripts/make_dmg.sh      # build the drag-to-install DMG

🧩 How it's built

Native Swift + SwiftUI, zero third-party dependencies. The system SQLite (WAL mode) stores each drive as a generation of rows, so a rescan is atomic — an interrupted scan never corrupts the previous catalog. Folder sizes are aggregated during the walk; previews are QuickLook thumbnails keyed by a stable hash of (drive UUID + path). Drives are identified by volume UUID, so renaming one keeps its catalog and its number.

Sources/DiskShelf/
├─ AppState.swift        coordinator: catalog, scan queue, volume events
├─ Database.swift        system SQLite, generation-based schema
├─ DiskScanner.swift     read-only walk, size aggregation, batching
├─ VolumeMonitor.swift   mount/unmount, UUID matching
├─ Planner.swift         bin-packing space planner
├─ Exporter.swift        streaming CSV / Markdown / JSON
└─ Views/                dashboard, drive, search, planner, duplicates, export

🐞 Feedback

Found a bug or something confusing? Open an issue — no roadmap or promises, but I read them.

📄 Terms

A personal project, shared as-is and free to use — no warranty of any kind, use at your own risk. Not affiliated with Apple. There's no formal open-source license: the code stays mine, but if you'd like to build on it, just ask.