c2c

A Python package that converts a directory structure into a single text file, preserving file contents and directory hierarchy while respecting .gitignore rules. Perfect for sharing codebase context with AI language models or creating project snapshots.

Features

• Smart Directory Scanning:

  • Recursively scans directories and outputs contents as a single well-formatted text file
  • Clear delimiters between files for unambiguous parsing
  • Memory-efficient streaming output for large codebases

• Git-Aware File Filtering:

  • Built on top of the high-performance gitignore-filter library
  • Fully respects .gitignore rules at both root and subdirectory levels
  • Supports advanced patterns including negation and directory-specific rules

• Intelligent File Handling:

  • Automatic binary file detection and exclusion
  • UTF-8 encoding support with robust error handling
  • Unique, collision-free delimiters for file separation
  • Efficient streaming I/O for large files

• Flexible Configuration:

  • Custom exclude patterns using gitignore syntax
  • Debug mode for troubleshooting pattern matches
  • Simple CLI and Python API integration

• AI-Ready Output:

  • Generates output optimized for AI language models
  • Preserves directory structure and file relationships
  • Clear metadata and file boundaries

Requirements

• Python 3.7 or higher
• gitignore-filter 0.2.2 or higher

Installation

Install from PyPI:

pip install c2c

Or install from source:

git clone https://github.com/ykawataki/c2c.git
cd c2c
pip install .

Usage

Command Line Interface

Basic usage - scan current directory:

c2c .

Scan specific directory:

c2c /path/to/directory

Choose output format:

# Default text format - human-readable with clear file boundaries
c2c .

# JSONL format - machine-readable, perfect for programmatic processing
c2c . --format jsonl

Text format is ideal for:

• Sharing code with AI language models
• Creating human-readable project snapshots
• Quick code reviews

JSONL format is better for:

• Programmatic processing of code
• Integration with data pipelines
• Structured data analysis
• Building development tools

Exclude specific patterns using gitignore format:

# Exclude all log files
c2c . -e "*.log"

# Exclude temp directory
c2c . -e "temp/"

# Complex patterns
c2c . -e "*.log" -e "!important.log" -e "debug/**/*.tmp"

Supported pattern formats:

• Simple patterns: *.log, *.tmp
• Directory patterns: temp/, build/
• Negative patterns: !important.log
• Path-specific patterns: src/*.log
• Nested patterns: **/*.log

Enable debug mode to see pattern matching details:

c2c . --debug

Save output to file:

# Text format
c2c . > project_snapshot.txt

# JSONL format
c2c . --format jsonl > project_snapshot.jsonl

Python API

The package provides a simple Python API for integration into your tools:

from c2c import scan_directory

# Basic usage with text format
with open('output.txt', 'w', encoding='utf-8') as output_file:
    scan_directory(
        directory=".",
        exclude_patterns=[".git"],  # Default exclude pattern
        output_file=output_file
    )

# With JSONL format and custom patterns
with open('output.jsonl', 'w', encoding='utf-8') as output_file:
    scan_directory(
        directory="/path/to/project",
        exclude_patterns=[
            ".git",
            "*.log",
            "temp/*",
            "!important.log"
        ],
        output_file=output_file,
        format="jsonl",
        debug=True
    )

Using with AI Language Models

1. Generate a project snapshot:

c2c . > context.txt

2. Use in your prompts:

Here's my project structure and contents:

[paste contents of context.txt]

Could you help me understand the code structure and suggest improvements?

Output Formats

Text Format

The text format is human-readable and follows this structure:

# Project Directory Contents
Format: Files are separated by a delimiter line starting with "### FILE_[uuid]"
Each delimiter line is followed by the file path, then the file contents.
Note: Binary files and patterns matching any .gitignore are excluded.

DELIMITER=### FILE_[uuid]

### FILE_[uuid] src/main.py
[contents of main.py]

### FILE_[uuid] src/utils/helper.py
[contents of helper.py]

JSONL Format

The JSONL format provides structured data where each line is a valid JSON object:

{"path": "src/main.py", "content": "print('Hello, World!')"}
{"path": "src/utils/helper.py", "content": "def helper():\n    pass"}

Each line contains:

• path: Relative path to the file within the project
• content: Complete content of the file

Default Behavior

By default, c2c:

• Excludes .git directories and Git-related files
• Excludes binary files (automatically detected)
• Respects all .gitignore patterns
• Uses UTF-8 encoding for file reading/writing
• Streams output for memory efficiency

Implementation Details

Pattern Matching

Built on the gitignore-filter library, c2c supports:

• Full gitignore pattern syntax
• Multiple .gitignore files with proper precedence
• Pattern negation with !
• Directory-specific patterns
• Path-based pattern scoping

File Processing

• Binary detection through UTF-8 decoding attempt
• Streaming file I/O for memory efficiency
• Proper resource cleanup
• Robust error handling

Performance Optimization

• Memory-efficient file processing
• Streaming output generation
• Minimal memory footprint
• High-performance pattern matching through gitignore-filter

Contributing

Contributions are welcome! Here's how you can help:

• Submit bug reports and feature requests
• Improve documentation and examples
• Share use cases and ideas
• Submit pull requests

Please feel free to open issues or submit pull requests on GitHub.

License

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