projpack

Name	projpack JSON
Version	1.0.0 JSON
	download
home_page	https://github.com/MFael1/ProjPack
Summary	Bundle project files into single text file for AI analysis
upload_time	2025-07-20 11:13:38
maintainer	None
docs_url	None
author	Muhammad Fael
requires_python	>=3.7
license	MIT
keywords	project bundling ai tools development utility
VCS
bugtrack_url
requirements	chardet
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 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

```bash
# 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)
```bash
pip install projpack
```

### From Source
```bash
git clone https://github.com/yourusername/projpack.git
cd projpack
pip install -e .
```

## 🏃‍♂️ Usage

### Basic Commands

#### Bundle a Project
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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

```bash
# 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:

```text
================================================================================
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
```bash
# Allow larger files (50MB limit)
projpack pack . -s 50

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

### Custom Ignore Files
```bash
# 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
```python
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](CONTRIBUTING.md) for details.

### Development Setup
```bash
git clone https://github.com/yourusername/projpack.git
cd projpack
pip install -e ".[dev]"
```

### Running Tests
```bash
# 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](LICENSE) file for details.

## 🐛 Bug Reports & Feature Requests

Please use the [GitHub Issues](https://github.com/yourusername/projpack/issues) page to report bugs or request features.

## 📞 Support

- 📖 Documentation: [GitHub README](https://github.com/MFael1/projpack#readme)
- 🐛 Issues: [GitHub Issues](https://github.com/MFael1/projpack/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/MFael1/projpack/discussions)

---

**Made with ❤️ for the AI-assisted development community**

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/MFael1/ProjPack",
    "name": "projpack",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "Muhammad Fael <muhmmdfa624@gmail.com>",
    "keywords": "project, bundling, ai, tools, development, utility",
    "author": "Muhammad Fael",
    "author_email": "Muhammad Fael <muhmmdfa624@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/63/1a/0ca135fdbfecea78449954143e1035ba4ce803911b2ce900d03b7da86bde/projpack-1.0.0.tar.gz",
    "platform": null,
    "description": "# ProjPack \ud83d\udce6\r\n\r\n**Bundle entire projects into single text files for AI analysis**\r\n\r\nProjPack 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.\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n```bash\r\n# Install ProjPack\r\npip install projpack\r\n\r\n# Bundle your project\r\nprojpack pack /path/to/your/project\r\n\r\n# Preview what would be included\r\nprojpack scan /path/to/your/project -v\r\n```\r\n\r\n## \u2728 Features\r\n\r\n- **\ud83c\udfaf Smart File Filtering**: Automatically excludes binary files, build artifacts, and dependencies\r\n- **\ud83d\udcdd Gitignore-like Syntax**: Uses `.ppignore` files with familiar pattern matching\r\n- **\ud83c\udf33 Structured Output**: Clear file organization with metadata and tree views\r\n- **\u26a1 Configurable**: Customizable file size limits, ignore patterns, and output formats\r\n- **\ud83d\udee1\ufe0f Safe by Default**: Includes comprehensive default ignore patterns\r\n- **\ud83c\udf0d Unicode Support**: Handles international characters and various encodings\r\n- **\ud83d\udcca Detailed Statistics**: Processing metrics and file categorization\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From PyPI (Recommended)\r\n```bash\r\npip install projpack\r\n```\r\n\r\n### From Source\r\n```bash\r\ngit clone https://github.com/yourusername/projpack.git\r\ncd projpack\r\npip install -e .\r\n```\r\n\r\n## \ud83c\udfc3\u200d\u2642\ufe0f Usage\r\n\r\n### Basic Commands\r\n\r\n#### Bundle a Project\r\n```bash\r\n# Bundle current directory\r\nprojpack pack .\r\n\r\n# Bundle specific directory with custom output\r\nprojpack pack /path/to/project -o my_bundle.txt\r\n\r\n# Verbose output with statistics\r\nprojpack pack . -v\r\n```\r\n\r\n#### Preview Project Analysis\r\n```bash\r\n# See what files would be included\r\nprojpack scan . -v\r\n\r\n# List all files that would be processed\r\nprojpack scan . --list-files\r\n\r\n# Check processing statistics\r\nprojpack scan . \r\n```\r\n\r\n#### Initialize Ignore File\r\n```bash\r\n# Create default .ppignore in current directory\r\nprojpack init\r\n\r\n# Create .ppignore in specific directory\r\nprojpack init /path/to/project\r\n```\r\n\r\n### Command Options\r\n\r\n#### `projpack pack` Options\r\n- `-o, --output`: Output file path (default: `<project_name>_bundle.txt`)\r\n- `-i, --ignore-file`: Custom ignore file path\r\n- `-s, --max-size`: Maximum file size in MB (default: 10)\r\n- `-v, --verbose`: Enable detailed output\r\n- `-f, --force`: Overwrite existing files without confirmation\r\n- `--no-stats`: Exclude statistics from bundle header\r\n\r\n#### `projpack scan` Options\r\n- `-i, --ignore-file`: Custom ignore file path\r\n- `-s, --max-size`: Maximum file size in MB (default: 10)\r\n- `-v, --verbose`: Enable detailed output\r\n- `-l, --list-files`: Show all files that would be processed\r\n\r\n## \ud83d\udeab Ignore Patterns\r\n\r\nProjPack uses `.ppignore` files with gitignore-like syntax to exclude unwanted files.\r\n\r\n### Default Patterns\r\nProjPack automatically ignores common files:\r\n- **Python**: `__pycache__/`, `*.pyc`, `*.pyo`, `build/`, `dist/`, `*.egg-info/`\r\n- **Node.js**: `node_modules/`, `.npm`, `bower_components/`\r\n- **Version Control**: `.git/`, `.svn/`, `.hg/`, `.bzr/`\r\n- **Virtual Environments**: `venv/`, `.venv`, `env/`, `ENV/`\r\n- **OS Files**: `.DS_Store`, `Thumbs.db`, `*.swp`\r\n- **Build Artifacts**: `build/`, `target/`, `bin/`, `obj/`\r\n\r\n### Custom .ppignore Syntax\r\n\r\n```bash\r\n# Comments start with #\r\n# This is a comment\r\n\r\n# Ignore all .log files\r\n*.log\r\n\r\n# Ignore entire directories\r\ntemp/\r\ncache/\r\n\r\n# Use ** for recursive matching\r\n**/node_modules/\r\n**/*.tmp\r\n\r\n# Negation with ! (include files that would otherwise be ignored)\r\n!important.log\r\n!src/**/*.min.js\r\n\r\n# Absolute paths from project root\r\n/specific-file.txt\r\n/build/release/\r\n```\r\n\r\n### Pattern Examples\r\n\r\n```bash\r\n# Ignore all files with specific extensions\r\n*.log\r\n*.tmp\r\n*.cache\r\n\r\n# Ignore directories anywhere in the project\r\n__pycache__/\r\nnode_modules/\r\n.vscode/\r\n\r\n# Ignore files in specific locations\r\n/build/\r\n/dist/\r\nsrc/generated/\r\n\r\n# Complex patterns\r\n**/*.test.js          # All .test.js files in any subdirectory\r\nsrc/**/*.min.*        # All minified files in src/ and subdirectories\r\n!src/important.min.js # Exception: keep this specific minified file\r\n\r\n# Environment and config files\r\n.env\r\n.env.local\r\nconfig/secrets/\r\n*.key\r\n*.pem\r\n\r\n# Temporary and cache files\r\n*.swp\r\n*.swo\r\n*~\r\n.cache/\r\ntmp/\r\n```\r\n\r\n## \ud83d\udcc4 Output Format\r\n\r\nProjPack creates well-structured bundles with:\r\n\r\n```text\r\n================================================================================\r\nPROJECT BUNDLE GENERATED BY PROJPACK\r\n================================================================================\r\n\r\nProject Root: /path/to/your/project\r\nGenerated: 2024-01-20 15:30:45\r\nTotal Files: 25\r\n\r\nSTATISTICS:\r\n  Files processed: 15\r\n  Total size: 45.2 KB\r\n  Files ignored: 8\r\n  Binary files skipped: 2\r\n  Large files skipped: 0\r\n  Directories scanned: 8\r\n  Processing time: 0.15s\r\n\r\nFILE STRUCTURE:\r\n\u251c\u2500\u2500 src/\r\n\u2502   \u251c\u2500\u2500 main.py\r\n\u2502   \u251c\u2500\u2500 utils/\r\n\u2502   \u2502   \u251c\u2500\u2500 helpers.py\r\n\u2502   \u2502   \u2514\u2500\u2500 constants.py\r\n\u2502   \u2514\u2500\u2500 tests/\r\n\u2502       \u2514\u2500\u2500 test_main.py\r\n\u251c\u2500\u2500 README.md\r\n\u251c\u2500\u2500 requirements.txt\r\n\u2514\u2500\u2500 setup.py\r\n\r\n================================================================================\r\nFILE CONTENTS\r\n================================================================================\r\n\r\nFILE: src/main.py\r\n------------------------------------------------------------\r\nSize: 2.1 KB\r\nEncoding: utf-8\r\n------------------------------------------------------------\r\n\r\n#!/usr/bin/env python3\r\n\"\"\"Main application module.\"\"\"\r\n\r\ndef main():\r\n    print(\"Hello, World!\")\r\n\r\nif __name__ == \"__main__\":\r\n    main()\r\n\r\n\r\nFILE: README.md\r\n------------------------------------------------------------\r\nSize: 1.5 KB\r\nEncoding: utf-8\r\n------------------------------------------------------------\r\n\r\n# My Project\r\n\r\nThis is a sample project...\r\n\r\n================================================================================\r\nEND OF PROJECT BUNDLE\r\n================================================================================\r\n```\r\n\r\n## \ud83d\udd27 Advanced Usage\r\n\r\n### Custom File Size Limits\r\n```bash\r\n# Allow larger files (50MB limit)\r\nprojpack pack . -s 50\r\n\r\n# Strict limit for smaller bundles (1MB limit)\r\nprojpack pack . -s 1\r\n```\r\n\r\n### Custom Ignore Files\r\n```bash\r\n# Use custom ignore file\r\nprojpack pack . -i my-custom.ignore\r\n\r\n# Use ignore file from different location\r\nprojpack pack . -i /path/to/custom/.ppignore\r\n```\r\n\r\n### Integration with Scripts\r\n```python\r\nfrom projpack import ProjectPacker\r\n\r\n# Programmatic usage\r\npacker = ProjectPacker(\r\n    project_root=\"/path/to/project\",\r\n    max_file_size=5 * 1024 * 1024,  # 5MB\r\n    include_stats=True\r\n)\r\n\r\n# Scan project\r\nfiles, stats = packer.scan_project(verbose=True)\r\n\r\n# Create bundle\r\nbundle_content = packer.pack_project(\r\n    output_file=\"my_bundle.txt\",\r\n    verbose=True\r\n)\r\n\r\n# Get summary\r\nsummary = packer.get_project_summary()\r\nprint(f\"Processed {summary['processed_files']} files\")\r\n```\r\n\r\n## \ud83c\udfaf Use Cases\r\n\r\n### AI-Assisted Development\r\n- **Code Reviews**: Share entire codebase context with AI\r\n- **Debugging**: Provide complete project context for error analysis\r\n- **Documentation**: Generate comprehensive project documentation\r\n- **Refactoring**: Analyze project structure for improvement suggestions\r\n\r\n### Project Analysis\r\n- **Dependency Analysis**: Understand project structure and dependencies\r\n- **Code Quality**: Review entire codebase for patterns and issues\r\n- **Knowledge Transfer**: Share project understanding with team members\r\n- **Backup**: Create text-based project snapshots\r\n\r\n### Educational\r\n- **Code Sharing**: Share projects in forums or educational platforms\r\n- **Portfolio**: Create readable project summaries\r\n- **Learning**: Analyze open-source project structures\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n```bash\r\ngit clone https://github.com/yourusername/projpack.git\r\ncd projpack\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n```bash\r\n# Run basic tests\r\npython tests/test_basic.py\r\n\r\n# Run with pytest (if available)\r\npytest tests/\r\n\r\n# Test CLI commands\r\nprojpack scan tests/fixtures/sample_project\r\n```\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python 3.7+\r\n- `chardet` (for encoding detection)\r\n\r\n## \ud83d\udcdc License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\udc1b Bug Reports & Feature Requests\r\n\r\nPlease use the [GitHub Issues](https://github.com/yourusername/projpack/issues) page to report bugs or request features.\r\n\r\n## \ud83d\udcde Support\r\n\r\n- \ud83d\udcd6 Documentation: [GitHub README](https://github.com/MFael1/projpack#readme)\r\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/MFael1/projpack/issues)\r\n- \ud83d\udcac Discussions: [GitHub Discussions](https://github.com/MFael1/projpack/discussions)\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f for the AI-assisted development community**\r\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Bundle project files into single text file for AI analysis",
    "version": "1.0.0",
    "project_urls": {
        "Bug Reports": "https://github.com/MFael1/projpack/issues",
        "Documentation": "https://github.com/MFael1/projpack#readme",
        "Homepage": "https://github.com/MFael1/ProjPack",
        "Source": "https://github.com/MFael1/projpack"
    },
    "split_keywords": [
        "project",
        " bundling",
        " ai",
        " tools",
        " development",
        " utility"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "e112c7c99ac63fadf227cfdfb4ded14b2e5bc40110631094ba505b52dc79a1a1",
                "md5": "8082e1468f9e94e0db799605b24ec4d8",
                "sha256": "ded441a0bdfb73038fe0f5afa26f6a247a96ac172046a30e7e53320ef0ad9013"
            },
            "downloads": -1,
            "filename": "projpack-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8082e1468f9e94e0db799605b24ec4d8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 47152,
            "upload_time": "2025-07-20T11:13:35",
            "upload_time_iso_8601": "2025-07-20T11:13:35.063939Z",
            "url": "https://files.pythonhosted.org/packages/e1/12/c7c99ac63fadf227cfdfb4ded14b2e5bc40110631094ba505b52dc79a1a1/projpack-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "631a0ca135fdbfecea78449954143e1035ba4ce803911b2ce900d03b7da86bde",
                "md5": "3299009423ea36a98c3e7223315ba6a6",
                "sha256": "44749299eefce0bb974f6daaaedd9eb401207bf877e06e31416cf759117302d0"
            },
            "downloads": -1,
            "filename": "projpack-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "3299009423ea36a98c3e7223315ba6a6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 136503,
            "upload_time": "2025-07-20T11:13:38",
            "upload_time_iso_8601": "2025-07-20T11:13:38.565964Z",
            "url": "https://files.pythonhosted.org/packages/63/1a/0ca135fdbfecea78449954143e1035ba4ce803911b2ce900d03b7da86bde/projpack-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-20 11:13:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "MFael1",
    "github_project": "ProjPack",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "chardet",
            "specs": [
                [
                    ">=",
                    "3.0.0"
                ]
            ]
        }
    ],
    "lcname": "projpack"
}