Metadata-Version: 2.5
Name: dupehunt
Version: 0.0.1
Summary: Fast, dependency-free duplicate file finder with a friendly CLI.
Project-URL: Homepage, https://github.com/lqxnjk/dupehunt
Project-URL: Source, https://github.com/lqxnjk/dupehunt
Author: lqxnjk
License: MIT
License-File: LICENSE
Keywords: cleanup,cli,dedupe,disk-usage,duplicate,duplicates,files,hash
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# dupehunt

Find duplicate files by content hash. Zero dependencies, one command, works on
Windows, macOS and Linux.

```console
$ dupehunt ~/Downloads
3 group(s), 9 file(s), 412.6 MB reclaimable

[1] 180.0 MB x 3  (360.0 MB wasted)
    /home/me/Downloads/ubuntu.iso
    /home/me/Downloads/ubuntu (1).iso
    /home/me/Downloads/backup/ubuntu.iso

[2] 26.3 MB x 2  (26.3 MB wasted)
    ...
```

## Install

```console
pip install dupehunt
```

## Usage

```console
dupehunt [paths ...] [options]
```

| Option | Meaning |
| --- | --- |
| `paths` | Files or directories to scan. Default: current directory |
| `-m, --min-size` | Skip files smaller than this. `1K`, `4M`, `1G` all accepted |
| `-a, --algo` | `blake2b` (default), `sha256`, `sha1`, `md5` |
| `-n, --top` | Show only the N largest groups |
| `--json` | Machine readable output |
| `--delete` | Delete extra copies, keeping the first path of each group |
| `--yes` | Required together with `--delete` to actually delete |

### Examples

```console
# biggest wins only, files above 10 MB
dupehunt ~/Pictures -m 10M -n 20

# feed the result to another tool
dupehunt ~/data --json > dupes.json

# preview what a cleanup would remove, without touching anything
dupehunt ~/data --delete -m 1M

# really delete the extra copies
dupehunt ~/data --delete --yes -m 1M
```

`--delete` without `--yes` is always a dry run: it prints the plan and removes
nothing. Nothing is ever deleted unless both flags are present.

## How it works

Three passes, cheapest first, so a full disk scan stays fast:

1. Group files by exact size. Unique sizes drop out immediately.
2. Hash the first 8 KiB of each remaining candidate.
3. Hash the whole file only for candidates that still collide.

Symlinks are never followed, and hard links to an already seen inode are counted
once, so the same physical data is not reported as duplicates of itself.

## Use as a library

```python
from pathlib import Path
from dupehunt import find_duplicates, total_wasted

groups = find_duplicates([Path(".")], n_min_size=1024 * 1024)
for group in groups:
    print(group.size, group.wasted, [str(p) for p in group.paths])
print(total_wasted(groups))
```

## License

MIT
