A powerful command-line tool for automatically organizing files by type, date, or custom rules
Features • Installation • Usage • Documentation • Contributing
A powerful command-line tool for automatically organizing files by type, date, or custom rules. Perfect for cleaning up messy Downloads folders, organizing project files, or maintaining a tidy file system.
- 🗂️ Multiple Organization Types: Organize by file type, creation/modification date, or custom rules
- 👀 Dry Run Mode: Preview changes before executing them
- ⏪ Undo Functionality: Easily reverse organization operations
- 🎯 Custom Rules: Define your own organization patterns with flexible rule engine
- 🚀 Fast & Efficient: Handles large directories with minimal resource usage
- 🔧 Configurable: Extensive configuration options via YAML files
- 📊 Rich Output: Beautiful, informative command-line interface
- 🔒 Safe: Built-in safeguards and error handling
# Method 1: Quick install from source
git clone https://github.com/locfaker/file-organizer-cli.git
cd file-organizer-cli
python scripts/install.py
# Method 2: Manual install
pip install -r requirements.txt
pip install -e .
# Method 3: Using Make (if available)
make install-dev# Organize files by type (images, documents, videos, etc.)
file-organizer organize /path/to/messy/folder
# Preview changes without executing
file-organizer organize /path/to/folder --dry-run
# Organize by date
file-organizer organize /path/to/folder --type date
# Undo last operation
file-organizer undo# Preview organization
file-organizer preview ~/Downloads
# Organize by file type
file-organizer organize ~/Downloads --type type
# Check what was organized
file-organizer undo --list# Organize photos by year/month
file-organizer organize ~/Pictures --type date
# Use custom date format (configured in config file)
file-organizer organize ~/Documents --type date# Create default configuration file
file-organizer init-config
# Use custom config
file-organizer --config my-config.yaml organize ~/folderCreate a configuration file to customize organization behavior:
file-organizer init-config --output ~/.config/file-organizer/config.yaml# File type mappings
file_types:
images:
- .jpg
- .jpeg
- .png
- .gif
- .webp
documents:
- .pdf
- .doc
- .docx
- .txt
code:
- .py
- .js
- .html
- .css
# Custom organization rules
custom_rules:
- name: "Backup Files"
pattern: "*.bak"
pattern_type: "glob"
destination: "backups"
- name: "Large Files"
pattern_type: "size"
min_size: 104857600 # 100MB
destination: "large_files"
# Date organization settings
date_format: "%Y/%m" # Year/Month
use_creation_date: true
# General settings
create_subdirs: true
max_depth: 10| Command | Description |
|---|---|
organize |
Organize files in a directory |
preview |
Preview organization without making changes |
undo |
Undo previous organization operations |
init-config |
Create a default configuration file |
| Type | Description |
|---|---|
type |
Organize by file extension/type (default) |
date |
Organize by file creation/modification date |
custom |
Use custom rules defined in configuration |
| Option | Description |
|---|---|
--config |
Path to configuration file |
--help |
Show help message |
--version |
Show version information |
| Option | Description |
|---|---|
--type |
Organization type (type/date/custom) |
--dry-run |
Preview changes without executing |
--verbose |
Show detailed output |
| Option | Description |
|---|---|
--session-id |
Undo specific session |
--dry-run |
Preview undo without executing |
--list |
List available undo sessions |
Define powerful custom rules in your configuration:
custom_rules:
# Organize by file size
- name: "Large Media Files"
pattern_type: "size"
min_size: 52428800 # 50MB
destination: "large_media/{year}"
# Organize by filename pattern
- name: "Screenshots"
pattern: "screenshot*"
pattern_type: "name"
destination: "screenshots/{year}/{month}"
# Organize by regex
- name: "Version Files"
pattern: ".*v\\d+\\.\\d+.*"
pattern_type: "regex"
destination: "versions"Use template variables in destination paths:
{filename}- File name without extension{extension}- File extension{full_name}- Complete file name{year},{month},{day}- Current date{file_year},{file_month},{file_day}- File date
# Organize multiple directories
for dir in ~/Downloads ~/Desktop ~/Documents; do
file-organizer organize "$dir" --type type
done
# Organize with different rules
file-organizer organize ~/Pictures --type date
file-organizer organize ~/Downloads --type type
file-organizer organize ~/Projects --type customRun the test suite:
# Run all tests
pytest
# Run with coverage
pytest --cov=src/file_organizer
# Run specific test file
pytest tests/test_core.py -vContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
# Clone the repository
git clone https://github.com/locfaker/file-organizer-cli.git
cd file-organizer-cli
# Install development dependencies
pip install -r requirements.txt
# Install pre-commit hooks
pre-commit install
# Run tests
pytestThis project is licensed under the MIT License - see the LICENSE file for details.
- Built with Click for the CLI interface
- Rich for beautiful terminal output
- PyYAML for configuration file handling
If you encounter any issues or have questions:
- Check the Issues page
- Create a new issue with detailed information
- Include your configuration file and command used (remove sensitive information)
Made with ❤️ for developers who love organized file systems
- ✅ Production Ready: Fully tested and documented
- ✅ Cross Platform: Windows, macOS, Linux support
- ✅ Active Development: Regular updates and improvements
- ✅ Community Driven: Open to contributions and feedback
Star ⭐ this repository if you find it useful!