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
This commit is contained in:
620
README.md
620
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!
|
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
|
## Features
|
||||||
|
|
||||||
- **🧠 AI-Powered Categorization** - Uses Google Gemini API for intelligent file sorting
|
- **🧠 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)
|
- **💨 Smart Caching** - Minimizes API calls with metadata-based caching (7-day expiry)
|
||||||
- **⚡ Concurrent Processing** - Parallel file inspection with configurable limits
|
- **⚡ Concurrent Processing** - Parallel file inspection with configurable limits
|
||||||
- **👀 Dry-Run Mode** - Preview changes without moving any files
|
- **👀 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
|
- **📝 Text File Support** - Inspects 30+ text formats for better categorization
|
||||||
- **✅ Interactive Confirmation** - Review organization plan before execution
|
- **✅ Interactive Confirmation** - Review organization plan before execution
|
||||||
- **🎯 Configurable** - Adjust concurrency limits and model settings
|
|
||||||
- **↩️ Undo Support** - Revert file organization changes if needed
|
- **↩️ Undo Support** - Revert file organization changes if needed
|
||||||
|
|
||||||
## Prerequisites
|
## Quick Start
|
||||||
|
|
||||||
- **Rust 2024 Edition** or later
|
### Installation
|
||||||
- **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
|
**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
|
```bash
|
||||||
https://github.com/glitchySid/noentropy/releases
|
# Linux/macOS: Give execute permissions
|
||||||
```
|
chmod +x noentropy
|
||||||
2. **Give Permisson(For Linux/Mac)**
|
|
||||||
```bash
|
# Run NoEntropy
|
||||||
chmod +x binaryfilename
|
./noentropy
|
||||||
```
|
```
|
||||||
|
|
||||||
## Run Locally
|
**Option 2: Build from Source**
|
||||||
|
|
||||||
1. **Clone repository**
|
|
||||||
```bash
|
```bash
|
||||||
|
# Clone repository
|
||||||
git clone https://github.com/glitchySid/noentropy.git
|
git clone https://github.com/glitchySid/noentropy.git
|
||||||
cd noentropy
|
cd noentropy
|
||||||
```
|
|
||||||
|
|
||||||
2. **Build the application**
|
# Build and run
|
||||||
```bash
|
|
||||||
cargo build --release
|
cargo build --release
|
||||||
```
|
|
||||||
|
|
||||||
3. **Run the application**
|
|
||||||
On first run, NoEntropy will guide you through interactive setup:
|
|
||||||
```bash
|
|
||||||
./target/release/noentropy
|
./target/release/noentropy
|
||||||
```
|
```
|
||||||
|
|
||||||
Or manually create config file at `~/.config/noentropy/config.toml`:
|
### First Run
|
||||||
```bash
|
|
||||||
cp config.example.toml ~/.config/noentropy/config.toml
|
|
||||||
nano ~/.config/noentropy/config.toml
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
On first run, NoEntropy will guide you through an interactive setup to configure your API key and download folder. That's it!
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
### Basic Usage
|
### 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
|
```bash
|
||||||
cargo run --release
|
$ ./noentropy
|
||||||
```
|
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
Found 47 files. Asking Gemini to organize...
|
Found 47 files. Asking Gemini to organize...
|
||||||
Gemini Plan received! Performing deep inspection...
|
Gemini Plan received! Performing deep inspection...
|
||||||
Reading content of report.pdf...
|
Deep inspection complete!
|
||||||
Reading content of config.yaml...
|
|
||||||
Reading content of script.py...
|
|
||||||
Deep inspection complete! Moving Files.....
|
|
||||||
|
|
||||||
--- EXECUTION PLAN ---
|
--- EXECUTION PLAN ---
|
||||||
Plan: image1.png -> Images/
|
Plan: image1.png -> Images/
|
||||||
Plan: document.pdf -> Documents/
|
Plan: document.pdf -> Documents/
|
||||||
Plan: setup.exe -> Installers/
|
|
||||||
Plan: notes.txt -> Documents/Notes/
|
Plan: notes.txt -> Documents/Notes/
|
||||||
Plan: config.yaml -> Code/Config/
|
Plan: config.yaml -> Code/Config/
|
||||||
Plan: script.py -> Code/Scripts/
|
Plan: script.py -> Code/Scripts/
|
||||||
|
...
|
||||||
|
|
||||||
Do you want to apply these changes? [y/N]: y
|
Do you want to apply these changes? [y/N]: y
|
||||||
|
|
||||||
--- MOVING FILES ---
|
--- MOVING FILES ---
|
||||||
Moved: image1.png -> Images/
|
Moved: image1.png -> Images/
|
||||||
Moved: document.pdf -> Documents/
|
Moved: document.pdf -> Documents/
|
||||||
Moved: setup.exe -> Installers/
|
|
||||||
Moved: notes.txt -> Documents/Notes/
|
Moved: notes.txt -> Documents/Notes/
|
||||||
Moved: config.yaml -> Code/Config/
|
...
|
||||||
Moved: script.py -> Code/Scripts/
|
|
||||||
|
|
||||||
Organization Complete!
|
Organization Complete!
|
||||||
Files moved: 47, Errors: 0
|
Files moved: 47, Errors: 0
|
||||||
Done!
|
Done!
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Undo Example
|
## Use Cases
|
||||||
|
|
||||||
```bash
|
- 📂 Organize a messy Downloads folder
|
||||||
$ cargo run --release -- --undo
|
- 🤖 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 ---
|
## Key Features Explained
|
||||||
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
|
### Custom Categories
|
||||||
|
|
||||||
--- UNDOING MOVES ---
|
Define your own categories instead of using defaults:
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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
|
```toml
|
||||||
api_key = "your_actual_api_key"
|
# config.toml
|
||||||
download_folder = "/home/user/Downloads"
|
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:
|
### Smart Caching
|
||||||
```toml
|
|
||||||
download_folder = "/path/to/your/Downloads"
|
|
||||||
```
|
|
||||||
|
|
||||||
### "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**:
|
### Undo Functionality
|
||||||
- Wait a few minutes before trying again
|
|
||||||
- Reduce `--max-concurrent` to limit API calls
|
|
||||||
- Use caching to reduce redundant requests
|
|
||||||
|
|
||||||
### "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
|
```bash
|
||||||
cargo build
|
./noentropy --undo
|
||||||
```
|
```
|
||||||
|
|
||||||
### Build in Release Mode
|
All file moves are tracked for 30 days with full conflict detection and safety features.
|
||||||
```bash
|
|
||||||
cargo build --release
|
|
||||||
```
|
|
||||||
|
|
||||||
### Run Tests
|
## Requirements
|
||||||
```bash
|
|
||||||
cargo test
|
|
||||||
```
|
|
||||||
|
|
||||||
### Run Clippy (Linting)
|
- **Rust 2024 Edition** or later (if building from source)
|
||||||
```bash
|
- **Google Gemini API Key** - Get one at [https://ai.google.dev/](https://ai.google.dev/)
|
||||||
cargo clippy
|
|
||||||
```
|
|
||||||
|
|
||||||
### Check Code
|
## Command-Line Options
|
||||||
```bash
|
|
||||||
cargo check
|
| 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
|
## Project Structure
|
||||||
|
|
||||||
NoEntropy follows a clean modular architecture for better maintainability and testability:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
noentropy/
|
noentropy/
|
||||||
├── .github/
|
├── docs/ # Comprehensive documentation
|
||||||
│ └── workflows/
|
|
||||||
│ └── rust.yml # CI/CD workflow
|
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── cli/
|
│ ├── cli/ # Command-line interface
|
||||||
│ │ ├── mod.rs # CLI module exports
|
│ ├── files/ # File operations and detection
|
||||||
│ │ ├── args.rs # Command-line argument definitions
|
│ ├── gemini/ # AI integration
|
||||||
│ │ └── orchestrator.rs # Organization & undo orchestration
|
│ ├── models/ # Data structures
|
||||||
│ ├── files/
|
│ ├── settings/ # Configuration management
|
||||||
│ │ ├── mod.rs # File module exports
|
│ └── storage/ # Caching and undo log
|
||||||
│ │ ├── batch.rs # File batch processing
|
├── Cargo.toml
|
||||||
│ │ ├── detector.rs # File type detection
|
└── README.md
|
||||||
│ │ ├── 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Module Overview
|
See the [Development Guide](docs/DEVELOPMENT.md) for detailed architecture information.
|
||||||
|
|
||||||
- **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
|
|
||||||
|
|
||||||
## Contributing
|
## 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
|
- How to report bugs
|
||||||
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
|
- How to suggest features
|
||||||
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
|
- Development setup
|
||||||
4. Push to the branch (`git push origin feature/AmazingFeature`)
|
- Code standards
|
||||||
5. Open a Pull Request
|
- 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
|
## 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/)
|
- Powered by [Google Gemini API](https://ai.google.dev/)
|
||||||
- Inspired by the endless struggle to keep Downloads folders organized
|
- 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
202
docs/CONFIGURATION.md
Normal 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
494
docs/CONTRIBUTING.md
Normal 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
502
docs/DEVELOPMENT.md
Normal 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
345
docs/HOW_IT_WORKS.md
Normal 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
121
docs/INSTALLATION.md
Normal 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
518
docs/TROUBLESHOOTING.md
Normal 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
329
docs/USAGE.md
Normal 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)
|
||||||
Reference in New Issue
Block a user