Flatten Directory

A Python tool that flattens all files in a directory into a single file, inspired by rendergit but designed for local directories.

Features

• Recursive directory scanning - processes all subdirectories
• Smart file filtering - automatically skips binary files, large files, and common directories to ignore
• Gitignore-style pattern matching - use .gitignore files or custom ignore patterns
• Syntax highlighting support - includes language hints for code blocks
• Directory structure overview - shows the file tree at the beginning
• File metadata - includes file sizes and extensions
• Configurable options - customize what to include/exclude
• Multiple output formats - supports various file extensions

Installation

No installation required! Just download the flatten_directory.py script and run it with Python 3.6+.

Usage

Basic Usage

python3 flatten_directory.py /path/to/directory

This will create a file named flattened_<directory_name>.txt in the current directory.

Specify Output File

python3 flatten_directory.py /path/to/directory -o output.txt
python3 flatten_directory.py /path/to/directory --output flattened_code.md

Advanced Options

# Set maximum file size to include (in bytes)
python3 flatten_directory.py /path/to/directory --max-size 2048000

# Skip additional file extensions
python3 flatten_directory.py /path/to/directory --skip-extensions .log .tmp .bak

# Skip additional directories
python3 flatten_directory.py /path/to/directory --skip-dirs logs temp cache

# Use gitignore-style patterns
python3 flatten_directory.py /path/to/directory --gitignore .flattenignore
python3 flatten_directory.py /path/to/directory --gitignore .gitignore

Gitignore-style Pattern Matching

Create a .flattenignore file (or use existing .gitignore) with patterns to skip:

# Skip all markdown files
*.md

# Skip documentation directories
docs/
documentation/

# Skip test files
*_test.py
test_*.py
tests/

# Skip configuration files
*.config
*.conf
config/

# Skip log files
*.log
logs/

# Skip temporary files
*.tmp
*.temp
temp/

# Skip specific files
secrets.txt
private.key
.env.local

# Skip directories with specific names
node_modules/
__pycache__/
.venv/

Command Line Options

• directory - The directory to flatten (required)
• -o, --output - Output file path (default: flattened_<directory_name>.txt)
• --max-size - Maximum file size to include in bytes (default: 1MB)
• --skip-extensions - Additional file extensions to skip
• --skip-dirs - Additional directories to skip
• --gitignore - Path to gitignore-style file with patterns to skip

What Gets Skipped

File Extensions (by default)

• Binary files: .pyc, .so, .dll, .exe, .bin, etc.
• Archives: .zip, .tar, .gz, .rar, etc.
• Media files: .jpg, .png, .mp3, .mp4, etc.
• Documents: .pdf, .doc, .xls, etc.
• Database files: .db, .sqlite, etc.

Directories (by default)

• Version control: .git, .svn, .hg
• Dependencies: node_modules, venv, .venv
• Build artifacts: build, dist, target, bin
• IDE files: .idea, .vscode, .vs
• Cache: __pycache__

Other Filters

• Files larger than 1MB (configurable)
• Binary files detected by content analysis
• Files that can't be read as text
• Gitignore patterns - custom patterns from ignore files

Output Format

The output file contains:

1. Header - Directory name, generation date, file count
2. Directory Structure - Tree view of all files with sizes
3. File Contents - Each file with metadata and syntax-highlighted content

Example output structure:

# Flattened Directory: my_project
# Generated on: Mon Jan 15 10:30:00 PST 2024
# Total files: 5

## Directory Structure

📁 src/
  📄 main.py (1.2 KB)
  📄 utils.py (800 bytes)
📁 tests/
  📄 test_main.py (1.5 KB)
📄 README.md (500 bytes)
📄 requirements.txt (200 bytes)

---

## File 1: src/main.py
Size: 1200 bytes
Extension: .py

```python
def main():
    print("Hello, World!")

---

## Examples

### Flatten a Python project
```bash
python3 flatten_directory.py /path/to/python/project -o project_code.txt

Flatten a web project (skip node_modules)

python3 flatten_directory.py /path/to/web/project --skip-dirs node_modules dist

Create a markdown file for documentation

python3 flatten_directory.py /path/to/project -o documentation.md

Use gitignore patterns for filtering

# Use custom ignore file
python3 flatten_directory.py /path/to/project --gitignore .flattenignore

# Use existing .gitignore
python3 flatten_directory.py /path/to/project --gitignore .gitignore

# Combine with other options
python3 flatten_directory.py /path/to/project --gitignore .flattenignore --skip-extensions .log .tmp

Use Cases

• Code Review - Get all project files in one place for easy review
• Documentation - Create comprehensive project documentation
• Backup - Create a text-based backup of your codebase
• Analysis - Feed entire codebase to AI tools for analysis
• Sharing - Share your entire project as a single file
• Selective Export - Use ignore patterns to export only specific parts of your codebase

Limitations

• Only processes text files (skips binaries)
• Maximum file size limit (default 1MB, configurable)
• Memory usage scales with total file size
• No support for file permissions or timestamps in output

Contributing

Feel free to submit issues and pull requests. This project is designed to be simple and focused.

License

This project is inspired by rendergit and is provided as-is for educational and practical use.