🗂️ TidyMate — A Safe, Simple & Private File Organizer

💡 Inspiration — Why TidyMate?

Managing a cluttered Downloads folder can be frustrating. Finding important documents, organizing screenshots, removing duplicate files, and keeping backups often requires multiple tools or manual effort.

We built TidyMate to make file management simple, safe, and accessible to everyone — directly from the terminal.

What makes TidyMate different?

🔒 Safe by Design: Every modifying operation previews the proposed changes and asks for confirmation. Files are never permanently deleted or silently overwritten.
↩️ One Undo for Everything: Reverse supported operations, including organizing, renaming, archiving, and duplicate management, with a single undo command.
🧭 Made for Humans: A beginner-friendly numbered menu, clear explanations of file types, and simple commands make file management accessible even to non-technical users.
📍 Works Where You Are: Open a terminal in any folder, type tidymate, and start managing that directory.
🪶 Private and Lightweight: No accounts, internet connection, or external dependencies required. Your files stay on your computer.
🖥️ Cross-Platform: Designed for Windows, macOS, and Linux with Python 3.8 or newer.

⚙️ What It Does

TidyMate brings essential file-management tools together in one lightweight command-line application.

#	Tool	Description	Command
1	🗂️ Tidy	Sorts files into folders such as Images, Documents, Videos, and Archives.	`tidymate tidy`
2	✏️ Rename	Bulk-renames files using lowercase names, underscores, dates, numbering, and text replacement.	`tidymate rename`
3	🕰️ Archive	Moves older files into `_Old/<year>/` based on a configurable age threshold.	`tidymate archive`
4	👯 Find Duplicates	Identifies exact duplicate files by content and optionally moves extras to a review folder.	`tidymate dupes`
5	🧹 Remove Empty Folders	Finds and removes empty directories.	`tidymate empty`
6	📊 Disk Report	Reports storage usage by category, largest files, and stale files.	`tidymate disk`
7	🌳 Folder Tree	Displays a structured view of directory contents and sizes.	`tidymate tree`
8	💾 Backup	Creates a dated ZIP backup and verifies it afterward.	`tidymate backup`
9	🔐 Checksums	Creates file fingerprints and verifies them later to detect changes or corruption.	`tidymate checksum`
10	↩️ Undo	Reverses the last supported file-changing operation.	`tidymate undo`
11	🔎 File-Type Lookup	Explains file extensions, their purpose, and where they belong.	`tidymate explain`
12	📚 Learn the Basics	Explains files, folders, previews, and undo in plain English.	`tidymate`
13	🛠️ Migrate	Converts supported legacy extension-based folder structures into the current organization format.	`tidymate migrate`

Read-only operations: Disk reports, folder trees, checksum verification, and duplicate reports inspect files without modifying them.

🚀 Use Cases

1. Organize Your Downloads Folder

Turn a cluttered Downloads folder full of PDFs, screenshots, installers, videos, and ZIP files into a structured directory.

tidymate tidy ~/Downloads --dry-run
tidymate tidy ~/Downloads

The first command previews the proposed changes. The second performs the operation after confirmation.

TidyMate can also skip files that are still being downloaded, helping avoid interference with incomplete downloads.

2. Rename Hundreds of Files at Once

Standardize filenames by converting them to lowercase, replacing spaces, numbering files, or modifying selected extensions.

tidymate rename . --lower --spaces --only jpg
tidymate rename . --number holiday

For example, numbered files can follow a consistent naming pattern:

holiday_001.jpg
holiday_002.jpg
holiday_003.jpg

3. Find Duplicate Files

Identify exact copies based on file content rather than filenames. Move extra copies into a review directory so you can inspect them manually.

tidymate dupes . --move-to ./_review

This helps reclaim storage while keeping the final deletion decision in the user's hands.

4. Archive Old Files

Move files that have not been modified for a specified period into year-based archive folders.

tidymate archive . --days 365

This keeps active folders clean while preserving older files for future reference.

5. Back Up and Verify Your Files

Create a dated ZIP backup and verify its integrity. Generate checksums to establish a baseline and compare them later to detect changes.

tidymate backup . --dest "D:\Backups"
tidymate checksum create .
tidymate checksum verify .

6. Undo Changes Safely

If an operation moves or renames files unexpectedly, use the undo command to reverse the last supported change.

tidymate undo .

This provides an additional layer of control over everyday file-management operations.

🛠️ How I Built It

TidyMate is designed as a lightweight command-line utility with an emphasis on simplicity, privacy, and safe file operations.

Python 3.8+: Core application logic and cross-platform filesystem operations.
Command-Line Interface: Commands and a numbered interactive menu for beginners and experienced users.
Filesystem Operations: File categorization, bulk renaming, archiving, duplicate handling, and directory inspection.
Content-Based Duplicate Detection: File-content comparison to identify exact duplicates.
ZIP Backups: Creation and subsequent verification of backup archives.
Checksums: File fingerprints for detecting changes between verification runs.
Undo Mechanism: Records the information required to reverse supported file operations.
Preview and Confirmation: Allows users to inspect proposed changes before applying them.

The application is intended to work locally without requiring an account, an internet connection, or third-party runtime dependencies.

🧩 Challenges I Ran Into

1. Making File Operations Reversible

Moving or renaming files is easy; reversing those operations reliably is harder. The undo mechanism needs to preserve original paths and handle conflicts when files or folders have changed since the original operation.

2. Preventing Accidental Data Loss

Bulk operations can affect hundreds of files at once. Previewing changes, requesting confirmation, avoiding silent overwrites, and keeping duplicate files available for manual review were central design considerations.

3. Detecting Duplicates Reliably

Files can have different names while containing identical data. Detecting exact duplicates requires comparing content rather than relying on filenames alone.

4. Supporting Different Operating Systems

Windows, macOS, and Linux have different path conventions and filesystem behaviors. Maintaining consistent behavior across platforms requires careful handling of paths and file operations.

5. Making the Terminal Beginner-Friendly

Many users find command-line tools intimidating. A numbered menu, readable explanations, and helpful file-type descriptions make TidyMate more approachable without sacrificing command-line efficiency.

🏆 Accomplishments I'm Proud Of

Built a unified toolkit for everyday file-management tasks.
Designed around a safety-first workflow with previews and confirmation.
Implemented an undo-oriented approach to supported file operations.
Combined organization, renaming, duplicate detection, backups, checksums, and disk analysis in one interface.
Focused on privacy by keeping file processing local.
Made essential file-management operations accessible through both commands and an interactive menu.
Designed the tool to support Windows, macOS, and Linux.

📚 What I Learned

Building TidyMate strengthened my understanding of:

Filesystem APIs, directory traversal, and path handling in Python.
Designing reversible operations and managing operation history.
Detecting duplicates through file-content comparison.
Creating and verifying ZIP backups and checksums.
Handling errors and edge cases during bulk file operations.
Designing command-line interfaces that serve both beginners and advanced users.
Building cross-platform utilities with safety and privacy as core principles.

Most importantly, I learned that a useful developer tool is not just about automating tasks — it is also about giving users confidence and control over what the automation does.

🔮 What's Next for TidyMate?

Future improvements could make TidyMate even more powerful and reliable:

Interactive Preview: Show a detailed before-and-after view of every planned change.
Safer Undo History: Support multiple operation records, clearer recovery information, and better handling of filename conflicts.
Smart File Categorization: Add configurable rules and optional content-aware organization.
Scheduled Cleanup: Allow users to run recurring organization and archival tasks.
Enhanced Duplicate Analysis: Provide size savings, duplicate groups, and easier review workflows.
Backup Improvements: Support incremental backups, configurable destinations, and stronger integrity checks.
Configuration Profiles: Let users customize folder categories, naming rules, and archive thresholds.
Improved Documentation: Add installation guides, examples, troubleshooting steps, and platform-specific instructions.
Automated Testing: Expand tests for filesystem edge cases, cross-platform compatibility, and recovery behavior.

The long-term goal is to make TidyMate a dependable, lightweight file-management companion that helps people keep their computers organized without sacrificing privacy, safety, or control.

TidyMate — Clean folders. Safe changes. Total control.