Metadata-Version: 2.4
Name: foldr
Version: 0.2.0
Summary: Smart, predictable CLI file organizer with world-class TUI
Author-email: Muhammad Qasim <amkassim444@gmail.com>
Project-URL: Homepage, https://github.com/qasimio/Foldr
Project-URL: Source Code, https://github.com/qasimio/Foldr
Project-URL: Bug Tracker, https://github.com/qasimio/Foldr/issues
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=3.0.0
Requires-Dist: tabulate>=0.9.0
Requires-Dist: colorama>=0.4.6
Provides-Extra: toml
Requires-Dist: tomli>=2.0; extra == "toml"
Provides-Extra: magic
Requires-Dist: python-magic==0.4.27; extra == "magic"
Dynamic: license-file

# FOLDR

[![PyPI Version](https://img.shields.io/pypi/v/foldr?cacheSeconds=300)](https://pypi.org/project/foldr/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](#)
[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/qasimio/foldr/blob/main/LICENSE)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/foldr?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLUE&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/foldr)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](#)
[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-pink?logo=github)](https://github.com/sponsors/qasimio)

### Safe, fast, and predictable CLI file organizer.

**FOLDR** cleans messy directories by organizing files into categorized folders  
without modifying existing folder structures.

Preview everything safely using `--dry-run` before any file is moved.

---

## Quick Example

```bash
foldr ~/Downloads --dry-run
```

---

### Features

- Organizes files by extension into clear categories
- Never modifies or moves existing folders
- Dry-run mode to preview actions safely
- Handles filename conflicts automatically
- Cross-platform (Windows, macOS, Linux)

---

## Support

If **FOLDR** saves you time or is useful in your workflow,
consider supporting continued development:

❤️ https://github.com/sponsors/qasimio

---

### Installation

```bash
pip install foldr
```

Requires Python 3.9+.

---

### Usage

Organize a directory:

```bash
foldr <directory>
```

Preview actions without moving files:

```bash
foldr <directory> --dry-run
```

Example:

```bash
foldr ~/Downloads --dry-run
```

> **Note (paths with spaces):**
>
> Wrap paths containing spaces in quotes.
>
> ```
> foldr "D:\My Downloads" --dry-run
> ```

---

### How It Works

- Files are grouped into predefined categories based on extension
- Category folders are created only when needed
- Existing filenames are safely renamed if conflicts occur
- Directories are detected, counted, and left untouched

---

### Safety First

- Folders are never modified
- Use `--dry-run` to preview changes
- No recursive behavior (by design)

Future versions may introduce optional recursive mode.

---

### Example Output

```
Mode: DRY RUN

report.pdf -> Documents
song.mp3 -> Audio
script.py -> Code

Total items: 24
Skipped directories: 6
Documents: 3
Audio: 1
Code: 1
Other files: 2
```

---

### Roadmap

- Optional `--recursive` flag
- User-defined category configuration
- Exclusion rules

---

### Author

**Muhammad Qasim**

GitHub: https://github.com/qasimio  
LinkedIn: https://www.linkedin.com/in/qasimio/

---

### License

MIT License
