From d4e8dbc6b3671c8638f77d80c8bbd1ee97b5ec67 Mon Sep 17 00:00:00 2001 From: glitchySid Date: Fri, 2 Jan 2026 00:55:29 +0530 Subject: [PATCH] docs: restructure documentation into organized files Split the 630-line README.md into focused, well-organized documentation: - README.md: Concise overview with quick start and links - docs/INSTALLATION.md: Installation instructions and setup - docs/CONFIGURATION.md: Configuration options and custom categories - docs/USAGE.md: Command-line options and usage examples - docs/HOW_IT_WORKS.md: Architecture and internal processes - docs/TROUBLESHOOTING.md: Common issues and solutions - docs/DEVELOPMENT.md: Project structure and development guide - docs/CONTRIBUTING.md: Contribution guidelines and standards Benefits: - Main README is now clean and welcoming (~150 lines vs 630) - Each doc has a clear, focused purpose - Better navigation with cross-linking between docs - Follows GitHub best practices with docs/ directory - Easier to maintain and update specific sections --- README.md | 628 +++++++--------------------------------- docs/CONFIGURATION.md | 202 +++++++++++++ docs/CONTRIBUTING.md | 494 +++++++++++++++++++++++++++++++ docs/DEVELOPMENT.md | 502 ++++++++++++++++++++++++++++++++ docs/HOW_IT_WORKS.md | 345 ++++++++++++++++++++++ docs/INSTALLATION.md | 121 ++++++++ docs/TROUBLESHOOTING.md | 518 +++++++++++++++++++++++++++++++++ docs/USAGE.md | 329 +++++++++++++++++++++ 8 files changed, 2621 insertions(+), 518 deletions(-) create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/HOW_IT_WORKS.md create mode 100644 docs/INSTALLATION.md create mode 100644 docs/TROUBLESHOOTING.md create mode 100644 docs/USAGE.md diff --git a/README.md b/README.md index 022e4da..816adef 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,6 @@ NoEntropy is a smart command-line tool that organizes your cluttered Downloads folder automatically. It uses Google's Gemini AI to analyze files, understand their content, and categorize them into organized folder structures. Say goodbye to manually sorting through hundreds of downloads! -### Use Cases - -- πŸ“‚ Organize a messy Downloads folder -- πŸ€– Auto-categorize downloaded files by type and content -- πŸ” Smart sub-folder creation based on file content -- πŸš€ Batch file organization without manual effort -- πŸ’Ύ Reduce clutter and improve file system organization - ## Features - **🧠 AI-Powered Categorization** - Uses Google Gemini API for intelligent file sorting @@ -26,589 +18,186 @@ NoEntropy is a smart command-line tool that organizes your cluttered Downloads f - **πŸ’¨ Smart Caching** - Minimizes API calls with metadata-based caching (7-day expiry) - **⚑ Concurrent Processing** - Parallel file inspection with configurable limits - **πŸ‘€ Dry-Run Mode** - Preview changes without moving any files -- **πŸ”„ Retry Logic** - Exponential backoff for resilient API handling - **πŸ“ Text File Support** - Inspects 30+ text formats for better categorization - **βœ… Interactive Confirmation** - Review organization plan before execution -- **🎯 Configurable** - Adjust concurrency limits and model settings - **↩️ Undo Support** - Revert file organization changes if needed -## Prerequisites +## Quick Start -- **Rust 2024 Edition** or later -- **Google Gemini API Key** - Get one at [https://ai.google.dev/](https://ai.google.dev/) -- A folder full of unorganized files to clean up! +### Installation -## Installation +**Option 1: Download Pre-built Binary** -1. **Download Binary** - Download binary for your operating system(Windows, Linux or Mac) - ```bash - https://github.com/glitchySid/noentropy/releases - ``` -2. **Give Permisson(For Linux/Mac)** - ```bash - chmod +x binaryfilename - ``` +Download the binary for your operating system from [releases](https://github.com/glitchySid/noentropy/releases): -## Run Locally +```bash +# Linux/macOS: Give execute permissions +chmod +x noentropy -1. **Clone repository** - ```bash - git clone https://github.com/glitchySid/noentropy.git - cd noentropy - ``` - -2. **Build the application** - ```bash - cargo build --release - ``` - -3. **Run the application** - On first run, NoEntropy will guide you through interactive setup: - ```bash - ./target/release/noentropy - ``` - - Or manually create config file at `~/.config/noentropy/config.toml`: - ```bash - cp config.example.toml ~/.config/noentropy/config.toml - nano ~/.config/noentropy/config.toml - ``` - -## Configuration - -NoEntropy stores configuration in `~/.config/noentropy/config.toml` following XDG Base Directory specifications. - -### Configuration File Format - -```toml -api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k" -download_folder = "/home/user/Downloads" - -# Optional: Custom categories for file organization -categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"] +# Run NoEntropy +./noentropy ``` -| Setting | Description | Example | Required | -|---------|-------------|---------|----------| -| `api_key` | Your Google Gemini API key | `AIzaSy...` | Yes | -| `download_folder` | Path to folder to organize | `/home/user/Downloads` | Yes | -| `categories` | Custom categories for organization | `["Work", "Personal", "School"]` | No | +**Option 2: Build from Source** -### Getting a Gemini API Key +```bash +# Clone repository +git clone https://github.com/glitchySid/noentropy.git +cd noentropy -1. Visit [Google AI Studio](https://ai.google.dev/) -2. Sign in with your Google account -3. Create a new API key -4. Copy the key to your configuration file - -### Interactive Setup - -NoEntropy provides an interactive setup on first run: - -- **Missing API key?** β†’ You'll be prompted to enter it -- **Missing download folder?** β†’ You'll be prompted to specify it (with default suggestion) -- **Both missing?** β†’ You'll be guided through complete setup - -Configuration is automatically saved to `~/.config/noentropy/config.toml` after interactive setup. - -### Custom Categories - -NoEntropy allows you to define your own custom categories instead of using the default ones. This is perfect for organizing files based on your specific workflow or needs. - -#### Default Categories - -If you don't specify custom categories, NoEntropy uses these defaults: -- **Images** - PNG, JPG, GIF, SVG, etc. -- **Documents** - PDF, DOC, DOCX, TXT, MD, etc. -- **Installers** - EXE, DMG, APP, PKG, etc. -- **Music** - MP3, WAV, FLAC, M4A, etc. -- **Archives** - ZIP, TAR, RAR, 7Z, etc. -- **Code** - Source code and configuration files -- **Misc** - Everything else - -#### Using Custom Categories - -To use custom categories, add a `categories` array to your `config.toml`: - -```toml -api_key = "your_api_key_here" -download_folder = "/home/user/Downloads" -categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"] +# Build and run +cargo build --release +./target/release/noentropy ``` -**Examples of Custom Category Sets:** +### First Run -**For Students:** -```toml -categories = ["Courses", "Assignments", "Research", "Personal", "Textbooks", "Media", "Misc"] -``` - -**For Professionals:** -```toml -categories = ["Client Work", "Internal", "Invoices", "Contracts", "Marketing", "Resources", "Misc"] -``` - -**For Creatives:** -```toml -categories = ["Projects", "Assets", "References", "Client Files", "Portfolio", "Tools", "Misc"] -``` - -**For Personal Use:** -```toml -categories = ["Family", "Finance", "Health", "Home", "Travel", "Hobbies", "Misc"] -``` - -#### Tips for Custom Categories - -1. **Keep it simple** - Use 5-10 categories for best results -2. **Be specific** - More descriptive names help the AI understand better -3. **Include "Misc"** - Always have a catch-all category for unclear files -4. **Think workflow** - Organize based on how you actually use files -5. **Test first** - Use `--dry-run` to preview categorization before committing - -#### How It Works - -When you define custom categories: -1. NoEntropy sends your file list to the Gemini AI -2. The AI is instructed to categorize files into your custom categories -3. Files are organized into folders matching your category names -4. Sub-folders are still created automatically for better organization - -**Example Output with Custom Categories:** -``` -Downloads/ -β”œβ”€β”€ Work/ -β”‚ β”œβ”€β”€ Reports/ -β”‚ β”‚ └── Q4-Report.pdf -β”‚ └── Presentations/ -β”‚ └── Client-Deck.pptx -β”œβ”€β”€ Personal/ -β”‚ β”œβ”€β”€ Photos/ -β”‚ β”‚ └── vacation.jpg -β”‚ └── Documents/ -β”‚ └── resume.pdf -└── School/ - β”œβ”€β”€ Assignments/ - β”‚ └── homework.docx - └── Notes/ - └── lecture-notes.pdf -``` - -## Usage +On first run, NoEntropy will guide you through an interactive setup to configure your API key and download folder. That's it! ### Basic Usage -Organize your Downloads folder with default settings: +```bash +# Organize your downloads folder +./noentropy + +# Preview changes without moving files +./noentropy --dry-run + +# Undo the last organization +./noentropy --undo +``` + +## Documentation + +Comprehensive documentation is available in the `docs/` directory: + +- **[Installation Guide](docs/INSTALLATION.md)** - Detailed installation instructions and setup +- **[Configuration Guide](docs/CONFIGURATION.md)** - Configure API key, folders, and custom categories +- **[Usage Guide](docs/USAGE.md)** - Command-line options and usage examples +- **[How It Works](docs/HOW_IT_WORKS.md)** - Architecture, caching, and internal processes +- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions +- **[Development Guide](docs/DEVELOPMENT.md)** - Project structure and development setup +- **[Contributing Guide](docs/CONTRIBUTING.md)** - How to contribute to NoEntropy + +## Example Output ```bash -cargo run --release -``` - -### Dry-Run Mode - -Preview what would happen without moving any files: - -```bash -cargo run --release -- --dry-run -``` - -### Custom Concurrency - -Adjust the number of concurrent API calls (default: 5): - -```bash -cargo run --release -- --max-concurrent 10 -``` - -### Combined Options - -Use multiple options together: -```bash -cargo run --release -- --dry-run --max-concurrent 3 -``` - -### Undo Mode - -Revert the last file organization: - -```bash -cargo run --release -- --undo -``` - -### Change API key - -To change gemini API key: -``` - -``` - -Preview what would be undone without actually reversing changes: - -```bash -cargo run --release -- --undo --dry-run -``` - -The undo feature: -- Tracks all file moves in `~/.config/noentropy/data/undo_log.json` -- Shows a preview of files that will be restored before execution -- Handles edge cases (missing files, conflicts, permission errors) -- Automatically cleans up empty directories after undo -- Keeps undo history for 30 days with auto-cleanup - -### Recursive Mode - -Organize files in subdirectories recursively: - -```bash -cargo run --release -- --recursive -``` - -This scans all subdirectories within your download folder and organizes files from the entire directory tree, maintaining relative folder structure when creating categories. - -### Command-Line Options - -| Option | Short | Default | Description | -|--------|-------|---------|-------------| -| `--dry-run` | `-d` | `false` | Preview changes without moving files | -| `--max-concurrent` | `-m` | `5` | Maximum concurrent API requests | -| `--recursive` | None | `false` | Recursively search files in subdirectories | -| `--undo` | None | `false` | Undo the last file organization | -| `--change-key` | `false` | Changes Api Key | -| `--help` | `-h` | - | Show help message | - -## How It Works - -NoEntropy follows a five-step process to organize your files: - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 1. Scan Files β”‚ β†’ Read all files in DOWNLOAD_FOLDER (and subdir if --recursive flag is used) -β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 2. Initial Categorization β”‚ β†’ Ask Gemini to categorize by filename -β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 3. Deep Inspection β”‚ β†’ Read text files for sub-categories -β”‚ (Concurrent) β”‚ β€’ Reads file content -β”‚ β”‚ β€’ Asks AI for sub-folder -β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 4. Preview & Confirmβ”‚ β†’ Show organization plan -β”‚ β”‚ β€’ Ask user approval -β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 5. Execute Moves β”‚ β†’ Move files to organized folders -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -### Example Terminal Output - -```bash -$ cargo run --release +$ ./noentropy Found 47 files. Asking Gemini to organize... Gemini Plan received! Performing deep inspection... -Reading content of report.pdf... -Reading content of config.yaml... -Reading content of script.py... -Deep inspection complete! Moving Files..... +Deep inspection complete! --- EXECUTION PLAN --- Plan: image1.png -> Images/ Plan: document.pdf -> Documents/ -Plan: setup.exe -> Installers/ Plan: notes.txt -> Documents/Notes/ Plan: config.yaml -> Code/Config/ Plan: script.py -> Code/Scripts/ +... Do you want to apply these changes? [y/N]: y --- MOVING FILES --- Moved: image1.png -> Images/ Moved: document.pdf -> Documents/ -Moved: setup.exe -> Installers/ Moved: notes.txt -> Documents/Notes/ -Moved: config.yaml -> Code/Config/ -Moved: script.py -> Code/Scripts/ +... Organization Complete! Files moved: 47, Errors: 0 Done! ``` -#### Undo Example +## Use Cases -```bash -$ cargo run --release -- --undo +- πŸ“‚ Organize a messy Downloads folder +- πŸ€– Auto-categorize downloaded files by type and content +- πŸ” Smart sub-folder creation based on file content +- πŸš€ Batch file organization without manual effort +- πŸ’Ύ Reduce clutter and improve file system organization ---- UNDO PREVIEW --- -INFO: will restore 5 files: - Documents/report.pdf -> Downloads/ - Documents/Notes/notes.txt -> Downloads/ - Code/Config/config.yaml -> Downloads/ - Code/Scripts/script.py -> Downloads/ - Images/photo.png -> Downloads/ +## Key Features Explained -Do you want to undo these changes? [y/N]: y +### Custom Categories ---- UNDOING MOVES --- -Restored: Documents/report.pdf -> Downloads/ -Restored: Documents/Notes/notes.txt -> Downloads/ -Restored: Code/Config/config.yaml -> Downloads/ -Restored: Code/Scripts/script.py -> Downloads/ -Restored: Images/photo.png -> Downloads/ +Define your own categories instead of using defaults: -INFO: Removed empty directory: Documents/Notes -INFO: Removed empty directory: Code/Config -INFO: Removed empty directory: Code/Scripts - -UNDO COMPLETE! -Files restored: 5, Skipped: 0, Failed: 0 -``` - -## Supported Categories - -NoEntropy organizes files into these categories: - -| Category | Description | -|----------|-------------| -| **Images** | PNG, JPG, GIF, SVG, etc. | -| **Documents** | PDF, DOC, DOCX, TXT, MD, etc. | -| **Installers** | EXE, DMG, APP, PKG, etc. | -| **Music** | MP3, WAV, FLAC, M4A, etc. | -| **Archives** | ZIP, TAR, RAR, 7Z, etc. | -| **Code** | Source code and configuration files | -| **Misc** | Everything else | - -## Supported Text Formats - -NoEntropy can read and analyze the content of 30+ text file formats: - -``` -Source Code: rs, py, js, ts, jsx, tsx, java, go, c, cpp, h, hpp, rb, php, swift, kt, scala, lua, r, m -Web/Config: html, css, json, xml, yaml, yml, toml, ini, cfg, conf -Documentation: txt, md, sql, sh, bat, ps1, log -``` - -## Caching - -NoEntropy includes an intelligent caching system to minimize API calls: - -- **Location**: `.noentropy_cache.json` in project root -- **Expiry**: 7 days (old entries auto-removed) -- **Change Detection**: Uses file metadata (size + modification time) instead of full content hashing -- **Max Entries**: 1000 entries (oldest evicted when limit reached) - -### How Caching Works - -1. **First Run**: Files are analyzed and categorized via Gemini API -2. **Response Cached**: Organization plan saved with file metadata -3. **Subsequent Runs**: - - Checks if files changed (size/modification time) - - If unchanged, uses cached categorization - - If changed, re-analyzes via API -4. **Auto-Cleanup**: Removes cache entries older than 7 days - -## Undo Log - -NoEntropy tracks all file moves to enable undo functionality: - -- **Location**: `~/.config/noentropy/data/undo_log.json` -- **Retention**: 30 days (old entries auto-removed) -- **Max Entries**: 1000 entries (oldest evicted when limit reached) -- **Status Tracking**: Completed, Undone, Failed states for each move -- **Conflict Handling**: Skips files with conflicts and reports warnings - -### How Undo Works - -1. **During Organization**: Every file move is recorded with source/destination paths -2. **Undo Execution**: - - Lists all completed moves to be reversed - - Shows preview of what will be restored - - Asks for user confirmation - - Moves files back to original locations - - Handles conflicts (source exists, destination missing) - - Cleans up empty directories left behind -3. **Status Updates**: Marks successfully undone operations -4. **Auto-Cleanup**: Removes undo log entries older than 30 days - -### Undo Safety Features - -- **Preview Before Action**: Always shows what will be undone before executing -- **Conflict Detection**: Checks if source path already exists before restoring -- **Missing File Handling**: Gracefully handles files that were deleted after move -- **Partial Undo Support**: Continues even if some operations fail -- **Dry-Run Mode**: Preview undo operations without executing them - -## Troubleshooting - -### "API key not configured" - -**Solution**: NoEntropy will prompt you for your API key on first run. Alternatively, manually create `~/.config/noentropy/config.toml`: ```toml -api_key = "your_actual_api_key" -download_folder = "/home/user/Downloads" +# config.toml +categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"] ``` -### "Download folder not configured" +Perfect for organizing files based on your specific workflow. See the [Configuration Guide](docs/CONFIGURATION.md) for examples. -**Solution**: NoEntropy will prompt you for the folder path on first run. Alternatively, manually add it to your config: -```toml -download_folder = "/path/to/your/Downloads" -``` +### Smart Caching -### "API rate limit exceeded" +NoEntropy caches API responses for 7 days to minimize costs and improve performance. Files are only re-analyzed if they change (based on size and modification time). -**Solution**: -- Wait a few minutes before trying again -- Reduce `--max-concurrent` to limit API calls -- Use caching to reduce redundant requests +### Undo Functionality -### "Network error" +Made a mistake? Easily undo the last organization: -**Solution**: -- Check your internet connection -- Verify Gemini API service is operational -- Ensure firewall allows outbound HTTPS requests - -### "Failed to move file" - -**Solution**: -- Check file permissions -- Ensure destination folder is writable -- Verify source files still exist - -### "Cache corrupted" - -**Solution**: Delete `.noentropy_cache.json` and run again. A new cache will be created. - -### "No completed moves to undo" - -**Solution**: This means there are no file moves that can be undone. Either: -- No files have been organized yet -- All previous moves have already been undone -- The undo log was deleted - -### "Undo log not found" - -**Solution**: No undo history exists. Run organization first to create undo log, or check that `~/.config/noentropy/data/` directory exists. - -### "Skipping [file] - source already exists" - -**Solution**: A file already exists at the original location. The undo operation will skip it to prevent data loss. Manually check and resolve the conflict if needed. - -### "Failed to restore [file]" - -**Solution**: Check file permissions and ensure the file exists at the destination location. Other files will continue to be restored. - -## Development - -### Build in Debug Mode ```bash -cargo build +./noentropy --undo ``` -### Build in Release Mode -```bash -cargo build --release -``` +All file moves are tracked for 30 days with full conflict detection and safety features. -### Run Tests -```bash -cargo test -``` +## Requirements -### Run Clippy (Linting) -```bash -cargo clippy -``` +- **Rust 2024 Edition** or later (if building from source) +- **Google Gemini API Key** - Get one at [https://ai.google.dev/](https://ai.google.dev/) -### Check Code -```bash -cargo check -``` +## Command-Line Options + +| Option | Short | Description | +|--------|-------|-------------| +| `--dry-run` | `-d` | Preview changes without moving files | +| `--max-concurrent` | `-m` | Maximum concurrent API requests (default: 5) | +| `--recursive` | - | Recursively search files in subdirectories | +| `--undo` | - | Undo the last file organization | +| `--change-key` | - | Change Gemini API key | +| `--help` | `-h` | Show help message | + +See the [Usage Guide](docs/USAGE.md) for detailed examples and workflows. ## Project Structure -NoEntropy follows a clean modular architecture for better maintainability and testability: - ``` noentropy/ -β”œβ”€β”€ .github/ -β”‚ └── workflows/ -β”‚ └── rust.yml # CI/CD workflow +β”œβ”€β”€ docs/ # Comprehensive documentation β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ cli/ -β”‚ β”‚ β”œβ”€β”€ mod.rs # CLI module exports -β”‚ β”‚ β”œβ”€β”€ args.rs # Command-line argument definitions -β”‚ β”‚ └── orchestrator.rs # Organization & undo orchestration -β”‚ β”œβ”€β”€ files/ -β”‚ β”‚ β”œβ”€β”€ mod.rs # File module exports -β”‚ β”‚ β”œβ”€β”€ batch.rs # File batch processing -β”‚ β”‚ β”œβ”€β”€ detector.rs # File type detection -β”‚ β”‚ β”œβ”€β”€ mover.rs # File moving operations -β”‚ β”‚ └── undo.rs # Undo file operations -β”‚ β”œβ”€β”€ gemini/ -β”‚ β”‚ β”œβ”€β”€ mod.rs # Gemini API module exports -β”‚ β”‚ β”œβ”€β”€ client.rs # Gemini API client -β”‚ β”‚ β”œβ”€β”€ errors.rs # Gemini error handling -β”‚ β”‚ β”œβ”€β”€ prompt.rs # AI prompt construction -β”‚ β”‚ └── types.rs # Gemini API types -β”‚ β”œβ”€β”€ models/ -β”‚ β”‚ β”œβ”€β”€ mod.rs # Data models exports -β”‚ β”‚ β”œβ”€β”€ metadata.rs # File metadata structures -β”‚ β”‚ β”œβ”€β”€ move_record.rs # File move tracking -β”‚ β”‚ └── organization.rs # Organization plan structures -β”‚ β”œβ”€β”€ settings/ -β”‚ β”‚ β”œβ”€β”€ mod.rs # Settings module exports -β”‚ β”‚ β”œβ”€β”€ config.rs # Configuration management -β”‚ β”‚ β”œβ”€β”€ prompt.rs # Interactive configuration prompts -β”‚ β”‚ └── tests.rs # Settings tests -β”‚ β”œβ”€β”€ storage/ -β”‚ β”‚ β”œβ”€β”€ mod.rs # Storage module exports -β”‚ β”‚ β”œβ”€β”€ cache.rs # Caching system -β”‚ β”‚ └── undo_log.rs # Undo log management -β”‚ β”œβ”€β”€ main.rs # Application entry point -β”‚ └── lib.rs # Library exports -β”œβ”€β”€ Cargo.toml # Dependencies and project metadata -β”œβ”€β”€ Cargo.lock # Dependency lock file -β”œβ”€β”€ config.example.toml # Configuration template -└── README.md # This file +β”‚ β”œβ”€β”€ cli/ # Command-line interface +β”‚ β”œβ”€β”€ files/ # File operations and detection +β”‚ β”œβ”€β”€ gemini/ # AI integration +β”‚ β”œβ”€β”€ models/ # Data structures +β”‚ β”œβ”€β”€ settings/ # Configuration management +β”‚ └── storage/ # Caching and undo log +β”œβ”€β”€ Cargo.toml +└── README.md ``` -### Module Overview - -- **cli/** - Command-line interface and orchestration logic for organizing and undoing operations -- **files/** - File detection, batching, moving, and undo operations with concurrent processing -- **gemini/** - Google Gemini API integration with retry logic and intelligent prompt engineering -- **models/** - Core data structures for file metadata, move records, and organization plans -- **settings/** - Configuration management with interactive prompts and XDG directory support -- **storage/** - Persistent data layer for caching API responses and tracking undo history - -## Future Enhancements - -Based on community feedback, we're planning: - -- [x] **Custom Categories** - Define custom categories in `config.toml` -- [x] **Recursive Mode** - Organize files in subdirectories with `--recursive` flag -- [x] **Undo Functionality** - Revert file organization changes -- [ ] **Custom Models** - Support for other AI providers -- [ ] **GUI Version** - Desktop application for non-CLI users +See the [Development Guide](docs/DEVELOPMENT.md) for detailed architecture information. ## Contributing -Contributions are welcome! Please feel free to submit a Pull Request. +Contributions are welcome! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for: -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +- How to report bugs +- How to suggest features +- Development setup +- Code standards +- Pull request process + +## Future Enhancements + +- [x] Custom Categories +- [x] Recursive Mode +- [x] Undo Functionality +- [ ] Custom AI Models (OpenAI, Claude, etc.) +- [ ] GUI Version +- [ ] Watch Mode ## License @@ -620,9 +209,12 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file - Powered by [Google Gemini API](https://ai.google.dev/) - Inspired by the endless struggle to keep Downloads folders organized -## Show Your Support +## Support -⭐ Star this repository if you find it useful! +- Check the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for common issues +- Browse [GitHub Issues](https://github.com/glitchySid/noentropy/issues) for known problems +- Create a new issue for bugs or feature requests +- Star this repository if you find it useful! --- diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..584321b --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,202 @@ +# Configuration Guide + +NoEntropy uses a simple TOML configuration file to store your API key, download folder path, and custom categories. + +## Configuration File Location + +NoEntropy stores configuration in `~/.config/noentropy/config.toml` following XDG Base Directory specifications. + +**Platform-specific paths:** +- **Linux/macOS**: `~/.config/noentropy/config.toml` +- **Windows**: `C:\Users\\AppData\Roaming\noentropy\config.toml` + +## Basic Configuration + +### Minimal Configuration + +The minimum required configuration includes just your API key and download folder: + +```toml +api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k" +download_folder = "/home/user/Downloads" +``` + +### Full Configuration with Custom Categories + +```toml +api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k" +download_folder = "/home/user/Downloads" + +# Optional: Custom categories for file organization +categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"] +``` + +## Configuration Options + +| Setting | Description | Example | Required | +|---------|-------------|---------|----------| +| `api_key` | Your Google Gemini API key | `AIzaSy...` | Yes | +| `download_folder` | Path to folder to organize | `/home/user/Downloads` | Yes | +| `categories` | Custom categories for organization | `["Work", "Personal", "School"]` | No | + +## Getting a Gemini API Key + +1. Visit [Google AI Studio](https://ai.google.dev/) +2. Sign in with your Google account +3. Create a new API key +4. Copy the key to your configuration file + +**Important**: Keep your API key secure and never commit it to version control. + +## Custom Categories + +NoEntropy allows you to define your own custom categories instead of using the default ones. This is perfect for organizing files based on your specific workflow or needs. + +### Default Categories + +If you don't specify custom categories, NoEntropy uses these defaults: +- **Images** - PNG, JPG, GIF, SVG, etc. +- **Documents** - PDF, DOC, DOCX, TXT, MD, etc. +- **Installers** - EXE, DMG, APP, PKG, etc. +- **Music** - MP3, WAV, FLAC, M4A, etc. +- **Archives** - ZIP, TAR, RAR, 7Z, etc. +- **Code** - Source code and configuration files +- **Misc** - Everything else + +### Using Custom Categories + +To use custom categories, add a `categories` array to your `config.toml`: + +```toml +api_key = "your_api_key_here" +download_folder = "/home/user/Downloads" +categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"] +``` + +### Category Examples by Use Case + +#### For Students +```toml +categories = ["Courses", "Assignments", "Research", "Personal", "Textbooks", "Media", "Misc"] +``` + +#### For Professionals +```toml +categories = ["Client Work", "Internal", "Invoices", "Contracts", "Marketing", "Resources", "Misc"] +``` + +#### For Creatives +```toml +categories = ["Projects", "Assets", "References", "Client Files", "Portfolio", "Tools", "Misc"] +``` + +#### For Personal Use +```toml +categories = ["Family", "Finance", "Health", "Home", "Travel", "Hobbies", "Misc"] +``` + +### Tips for Effective Custom Categories + +1. **Keep it simple** - Use 5-10 categories for best results +2. **Be specific** - More descriptive names help the AI understand better +3. **Include "Misc"** - Always have a catch-all category for unclear files +4. **Think workflow** - Organize based on how you actually use files +5. **Test first** - Use `--dry-run` to preview categorization before committing + +### How Custom Categories Work + +When you define custom categories: +1. NoEntropy sends your file list to the Gemini AI +2. The AI is instructed to categorize files into your custom categories +3. Files are organized into folders matching your category names +4. Sub-folders are still created automatically for better organization + +**Example Output with Custom Categories:** +``` +Downloads/ +β”œβ”€β”€ Work/ +β”‚ β”œβ”€β”€ Reports/ +β”‚ β”‚ └── Q4-Report.pdf +β”‚ └── Presentations/ +β”‚ └── Client-Deck.pptx +β”œβ”€β”€ Personal/ +β”‚ β”œβ”€β”€ Photos/ +β”‚ β”‚ └── vacation.jpg +β”‚ └── Documents/ +β”‚ └── resume.pdf +└── School/ + β”œβ”€β”€ Assignments/ + β”‚ └── homework.docx + └── Notes/ + └── lecture-notes.pdf +``` + +## Interactive Setup + +If configuration is missing, NoEntropy will prompt you interactively: + +```bash +$ ./noentropy + +NoEntropy Configuration Setup +============================= + +API key not found. Please enter your Google Gemini API key: +> AIzaSy... + +Download folder not found. Please enter the path to organize: +(Default: /home/user/Downloads) +> /home/user/Downloads + +Configuration saved to ~/.config/noentropy/config.toml +``` + +Configuration is automatically saved after interactive setup. + +## Changing Configuration + +### Changing API Key + +To change your Gemini API key, use the `--change-key` flag: + +```bash +./noentropy --change-key +``` + +Or manually edit `~/.config/noentropy/config.toml` and update the `api_key` value. + +### Changing Download Folder + +Edit your configuration file and update the `download_folder` value: + +```toml +download_folder = "/path/to/new/folder" +``` + +### Adding or Modifying Categories + +Edit your configuration file and add or modify the `categories` array: + +```toml +categories = ["Category1", "Category2", "Category3"] +``` + +To remove custom categories and use defaults, simply delete the `categories` line from your config file. + +## Configuration Best Practices + +1. **Backup your config** - Keep a copy of your configuration, especially if you have custom categories +2. **Use absolute paths** - Always specify absolute paths for `download_folder` +3. **Test changes** - Use `--dry-run` after changing categories to preview results +4. **Keep API key secure** - Don't share or commit your API key +5. **Regular reviews** - Periodically review if your custom categories still match your needs + +## Next Steps + +- [Usage Guide](USAGE.md) - Learn how to use NoEntropy +- [How It Works](HOW_IT_WORKS.md) - Understand the organization process +- [Troubleshooting](TROUBLESHOOTING.md) - Solve common configuration issues + +--- + +[Back to Main README](../README.md) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..43c7322 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,494 @@ +# Contributing to NoEntropy + +Thank you for considering contributing to NoEntropy! This guide will help you get started with contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Testing Guidelines](#testing-guidelines) +- [Documentation Guidelines](#documentation-guidelines) + +## Code of Conduct + +### Our Pledge + +We are committed to providing a welcoming and inspiring community for everyone. Please be respectful and constructive in your interactions. + +### Expected Behavior + +- Be respectful and inclusive +- Accept constructive criticism gracefully +- Focus on what's best for the community +- Show empathy towards other community members + +### Unacceptable Behavior + +- Harassment or discriminatory language +- Trolling or insulting comments +- Public or private harassment +- Publishing others' private information + +## How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check existing issues to avoid duplicates. + +**How to submit a good bug report:** + +1. **Use a clear and descriptive title** +2. **Describe the exact steps to reproduce the problem** +3. **Provide specific examples** +4. **Describe the behavior you observed and what you expected** +5. **Include system information**: + - OS and version + - Rust version + - NoEntropy version + +**Bug report template:** + +```markdown +**Description** +A clear description of the bug. + +**Steps to Reproduce** +1. Run command '...' +2. See error '...' + +**Expected Behavior** +What you expected to happen. + +**Actual Behavior** +What actually happened. + +**System Information** +- OS: [e.g., Ubuntu 22.04] +- Rust version: [e.g., 1.75.0] +- NoEntropy version: [e.g., 1.0.0] + +**Additional Context** +Any other relevant information. +``` + +### Suggesting Enhancements + +Enhancement suggestions are welcome! Please provide: + +1. **Clear use case**: Explain why this enhancement would be useful +2. **Detailed description**: Describe how it should work +3. **Examples**: Provide examples of how it would be used +4. **Alternatives considered**: Mention alternative solutions you've considered + +**Enhancement template:** + +```markdown +**Feature Description** +A clear description of the feature. + +**Use Case** +Why this feature would be useful. + +**Proposed Solution** +How you think it should work. + +**Alternatives Considered** +Other solutions you've thought about. + +**Additional Context** +Any other relevant information. +``` + +### Contributing Code + +We love code contributions! Here's how to get started: + +1. **Fork the repository** +2. **Create a feature branch** +3. **Make your changes** +4. **Test thoroughly** +5. **Submit a pull request** + +See [Development Setup](#development-setup) below for details. + +### Improving Documentation + +Documentation improvements are highly valued: + +- Fix typos or unclear explanations +- Add examples or clarifications +- Improve code comments +- Write tutorials or guides + +### Helping Others + +- Answer questions in GitHub Issues +- Participate in discussions +- Help review pull requests +- Share your use cases and experiences + +## Development Setup + +### Prerequisites + +- **Rust 2024 Edition** or later +- **Git** for version control +- **Google Gemini API Key** for testing (get one at [https://ai.google.dev/](https://ai.google.dev/)) + +### Setup Steps + +1. **Fork and clone the repository**: + ```bash + git clone https://github.com/YOUR_USERNAME/noentropy.git + cd noentropy + ``` + +2. **Add upstream remote**: + ```bash + git remote add upstream https://github.com/glitchySid/noentropy.git + ``` + +3. **Build the project**: + ```bash + cargo build + ``` + +4. **Run tests**: + ```bash + cargo test + ``` + +5. **Set up configuration** (for testing): + ```bash + cp config.example.toml ~/.config/noentropy/config.toml + # Edit config.toml with your API key and test folder + ``` + +6. **Verify installation**: + ```bash + cargo run -- --dry-run + ``` + +### Keeping Your Fork Updated + +```bash +git fetch upstream +git checkout main +git merge upstream/main +git push origin main +``` + +## Pull Request Process + +### Before Submitting + +1. **Ensure tests pass**: + ```bash + cargo test + ``` + +2. **Run code formatter**: + ```bash + cargo fmt + ``` + +3. **Run linter**: + ```bash + cargo clippy + ``` + +4. **Test manually** with various scenarios + +5. **Update documentation** if needed + +### Creating a Pull Request + +1. **Create a feature branch**: + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** and commit: + ```bash + git add . + git commit -m "Add feature: description" + ``` + +3. **Push to your fork**: + ```bash + git push origin feature/your-feature-name + ``` + +4. **Open a pull request** on GitHub + +5. **Fill out the PR template** with: + - Description of changes + - Related issue number (if applicable) + - Testing performed + - Screenshots (if UI changes) + +### PR Review Process + +1. **Automated checks** will run (tests, linting, formatting) +2. **Maintainers will review** your code +3. **Address feedback** by making additional commits +4. **Once approved**, your PR will be merged + +### PR Guidelines + +- **Keep PRs focused**: One feature or fix per PR +- **Write clear descriptions**: Explain what and why +- **Reference issues**: Use "Fixes #123" to link issues +- **Be responsive**: Respond to review feedback promptly +- **Be patient**: Reviews may take time + +## Coding Standards + +### Rust Style Guide + +Follow the official [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/): + +- Use `cargo fmt` to format code +- Use `cargo clippy` to catch common mistakes +- Follow Rust naming conventions: + - `snake_case` for functions and variables + - `PascalCase` for types and traits + - `SCREAMING_SNAKE_CASE` for constants + +### Code Organization + +- Keep functions focused and small +- Group related functionality in modules +- Use meaningful variable and function names +- Avoid deep nesting (prefer early returns) + +### Error Handling + +- Use `Result` types for fallible operations +- Provide meaningful error messages +- Don't panic in library code +- Use `?` operator for error propagation + +### Comments and Documentation + +- Add doc comments (`///`) for public APIs +- Explain "why" not "what" in comments +- Keep comments up-to-date with code changes +- Use examples in doc comments when helpful + +### Example + +```rust +/// Calculates the destination path for a file based on its category. +/// +/// # Arguments +/// +/// * `file_path` - The original file path +/// * `category` - The category to organize into +/// * `subfolder` - Optional subfolder within category +/// +/// # Examples +/// +/// ``` +/// let dest = calculate_destination("/downloads/file.txt", "Documents", Some("Work")); +/// assert_eq!(dest, "/downloads/Documents/Work/file.txt"); +/// ``` +/// +/// # Errors +/// +/// Returns an error if the path cannot be constructed. +pub fn calculate_destination( + file_path: &Path, + category: &str, + subfolder: Option<&str> +) -> Result { + // Implementation +} +``` + +## Commit Message Guidelines + +### Format + +``` +(): + + + +