siddheshmhatre/noentropy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure documentation into organized files

Browse Source 
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
This commit is contained in:
glitchySid
2026-01-02 00:55:29 +05:30
parent 0eedb61455
commit d4e8dbc6b3
8 changed files with 2621 additions and 518 deletions
Download Patch File Download Diff File Expand all files Collapse all files

620
README.md
View File

@@ -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**
Download the binary for your operating system from [releases](https://github.com/glitchySid/noentropy/releases):
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
# Linux/macOS: Give execute permissions
chmod +x noentropy
# Run NoEntropy
./noentropy
```
## Run Locally
**Option 2: Build from Source**
1. **Clone repository**
```bash
# Clone repository
git clone https://github.com/glitchySid/noentropy.git
cd noentropy
```
2. **Build the application**
```bash
# Build and run
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
```
### First Run
## 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"]
```
| 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
### 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"]
```
**Examples of Custom Category Sets:**
**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!
---

202
docs/CONFIGURATION.md Normal file
View File

@@ -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\<username>\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)

494
docs/CONTRIBUTING.md Normal file
View File

@@ -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<PathBuf, Error> {
// Implementation
}
```
## Commit Message Guidelines
### Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Code style changes (formatting, etc.)
- **refactor**: Code refactoring
- **test**: Adding or updating tests
- **chore**: Maintenance tasks
### Examples
**Good commit messages:**
```
feat(cli): add recursive flag for subdirectory scanning
Adds --recursive flag to scan and organize files in subdirectories.
This is useful when downloads are already partially organized.
Fixes #42
```
```
fix(cache): prevent cache corruption on interrupted writes
Use atomic writes to ensure cache file is not corrupted if
process is interrupted during save operation.
```
```
docs: update configuration guide with new examples
Add examples for different user types (students, professionals).
Clarify custom category usage.
```
**Bad commit messages:**
```
fix stuff
```
```
WIP
```
```
more changes
```
### Tips
- Use present tense ("add feature" not "added feature")
- Be specific and descriptive
- Reference issues and PRs when relevant
- Keep subject line under 72 characters
- Separate subject from body with blank line
## Testing Guidelines
### Writing Tests
- Write tests for new functionality
- Test both success and error cases
- Use descriptive test names
- Keep tests focused and independent
### Test Structure
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_parse_valid_config() {
// Arrange
let config_str = r#"
api_key = "test_key"
download_folder = "/tmp/test"
"#;
// Act
let result = parse_config(config_str);
// Assert
assert!(result.is_ok());
let config = result.unwrap();
assert_eq!(config.api_key, "test_key");
assert_eq!(config.download_folder, "/tmp/test");
}
#[test]
fn test_parse_invalid_config() {
let config_str = "invalid toml";
let result = parse_config(config_str);
assert!(result.is_err());
}
}
```
### Running Tests
```bash
# Run all tests
cargo test
# Run specific test
cargo test test_name
# Run with output
cargo test -- --nocapture
# Run tests in specific module
cargo test module_name::
```
## Documentation Guidelines
### Code Documentation
- Document all public APIs
- Include examples in doc comments
- Explain parameters and return values
- Document errors that can occur
### User Documentation
When updating user-facing docs:
- Keep language clear and simple
- Provide examples
- Include screenshots for UI changes
- Update all relevant docs
### Documentation Files
- **README.md**: Project overview and quick start
- **docs/INSTALLATION.md**: Installation instructions
- **docs/CONFIGURATION.md**: Configuration guide
- **docs/USAGE.md**: Usage examples and options
- **docs/HOW_IT_WORKS.md**: Architecture and internals
- **docs/TROUBLESHOOTING.md**: Common issues and solutions
- **docs/DEVELOPMENT.md**: Development guide
- **docs/CONTRIBUTING.md**: This file
## Questions?
- Check [existing documentation](../README.md)
- Search [GitHub Issues](https://github.com/glitchySid/noentropy/issues)
- Ask in [GitHub Discussions](https://github.com/glitchySid/noentropy/discussions)
- Contact maintainers
## Recognition
Contributors will be recognized in:
- GitHub contributors list
- Release notes (for significant contributions)
- Project documentation (for major features)
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
---
Thank you for contributing to NoEntropy!
[Back to Main README](../README.md) | [Development Guide](DEVELOPMENT.md)

502
docs/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,502 @@
# Development Guide
This guide is for developers who want to understand NoEntropy's codebase, contribute features, or extend functionality.
## Project Structure
NoEntropy follows a clean modular architecture for better maintainability and testability:
```
noentropy/
├── .github/
│ └── workflows/
│ └── rust.yml # CI/CD workflow
├── docs/ # Documentation files
│ ├── INSTALLATION.md
│ ├── CONFIGURATION.md
│ ├── USAGE.md
│ ├── HOW_IT_WORKS.md
│ ├── TROUBLESHOOTING.md
│ ├── DEVELOPMENT.md # This file
│ └── CONTRIBUTING.md
├── 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 # Project overview
```
## Module Overview
### cli/
**Purpose**: Command-line interface and orchestration logic
- **args.rs**: Defines CLI arguments using `clap` crate
- Command-line flags and options
- Argument validation
- Help text generation
- **orchestrator.rs**: Main orchestration logic
- Coordinates file scanning, categorization, and moving
- Handles undo operations
- Manages user interaction and confirmation
### files/
**Purpose**: File detection, batching, moving, and undo operations
- **batch.rs**: Batch file processing
- Groups files for processing
- Manages concurrent operations
- Handles batch-level errors
- **detector.rs**: File type detection
- Identifies text files that can be inspected
- Determines file categories by extension
- Supports 30+ text file formats
- **mover.rs**: File moving operations
- Moves files to destination folders
- Creates directories as needed
- Handles file operation errors
- **undo.rs**: Undo functionality
- Reverses file moves
- Handles conflicts and edge cases
- Cleans up empty directories
### gemini/
**Purpose**: Google Gemini API integration
- **client.rs**: API client implementation
- Makes HTTP requests to Gemini API
- Handles authentication
- Manages response parsing
- **errors.rs**: Error types and handling
- Custom error types for API failures
- Error conversion and propagation
- User-friendly error messages
- **prompt.rs**: Prompt engineering
- Constructs prompts for categorization
- Handles custom vs default categories
- Formats file lists for API
- **types.rs**: API request/response types
- Serialization/deserialization structures
- Type-safe API communication
- JSON parsing
### models/
**Purpose**: Core data structures
- **metadata.rs**: File metadata
- File size, modification time
- Used for cache invalidation
- Lightweight file tracking
- **move_record.rs**: File move tracking
- Records source and destination paths
- Tracks move status (completed/undone/failed)
- Used by undo system
- **organization.rs**: Organization plan
- Represents categorization decisions
- Maps files to destination paths
- Used for preview and execution
### settings/
**Purpose**: Configuration management
- **config.rs**: Configuration loading/saving
- Reads from TOML file
- Validates configuration
- Provides default values
- **prompt.rs**: Interactive setup
- Prompts user for missing config
- Validates user input
- Saves configuration
- **tests.rs**: Configuration tests
- Unit tests for config parsing
- Validation tests
- Edge case handling
### storage/
**Purpose**: Persistent data layer
- **cache.rs**: Caching system
- Stores API responses
- Implements expiry logic (7 days)
- LRU eviction when limit reached
- **undo_log.rs**: Undo log management
- Persists move records
- Implements retention policy (30 days)
- Handles log corruption
## Building and Testing
### Build in Debug Mode
For development with debug symbols:
```bash
cargo build
```
Binary location: `./target/debug/noentropy`
### Build in Release Mode
Optimized build for production:
```bash
cargo build --release
```
Binary location: `./target/release/noentropy`
### Run Tests
Run all unit tests:
```bash
cargo test
```
Run tests with output:
```bash
cargo test -- --nocapture
```
Run specific test:
```bash
cargo test test_name
```
### Run with Debug Output
Enable verbose logging:
```bash
RUST_LOG=debug cargo run
```
### Run Clippy (Linting)
Check for common mistakes and code quality:
```bash
cargo clippy
```
Fix auto-fixable issues:
```bash
cargo clippy --fix
```
### Check Code
Fast check without building:
```bash
cargo check
```
### Format Code
Format code according to Rust standards:
```bash
cargo fmt
```
Check formatting without changing files:
```bash
cargo fmt -- --check
```
## Key Dependencies
NoEntropy uses these main dependencies (see `Cargo.toml` for full list):
- **clap**: Command-line argument parsing
- **tokio**: Async runtime for concurrent operations
- **reqwest**: HTTP client for API requests
- **serde**: Serialization/deserialization
- **serde_json**: JSON parsing
- **toml**: TOML configuration parsing
- **directories**: Cross-platform directory paths
## Development Workflow
### 1. Set Up Development Environment
```bash
# Clone repository
git clone https://github.com/glitchySid/noentropy.git
cd noentropy
# Build project
cargo build
# Run tests
cargo test
# Check code quality
cargo clippy
```
### 2. Create Feature Branch
```bash
git checkout -b feature/your-feature-name
```
### 3. Make Changes
- Write code following Rust conventions
- Add tests for new functionality
- Update documentation as needed
- Run `cargo fmt` before committing
### 4. Test Changes
```bash
# Run tests
cargo test
# Test manually with your changes
cargo run -- --dry-run
# Check for issues
cargo clippy
```
### 5. Commit and Push
```bash
git add .
git commit -m "Add feature: description"
git push origin feature/your-feature-name
```
### 6. Create Pull Request
- Go to GitHub and create a pull request
- Describe your changes clearly
- Reference any related issues
- Wait for review and feedback
## Code Style Guidelines
### Rust Conventions
- Follow standard Rust naming conventions
- Use `snake_case` for functions and variables
- Use `PascalCase` for types and traits
- Use `SCREAMING_SNAKE_CASE` for constants
### Documentation
- Add doc comments (`///`) for public APIs
- Explain complex logic with inline comments
- Update relevant documentation files
### Error Handling
- Use `Result` types for operations that can fail
- Provide meaningful error messages
- Avoid panicking in library code
### Testing
- Write unit tests for new functionality
- Test error cases and edge conditions
- Use descriptive test names
## Common Development Tasks
### Adding a New CLI Flag
1. Edit `src/cli/args.rs`
2. Add new field to `Args` struct
3. Add clap attribute for the flag
4. Update `orchestrator.rs` to use the flag
### Adding a New File Type
1. Edit `src/files/detector.rs`
2. Add extension to relevant detection function
3. Add tests for the new file type
### Modifying AI Prompts
1. Edit `src/gemini/prompt.rs`
2. Update prompt construction logic
3. Test with various file types
4. Consider token limits
### Adding New Configuration Options
1. Edit `src/settings/config.rs`
2. Add field to `Config` struct
3. Update serialization/deserialization
4. Add validation if needed
5. Update `config.example.toml`
6. Update documentation
## Debugging Tips
### Enable Detailed Logging
```bash
RUST_LOG=debug cargo run
```
### Use Rust Backtrace
```bash
RUST_BACKTRACE=1 cargo run
```
Full backtrace:
```bash
RUST_BACKTRACE=full cargo run
```
### Debug Specific Modules
```bash
RUST_LOG=noentropy::gemini=debug cargo run
```
### Print Debugging
Use `dbg!()` macro for quick debugging:
```rust
dbg!(&some_variable);
```
## Performance Profiling
### Basic Timing
```bash
time cargo run --release
```
### CPU Profiling (Linux)
```bash
cargo install flamegraph
sudo cargo flamegraph
```
### Memory Profiling
```bash
cargo install cargo-instruments
cargo instruments -t Allocations
```
## Continuous Integration
NoEntropy uses GitHub Actions for CI/CD (see `.github/workflows/rust.yml`):
- Runs on push and pull requests
- Tests on Linux, macOS, and Windows
- Checks formatting, linting, and tests
- Builds release binaries
## Release Process
1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md` (if exists)
3. Create git tag: `git tag v1.0.0`
4. Push tag: `git push origin v1.0.0`
5. GitHub Actions builds and publishes release
## Architecture Decisions
### Why Rust?
- Performance: Fast file operations and concurrent processing
- Safety: Memory safety without garbage collection
- Ecosystem: Great libraries for CLI, HTTP, and serialization
### Why Tokio?
- Async/await support for concurrent API calls
- Efficient handling of I/O operations
- Industry-standard async runtime
### Why Gemini API?
- Powerful language understanding
- Good at semantic file categorization
- Reasonable rate limits and pricing
### Why Caching?
- Reduces API costs
- Improves performance for repeated runs
- Minimizes redundant analysis
## Future Enhancements
Ideas for future development:
- [ ] Custom AI model support (OpenAI, Claude, etc.)
- [ ] GUI version (desktop application)
- [ ] Watch mode (automatic organization on file creation)
- [ ] Plugin system for custom organization rules
- [ ] Dry-run improvements with more detailed analysis
- [ ] Better conflict resolution strategies
- [ ] Multi-folder support
- [ ] Rule-based organization (in addition to AI)
## Getting Help
- Read existing documentation
- Check GitHub issues for similar questions
- Ask in GitHub Discussions
- Contact maintainers
## Resources
- [Rust Book](https://doc.rust-lang.org/book/)
- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
- [Clap Documentation](https://docs.rs/clap/)
- [Serde Guide](https://serde.rs/)
---
[Back to Main README](../README.md) | [Contributing Guide](CONTRIBUTING.md)

345
docs/HOW_IT_WORKS.md Normal file
View File

@@ -0,0 +1,345 @@
# How NoEntropy Works
This guide explains the internal architecture and processes that power NoEntropy's intelligent file organization.
## Overview
NoEntropy uses a multi-stage pipeline that combines AI-powered categorization with intelligent caching and concurrent processing to efficiently organize your files.
## Organization Process
NoEntropy follows a five-step process to organize your files:
```
┌─────────────────┐
│ 1. Scan Files │ → Read all files in DOWNLOAD_FOLDER
└────────┬────────┘ (and subdirs 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
└──────────────────────┘
```
### Step 1: File Scanning
**What happens:**
- Scans the configured download folder
- Optionally scans subdirectories with `--recursive` flag
- Collects file paths and metadata (size, modification time)
- Filters out directories and focuses on files only
**Output:** List of file paths ready for categorization
### Step 2: Initial Categorization
**What happens:**
- Sends list of filenames to Gemini API
- AI analyzes filenames and determines appropriate categories
- Returns a categorization plan for all files
- Uses custom categories if configured, otherwise uses defaults
**AI Prompt includes:**
- List of all filenames
- Available categories (default or custom)
- Instructions to categorize based on file type and content
- Request for main category assignment
**Output:** Initial organization plan with main categories
### Step 3: Deep Inspection
**What happens:**
- Identifies text-based files that can be read
- Concurrently reads file contents (up to `--max-concurrent` files at once)
- Sends content to Gemini AI for sub-folder suggestions
- AI analyzes content and suggests relevant sub-categories
- Applies intelligent retry logic with exponential backoff
**Supported 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
```
**Why concurrent?**
- Processes multiple files simultaneously
- Significantly reduces total processing time
- Configurable concurrency limit prevents API rate limiting
**Output:** Enhanced organization plan with sub-folders
### Step 4: Preview & Confirmation
**What happens:**
- Displays complete organization plan to user
- Shows source file and destination path for each file
- Waits for user confirmation (y/n)
- Allows user to review before any changes are made
**User options:**
- Accept: Proceed with organization
- Decline: Cancel and exit without changes
**Output:** User decision (proceed or abort)
### Step 5: Execute Moves
**What happens:**
- Creates destination directories as needed
- Moves files to their designated locations
- Records each move in the undo log
- Reports success/failure for each operation
- Displays final summary statistics
**Safety features:**
- Only moves files after user confirmation
- Tracks all operations for undo capability
- Handles errors gracefully without stopping entire process
- Creates parent directories automatically
**Output:** Organized files and execution summary
## Caching System
NoEntropy includes an intelligent caching system to minimize API calls and improve performance.
### Cache Design
- **Location**: `.noentropy_cache.json` in project root
- **Format**: JSON with file path as key
- **Expiry**: 7 days (automatically cleaned up)
- **Max Entries**: 1000 entries (LRU eviction)
- **Change Detection**: File size + modification time (not content hash)
### How Caching Works
1. **First Run**:
- Files are analyzed via Gemini API
- Categorization results are cached with metadata
2. **Cache Check** (subsequent runs):
```
File found in cache?
├─ No → Analyze via API, cache result
└─ Yes → File changed (size/time)?
├─ Yes → Re-analyze via API, update cache
└─ No → Use cached categorization
```
3. **Cache Maintenance**:
- Removes entries older than 7 days on every run
- Evicts oldest entries when limit (1000) is reached
- Validates file still exists before using cache
### Cache Benefits
- **Reduced API Costs**: Avoids re-analyzing unchanged files
- **Faster Processing**: No API call needed for cached files
- **Efficient**: Metadata-based change detection (no content hashing)
- **Automatic Cleanup**: Self-maintaining with age and size limits
### When Cache is Invalidated
Cache entries are invalidated when:
- File size changes
- File modification time changes
- Cache entry is older than 7 days
- File no longer exists
- Cache is manually deleted
## Undo Log System
NoEntropy tracks all file moves to enable undo functionality.
### Undo Log Design
- **Location**: `~/.config/noentropy/data/undo_log.json`
- **Format**: JSON array of move records
- **Retention**: 30 days (automatically cleaned up)
- **Max Entries**: 1000 entries (oldest evicted)
- **Status Tracking**: Completed, Undone, Failed states
### Move Record Structure
Each file move is recorded with:
- Source path (original location)
- Destination path (new location)
- Timestamp of move
- Status (completed/undone/failed)
### How Undo Works
1. **During Organization**:
```
For each file moved:
├─ Record source path
├─ Record destination path
├─ Record timestamp
└─ Mark as "completed"
```
2. **Undo Execution**:
```
Load undo log
├─ Filter "completed" moves (not already undone)
├─ Show preview to user
├─ Request confirmation
└─ If confirmed:
├─ Check destination exists
├─ Check source doesn't exist (avoid conflicts)
├─ Move file back to source
├─ Mark as "undone"
└─ Clean up empty directories
```
3. **Conflict Handling**:
- **Source exists**: Skip restore (prevent overwrite)
- **Destination missing**: Skip restore (file was deleted)
- **Permission error**: Skip restore, report error
### Undo Safety Features
- **Preview Before Action**: Always shows what will be undone
- **Conflict Detection**: Prevents data loss from overwrites
- **Missing File Handling**: Gracefully skips deleted files
- **Partial Undo Support**: Continues processing despite individual failures
- **Empty Directory Cleanup**: Removes empty folders after undo
- **Dry-Run Mode**: Preview undo without executing
### Undo Limitations
- Only tracks moves made by NoEntropy
- Cannot track manual file operations
- Limited to 30-day history
- Cannot restore deleted files (only moves)
## Supported File Categories
NoEntropy can organize files into these default categories:
| Category | File Types |
|----------|------------|
| **Images** | PNG, JPG, JPEG, GIF, SVG, BMP, WEBP, ICO, TIFF |
| **Documents** | PDF, DOC, DOCX, TXT, MD, RTF, ODT, PAGES |
| **Installers** | EXE, DMG, APP, PKG, DEB, RPM, MSI, APK |
| **Music** | MP3, WAV, FLAC, M4A, AAC, OGG, WMA |
| **Videos** | MP4, AVI, MKV, MOV, WMV, FLV, WEBM |
| **Archives** | ZIP, TAR, GZ, RAR, 7Z, BZ2, XZ |
| **Code** | Source code and configuration files |
| **Misc** | Everything else |
## AI Integration
NoEntropy uses Google's Gemini API for intelligent categorization.
### API Usage
- **Model**: Gemini 1.5 Flash (configurable)
- **Concurrent Requests**: 5 by default (configurable via `--max-concurrent`)
- **Retry Logic**: Exponential backoff for failed requests
- **Rate Limiting**: Respects API rate limits with configurable concurrency
### Prompt Engineering
NoEntropy uses carefully crafted prompts to get accurate categorization:
1. **Initial Categorization Prompt**:
- Lists all filenames
- Specifies available categories
- Requests JSON response with categorization plan
2. **Deep Inspection Prompt**:
- Provides file content
- Requests sub-folder suggestion based on content
- Asks for semantic analysis, not just extension
### Error Handling
- **Network Errors**: Retry with exponential backoff
- **Rate Limiting**: Respects limits, retries after delay
- **Invalid Responses**: Logs error, continues with other files
- **Timeout**: Configurable timeout with fallback behavior
## Performance Characteristics
### Factors Affecting Performance
1. **Number of Files**:
- 10-50 files: ~10-30 seconds
- 100-500 files: 1-3 minutes
- 1000+ files: 5-10 minutes
2. **Concurrency Level**:
- Higher = faster but more API load
- Lower = slower but safer for rate limits
- Default (5) balances speed and safety
3. **Cache Hit Rate**:
- High hit rate (>80%): Significantly faster
- Low hit rate (<20%): More API calls needed
- Regular usage improves hit rate over time
4. **Text File Count**:
- More text files = more deep inspection
- Deep inspection adds processing time
- Concurrent processing mitigates this
### Optimization Strategies
1. **Use caching**: Regular runs benefit from cached results
2. **Adjust concurrency**: Increase for faster processing
3. **Dry-run first**: Test configuration without full processing
4. **Organize regularly**: Smaller batches process faster
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────┐
│ NoEntropy CLI │
│ (Orchestrator) │
└────────────┬──────────────────────────────┬─────────────┘
│ │
┌────────▼─────────┐ ┌───────▼────────┐
│ File Scanner │ │ Config Manager │
│ & Detector │ │ │
└────────┬─────────┘ └────────────────┘
│
┌────────▼──────────────────────────────────────┐
│ Gemini AI Client │
│ (with retry logic & concurrent processing) │
└────────┬──────────────────────────────────────┘
│
┌────────▼─────────┐ ┌────────────────┐
│ Cache System │ │ Undo Log │
└──────────────────┘ └────────────────┘
│
┌────────▼─────────┐
│ File Mover │
└──────────────────┘
```
## Next Steps
- [Usage Guide](USAGE.md) - Learn how to use NoEntropy
- [Configuration Guide](CONFIGURATION.md) - Configure NoEntropy
- [Development Guide](DEVELOPMENT.md) - Contribute to NoEntropy
---
[Back to Main README](../README.md)

121
docs/INSTALLATION.md Normal file
View File

@@ -0,0 +1,121 @@
# Installation Guide
This guide covers different ways to install and set up NoEntropy on your system.
## Prerequisites
Before installing NoEntropy, ensure you have:
- **Rust 2024 Edition** or later (if building from source)
- **Google Gemini API Key** - Get one at [https://ai.google.dev/](https://ai.google.dev/)
- A folder full of unorganized files to clean up!
## Option 1: Download Pre-built Binary
The easiest way to get started is to download a pre-built binary for your operating system.
1. **Download Binary**
Visit the releases page and download the binary for your operating system (Windows, Linux, or macOS):
```bash
https://github.com/glitchySid/noentropy/releases
```
2. **Give Permission (Linux/macOS only)**
Make the binary executable:
```bash
chmod +x noentropy
```
3. **Run NoEntropy**
```bash
./noentropy
```
## Option 2: Build from Source
If you prefer to build from source or want the latest development version:
1. **Clone the Repository**
```bash
git clone https://github.com/glitchySid/noentropy.git
cd noentropy
```
2. **Build the Application**
```bash
cargo build --release
```
3. **Run the Application**
```bash
./target/release/noentropy
```
## First-Run Setup
On first run, NoEntropy will guide you through an interactive setup process:
### Interactive Setup
NoEntropy provides an interactive setup if configuration is missing:
- **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.
### Manual Configuration
Alternatively, you can manually create the configuration file:
```bash
cp config.example.toml ~/.config/noentropy/config.toml
nano ~/.config/noentropy/config.toml
```
See the [Configuration Guide](CONFIGURATION.md) for detailed configuration options.
## Getting Your 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 or enter it during interactive setup
## Verification
To verify your installation works correctly:
1. Run NoEntropy with the `--dry-run` flag:
```bash
./noentropy --dry-run
```
2. You should see NoEntropy scan your downloads folder and display an organization plan without moving any files.
## Next Steps
- [Configure NoEntropy](CONFIGURATION.md) - Learn about configuration options
- [Usage Guide](USAGE.md) - Learn how to use NoEntropy effectively
- [How It Works](HOW_IT_WORKS.md) - Understand the organization process
## Troubleshooting
If you encounter issues during installation, check the [Troubleshooting Guide](TROUBLESHOOTING.md).
Common installation issues:
- **Rust not installed**: Install Rust from [rustup.rs](https://rustup.rs/)
- **Build errors**: Ensure you have the latest Rust toolchain: `rustup update`
- **Permission denied**: Make sure the binary has execute permissions (Linux/macOS)
---
[Back to Main README](../README.md)

518
docs/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,518 @@
# Troubleshooting Guide
This guide helps you solve common issues you might encounter while using NoEntropy.
## Configuration Issues
### "API key not configured"
**Problem**: NoEntropy cannot find your Gemini API key.
**Solutions**:
1. **Interactive Setup** (Recommended):
- Simply run NoEntropy and it will prompt you for your API key
- The configuration will be saved automatically
2. **Manual Configuration**:
```bash
mkdir -p ~/.config/noentropy
nano ~/.config/noentropy/config.toml
```
Add:
```toml
api_key = "your_actual_api_key_here"
download_folder = "/home/user/Downloads"
```
3. **Use Change Key Flag**:
```bash
./noentropy --change-key
```
**Verify**: Run `./noentropy --dry-run` to test your configuration.
---
### "Download folder not configured"
**Problem**: NoEntropy doesn't know which folder to organize.
**Solutions**:
1. **Interactive Setup**:
- Run NoEntropy and it will prompt you for the folder path
- It will suggest a default location based on your system
2. **Manual Configuration**:
```bash
nano ~/.config/noentropy/config.toml
```
Add or update:
```toml
download_folder = "/path/to/your/Downloads"
```
**Important**: Use absolute paths, not relative paths (e.g., `/home/user/Downloads`, not `~/Downloads`).
---
### "Configuration file not found"
**Problem**: The configuration file doesn't exist or is in the wrong location.
**Expected Locations**:
- **Linux/macOS**: `~/.config/noentropy/config.toml`
- **Windows**: `C:\Users\<username>\AppData\Roaming\noentropy\config.toml`
**Solutions**:
1. **Create configuration directory**:
```bash
mkdir -p ~/.config/noentropy
```
2. **Copy example configuration**:
```bash
cp config.example.toml ~/.config/noentropy/config.toml
```
3. **Edit configuration**:
```bash
nano ~/.config/noentropy/config.toml
```
---
### "Invalid API key format"
**Problem**: Your API key is incorrectly formatted or invalid.
**Solutions**:
1. **Get a new API key**:
- Visit [Google AI Studio](https://ai.google.dev/)
- Create a new API key
- Copy it exactly (including all characters)
2. **Check for common issues**:
- No extra spaces before or after the key
- Key is enclosed in quotes in TOML file
- No line breaks within the key
**Example of correct format**:
```toml
api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k"
```
---
## API and Network Issues
### "API rate limit exceeded"
**Problem**: You're making too many requests to the Gemini API.
**Solutions**:
1. **Wait and retry**:
- Wait 5-10 minutes before trying again
- Rate limits reset over time
2. **Reduce concurrency**:
```bash
./noentropy --max-concurrent 2
```
3. **Use caching**:
- NoEntropy caches results for 7 days
- Subsequent runs of same files won't hit API
- Cache is automatic, no configuration needed
4. **Check API quota**:
- Visit [Google AI Studio](https://ai.google.dev/)
- Check your API usage and quotas
- Consider upgrading if you hit limits frequently
---
### "Network error" or "Connection timeout"
**Problem**: Cannot connect to Gemini API.
**Solutions**:
1. **Check internet connection**:
```bash
ping google.com
```
2. **Verify API service status**:
- Check [Google Cloud Status](https://status.cloud.google.com/)
- Verify Gemini API is operational
3. **Check firewall settings**:
- Ensure outbound HTTPS (port 443) is allowed
- Whitelist generativelanguage.googleapis.com if needed
4. **Try with fewer files**:
- API timeout might be due to large batch
- Reduce `--max-concurrent` value
- Organize files in smaller batches
5. **Check proxy settings**:
- If behind corporate proxy, configure proxy settings
- Some proxies block API calls
---
### "Invalid API response" or "Failed to parse response"
**Problem**: API returned unexpected or malformed data.
**Solutions**:
1. **Retry the operation**:
- Temporary API glitch might resolve itself
- Run NoEntropy again
2. **Check API key validity**:
- API key might have been revoked
- Create a new API key
3. **Clear cache and retry**:
```bash
rm .noentropy_cache.json
./noentropy
```
4. **Report issue**:
- If problem persists, it might be a bug
- Check [GitHub Issues](https://github.com/glitchySid/noentropy/issues)
---
## File Operation Issues
### "Failed to move file" or "Permission denied"
**Problem**: Cannot move files to destination folder.
**Solutions**:
1. **Check file permissions**:
```bash
ls -la /path/to/file
```
2. **Check destination permissions**:
```bash
ls -la /path/to/Downloads
```
3. **Fix permissions**:
```bash
chmod 644 /path/to/file # For files
chmod 755 /path/to/directory # For directories
```
4. **Run as appropriate user**:
- Don't run as root unless necessary
- Ensure you own the files and folder
5. **Check disk space**:
```bash
df -h /path/to/Downloads
```
---
### "File not found" or "Source file doesn't exist"
**Problem**: Files were deleted or moved before organization completed.
**Solutions**:
1. **Verify files exist**:
```bash
ls -la /path/to/Downloads
```
2. **Check if another process is moving files**:
- Browser might be cleaning up
- Another organization tool might be running
- Antivirus might have quarantined files
3. **Use dry-run first**:
```bash
./noentropy --dry-run
```
- This ensures files exist before actual move
---
### "Destination already exists" or "File conflict"
**Problem**: A file with the same name already exists at destination.
**Solutions**:
1. **Current behavior**: NoEntropy will skip the file to prevent overwrites
2. **Manual resolution**:
- Rename the existing file
- Delete the existing file if not needed
- Run organization again
3. **Check for duplicates**:
- You might have duplicate downloads
- Consider cleaning duplicates manually
---
## Cache Issues
### "Cache corrupted" or "Failed to read cache"
**Problem**: Cache file is corrupted or malformed.
**Solutions**:
1. **Delete cache file**:
```bash
rm .noentropy_cache.json
```
2. **Run NoEntropy again**:
- A new cache will be created automatically
- Files will be analyzed fresh via API
3. **Prevent corruption**:
- Don't manually edit cache file
- Let NoEntropy manage cache automatically
---
### "Cache not working" or "Too many API calls"
**Problem**: Cache doesn't seem to reduce API calls.
**Diagnosis**:
Check if files are being modified:
```bash
ls -lt /path/to/Downloads | head
```
**Reasons cache might not work**:
1. **Files are constantly changing**:
- If file modification time or size changes, cache is invalidated
- This is expected behavior
2. **Cache expired**:
- Cache entries older than 7 days are removed
- Run organization more frequently
3. **Cache deleted**:
- Check if `.noentropy_cache.json` exists in project root
- If not, cache will rebuild on next run
**Solution**: This is often expected behavior, not a bug.
---
## Undo Issues
### "No completed moves to undo"
**Problem**: Cannot undo because no undo history exists.
**Reasons**:
1. **No files have been organized yet**
- Run organization first
2. **All moves already undone**
- You've already undone the previous organization
3. **Undo log was deleted**
- Check if `~/.config/noentropy/data/undo_log.json` exists
4. **Undo log expired**
- Entries older than 30 days are automatically removed
**Solution**: Run organization to create new undo history.
---
### "Undo log not found"
**Problem**: The undo log file doesn't exist.
**Solutions**:
1. **Create data directory**:
```bash
mkdir -p ~/.config/noentropy/data
```
2. **Run organization**:
- This will create the undo log automatically
---
### "Skipping [file] - source already exists"
**Problem**: During undo, a file already exists at the original location.
**This is a safety feature**:
- NoEntropy won't overwrite existing files
- Prevents data loss
**Solutions**:
1. **Manual inspection**:
- Check both source and destination files
- Determine which one to keep
- Manually resolve the conflict
2. **Rename existing file**:
- Move or rename the file at source location
- Run undo again
---
### "Failed to restore [file]"
**Problem**: Unable to move file back to original location during undo.
**Common causes**:
1. **Permission issues**: See "Permission denied" section above
2. **File deleted**: Destination file was deleted after organization
3. **Disk space**: Not enough space at source location
**Solution**: Check logs for specific error, then address the underlying cause.
---
## Build and Development Issues
### "Rust not installed" or "cargo command not found"
**Problem**: Rust toolchain is not installed.
**Solution**:
Install Rust from official source:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Then restart your terminal and try again.
---
### Build errors or compilation failures
**Problem**: Cannot build from source.
**Solutions**:
1. **Update Rust toolchain**:
```bash
rustup update
```
2. **Clean build directory**:
```bash
cargo clean
cargo build --release
```
3. **Check Rust version**:
```bash
rustc --version
```
- Ensure you have Rust 2024 edition or later
4. **Check dependencies**:
```bash
cargo update
```
---
## Platform-Specific Issues
### Linux/macOS: "Permission denied" when running binary
**Solution**:
```bash
chmod +x noentropy
```
---
### Windows: "Windows protected your PC" warning
**This is expected** for unsigned binaries.
**Solution**:
1. Click "More info"
2. Click "Run anyway"
Alternatively, build from source to avoid this warning.
---
### macOS: "noentropy cannot be opened because the developer cannot be verified"
**Solution**:
1. **First method** (Recommended):
```bash
xattr -d com.apple.quarantine noentropy
```
2. **Alternative method**:
- Right-click the binary
- Select "Open"
- Click "Open" in the dialog
---
## Getting More Help
If you've tried the solutions above and still have issues:
1. **Check GitHub Issues**: [https://github.com/glitchySid/noentropy/issues](https://github.com/glitchySid/noentropy/issues)
- Someone might have reported the same issue
- Solutions might already be available
2. **Create a new issue**:
- Describe the problem clearly
- Include error messages
- Mention your OS and NoEntropy version
- Describe steps to reproduce
3. **Join discussions**:
- Check GitHub Discussions for community help
- Share your use case and ask questions
## Debug Mode
For detailed error information, run with Rust backtrace:
```bash
RUST_BACKTRACE=1 ./noentropy
```
This provides detailed stack traces for debugging issues.
---
[Back to Main README](../README.md)

329
docs/USAGE.md Normal file
View File

@@ -0,0 +1,329 @@
# Usage Guide
This guide covers all the ways you can use NoEntropy to organize your files.
## Quick Start
The simplest way to organize your downloads folder:
```bash
./noentropy
```
This will:
1. Scan your configured downloads folder
2. Ask Gemini AI to categorize files
3. Show you a preview of the organization plan
4. Ask for confirmation before moving files
5. Execute the organization if you approve
## Command-Line Options
NoEntropy supports several command-line flags to customize its behavior:
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--dry-run` | `-d` | `false` | Preview changes without moving files |
| `--max-concurrent` | `-m` | `5` | Maximum concurrent API requests |
| `--recursive` | - | `false` | Recursively search files in subdirectories |
| `--undo` | - | `false` | Undo the last file organization |
| `--change-key` | - | `false` | Change Gemini API key |
| `--help` | `-h` | - | Show help message |
## Usage Examples
### Dry-Run Mode
Preview what NoEntropy would do without actually moving any files:
```bash
./noentropy --dry-run
```
**When to use:**
- First time using NoEntropy
- Testing new custom categories
- Checking how specific files will be categorized
- Verifying organization plan before execution
**Example output:**
```
Found 47 files. Asking Gemini to organize...
Gemini Plan received! Performing deep inspection...
Deep inspection complete!
--- EXECUTION PLAN (DRY RUN) ---
Plan: image1.png -> Images/
Plan: document.pdf -> Documents/
Plan: setup.exe -> Installers/
Plan: notes.txt -> Documents/Notes/
Plan: config.yaml -> Code/Config/
DRY RUN - No files were moved
```
### Recursive Mode
Organize files in subdirectories recursively:
```bash
./noentropy --recursive
```
**What it does:**
- Scans all subdirectories within your download folder
- Organizes files from the entire directory tree
- Maintains relative folder structure when creating categories
**Use case:** When you have downloads organized in subfolders that you want to consolidate into proper categories.
### Custom Concurrency
Adjust the number of concurrent API calls (default: 5):
```bash
./noentropy --max-concurrent 10
```
**When to adjust:**
- **Increase (10-15)**: If you have fast internet and many files
- **Decrease (1-3)**: If you're hitting rate limits or have slow internet
- **Keep default (5)**: Works well for most use cases
### Combined Options
You can combine multiple options:
```bash
./noentropy --dry-run --max-concurrent 3
```
```bash
./noentropy --recursive --max-concurrent 10
```
## Undo Operations
NoEntropy tracks all file moves and allows you to undo them.
### Basic Undo
Revert the last file organization:
```bash
./noentropy --undo
```
**Example output:**
```
--- 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/
Do you want to undo these changes? [y/N]: y
--- 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/
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
```
### Undo Dry-Run
Preview what would be undone without actually reversing changes:
```bash
./noentropy --undo --dry-run
```
**When to use:**
- Check what files will be restored before undoing
- Verify undo log integrity
- See if any conflicts exist
### Undo Features
The undo system provides several 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
- **Empty Directory Cleanup**: Automatically removes empty directories after undo
- **History Retention**: Keeps undo history for 30 days with auto-cleanup
### Undo Limitations
- Only the most recent organization can be undone
- Files deleted after organization cannot be restored
- Files moved outside NoEntropy cannot be tracked
- Undo log is cleared after 30 days
## Interactive Confirmation
Before moving files, NoEntropy shows you the organization plan:
```
--- EXECUTION PLAN ---
Plan: image1.png -> Images/
Plan: document.pdf -> Documents/
Plan: setup.exe -> Installers/
...
Do you want to apply these changes? [y/N]:
```
**Options:**
- Type `y` or `yes` to proceed with organization
- Type `n`, `no`, or press Enter to cancel
**Tip**: Always review the plan carefully, especially when using custom categories for the first time.
## Changing Configuration
### Change API Key
Update your Gemini API key interactively:
```bash
./noentropy --change-key
```
This will prompt you to enter a new API key and save it to your configuration.
### Change Download Folder
Edit your config file manually:
```bash
nano ~/.config/noentropy/config.toml
```
Update the `download_folder` value and save.
## Typical Workflows
### First-Time User Workflow
1. Install NoEntropy
2. Run with `--dry-run` to preview:
```bash
./noentropy --dry-run
```
3. Review the organization plan
4. If satisfied, run without dry-run:
```bash
./noentropy
```
5. Review and confirm the plan
6. Let NoEntropy organize your files
### Regular Usage Workflow
1. Download files throughout the week
2. Periodically run NoEntropy:
```bash
./noentropy
```
3. Review and confirm the plan
4. Files are organized automatically
### Testing Custom Categories
1. Edit config file and add custom categories
2. Test with dry-run:
```bash
./noentropy --dry-run
```
3. Review how files are categorized
4. Adjust categories if needed
5. Run without dry-run when satisfied
### Recovery Workflow
If organization didn't work as expected:
1. Undo the changes:
```bash
./noentropy --undo
```
2. Adjust configuration or categories
3. Test with dry-run again
4. Re-run organization
## Example Terminal Output
### Successful Organization
```bash
$ ./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.....
--- 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!
```
## Tips and Best Practices
1. **Start with dry-run**: Always test first, especially with custom categories
2. **Review the plan**: Don't blindly accept the organization plan
3. **Use undo when needed**: Don't hesitate to undo and reorganize
4. **Adjust concurrency**: Lower it if you hit rate limits
5. **Regular organization**: Run NoEntropy regularly to keep folders tidy
6. **Test categories**: Use dry-run to test custom categories before committing
7. **Backup important files**: Always maintain backups of critical files
## Performance Considerations
- **Concurrency**: Higher concurrency = faster processing but more API calls
- **Caching**: NoEntropy caches API responses for 7 days to minimize API usage
- **File count**: Large numbers of files (1000+) may take several minutes
- **Rate limits**: Gemini API has rate limits; adjust `--max-concurrent` if needed
## Next Steps
- [How It Works](HOW_IT_WORKS.md) - Understand the organization process
- [Configuration Guide](CONFIGURATION.md) - Learn about configuration options
- [Troubleshooting](TROUBLESHOOTING.md) - Solve common issues
---
[Back to Main README](../README.md)