tidyfiles 0.12.1
TidyFiles is a user-friendly, lightweight CLI tool designed to bring order to your Downloads (or any other) folder! It intelligently organizes files by type and keep logs of all the sorting magic.
License: MIT
Requires Python: >=3.10

# TidyFiles

![TidyFiles Logo](https://i.imgur.com/VkDL4QU.jpeg)

[![PyPI - Version](https://img.shields.io/pypi/v/tidyfiles)](https://pypi.org/project/tidyfiles/)
[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![codecov](https://codecov.io/gh/RYZHAIEV-SERHII/TidyFiles/branch/main/graph/badge.svg)](https://codecov.io/gh/RYZHAIEV-SERHII/TidyFiles)
[![Tests](https://github.com/RYZHAIEV-SERHII/TidyFiles/actions/workflows/tests.yml/badge.svg)](https://github.com/RYZHAIEV-SERHII/TidyFiles/actions)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat&logo=github)](CONTRIBUTING.md)

**TidyFiles** is a user-friendly, lightweight CLI tool designed to bring order to your Downloads (or any other) folder!
It intelligently organizes files by type and keeps logs of all the sorting magic.

## 🌟 Features

- **Smart Organization**: Automatically categorizes files by type (images, documents, videos, etc.)
- **Extensive Format Support & Nested Sorting**: Organizes a wide variety of file types into relevant categories and subcategories (e.g., `documents/ebooks`, `archives/installers`).
- **Operation History**: Track and manage all file operations with detailed history
    - View session history with source and destination directories
    - Filter history by session ID or limit number of entries
    - Detailed operation logs with timestamps and status
- **Undo Support**: Revert specific operations or entire sessions safely
    - Undo individual file moves or directory deletions
    - Revert entire sessions with a single command
    - Independent operation handling - undo specific files without affecting others
    - Operation status tracking (completed, partially_undone, undone)
- **Session Management**: Track operations by session with detailed status information
    - Group operations by session for better organization
    - Track session status and completion
    - View session details including source/destination paths
- **Dry Run Mode**: Preview changes with `--dry-run` before actual organization
- **Flexible Configuration**: Customize source and destination directories
- **Detailed Logging**: Track all operations with console and file logging
- **Rich CLI Interface**: Beautiful command-line interface with progress indicators
- **Safe Operations**: Maintains file integrity during organization

## 🔧 Tech Stack

- **Core Dependencies**
    - Python >=3.10: Modern Python features
    - Typer: Elegant CLI interface
    - Rich: Beautiful terminal formatting
    - Loguru: Advanced logging
    - Click: CLI framework (Typer dependency)

- **Development Tools**
    - Ruff: Fast Python linter and formatter
    - Pre-commit: Automated code quality checks
    - Semantic Release: Automated versioning

- **Testing Framework**
    - PyTest: Comprehensive test coverage
    - Coverage reporting: Detailed test coverage analysis

## 🚀 Getting Started

### Installation

```bash
pip install tidyfiles
```

### Basic Usage

```bash
# Organize files in a specific directory
tidyfiles --source-dir /path/to/your/folder

# Undo last session if something went wrong
tidyfiles undo
```

### Advanced Usage

* ###### Dry run to preview changes

```bash
tidyfiles --source-dir ~/Downloads --dry-run
```

* ###### Specify custom destination

```bash
tidyfiles --source-dir ~/Downloads --destination-dir ~/Organized
```

* ###### Custom logging

```bash
tidyfiles --source-dir ~/Downloads --log-console-level DEBUG
```

* ###### View operation history (last 10 sessions)

```bash
tidyfiles history
```

* ###### View more history entries

```bash
tidyfiles history --limit 20
```

* ###### View the last session's details

```bash
tidyfiles history --last-session
```

* ###### View detailed session information

```bash
tidyfiles history --session 3
```

* ###### Undo entire specific session

```bash
tidyfiles undo --session 3
```

* ###### Undo specific operation in a session

```bash
tidyfiles undo --session 3 --number 2
```

---

**_If you decide to make cleanup you can use:_**

* ###### Clear the log file

```bash
tidyfiles --clear-log
```

* ###### Clear the entire history

```bash
tidyfiles history --clear-history
```


## 📁 Example Usage

### Initial State

```plaintext
Downloads/
├── photo1.jpg
├── document.pdf
├── video.mp4
├── archive.zip
├── song.mp3
├── unknown.xyz
├── image.iso
├── script.py
├── report.epub
├── utility.deb
├── driver.exe
└── Telegram Desktop/
    ├── photo2.jpg
    └── photo3.jpg
```

### After Organization

```plaintext
Downloads/
├── images/
│   ├── photo1.jpg
│   ├── photo2.jpg
│   └── photo3.jpg
├── documents/
│   ├── document.pdf
│   └── ebooks/
│       └── report.epub
├── videos/
│   └── video.mp4
├── music/
│   └── song.mp3
├── archives/
│   ├── archive.zip
│   ├── installers/
│   │   ├── windows/
│   │   │   └── driver.exe
│   │   └── unix/
│   │       └── utility.deb
│   └── disk_images/
│       └── image.iso
├── code/
│   └── scripts/
│       └── script.py
└── other/
    └── unknown.xyz
```

### View History

```bash
$ tidyfiles history --limit 3
                                    Operation Sessions
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Session ID ┃ Date       ┃ Time     ┃ Source                             ┃ Destination                      ┃ Operations ┃ Status      ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│          3 │ 2025-04-04 │ 00:35:48 │ ~/Downloads                        │ ~/Organized                      │         13 │ completed   │
│          2 │ 2025-04-04 │ 00:34:12 │ ~/Documents                        │ ~/Organized                      │          3 │ completed   │
│          1 │ 2025-04-04 │ 00:32:05 │ ~/Desktop                          │ ~/Organized                      │          2 │ completed   │
└────────────┴────────────┴──────────┴────────────────────────────────────┴──────────────────────────────────┴────────────┴─────────────┘

```

### View detailed session information

```bash
$ tidyfiles history --session 3

Session Details
Started: 2025-04-04 00:35:48
Source: ~/Downloads
Destination: ~/Organized
Status: completed
Operations: 13
                                                Session 3 Operations
┏━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ #  ┃ Time     ┃ Type ┃ Source                                       ┃ Destination                                              ┃ Status    ┃
┡━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│  1 │ 00:35:48 │ move │ ~/Downloads/photo1.jpg                       │ ~/Organized/images/photo1.jpg                            │ completed │
│  2 │ 00:35:48 │ move │ ~/Downloads/document.pdf                     │ ~/Organized/documents/document.pdf                       │ completed │
│  3 │ 00:35:48 │ move │ ~/Downloads/video.mp4                        │ ~/Organized/videos/video.mp4                             │ completed │
│  4 │ 00:35:48 │ move │ ~/Downloads/archive.zip                      │ ~/Organized/archives/archive.zip                         │ completed │
│  5 │ 00:35:48 │ move │ ~/Downloads/song.mp3                         │ ~/Organized/music/song.mp3                               │ completed │
│  6 │ 00:35:48 │ move │ ~/Downloads/unknown.xyz                      │ ~/Organized/other/unknown.xyz                            │ completed │
│  7 │ 00:35:48 │ move │ ~/Downloads/image.iso                        │ ~/Organized/archives/disk_images/image.iso               │ completed │
│  8 │ 00:35:48 │ move │ ~/Downloads/script.py                        │ ~/Organized/code/scripts/script.py                       │ completed │
│  9 │ 00:35:48 │ move │ ~/Downloads/report.epub                      │ ~/Organized/documents/ebooks/report.epub                 │ completed │
│ 10 │ 00:35:48 │ move │ ~/Downloads/utility.deb                      │ ~/Organized/archives/installers/unix/utility.deb         │ completed │
│ 11 │ 00:35:48 │ move │ ~/Downloads/driver.exe                       │ ~/Organized/archives/installers/windows/driver.exe       │ completed │
│ 12 │ 00:35:48 │ move │ ~/Downloads/Telegram Desktop/photo2.jpg      │ ~/Organized/images/photo2.jpg                            │ completed │
│ 13 │ 00:35:48 │ move │ ~/Downloads/Telegram Desktop/photo3.jpg      │ ~/Organized/images/photo3.jpg                            │ completed │
└────┴──────────┴──────┴──────────────────────────────────────────────┴──────────────────────────────────────────────────────────┴───────────┘

```

### Undo specific session

```bash
$ tidyfiles undo --session 3
Do you want to undo all operations in this session? [y/N]: y
✔ Successfully undone all operations in session 3

```

### Undo specific operation

```bash
$ tidyfiles undo --session 3 --number 1
Do you want to undo operation 1 (~/Downloads/photo1.jpg -> ~/Organized/images/photo1.jpg)? [y/N]: y
✔ Successfully undone operation 1 in session 3
```

## 📋 Logging and History

TidyFiles maintains comprehensive logs and history:

### Console Output

- Real-time operation progress
- Configurable log levels (DEBUG, INFO, WARNING, ERROR)
- Rich formatting with colors and icons
- Operation summaries and confirmations

### File Logs

- Detailed operation logs in `~/.tidyfiles/tidyfiles.log`
- Session history in `~/.tidyfiles/history.json`
- Persistent across program restarts
- Human-readable format for easy debugging

### Logging Configuration

Configure logging with various options:

```bash
# Set console log level
tidyfiles --console-log-level DEBUG

# Disable console logging
tidyfiles --no-console-log

# Configure log rotation
tidyfiles --log-rotation "100 MB" --log-retention "30 days"

# Disable file logging
tidyfiles --no-file-log
```

## 🧰️ Contributing

We welcome contributions! Check out our [Contributing Guidelines](CONTRIBUTING.md).

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## 🎯 Future Roadmap

- 🛈 **Info Feature Expansion**: Enhance the info feature to provide detailed metadata and file information.
- 🌐 **Multi-language Interface**: Switch between different languages using `--lang` flag for global accessibility.
- 📁 **Custom Categories**: Define your own file categories and organization rules via simple configuration.
- 🔍 **Smart Deduplication**: Intelligently detect and handle duplicate files while preserving the newest versions.
- ✨ **Advanced Renaming**: Bulk rename files using patterns, dates, and custom templates.
- 🤖 **AI Organization**: Use AI to categorize files based on content, not just extensions.
- 🖥️ **GUI Interface**: Optional graphical interface for users who prefer visual file management.
- ☁️ **Cloud Integration**: Direct organization of Dropbox and Google Drive folders.
- ⏰ **Scheduled Tasks**: Set up automatic organization at specified times or intervals.
- 🗜️ **Smart Compression**: Automatically compress old or large files to save space.
- 📊 **Organization Presets**: Save and share your favorite organization patterns.
- 📈 **Usage Analytics**: Track space savings and organization patterns over time.
- 🔄 **Silent Updates**: Seamless background updates with rollback support.
- 🎨 **Terminal Themes**: Customize CLI appearance with modern color schemes.
- 🔔 **Smart Notifications**: Get notified when long-running operations complete.
- 📱 **Remote Control**: Monitor and manage operations from your mobile device.

For detailed version history and latest changes, see our [CHANGELOG](CHANGELOG.md) 📈

## 📊 Stats

- **First Release**: March 2025
- **Latest Version**: [![PyPI version](https://badge.fury.io/py/tidyfiles.svg)](https://badge.fury.io/py/tidyfiles)
- **Python Compatibility**: [![Python 3.10-3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
- **Platform Support**: Windows, macOS, Linux

### Created with ❤️ by Serhii Ryzhaiev