tidyfiles 0.12.0

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.

TidyFiles

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
• Optional Force Mode (--force): Allow normally restricted actions (e.g., operations in protected/system directories, or overwriting files) by explicitly specifying --force on the command line. Use with caution for non-reversible actions.

🔧 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

pip install tidyfiles

Basic Usage

# 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

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

• Specify custom destination

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

• Custom logging

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

• View operation history (last 10 sessions)

tidyfiles history

• View more history entries

tidyfiles history --limit 20

• View the last session's details

tidyfiles history --last-session

• View detailed session information

tidyfiles history --session 3

• Undo entire specific session

tidyfiles undo --session 3

• Undo specific operation in a session

tidyfiles undo --session 3 --number 2

• Force operation in protected/system directories (Dangerous!)

tidyfiles --source-dir /some/protected/folder --force

• By default, TidyFiles will block potentially unsafe operations, such as in system directories or for non-writable files. The --force flag overrides this safety check. Use with caution.

---

If you decide to make cleanup you can use:

• Clear the log file

tidyfiles --clear-log

• Clear the entire history

tidyfiles history --clear-history

📁 Example Usage

Initial State

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

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

$ 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

$ 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

$ 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

$ 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:

# 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.

📄 License

This project is licensed under the MIT License. See the 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 📈

📊 Stats

• First Release: March 2025
• Latest Version:
• Python Compatibility:
• Platform Support: Windows, macOS, Linux

Created with ❤️ by Serhii Ryzhaiev