Code File Organizer

Intelligent file organization for developers

Features • Installation • Usage • Documentation • Examples • License

---

🔍 Overview

Code File Organizer is a powerful Python tool that automatically organizes code files into directories based on file type, project structure, and content analysis. It uses intelligent algorithms to categorize files beyond just their extensions, making it perfect for cleaning up messy project directories or standardizing your development workspace.

✨ Features

• Intelligent Content Analysis

  • Detects file types based on content patterns and signatures
  • Identifies framework-specific files like React components
  • Recognizes configuration files regardless of extension

• Project Structure Detection

  • Automatically identifies Node.js, Python, and Git projects
  • Preserves important project structure with project mode
  • Adapts organization strategy based on detected project type

• Advanced Organization

  • Customizable mappings for complete control
  • Duplicate file detection using MD5 hashing
  • Smart categorization of scripts by shebang line detection

• Developer Experience

  • Dry run mode to preview changes
  • Detailed report generation
  • Performance metrics and statistics
  • Extensive configuration options

🚀 Installation

Option 1: Direct Installation (Recommended)

# Clone the repository
git clone https://github.com/SNO7E-G/code-file-organizer.git

# Navigate to the directory
cd code-file-organizer

# Install the package
pip install -e .

Option 2: Install from GitHub

pip install git+https://github.com/SNO7E-G/code-file-organizer.git

📋 Usage

Basic Command

Organize the current directory:

code-organizer

Or use the Python script directly:

python file_organizer.py

Command Line Arguments

usage: file_organizer.py [-h] [--target-dir TARGET_DIR] [--project-mode]
                        [--dry-run] [--save-config] [--load-config]
                        [--config-file CONFIG_FILE] [--report]
                        [--report-file REPORT_FILE] [--no-smart]
                        [--no-duplicates] [--exclude-dir EXCLUDE_DIR]
                        [--exclude-file EXCLUDE_FILE] [--version] [--verbose]
                        [source_dir]

Common Commands

Task	Command
Organize current directory	code-organizer
Preview changes without applying	code-organizer --dry-run
Preserve project structure	code-organizer --project-mode
Generate detailed report	code-organizer --report
Verbose output	code-organizer --verbose
Show version info	code-organizer --version

Advanced Examples

1. Organize files with custom exclusions:

   code-organizer --exclude-dir build --exclude-dir dist --exclude-file README.md

2. Organize files from one directory to another:

   code-organizer /source/directory --target-dir /target/directory

3. Save and load configuration:

   # Save current settings
   code-organizer --save-config --config-file my_config.json
   
   # Load saved settings
   code-organizer --load-config --config-file my_config.json

📊 How It Works

Smart Detection Process

1. Project Analysis

   • Scans for project identifiers (package.json, requirements.txt, etc.)
   • Identifies repository type and structure
   • Determines optimal organization strategy

2. File Processing

   • Examines file content with pattern recognition
   • Analyzes file headers and signatures
   • Computes file hashes to detect duplicates
   • Identifies relationships between files

3. Intelligent Organization

   • Categorizes files based on combined analysis results
   • Creates logical directory structure
   • Maintains project integrity

🛠️ Custom Configuration

You can create a custom mapping file in JSON format:

{
  "source_dir": "/path/to/source",
  "target_dir": "/path/to/target",
  "mappings": {
    "py": "Python",
    "js": "JavaScript",
    "html": "Web/HTML"
  },
  "project_mode": false,
  "exclude_dirs": [".git", "node_modules", "venv"],
  "exclude_files": ["file_organizer.py", "file_organizer_config.json"]
}

See examples.md for more custom configuration examples.

📁 Default Mappings

The organizer includes comprehensive mappings for:

Category	File Types
Web Technologies	HTML, CSS, JavaScript, TypeScript, PHP, React
Programming Languages	Python, Java, C/C++, C#, Go, Ruby, Rust, Swift, Kotlin
Data Formats	JSON, XML, YAML, CSV, Excel
Documentation	Markdown, Text, PDF, Word
Configuration	INI, CFG, ENV, TOML
Media	Images (JPG, PNG, SVG, etc.)
Scripts	Shell, Batch, PowerShell
Database	SQL

🤝 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/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📑 Documentation

For more detailed documentation and examples, see:

• examples.md - Examples of intelligent file detection
• custom_mappings_example.json - Example of custom mapping configurations

📄 License

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

👨‍💻 Author

Mahmoud Ashraf (SNO7E)

---

If you find this tool useful, please consider giving it a star! ⭐