florg 1.0.0

A CLI tool for batch file renaming and organizing

florg - File Organizer by Command line

A powerful CLI tool for batch file renaming and organizing with an intuitive interface, preview mode, and undo capability.

Features

✨ Multiple Renaming Strategies:

• Numeric sequence (file001, file002, ...)
• Alphabetical order
• Creation date
• Last modification date
• File size
• File type/extension
• Custom prefix/suffix

📁 Smart Grouping:

• Group by creation date
• Group by modification date
• Group by size range
• Group by file type

🔍 Preview Mode:

• See changes before they happen
• Beautiful table display with Rich library
• Confirm before executing

↩️ Undo Capability:

• Revert the last operation
• Automatic history tracking
• Per-directory undo support

🎯 Flexible Filtering:

• Filter by file extensions
• Interactive extension selection
• Support for multiple extensions

Installation

From PyPI (Recommended)

Install florg directly from PyPI using pip:

pip install florg

That's it! The organize command will be available immediately.

From Source

For development or the latest changes:

1. Clone the repository:

git clone https://github.com/laisario/florg.git
cd florg

2. Install in development mode:

pip install -e .

Dependencies

florg automatically installs these dependencies:

• click - CLI framework
• rich - Beautiful terminal output
• questionary - Interactive prompts

Usage

Basic Usage

organize /path/to/directory

This will:

1. Show available files
2. Prompt you to choose an organization method
3. Display a preview of changes
4. Ask for confirmation
5. Execute the operation

Command Line Options

organize [OPTIONS] DIRECTORY

Options:

• --group - Enable grouping mode (organize files into folders)
• --undo - Revert the last operation in this directory
• --no-preview - Skip preview and execute immediately
• --extensions, -e - Filter by file extensions (comma-separated)

Examples

Basic Rename with Preview (Default)

organize ~/Documents/photos

The tool will interactively guide you through:

1. Choosing a renaming strategy
2. Setting parameters (prefix, suffix, etc.)
3. Showing a preview of all changes
4. Asking for confirmation

Rename Specific Extensions

organize ~/Downloads --extensions .pdf,.docx

Only process PDF and Word documents.

Skip Preview for Automation

organize ~/Music --no-preview

Execute immediately without confirmation (use with caution!).

Group Files into Folders

organize ~/Documents --group

After choosing a rename strategy, you'll be asked how to group files:

• By date (folders like "2025-11-04")
• By size range (folders like "Small (10 KB - 1 MB)")
• By file type (folders like "pdf", "jpg")

Combined: Filter and Group

organize ~/Downloads --group --extensions .jpg,.png,.gif

Filter for image files and organize them into folders.

Undo Last Operation

organize ~/Documents --undo

Revert the last batch operation performed in this directory.

Renaming Strategies

1. Numeric Increase

Rename files with sequential numbers.

Prompts:

• Starting number (default: 1)
• Padding digits (default: 3)
• Prefix (optional)
• Suffix (optional)

Example output:

file001.txt
file002.txt
file003.txt

2. Alphabetical Order

Sort and optionally rename files alphabetically.

Prompts:

• Reverse order? (Y/n)
• Prefix (optional)
• Suffix (optional)

Example output:

document_a.txt
document_b.txt
document_c.txt

3. Creation Date

Rename based on file creation date.

Prompts:

• Date format (default: %Y%m%d)
• Prefix (optional)
• Suffix (optional)

Example output:

20251104_1.jpg
20251104_2.jpg
20251105_1.jpg

4. Modification Date

Rename based on last modification date.

Prompts:

• Date format (default: %Y%m%d)
• Prefix (optional)
• Suffix (optional)

Example output:

mod_20251104.pdf
mod_20251103.pdf

5. File Size

Rename files sorted by size.

Prompts:

• Sort order (ascending/descending)
• Prefix (optional)
• Suffix (optional)

Example output:

001_15.2KB.jpg
002_124.5KB.jpg
003_1.2MB.jpg

6. File Type/Extension

Organize by file type with sequential numbering.

Prompts:

• Keep original names? (Y/n)
• Prefix (optional)
• Suffix (optional)

Example output:

jpg_001.jpg
jpg_002.jpg
pdf_001.pdf

7. Custom Prefix/Suffix

Simply add prefix and/or suffix to existing names.

Prompts:

• Prefix text
• Suffix text

Example output:

PREFIX_original_name_SUFFIX.txt

Grouping Strategies

Same Creation Date

Groups files into folders based on creation date.

Folder names: 2025-11-04/, 2025-11-03/

Same Modification Date

Groups files into folders based on modification date.

Folder names: 2025-11-04/, 2025-11-03/

Same Size Range

Groups files into predefined size categories.

Folder names:

• Tiny (< 10 KB)/
• Small (10 KB - 1 MB)/
• Medium (1 MB - 10 MB)/
• Large (10 MB - 100 MB)/
• Huge (> 100 MB)/

Same File Type

Groups files by extension.

Folder names: txt/, jpg/, pdf/

Preview Mode

By default, the tool shows a beautiful preview of all changes before executing:

┌─────────────── Rename Preview ───────────────┐
│ #   Current Name     →  New Name             │
├─────────────────────────────────────────────┤
│ 1   image.jpg        →  photo_001.jpg        │
│ 2   document.txt     →  photo_002.txt        │
│ 3   file.pdf         →  photo_003.pdf        │
└─────────────────────────────────────────────┘

Total files to rename: 3

Do you want to proceed with these changes? (Y/n):

Undo Feature

Every operation is automatically saved to history. You can undo the last operation:

organize ~/Documents --undo

This will:

1. Load the last operation for that directory
2. Show what will be reverted
3. Ask for confirmation
4. Move all files back to original locations
5. Remove empty folders (for group operations)

History Location: ~/.florg_history.json

Error Handling

The tool handles various error scenarios:

• ✓ Permission errors - Shows clear error messages
• ✓ Name collisions - Automatically appends (1), (2), etc.
• ✓ Invalid characters - Sanitizes filenames
• ✓ Missing files - Gracefully skips
• ✓ Interrupted operations - Partial operations are tracked

Testing

Run the test suite:

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=organize --cov-report=html

Project Structure

florg/
├── organize/
│   ├── __init__.py
│   ├── cli.py          # Main CLI entry point
│   ├── renamer.py      # Renaming strategies
│   ├── grouper.py      # Grouping logic
│   ├── history.py      # Undo functionality
│   ├── preview.py      # Preview display
│   ├── filters.py      # File filtering
│   └── utils.py        # Utility functions
├── tests/
│   ├── test_renamer.py
│   ├── test_grouper.py
│   ├── test_history.py
│   └── test_filters.py
├── setup.py
├── requirements.txt
└── README.md

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/laisario/florg.git
cd florg

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Code Style

The project uses black for code formatting:

black organize/ tests/

Future Enhancements

Potential features for future versions:

• 🔄 Recursive mode for subdirectories
• 📝 Configuration file support
• 🔍 Regex pattern support
• 📊 Duplicate file detection
• 🏷️ EXIF/metadata-based renaming
• 🌐 Web interface
• 🔌 Plugin system for custom strategies
• 📅 Scheduled/automated organization
• 🌍 Multi-language support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Command not found after installation

Make sure your Python scripts directory is in your PATH:

# On Linux/Mac
export PATH="$HOME/.local/bin:$PATH"

# On Windows (PowerShell)
$env:Path += ";$HOME\AppData\Local\Programs\Python\Python3X\Scripts"

Permission denied errors

Ensure you have write permissions in the target directory:

chmod u+w /path/to/directory

Undo not working

Check if the history file exists:

cat ~/.florg_history.json

If corrupted, you can reset it:

rm ~/.florg_history.json

Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include error messages and steps to reproduce

Acknowledgments

• Built with Click for CLI handling
• Styled with Rich for beautiful output
• Interactive prompts powered by Questionary

---

Made with ❤️