projpack 1.0.0

Bundle project files into single text file for AI analysis

ProjPack 📦

Bundle entire projects into single text files for AI analysis

ProjPack solves the problem of sharing complex projects with AI tools by intelligently bundling all relevant files into a single, well-structured text document. Perfect for code reviews, debugging sessions, documentation generation, or any scenario where you need to provide complete project context to an AI assistant.

🚀 Quick Start

# Install ProjPack
pip install projpack

# Bundle your project
projpack pack /path/to/your/project

# Preview what would be included
projpack scan /path/to/your/project -v

✨ Features

• 🎯 Smart File Filtering: Automatically excludes binary files, build artifacts, and dependencies
• 📝 Gitignore-like Syntax: Uses .ppignore files with familiar pattern matching
• 🌳 Structured Output: Clear file organization with metadata and tree views
• ⚡ Configurable: Customizable file size limits, ignore patterns, and output formats
• 🛡️ Safe by Default: Includes comprehensive default ignore patterns
• 🌍 Unicode Support: Handles international characters and various encodings
• 📊 Detailed Statistics: Processing metrics and file categorization

📦 Installation

From PyPI (Recommended)

pip install projpack

From Source

git clone https://github.com/yourusername/projpack.git
cd projpack
pip install -e .

🏃‍♂️ Usage

Basic Commands

Bundle a Project

# Bundle current directory
projpack pack .

# Bundle specific directory with custom output
projpack pack /path/to/project -o my_bundle.txt

# Verbose output with statistics
projpack pack . -v

Preview Project Analysis

# See what files would be included
projpack scan . -v

# List all files that would be processed
projpack scan . --list-files

# Check processing statistics
projpack scan . 

Initialize Ignore File

# Create default .ppignore in current directory
projpack init

# Create .ppignore in specific directory
projpack init /path/to/project

Command Options

projpack pack Options

• -o, --output: Output file path (default: <project_name>_bundle.txt)
• -i, --ignore-file: Custom ignore file path
• -s, --max-size: Maximum file size in MB (default: 10)
• -v, --verbose: Enable detailed output
• -f, --force: Overwrite existing files without confirmation
• --no-stats: Exclude statistics from bundle header

projpack scan Options

• -i, --ignore-file: Custom ignore file path
• -s, --max-size: Maximum file size in MB (default: 10)
• -v, --verbose: Enable detailed output
• -l, --list-files: Show all files that would be processed

🚫 Ignore Patterns

ProjPack uses .ppignore files with gitignore-like syntax to exclude unwanted files.

Default Patterns

ProjPack automatically ignores common files:

• Python: __pycache__/, *.pyc, *.pyo, build/, dist/, *.egg-info/
• Node.js: node_modules/, .npm, bower_components/
• Version Control: .git/, .svn/, .hg/, .bzr/
• Virtual Environments: venv/, .venv, env/, ENV/
• OS Files: .DS_Store, Thumbs.db, *.swp
• Build Artifacts: build/, target/, bin/, obj/

Custom .ppignore Syntax

# Comments start with #
# This is a comment

# Ignore all .log files
*.log

# Ignore entire directories
temp/
cache/

# Use ** for recursive matching
**/node_modules/
**/*.tmp

# Negation with ! (include files that would otherwise be ignored)
!important.log
!src/**/*.min.js

# Absolute paths from project root
/specific-file.txt
/build/release/

Pattern Examples

# Ignore all files with specific extensions
*.log
*.tmp
*.cache

# Ignore directories anywhere in the project
__pycache__/
node_modules/
.vscode/

# Ignore files in specific locations
/build/
/dist/
src/generated/

# Complex patterns
**/*.test.js          # All .test.js files in any subdirectory
src/**/*.min.*        # All minified files in src/ and subdirectories
!src/important.min.js # Exception: keep this specific minified file

# Environment and config files
.env
.env.local
config/secrets/
*.key
*.pem

# Temporary and cache files
*.swp
*.swo
*~
.cache/
tmp/

📄 Output Format

ProjPack creates well-structured bundles with:

================================================================================
PROJECT BUNDLE GENERATED BY PROJPACK
================================================================================

Project Root: /path/to/your/project
Generated: 2024-01-20 15:30:45
Total Files: 25

STATISTICS:
  Files processed: 15
  Total size: 45.2 KB
  Files ignored: 8
  Binary files skipped: 2
  Large files skipped: 0
  Directories scanned: 8
  Processing time: 0.15s

FILE STRUCTURE:
├── src/
│   ├── main.py
│   ├── utils/
│   │   ├── helpers.py
│   │   └── constants.py
│   └── tests/
│       └── test_main.py
├── README.md
├── requirements.txt
└── setup.py

================================================================================
FILE CONTENTS
================================================================================

FILE: src/main.py
------------------------------------------------------------
Size: 2.1 KB
Encoding: utf-8
------------------------------------------------------------

#!/usr/bin/env python3
"""Main application module."""

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

if __name__ == "__main__":
    main()


FILE: README.md
------------------------------------------------------------
Size: 1.5 KB
Encoding: utf-8
------------------------------------------------------------

# My Project

This is a sample project...

================================================================================
END OF PROJECT BUNDLE
================================================================================

🔧 Advanced Usage

Custom File Size Limits

# Allow larger files (50MB limit)
projpack pack . -s 50

# Strict limit for smaller bundles (1MB limit)
projpack pack . -s 1

Custom Ignore Files

# Use custom ignore file
projpack pack . -i my-custom.ignore

# Use ignore file from different location
projpack pack . -i /path/to/custom/.ppignore

Integration with Scripts

from projpack import ProjectPacker

# Programmatic usage
packer = ProjectPacker(
    project_root="/path/to/project",
    max_file_size=5 * 1024 * 1024,  # 5MB
    include_stats=True
)

# Scan project
files, stats = packer.scan_project(verbose=True)

# Create bundle
bundle_content = packer.pack_project(
    output_file="my_bundle.txt",
    verbose=True
)

# Get summary
summary = packer.get_project_summary()
print(f"Processed {summary['processed_files']} files")

🎯 Use Cases

AI-Assisted Development

• Code Reviews: Share entire codebase context with AI
• Debugging: Provide complete project context for error analysis
• Documentation: Generate comprehensive project documentation
• Refactoring: Analyze project structure for improvement suggestions

Project Analysis

• Dependency Analysis: Understand project structure and dependencies
• Code Quality: Review entire codebase for patterns and issues
• Knowledge Transfer: Share project understanding with team members
• Backup: Create text-based project snapshots

Educational

• Code Sharing: Share projects in forums or educational platforms
• Portfolio: Create readable project summaries
• Learning: Analyze open-source project structures

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/yourusername/projpack.git
cd projpack
pip install -e ".[dev]"

Running Tests

# Run basic tests
python tests/test_basic.py

# Run with pytest (if available)
pytest tests/

# Test CLI commands
projpack scan tests/fixtures/sample_project

📋 Requirements

• Python 3.7+
• chardet (for encoding detection)

📜 License

MIT License - see LICENSE file for details.

🐛 Bug Reports & Feature Requests

Please use the GitHub Issues page to report bugs or request features.

📞 Support

• 📖 Documentation: GitHub README
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for the AI-assisted development community