DupeCheck Help

Why Duplicates Matter on Shared Storage

Media production workflows generate duplicates constantly. Project imports copy source footage into new timelines. Archive passes duplicate deliverables across volumes. Multi-editor environments scatter identical assets across shares and local caches. On shared storage, every duplicate consumes capacity your team can't use for new work.

DupeCheck is designed for environments where duplicate management needs to span network volumes, reach outside the user sandbox, and handle large file counts efficiently — the scenarios that matter most in media production and that sandboxed App Store tools can't address.

Getting Started

Quick Start

1. Launch DupeCheck and add one or more source folders from the toolbar
2. Click Scan to begin scanning
3. Review duplicate sets in the main table, sorted by wasted space (every copy except one)
4. Choose which copy of each set to keep: select a file and choose Promote to Primary, or right-click a folder in the sidebar and choose Mark Files Here as Primary…
5. Clean a single file or set from the list, clean a folder from the sidebar, or click Clean Up to clean every set
6. Every cleanup saves a report automatically; see them with File → Show Cleanup Reports in Finder

Main window showing duplicate groups sorted by wasted space, with file preview panel on the right.

Source Folders & Primary Copies

Source folder management — add local and network volumes.

Adding Source Folders

Click the Folders button in the toolbar to add folders. You can add any combination of local directories and network-mounted volumes. DupeCheck scans all source folders and finds duplicates across them.

If one source folder is a child of another, the child is automatically excluded from the parent's scan to prevent double-counting. If you remove the child folder later, click Scan to pick up the files the parent was skipping.

DupeCheck scans only when you click Scan — not at launch, when a volume mounts, or when you add or remove a source folder. A source folder on a share that isn't mounted keeps its results and shows Not connected until the share mounts again.

Primary Copies

Each duplicate set has at most one primary copy: the one DupeCheck keeps during cleanup. The other copies in the set are the duplicates that cleanup removes or replaces. Primary is a property of a file, not of a folder, and scans never change it.

• To keep one file, select it and choose Promote to Primary (⌘P).
• To keep everything in one folder — useful when one folder is your canonical source and everything else is a copy — right-click the folder in the sidebar and choose Mark Files Here as Primary…. The current primary copies, including ones outside the folder, can then be removed by a cleanup. A set with more than one copy in the folder is left unchanged: choose its primary in the list.
• When a set's primary copy is edited, moved or deleted, the remaining copies stay a duplicate set with no primary until you choose one. Cleanup skips sets with no primary.

Folder Sidebar

The sidebar lists your source folders and every subfolder that contains duplicates, with a count of the duplicate files in it and below it. Select a folder to see only the duplicate sets with a file there; files in that folder are marked in the file list. Show or hide the sidebar with the Sidebar toolbar button or View → Hide Sidebar (⌃⌘S).

Right-click a file in the list and choose Go to Folder to jump to its folder in the sidebar. Right-click a folder in the sidebar to:

• Clean Duplicates in This Folder… — clean the duplicates in the folder, keeping each set's primary copy
• Clean Duplicates of Originals in This Folder… — keep the folder's files as the originals and clean their copies everywhere else. Each file in the folder first becomes its set's primary. A set with more than one copy in the folder is skipped.
• Mark Files Here as Primary… — make the folder's files the copies that are kept

Each action asks for confirmation first. It covers every duplicate set with a copy in the folder or its subfolders, including source folders inside it. The type filter and search don't change what an action covers; they only change what the list shows.

Duplicate Folders

Find whole folders that were copied, such as a project copied to a second share, and clean the copies in one step. Click Folders above the list to see groups of identical folders: folders with the same file names, the same layout, and the same content. Only the highest identical folder is listed; its identical subfolders aren't listed again.

• Copies, Files and Size describe one group. Reclaimable is the space that removing the extra copies would free. Copies that are already APFS clones take no extra space and don't count.
• Expand a group to see its folders. A folder inside it that also has copies somewhere else appears as a nested group, counting only those extra copies.
• Groups that would free less than 1 GB are hidden. Select Show groups under 1 GB to see them.
• The search matches folder paths.

Folders are compared using the files DupeCheck recorded in its last scan. Small, hidden and excluded files aren't part of the comparison; DupeCheck checks them when you clean.

Keep One Copy and Clean the Others

1. In the Folders list, right-click the folder you want to keep and choose Keep This Copy…. DupeCheck lists the other copies again, including the files it never scanned, and compares those files with the kept folder.
2. Review the confirmation. Show Files lists every file to clean with the copy it's kept against.
3. Click OK. In Move to Trash mode, if the other copies hold files DupeCheck never scanned that have no identical copy in the kept folder, the confirmation names them. Choose Remove Folders Anyway to remove them with their folder, or Keep Unscanned Files to leave those folders in place with them.

The files in the kept folder become their sets' primary copies where needed. The files in the other copies are then cleaned with the cleanup mode selected in Settings:

• Move to Trash: each folder that's left empty is then removed the same way as its files — to the Trash, or deleted when Recover space immediately is on. A folder that still holds files stays where it is, and the cleanup report lists what's left. This happens when a file was skipped, is an APFS clone, is inside a Photos or Music library, was kept as an unscanned file, or was added after the check. .DS_Store files are always removed with their folder.
• Replace with APFS Clones or Replace with Symlinks: the folders stay, and files DupeCheck never scanned aren't changed.

If a file in a folder you're cleaning no longer matches the kept folder, DupeCheck doesn't clean anything and asks you to scan again.

NAS Helper

Scanning a large SMB share from a Mac means listing and reading every file over the network. The NAS helper is a small program that runs on the NAS itself: it lists and hashes the files there, so finding files on a large share takes minutes instead of hours, and hashing no longer reads files over the network. Cleanup still moves and deletes files over SMB.

Setup

1. Mount the share in Finder and add a folder on it as a source folder
2. Choose DupeCheck → Connect to NAS Helper… and click Deploy Helper… for the share. DupeCheck copies the helper files onto the share and shows a command
3. On the NAS, open a root shell (sudo -s), cd into the share if you can, and paste the command. It installs the helper as a service and starts it
4. Back in DupeCheck, the share shows Connected. The first time, macOS asks to allow DupeCheck to find devices on your local network — allow it

Scans of source folders on that share then run through the helper. To go back to scanning over SMB, choose Disconnect; Uninstall… gives you a command to remove the helper from the NAS.

With SHA-256 or MD5 verification, background verification and the check before cleanup also run on the NAS. The helper has its own NAS helper hash workers and NAS helper enumeration workers settings (Settings → Performance, defaults 16 and 4); lower them if other people use the NAS while you scan.

How Detection Works

Three-Phase Scan Pipeline

DupeCheck uses a multi-phase approach to find duplicates efficiently without hashing every file on disk:

1. Enumeration — discover all files across source folders, collecting path, size, and modification date
2. Size grouping — files with unique sizes across the entire database are skipped immediately. Two files can only be duplicates if they're the same size
3. Content hashing — files that share a size are hashed for content verification. A fast multi-sample hash narrows candidates, then full SHA-256 or MD5 confirms the match

Hash Verification

Duplicates are always compared with multi-sample hashing during the scan. The Hash Method setting chooses whether cleanup also checks each file against a full-file hash first:

With SHA-256 or MD5, Verify in background after scan computes full hashes for all duplicates at low priority after a scan and logs any false positives in the Activity log.

Concurrent Processing

DupeCheck uses concurrent workers for both directory enumeration and file hashing. The default configuration (2 enumeration workers, 4 hash workers) balances speed with I/O pressure on the volume being scanned. Shares connected through the NAS helper use their own settings (16 hash workers, 4 enumeration workers by default).

Cleanup Modes

Three cleanup modes: APFS Clones, Symlinks, and Move to Trash.

DupeCheck offers three strategies for handling confirmed duplicates. Choose the mode that best fits your storage and workflow:

Replace with APFS Clones

The duplicate is replaced with an APFS clone of the primary copy. Clones share physical disk blocks but behave as completely independent files — applications see two separate files, but the underlying storage is shared. If either file is later modified, only the changed blocks are written (copy-on-write).

DupeCheck preserves the duplicate's original metadata (modification date, permissions, extended attributes) through an atomic clone-swap operation. The original file's inode is preserved, so references from other applications remain valid.

Replace with Symlinks

The duplicate is replaced with a symbolic link pointing to the primary copy. This saves space without requiring APFS, but symlinks are visible to applications and may not work with all software. DupeCheck uses a safe rename-verify-move pattern to ensure atomic replacement.

Like clone mode, symlinks require both copies to be on the same volume. Cross-volume duplicates are skipped automatically — the Clean Up confirmation tells you how many.

Move to Trash

Duplicate files are moved to the system Trash. This is the simplest option — duplicates are removed but recoverable from Trash if needed. For privileged paths where the system Trash is unavailable, DupeCheck creates a DupeCheck-Trash recovery folder at the source root.

Cleanup confirmation — review mode, file count, and recovery options before any files are modified.

Protected Files

DupeCheck protects certain files from cleanup regardless of mode:

• Locked files — files with the immutable flag are scanned and shown with a lock badge, but cleanup is blocked
• Protected containers — Photo libraries, Music libraries, and other managed containers are scanned for detection but cleanup is blocked to protect library integrity

Live Monitoring

DupeCheck can continuously monitor source folders for new duplicates using the Start Watching / Stop Watching toolbar button. When watching is active, macOS FSEvents detects file changes in near real-time with intelligent debouncing to batch event bursts. Watching is off by default; the watching state persists across app launches.

On a share connected through the NAS helper, a folder that changes is scanned through the helper. Whether changes made from other computers are noticed depends on the file server: a Mac file server reports them, but some NAS servers report only the changes made from this Mac. Click Scan to pick up everything. If the helper isn't connected when a change arrives, the Activity log says which changes weren't scanned; the next scan covers them.

Changes you make from within DupeCheck — cleaning, renaming, or cloning duplicates — update the UI immediately without waiting for a rescan, regardless of whether watching is enabled.

Keyboard Shortcuts

DupeCheck supports full keyboard navigation. Press Tab to switch focus between the duplicate groups table and the file list below it. Use Up/Down arrows to navigate within the focused pane. The active pane is indicated by an accent-colored border.

File Actions (Edit Menu)

Navigation (View Menu)

All shortcuts are also shown in context menus for discoverability. Destructive actions show a confirmation dialog which can be suppressed via Don't Ask Again. Use Reset Dialogs in Advanced settings to re-enable suppressed confirmations.

Exclusions & Filtering

Exclusion settings with implicit system protections, user-configured directories, and pattern-based filtering.

Implicit Directory Exclusions

The following directories are always excluded from scanning. These are detected automatically based on filesystem metadata and cannot be disabled:

• System directories — owned by root with restricted permissions (e.g. /System, /usr, /bin)
• SIP-protected directories — directories with the com.apple.rootless extended attribute
• Library directories — ~/Library and other users' Library folders contain application support data
• Firmlinks — synthetic firmlink targets (e.g. /System/Volumes/Data)

Implicit File Type Exclusions

• Opaque bundles — .app, .framework, .sparsebundle files are skipped entirely (contents not scanned)
• Protected containers — .photoslibrary, .musiclibrary are scanned for detection but cleanup is blocked
• Locked files — scanned and shown with a lock badge but cleanup is blocked
• Small files — files below the minimum file size threshold (default: 100 KB) are skipped during detection
• Symbolic links — not followed during scanning

User-Configured Exclusions

Add directories to the exclusion list in Settings to skip them during scanning. The /Applications directory is excluded by default.

Exclude Patterns

Define filename-based exclusion patterns using glob syntax (*, ?) or regex (/pattern/). Patterns match against filenames only, not full paths. One pattern per line. Default patterns:

• .* — hidden files (dotfiles)
• *.tmp — temporary files
• .DS_Store — Finder metadata

Minimum File Size

Files below the minimum size threshold are skipped during duplicate detection. The default of 100 KB is recommended — smaller files are rarely meaningful duplicates in media workflows and skipping them significantly reduces scan time. Options range from no minimum to 10 MB.

Type Filter and Search

The type filter and the search box only change what the list shows, to help you find specific media. They never change what a cleanup, a folder action or the Duplicates Report covers. To keep files out of DupeCheck, use the exclusions above.

Privileged Helper

By default, DupeCheck can only scan and modify files within your home folder. To operate on files outside your home directory — including shared volumes, system-wide locations, and other users' directories — enable the privileged helper in Settings.

Setup

1. Enable Use privileged helper in Settings → Advanced
2. DupeCheck registers a helper daemon — you may be prompted for your administrator password
3. Approve the helper in System Settings → General → Login Items & Extensions (under "Allow in the Background")
4. Grant Full Disk Access to the helper in System Settings → Privacy & Security → Full Disk Access

The helper status indicator in Settings shows green when the helper is running and ready, or orange when approval is still pending.

Reports & Export

Every cleanup saves a report; Export Report saves another copy where you choose.

Every cleanup — including cleaning a single file or set from the list — saves a CSV report automatically. See them with File → Show Cleanup Reports in Finder. The Cleanup Complete message lists files that weren't cleaned and why, and Export Report saves a copy in the format chosen in Settings. Reports include per-file status, the action taken, recovery paths, and summary statistics.

Before a cleanup, Show Files in the confirmation lists every file it will process with the copy that is kept, and Save List… saves the list as a CSV file.

File → Export Duplicates Report… saves every file in every duplicate set, grouped by set, as a CSV file. The type filter, search and sidebar folder don't limit the report.

Export Formats

What Gets Reported

The report captures every file processed during cleanup, including:

• Succeeded — files that were cloned, symlinked, or trashed
• Skipped (cross-volume) — duplicates on different volumes when using clone or symlink mode
• Skipped (protected) — locked files or protected containers
• Skipped (not confirmed) — files that failed verification before cleanup
• Skipped (primary missing or changed) — the primary copy is gone, or a file changed since the scan
• Skipped (read-only volume) and skipped (same file) — a file that is the primary itself through a symlink or hard link is never removed
• Failed — files where the cleanup operation encountered an error, with the error message recorded

Troubleshooting

Cleanup Fails on Network Volume

APFS clone and symlink modes only work when both copies are on the same volume. Cross-volume duplicates are automatically skipped in these modes. If most of your duplicates span volumes, use Move to Trash mode instead.

Helper Not Available

• Check that the helper is approved in System Settings → General → Login Items & Extensions
• Verify Full Disk Access is granted in System Settings → Privacy & Security
• Click Enable Helper or System Settings in Settings → Advanced and follow the steps shown there
• If the helper remains unavailable, quit DupeCheck, reopen it, and check the status again — registration retries on launch

Files Not Found After Cleanup

In Trash mode, cleaned files are in your system Trash (recoverable via Finder → Trash). For privileged paths where system Trash is unavailable, look for a DupeCheck-Trash folder at the root of each source folder.

In Clone mode, both copies still exist — they just share physical storage blocks. The file at each path is fully functional and independently modifiable.

Scan Takes a Long Time

• Increase the minimum file size to skip small files (e.g. 1 MB for media-only workflows)
• Add directories you don't need scanned to the exclusion list
• Network volume scans are inherently slower than local scans due to I/O latency. For large SMB shares, install the NAS helper
• The first scan is always the slowest — subsequent scans are incremental and reuse existing hash data from the database

Stale "Busy" Files

If cleanup reports files as busy, DupeCheck checks whether the busy flag has been idle for more than 24 hours. Stale busy flags (common with SMB oplocks that weren't properly released) are automatically cleared before retrying the operation.

Database Reset

If the file index becomes corrupted or you want to start fresh, use Reset Database in Settings → Advanced. This stops any running scan, clears all scanned file records and requires a full rescan. Your source folder configuration and preferences are preserved.

Debug Logging

Enable Debug Logging in Settings → General for verbose diagnostic output. Logs are written to ~/Library/Logs/daveco/ and include scan progress, hash computations, cleanup operations, and error details.