https://github.com/laisario/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.
https://github.com/laisario/florg
cli organizer system-files
Last synced: 5 months ago
JSON representation
File Organizer by Command line - A powerful CLI tool for batch file renaming and organizing with an intuitive interface, preview mode, and undo capability.
- Host: GitHub
- URL: https://github.com/laisario/florg
- Owner: laisario
- License: mit
- Created: 2025-11-13T14:12:56.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-13T14:52:46.000Z (7 months ago)
- Last Synced: 2025-12-20T11:33:13.138Z (5 months ago)
- Topics: cli, organizer, system-files
- Language: Python
- Homepage: https://pypi.org/project/florg/
- Size: 26.4 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```bash
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:
```bash
git clone https://github.com/laisario/florg.git
cd florg
```
2. Install in development mode:
```bash
pip install -e .
```
### Dependencies
florg automatically installs these dependencies:
- `click` - CLI framework
- `rich` - Beautiful terminal output
- `questionary` - Interactive prompts
## Usage
### Basic Usage
```bash
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
```bash
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)
```bash
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
```bash
organize ~/Downloads --extensions .pdf,.docx
```
Only process PDF and Word documents.
#### Skip Preview for Automation
```bash
organize ~/Music --no-preview
```
Execute immediately without confirmation (use with caution!).
#### Group Files into Folders
```bash
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
```bash
organize ~/Downloads --group --extensions .jpg,.png,.gif
```
Filter for image files and organize them into folders.
#### Undo Last Operation
```bash
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:
```bash
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:
```bash
# 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
```bash
# 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:
```bash
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:
```bash
# 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:
```bash
chmod u+w /path/to/directory
```
### Undo not working
Check if the history file exists:
```bash
cat ~/.florg_history.json
```
If corrupted, you can reset it:
```bash
rm ~/.florg_history.json
```
## Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/laisario/florg/issues) page
2. Create a new issue with detailed information
3. Include error messages and steps to reproduce
## Acknowledgments
- Built with [Click](https://click.palletsprojects.com/) for CLI handling
- Styled with [Rich](https://rich.readthedocs.io/) for beautiful output
- Interactive prompts powered by [Questionary](https://questionary.readthedocs.io/)
---
Made with â¤ī¸