DupeScan

یک ابزار خط فرمان سریع و امن برای پیدا کردن فایل‌های تکراری در Windows، نوشته‌شده با Rust.

A fast and safe Rust command-line tool for finding duplicate files on Windows.

فارسی · English

---

فارسی

معرفی

DupeScan یک یا چند مسیر را به‌صورت بازگشتی بررسی می‌کند و فایل‌هایی را که محتوای واقعاً یکسان دارند در یک گروه قرار می‌دهد. تشخیص تکراری بودن فقط بر اساس نام فایل نیست: برنامه ابتدا اندازهٔ فایل‌ها را مقایسه می‌کند و سپس برای فایل‌های هم‌اندازه، هش BLAKE3 محاسبه می‌کند.

این برنامه hard linkها را نیز تشخیص می‌دهد؛ بنابراین چند مسیر که در واقع به یک فایل فیزیکی اشاره می‌کنند، فضای قابل‌بازیابی را به‌اشتباه افزایش نمی‌دهند.

قابلیت‌ها

• اسکن بازگشتی یک پوشه یا همهٔ دیسک‌های محلی
• الگوریتم دو مرحله‌ای برای کاهش مصرف حافظه و عملیات خواندن
• محاسبهٔ موازی هش BLAKE3 با تعداد thread قابل تنظیم
• پشتیبانی از الگوهای include و exclude
• تشخیص hard link در فایل‌سیستم‌های Windows
• محاسبهٔ محافظه‌کارانهٔ فضای قابل‌بازیابی
• گزارش خوانا در ترمینال یا خروجی JSON
• نمایش progress bar برای مراحل اسکن و هش‌گذاری
• لغو امن با Ctrl+C بدون تولید گزارش ناقص
• ثبت خطاهای غیرمرگبار مانند فایل‌های غیرقابل‌خواندن در بخش warnings

نحوهٔ کار

DupeScan برای سریع‌تر و کم‌حافظه‌تر شدن، فایل‌ها را در چند مرحله پردازش می‌کند:

1. گذر اول: پوشه‌ها پیمایش می‌شوند و فقط تعداد فایل‌ها بر اساس اندازه ثبت می‌شود.
2. انتخاب کاندیداها: اندازه‌هایی که فقط یک بار دیده شده‌اند کنار گذاشته می‌شوند؛ چنین فایل‌هایی قطعاً تکراری نیستند.
3. گذر دوم: مسیر فایل‌هایی که اندازهٔ مشترک دارند جمع‌آوری می‌شود.
4. هش‌گذاری: محتوای کاندیداها به‌صورت stream و موازی با BLAKE3 هش می‌شود.
5. گروه‌بندی: فقط فایل‌هایی که هم اندازه و هم هش یکسان دارند تکراری محسوب می‌شوند.
6. تحلیل فایل فیزیکی: شناسهٔ فایل بررسی می‌شود تا hard linkها از کپی‌های مستقل تفکیک شوند.
7. گزارش: گروه‌ها، فضای قابل‌بازیابی، آمار عملکرد و warningها نمایش داده می‌شوند.

DupeScan هیچ فایلی را حذف یا تغییر نمی‌دهد؛ این ابزار فقط اسکن و گزارش تولید می‌کند.

پیش‌نیازها و ساخت

ابتدا Rust را روی Windows نصب کنید. سپس در PowerShell مخزن را clone و نسخهٔ release را build کنید:

git clone https://github.com/iarash84/dupescan.git
cd dupescan
cargo build --release

فایل اجرایی Windows در مسیر target\release\dupescan.exe ساخته می‌شود.

برای اجرا بدون build جداگانه نیز می‌توانید از Cargo استفاده کنید:

cargo run --release -- scan .

استفادهٔ پایه

نمایش راهنما:

dupescan --help
dupescan scan --help

اسکن پوشهٔ فعلی:

dupescan scan .

اسکن یک پوشهٔ مشخص:

dupescan scan "C:\Users\Admin\Downloads"

مثال‌های کاربردی

اسکن تمام دیسک‌های محلی:

dupescan scan --all-disks

اسکن تمام دیسک‌ها همراه با حافظه‌های removable:

dupescan scan --all-disks --include-removable

نادیده گرفتن فایل‌های کوچک‌تر از ۱۰ مگابایت:

dupescan scan . --min-size 10MB

اسکن فقط تصاویر JPEG و PNG:

dupescan scan . --include "*.jpg" --include "*.png"

اسکن چند نوع فایل ویدیویی با یک الگو:

dupescan scan . --include "*.{mp4,mkv,avi,mov}"

نادیده گرفتن پوشه‌های توسعه:

dupescan scan . --exclude node_modules --exclude target --exclude .git

ترکیب include و exclude؛ در صورت تطابق هر دو، exclude اولویت دارد:

dupescan scan . --include "*.jpg" --exclude "**/thumbnails/**"

استفاده از ۸ thread برای هش‌گذاری:

dupescan scan . --threads 8

نمایش هش BLAKE3 در گزارش متنی:

dupescan scan . --show-hash

ذخیرهٔ گزارش متنی در فایل:

dupescan scan . --output duplicates.txt

تولید گزارش JSON برای پردازش توسط ابزارهای دیگر:

dupescan scan . --format json --output duplicates.json

اجرای بدون progress bar، مناسب اسکریپت و CI:

dupescan scan . --no-progress --format json --output duplicates.json

الگوهای فیلتر

گزینهٔ --include فقط روی فایل‌ها اثر دارد و پیمایش پوشه‌ها را متوقف نمی‌کند. گزینهٔ --exclude روی فایل‌ها و پوشه‌ها اثر دارد؛ اگر پوشه‌ای exclude شود، زیرشاخهٔ آن نیز پیمایش نخواهد شد. هر دو گزینه را می‌توان چند بار تکرار کرد.

الگو	کاربرد
*.jpg	فایل‌های JPEG در هر عمق
*.{jpg,png}	فایل‌های JPEG و PNG
node_modules	هر ورودی با این نام
**/target/**	محتوای پوشه‌های target
documents/**/*.pdf	فایل‌های PDF زیر documents
C:/Windows/**	شاخهٔ Windows در اسکن دیسک کامل

واحدهای اندازه

گزینهٔ --min-size عدد صحیح و واحدهای B، KB، MB، GB، TB و شکل‌های KiB، MiB، GiB، TiB را می‌پذیرد. محاسبه به‌صورت دودویی و بر پایهٔ ۱۰۲۴ است.

500       500 bytes
500B      500 bytes
10KB      10 KiB
25MB      25 MiB
2GB       2 GiB
1TB       1 TiB

مقادیر اعشاری مانند 1.5GB پشتیبانی نمی‌شوند.

hard link و فضای قابل‌بازیابی

دو مسیر ممکن است نام‌های متفاوتی داشته باشند اما به یک فایل فیزیکی اشاره کنند. DupeScan این مسیرها را به‌عنوان hard-link alias گزارش می‌کند و آن‌ها را چند بار در فضای قابل‌بازیابی حساب نمی‌کند.

اگر شناسهٔ فیزیکی یک فایل قابل خواندن نباشد، برنامه آن فایل را قابل حذف فرض نمی‌کند. این رفتار باعث می‌شود مقدار فضای قابل‌بازیابی محافظه‌کارانه باشد.

خروجی و کدهای خروج

• حالت پیش‌فرض text یک گزارش خوانا شامل خلاصه، گروه‌ها، عملکرد و warningها تولید می‌کند.
• حالت json یک سند pretty-printed با نسخهٔ schema، خلاصه، آمار عملکرد، گروه‌ها و warningها تولید می‌کند.
• بدون --output، گزارش روی standard output نوشته می‌شود؛ پیام شروع و progress روی standard error قرار می‌گیرد.
• خروج موفق کد 0، خطای برنامه کد 1 و لغو با Ctrl+C کد 130 دارد.
• در صورت لغو هنگام اسکن یا هش‌گذاری، فایل گزارش ناقص ساخته نمی‌شود.
• گزارش فایل ابتدا در یک فایل موقت نوشته و سپس به‌صورت atomic جایگزین می‌شود؛ در نتیجه خطای نوشتن نیز گزارش قبلی را ناقص نمی‌کند.

تست و بررسی کد

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

مجوز

این پروژه با مجوز آزاد و سادهٔ MIT منتشر شده است. می‌توانید از کد استفاده کنید، آن را تغییر دهید و بازتوزیع کنید؛ به شرط آنکه اعلان copyright و متن مجوز در نسخه‌های نرم‌افزار باقی بمانند. جزئیات کامل در فایل LICENSE قرار دارد.

---

English

Overview

DupeScan is built specifically for Windows. It recursively scans one or more filesystem roots and groups files whose contents are genuinely identical. It does not rely on filenames: files are first compared by size, then same-size candidates are hashed with BLAKE3.

Hard links are detected as well, so multiple paths pointing to the same physical file do not inflate the recoverable-space estimate.

Features

• Recursively scan one directory or every local disk
• Memory-conscious two-pass candidate discovery
• Parallel BLAKE3 hashing with a configurable worker count
• Repeatable include and exclude glob filters
• Hard-link detection on Windows filesystems
• Conservative recoverable-space calculation
• Human-readable terminal reports and structured JSON output
• Progress indicators for traversal and hashing
• Safe Ctrl+C cancellation without partial reports
• Non-fatal filesystem errors collected as report warnings

How it works

DupeScan processes files in several stages:

1. First pass: traverse the roots and count files by size without retaining every path.
2. Candidate selection: discard sizes seen only once, because those files cannot have duplicates.
3. Second pass: retain paths only for files whose sizes are repeated.
4. Hashing: stream candidate contents through BLAKE3 in parallel.
5. Grouping: consider files duplicates only when both size and hash match.
6. Physical-file analysis: inspect file identities to distinguish independent copies from hard-link aliases.
7. Reporting: render duplicate groups, recoverable bytes, performance statistics, and warnings.

DupeScan never deletes or modifies files. It is a read-only scanner and reporter.

Requirements and build

Install Rust on Windows, then clone and build the release binary from PowerShell:

git clone https://github.com/iarash84/dupescan.git
cd dupescan
cargo build --release

The Windows executable is written to target\release\dupescan.exe.

You can also run the project directly through Cargo:

cargo run --release -- scan .

Basic usage

Show command help:

dupescan --help
dupescan scan --help

Scan the current directory:

dupescan scan .

Scan a specific directory:

dupescan scan "C:\Users\Admin\Downloads"

Practical examples

Scan all local disks:

dupescan scan --all-disks

Include removable disks in automatic discovery:

dupescan scan --all-disks --include-removable

Ignore files smaller than 10 MiB:

dupescan scan . --min-size 10MB

Scan only JPEG and PNG images:

dupescan scan . --include "*.jpg" --include "*.png"

Scan several video formats with one glob:

dupescan scan . --include "*.{mp4,mkv,avi,mov}"

Exclude common development directories:

dupescan scan . --exclude node_modules --exclude target --exclude .git

Combine filters; exclusions take precedence when both match:

dupescan scan . --include "*.jpg" --exclude "**/thumbnails/**"

Use eight hashing workers:

dupescan scan . --threads 8

Include BLAKE3 hashes in the report:

dupescan scan . --show-hash

Write a text report to a file:

dupescan scan . --output duplicates.txt

Write JSON for use by another tool:

dupescan scan . --format json --output duplicates.json

Disable progress output for scripts or CI:

dupescan scan . --no-progress --format json --output duplicates.json

Filter rules

--include applies only to files and does not prevent directory traversal. --exclude applies to both files and directories; excluding a directory prunes its entire subtree. Both options may be repeated.

Pattern	Matches
*.jpg	JPEG files at any depth
*.{jpg,png}	JPEG and PNG files
node_modules	Any entry named node_modules
**/target/**	Everything inside target directories
documents/**/*.pdf	PDF files below documents
C:/Windows/**	The Windows tree during a full-disk scan

Size syntax

--min-size accepts an integer followed by B, KB, MB, GB, TB, or the equivalent KiB, MiB, GiB, and TiB suffixes. Units use binary multiples based on 1024.

500       500 bytes
500B      500 bytes
10KB      10 KiB
25MB      25 MiB
2GB       2 GiB
1TB       1 TiB

Decimal values such as 1.5GB are not supported.

Hard links and recoverable space

Different paths can reference the same physical file. DupeScan reports those paths as hard-link aliases and does not count them multiple times when estimating recoverable space.

If a physical identity cannot be read, that path is not assumed to be removable. This keeps the recoverable-space estimate conservative.

Output and exit codes

• The default text format contains a summary, duplicate groups, performance data, and warnings.
• The json format contains a versioned schema, summary, performance data, groups, and warning samples.
• Without --output, the report is written to standard output; startup and progress messages use standard error.
• Success exits with code 0, application errors with 1, and Ctrl+C cancellation with 130.
• Cancellation during scanning or hashing does not create a partial report file.
• File reports are written to a temporary sibling and atomically replaced, so write failures do not corrupt an existing report.

Development checks

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

License

This project is released under the permissive MIT License. You may use, modify, and redistribute the code provided that the copyright and license notices are retained. See LICENSE for the full terms.