Metadata-Version: 2.4
Name: dupegun
Version: 2.3.0
Summary: Cross-platform duplicate file finder and cleaner
Author-email: Prasanna B <prasannab806@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Prasanna B
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/Prasanna-Balakrishnan/dupegun
Project-URL: Repository, https://github.com/Prasanna-Balakrishnan/dupegun
Project-URL: Bug Tracker, https://github.com/Prasanna-Balakrishnan/dupegun/issues
Keywords: duplicate,files,cli,disk,cleaner,cross-platform
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: tui
Requires-Dist: textual>=0.50; extra == "tui"
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == "watch"
Provides-Extra: all
Requires-Dist: textual>=0.50; extra == "all"
Requires-Dist: watchdog>=3.0; extra == "all"
Dynamic: license-file



# dupegun 🔫

> A fast, cross-platform command-line tool to find and eliminate duplicate files.

![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
![PyPI](https://img.shields.io/pypi/v/dupegun.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)

---

## What is dupegun?

**dupegun** scans your folders, detects duplicate files using a fast 3-pass hashing engine, and lets you delete, move, or hard-link them — all from your terminal. It works on every file type and every major operating system.

No GUI. No bloat. Just fast, safe, and simple.

---

## Install

```bash
# Core install
pip install dupegun

# With TUI browser
pip install "dupegun[tui]"

# With watch mode
pip install "dupegun[watch]"

# Everything
pip install "dupegun[all]"

```

Requires Python 3.9 or higher.

---

## Quick Start

```bash
# Scan a folder and see all duplicates
dupegun scan ~/Downloads

# Interactive TUI browser
dupegun tui ~/Downloads

# Monitor a folder for new duplicates
dupegun watch ~/Downloads

# Preview what would be deleted (nothing actually deleted)
dupegun delete ~/Downloads --strategy newest

# Actually delete duplicates
dupegun delete ~/Downloads --strategy newest --no-dry-run

# Run a system and configuration check
dupegun doctor

```

---

## Commands

### `scan` — find duplicates

```bash
dupegun scan <path> [options]

```

```bash
# Scan a single folder
dupegun scan ~/Downloads

# Scan multiple folders at once
dupegun scan ~/Downloads ~/Documents ~/Desktop

# Skip files smaller than 1 MB
dupegun scan ~/Downloads --min-size 1MB

# Scan specific size ranges (e.g., between 1MB and 100MB)
dupegun scan ~/Downloads --min-size 1MB --max-size 100MB

# Regex filename filter (e.g., files starting with "Copy of")
dupegun scan ~/Downloads --pattern "Copy of.*"

# Limit how deep the scan goes (e.g., 2 levels deep)
dupegun scan ~/Downloads --depth 2

# Speed up scans on SSDs using parallel hashing threads
dupegun scan ~/Downloads --workers 4

# Only scan image files
dupegun scan ~/Downloads --type .jpg --type .png --type .gif

# Skip specific folders
dupegun scan C:\ --exclude Windows --exclude "Program Files"

# Sort results by wasted space, size, count, or path
dupegun scan ~/Downloads --sort wasted

# Clean output for scripts (disable colors)
dupegun scan ~/Downloads --no-color

# Export results
dupegun scan ~/Downloads --json results.json
dupegun scan ~/Downloads --csv results.csv
dupegun scan ~/Downloads --html report.html

```

---

### `tui` — interactive terminal browser

Browse duplicates visually, mark files for deletion, and act — all from your keyboard.

```bash
# Requires: pip install "dupegun[tui]"
dupegun tui ~/Downloads
dupegun tui ~/Downloads --strategy newest
dupegun tui ~/Downloads --no-dry-run   # actually delete (default is dry-run)

```

**Controls:**

| Key | Action |
| --- | --- |
| Arrow keys / j k | Navigate files |
| Space | Toggle file for deletion |
| A | Mark all duplicates in group (keep first) |
| U | Unmark all in group |
| D | Delete all marked files in current group |
| S | Skip to next group |
| Q / Escape | Quit |

---

### `watch` — monitor for new duplicates

Watch a folder in real time and get an alert whenever a duplicate file appears.

```bash
# Requires: pip install "dupegun[watch]"
dupegun watch ~/Downloads

```

Press **Ctrl+C** to stop watching.

---

### `delete` — remove duplicates

```bash
dupegun delete <path> [options]

```

```bash
# Preview (dry-run is ON by default — nothing deleted)
dupegun delete ~/Downloads --strategy newest

# Actually delete
dupegun delete ~/Downloads --strategy newest --no-dry-run

# Auto-delete by age (only delete copies older than 30 days)
dupegun delete ~/Downloads --older-than 30 --no-dry-run

# Save a log of everything deleted
dupegun delete ~/Downloads --no-dry-run --log deleted.log

```

---

### `symlink` & `hardlink` — save space

Replace duplicates with links pointing to a single kept file. Symlinks work across different drives, whereas hardlinks must be on the same drive.

```bash
dupegun symlink ~/Photos --strategy newest --no-dry-run
dupegun hardlink ~/Videos --no-dry-run

```

---

### `move` — quarantine duplicates

```bash
dupegun move ~/Downloads --dest ~/quarantine --no-dry-run

```

---

### Utilities: `compare`, `stats`, `open`, `doctor`, `config`, `completion`

* **`compare`**: Find files that exist in *both* folders by content. Great for backups.
```bash
dupegun compare ~/Downloads ~/Backup

```


* **`stats`**: Get a quick overview of total files, duplicate groups, and wasted space.
```bash
dupegun stats ~/Downloads

```


* **`open`**: Open a file directly using your OS default application.
```bash
dupegun open ~/Downloads/duplicate_file.txt

```


* **`doctor`**: Check system health, verify dependencies, and validate your config.
```bash
dupegun doctor

```


* **`completion`**: Setup shell tab-completion for Bash, Zsh, or Fish.
```bash
dupegun completion

```


* **`config`**: Create and manage your `~/.dupegun.toml` defaults.
```bash
dupegun config --init

```



---

## Plugin system

Extend dupegun with custom strategies without touching the core code.

**Create a plugin file:**

```python
# my_plugin.py
from dupegun.plugins import register_strategy

@register_strategy("by_name")
def keep_alphabetically(paths):
    """Keep the file whose name comes first alphabetically."""
    return min(paths, key=lambda p: p.name.lower())

```

**Use it:**

```bash
dupegun delete ~/Downloads --plugin my_plugin.py --strategy by_name --no-dry-run

```

---

## Options

| Option | Commands | Description | Default |
| --- | --- | --- | --- |
| `--strategy <name>` | delete, move, symlink, hardlink, tui | Which copy to keep: shortest, newest, oldest, or plugin | shortest |
| `--dry-run` | delete, move, symlink, hardlink, tui | Preview without making any changes | ON |
| `--no-dry-run` | delete, move, symlink, hardlink, tui | Actually perform the action | — |
| `--older-than <days>` | delete | Only delete copies modified more than this many days ago | — |
| `--log <file>` | delete | Append a TSV log of every deleted file | — |
| `--plugin <file>` | delete, tui | Load a plugin .py file (repeatable) | — |
| `--config <file>` | all | Path to a config TOML file | ~/.dupegun.toml |
| `--min-size <size>` | all | Skip files smaller than this (e.g. 1MB) | 1 byte |
| `--max-size <size>` | all | Skip files larger than this (e.g. 100MB) | no limit |
| `--pattern <regex>` | all | Only scan filenames matching this regex | none |
| `--depth <n>` | all | Maximum directory depth to scan | unlimited |
| `--workers <n>` | all | Number of parallel hashing threads | 1 |
| `--type <ext>` | all | Only include files with this extension (repeatable) | all types |
| `--exclude <name>` | all | Skip any folder with this name (repeatable) | none |
| `--sort <key>` | scan | Sort output by size, count, path, or wasted | — |
| `--summary` | scan | Print total wasted space only, no file list | OFF |
| `--count` | scan | Print group count and wasted space, then exit | OFF |
| `--no-color` | all | Disable colored terminal output | OFF |
| `--json <file>` | scan | Export scan results to JSON | — |
| `--csv <file>` | scan | Export scan results to CSV | — |
| `--html <file>` | scan | Export a self-contained HTML report | — |

---

## How it works

dupegun uses a **3-pass engine** to detect duplicates accurately and efficiently:

```
Pass 1 — Group files by exact byte size
         (files with unique sizes are skipped immediately)

Pass 2 — Hash the first 4 KB of each size-match
         (quick pre-filter before full hashing)

Pass 3 — Full SHA-256 hash of remaining candidates
         (guaranteed accurate duplicate detection)

```

---

## Supported file types

dupegun works on **all file types** — it compares raw file contents, not names or extensions.

| Category | Examples |
| --- | --- |
| Documents | `.pdf` `.docx` `.xlsx` `.txt` |
| Images | `.jpg` `.png` `.gif` `.webp` |
| Videos | `.mp4` `.mkv` `.avi` `.mov` |
| Audio | `.mp3` `.wav` `.flac` `.aac` |
| Archives | `.zip` `.rar` `.7z` `.tar` `.gz` |
| Code | `.py` `.js` `.html` `.css` `.java` |

---

## Platform support

| Platform | Supported |
| --- | --- |
| Windows | Yes |
| Linux | Yes |
| macOS | Yes |

---

## Changelog

### v2.3.0

* **`open` command**: Quickly open a file directly using your OS default application.
* **`--no-color` flag**: Disable colored terminal output for CI pipelines and logging.
* **Shell Completion**: Use `dupegun completion` for Bash, Zsh, and Fish setup instructions.
* **`doctor` command**: Instantly check system health, dependencies, and validate config files.

### v2.2.0

* **`symlink` command**: Replace duplicates with symbolic links.
* **Parallel Hashing**: Added `--workers <n>` to utilize concurrent threads for a massive speed boost on SSDs.
* **Recursion Limits**: Added `--depth <n>` flag to limit how deep a scan navigates.
* **Sorting**: Added `--sort` flag to `scan` for ordering by size, count, path, or wasted space.

### v2.1.0

* Stability improvements and quick win optimizations for the core scanner.

### v2.0.0

* **`tui` command**: Interactive terminal UI — browse duplicate groups, mark files, delete with keyboard shortcuts.
* **`watch` command**: Monitor a folder in real time and alert when a duplicate appears.
* **`config` command**: Create and manage `~/.dupegun.toml` to save your preferred defaults.
* **Plugin system**: Register custom keep-strategies with `@register_strategy("name")`.

### v1.3.0

* **`stats` command**: Show total files, size, duplicate groups, and wasted space percentage.
* **`--html` flag**: Generate a self-contained HTML report.
* **`--log` flag**: Append a TSV audit log of every deleted file.

### v1.2.0

* **`compare` command**: Compare two directories to find cross-duplicates.
* **`--older-than` flag**: Auto-delete files based on age.
* Size parsing supports human-readable formats (e.g., `1MB`, `2GB`).

### v1.1.0

* **`--type` filter**: Scan only specific file extensions.
* **`--exclude` filter**: Skip folders by name.

### v1.0.0

* Initial release: `scan`, `delete`, `move`, `hardlink` commands.

---

## Contributing

Pull requests are welcome! To get started:

```bash
git clone [https://github.com/Prasanna-Balakrishnan/dupegun.git](https://github.com/Prasanna-Balakrishnan/dupegun.git)
cd dupegun
pip install -e ".[all]"
pip install pytest
python -m pytest tests/ -v

```

---

## License

MIT — see [LICENSE](https://www.google.com/search?q=LICENSE) for details.

---

## Author

Made by **Prasanna B**

GitHub: https://github.com/Prasanna-Balakrishnan/dupegun

If this tool helped you, consider giving it a star on GitHub!

```
