# 🗂️ prepdir
[](https://github.com/eyecantell/prepdir/actions/runs/16282502771)
[](https://badge.fury.io/py/prepdir)
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/prepdir)
[](https://opensource.org/licenses/MIT)
A lightweight directory traversal utility designed to prepare project contents for AI code review and analysis. Quickly gather all your project files into a single, well-formatted document that's perfect for sharing with AI assistants.
## 🚀 Quick Start
Get up and running in 30 seconds:
```bash
# Install
pip install prepdir
# Navigate to your project
cd /path/to/your/project
# Generate a file with all your code
prepdir
# Share prepped_dir.txt with your AI assistant
```
That's it! You now have a `prepped_dir.txt` file containing all your project files with clear delimiters, ready for AI review.
### Python Integration
```python
from prepdir import run
# Generate content for Python files
content, _ = run(directory="/path/to/project", extensions=["py"])
print(content) # Use the content directly
```
## 🎯 Why Use prepdir?
**Save hours of manual work** when sharing code with AI assistants:
- ✅ **Instant Context**: Combines all relevant files into one structured document
- ✅ **Smart Filtering**: Automatically excludes cache files, build artifacts, and other noise
- ✅ **Privacy Protection**: Scrubs UUIDs and sensitive identifiers by default
- ✅ **AI-Optimized**: Uses clear separators and formatting that AI models love
- ✅ **Flexible**: CLI tool + Python library for any workflow
## 📦 Installation
```bash
pip install prepdir
```
**Alternative methods:**
```bash
# From GitHub
pip install git+https://github.com/eyecantell/prepdir.git
# Development install
git clone https://github.com/eyecantell/prepdir.git
cd prepdir
pip install -e .
```
## 💡 Usage Examples
### Command Line Interface
```bash
# Basic usage - all files
prepdir
# Only Python files
prepdir -e py
# Multiple file types
prepdir -e py js html css
# Custom output file
prepdir -o my_review.txt
# Specific directory
prepdir /path/to/project
# Include everything (ignore exclusions)
prepdir --all
# Disable UUID scrubbing
prepdir --no-scrub-uuids
```
### Programmatic Use
Use `prepdir` as a library to process directories programmatically:
```python
from prepdir import run, PrepdirOutputFile
# Run and get a PrepdirOutputFile object
output: PrepdirOutputFile = run(directory="my_project", extensions=["py", "md"], use_unique_placeholders=True)
# Access processed files
for file_entry in output.files:
print(f"File: {file_entry.path}, Content: {file_entry.content}")
# Save to file
output.save("prepped_dir.txt")
# For legacy use, get raw output
content, uuid_mapping, files_list, metadata = run(directory="my_project", return_raw=True)
```
### Sample Output
```plaintext
File listing generated 2025-06-14 23:24:00.123456 by prepdir version 0.14.1
Base directory is '/path/to/project'
=-=-=-=-=-=-=-= Begin File: 'src/main.py' =-=-=-=-=-=-=-=
print("Hello, World!")
=-=-=-=-=-=-=-= End File: 'src/main.py' =-=-=-=-=-=-=-=
=-=-=-=-=-=-=-= Begin File: 'README.md' =-=-=-=-=-=-=-=
# My Project
This is a sample project.
=-=-=-=-=-=-=-= End File: 'README.md' =-=-=-=-=-=-=-=
```
## 🔍 Common Use Cases
### 1. **Code Review with AI**
```bash
prepdir -e py -o code_review.txt
# Ask AI: "Review my Python code for bugs and improvements"
```
### 2. **Debugging Help**
```bash
prepdir -e py log -o debug_context.txt
# Ask AI: "Help me debug errors in these logs and Python files"
```
### 3. **Documentation Generation**
```bash
prepdir -e py md rst -o docs_context.txt
# Ask AI: "Generate detailed documentation for this project"
```
### 4. **Architecture Analysis**
```bash
prepdir -e py js ts -o architecture.txt
# Ask AI: "Analyze the architecture and suggest improvements"
```
## ⚙️ Configuration
### Configuration Files
prepdir looks for configuration in this order:
1. Custom config (via `--config`)
2. Local: `.prepdir/config.yaml`
3. Global: `~/.prepdir/config.yaml`
4. Built-in defaults
### Create Configuration
```bash
# Initialize local config
prepdir --init
# Or create manually
mkdir .prepdir
cat > .prepdir/config.yaml << EOF
EXCLUDE:
DIRECTORIES:
- .git
- node_modules
- __pycache__
FILES:
- "*.pyc"
- "*.log"
SCRUB_HYPHENATED_UUIDS: true
SCRUB_HYPHENLESS_UUIDS: true
REPLACEMENT_UUID: "00000000-0000-0000-0000-000000000000"
EOF
```
### Default Exclusions
- **Version control**: `.git`
- **Cache files**: `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`
- **Build artifacts**: `dist`, `build`, `*.egg-info`
- **IDE files**: `.idea`, `.vscode`
- **Dependencies**: `node_modules`
- **Temporary files**: `*.pyc`, `*.log`
- **prepdir outputs**: `prepped_dir.txt` (unless `--include-prepdir-files`)
## 🔒 Privacy & Security
### UUID Scrubbing
By default, prepdir protects your privacy by replacing UUIDs with placeholder values:
```python
# Original
user_id = "123e4567-e89b-12d3-a456-426614174000"
# After scrubbing
user_id = "00000000-0000-0000-0000-000000000000"
```
**Control UUID scrubbing:**
- CLI: `--no-scrub-uuids` or `--replacement-uuid <uuid>`
- Python: `scrub_hyphenated_uuids=False` or `replacement_uuid="custom-uuid"`
- Config: Set `SCRUB_HYPHENATED_UUIDS: false` or `REPLACEMENT_UUID: "custom-uuid"`
### Unique Placeholders (New in 0.14.0)
Generate unique placeholders for each UUID to maintain relationships:
```python
content, uuid_mapping = run(
directory="/path/to/project",
use_unique_placeholders=True
)
print("UUID Mapping:", uuid_mapping)
# Output: {'PREPDIR_UUID_PLACEHOLDER_1': 'original-uuid-1', ...}
```
## 🔧 Advanced Features
### Command Line Options
```bash
prepdir --help
# Key options:
-e, --extensions File extensions to include
-o, --output Output file name
--all Include all files (ignore exclusions)
--include-prepdir-files Include prepdir-generated files
--no-scrub-uuids Disable UUID scrubbing
--replacement-uuid Custom replacement UUID
--config Custom config file
-v, --verbose Verbose output
```
### Python API Reference
```python
from prepdir import run, validate_output_file
# Full API
content, uuid_mapping = run(
directory="/path/to/project", # Target directory
extensions=["py", "js"], # File extensions
output_file="output.txt", # Save to file
scrub_hyphenated_uuids=True, # Scrub (hyphenated) UUIDs
scrub_hyphenless_uuids=True, # Scrub hyphenless UUIDs
replacement_uuid="custom-uuid", # Custom replacement
use_unique_placeholders=False, # Unique placeholders
include_all=False, # Ignore exclusions
include_prepdir_files=False, # Include prepdir outputs
verbose=False # Verbose logging
)
# Validate output
result = validate_output_file("output.txt")
# Returns: {"is_valid": bool, "errors": [], "warnings": [], "files": {}, "creation": {}}
```
## 📊 Logging & Debugging
Control verbosity with environment variables:
```bash
LOGLEVEL=DEBUG prepdir -v
```
Valid levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
## 📈 What's New
### Version 0.14.1 (Latest)
- Fixed typos in README and CHANGELOG
### Version 0.14.0
- ✨ **Unique UUID placeholders** - Maintain UUID relationships with unique placeholders
- 🔧 **Enhanced validation** - Improved validation of prepdir-generated files
- 🎯 **Lenient parsing** - More flexible delimiter parsing for edited files
### Version 0.13.0
- 🐍 **Python library support** - Use `from prepdir import run`
- ✅ **File validation** - Validate prepdir output files
- 🧪 **Testing improvements** - Better test isolation
[View complete changelog](docs/CHANGELOG.md)
## 🤔 FAQ
<details>
<summary><strong>Q: What project sizes can prepdir handle?</strong></summary>
A: Effective for small to moderate projects (thousands of files). Use file extension filters for larger projects. The limitation will more likely be what the LLM can handle.
</details>
<details>
<summary><strong>Q: Why are my prepdir output files missing?</strong></summary>
A: prepdir excludes its own generated files by default. Use <code>--include-prepdir-files</code> to include them.
</details>
<details>
<summary><strong>Q: Why are UUIDs replaced in my output?</strong></summary>
A: Privacy protection! prepdir scrubs UUIDs by default. Use <code>--no-scrub-uuids</code> to disable.
</details>
<details>
<summary><strong>Q: Can I use prepdir with non-code files?</strong></summary>
A: Yes! It works with any text files. Use <code>-e txt md</code> for specific types.
</details>
<details>
<summary><strong>Q: How do I upgrade from older versions?</strong></summary>
A: For versions <0.6.0, move <code>config.yaml</code> to <code>.prepdir/config.yaml</code>. Most upgrades are seamless.
</details>
## 🛠️ Development
```bash
git clone https://github.com/eyecantell/prepdir.git
cd prepdir
pdm install # Install dependencies
pdm run prepdir # Run development version
pdm run pytest # Run tests
pdm publish # Publish to PyPI
```
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
**Love prepdir?** Give it a ⭐ on [GitHub](https://github.com/eyecantell/prepdir)!
Raw data
{
"_id": null,
"home_page": null,
"name": "prepdir",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, artificial intelligence, code review, directory traversal, file content, project documentation, code sharing, developer tools, large language models, llm, project structure",
"author": null,
"author_email": "eyecantell <paul@pneuma.solutions>",
"download_url": "https://files.pythonhosted.org/packages/5b/c1/037aeb192953ebad2512c74a37625e5eb1af7c844814ee2d32ebdb1bad8a/prepdir-0.16.0.tar.gz",
"platform": null,
"description": "# \ud83d\uddc2\ufe0f prepdir\n\n[](https://github.com/eyecantell/prepdir/actions/runs/16282502771)\n[](https://badge.fury.io/py/prepdir)\n[](https://www.python.org/downloads/)\n[](https://pepy.tech/project/prepdir)\n[](https://opensource.org/licenses/MIT)\n\nA lightweight directory traversal utility designed to prepare project contents for AI code review and analysis. Quickly gather all your project files into a single, well-formatted document that's perfect for sharing with AI assistants.\n\n## \ud83d\ude80 Quick Start\n\nGet up and running in 30 seconds:\n\n```bash\n# Install\npip install prepdir\n\n# Navigate to your project\ncd /path/to/your/project\n\n# Generate a file with all your code\nprepdir\n\n# Share prepped_dir.txt with your AI assistant\n```\n\nThat's it! You now have a `prepped_dir.txt` file containing all your project files with clear delimiters, ready for AI review.\n\n### Python Integration\n```python\nfrom prepdir import run\n\n# Generate content for Python files\ncontent, _ = run(directory=\"/path/to/project\", extensions=[\"py\"])\nprint(content) # Use the content directly\n```\n\n## \ud83c\udfaf Why Use prepdir?\n\n**Save hours of manual work** when sharing code with AI assistants:\n- \u2705 **Instant Context**: Combines all relevant files into one structured document\n- \u2705 **Smart Filtering**: Automatically excludes cache files, build artifacts, and other noise\n- \u2705 **Privacy Protection**: Scrubs UUIDs and sensitive identifiers by default\n- \u2705 **AI-Optimized**: Uses clear separators and formatting that AI models love\n- \u2705 **Flexible**: CLI tool + Python library for any workflow\n\n## \ud83d\udce6 Installation\n\n```bash\npip install prepdir\n```\n\n**Alternative methods:**\n```bash\n# From GitHub\npip install git+https://github.com/eyecantell/prepdir.git\n\n# Development install\ngit clone https://github.com/eyecantell/prepdir.git\ncd prepdir\npip install -e .\n```\n\n## \ud83d\udca1 Usage Examples\n\n### Command Line Interface\n\n```bash\n# Basic usage - all files\nprepdir\n\n# Only Python files\nprepdir -e py\n\n# Multiple file types\nprepdir -e py js html css\n\n# Custom output file\nprepdir -o my_review.txt\n\n# Specific directory\nprepdir /path/to/project\n\n# Include everything (ignore exclusions)\nprepdir --all\n\n# Disable UUID scrubbing\nprepdir --no-scrub-uuids\n```\n\n### Programmatic Use\n\nUse `prepdir` as a library to process directories programmatically:\n\n```python\nfrom prepdir import run, PrepdirOutputFile\n\n# Run and get a PrepdirOutputFile object\noutput: PrepdirOutputFile = run(directory=\"my_project\", extensions=[\"py\", \"md\"], use_unique_placeholders=True)\n\n# Access processed files\nfor file_entry in output.files:\n print(f\"File: {file_entry.path}, Content: {file_entry.content}\")\n\n# Save to file\noutput.save(\"prepped_dir.txt\")\n\n# For legacy use, get raw output\ncontent, uuid_mapping, files_list, metadata = run(directory=\"my_project\", return_raw=True)\n```\n\n### Sample Output\n\n```plaintext\nFile listing generated 2025-06-14 23:24:00.123456 by prepdir version 0.14.1\nBase directory is '/path/to/project'\n=-=-=-=-=-=-=-= Begin File: 'src/main.py' =-=-=-=-=-=-=-=\nprint(\"Hello, World!\")\n=-=-=-=-=-=-=-= End File: 'src/main.py' =-=-=-=-=-=-=-=\n\n=-=-=-=-=-=-=-= Begin File: 'README.md' =-=-=-=-=-=-=-=\n# My Project\nThis is a sample project.\n=-=-=-=-=-=-=-= End File: 'README.md' =-=-=-=-=-=-=-=\n```\n\n## \ud83d\udd0d Common Use Cases\n\n### 1. **Code Review with AI**\n```bash\nprepdir -e py -o code_review.txt\n# Ask AI: \"Review my Python code for bugs and improvements\"\n```\n\n### 2. **Debugging Help**\n```bash\nprepdir -e py log -o debug_context.txt\n# Ask AI: \"Help me debug errors in these logs and Python files\"\n```\n\n### 3. **Documentation Generation**\n```bash\nprepdir -e py md rst -o docs_context.txt\n# Ask AI: \"Generate detailed documentation for this project\"\n```\n\n### 4. **Architecture Analysis**\n```bash\nprepdir -e py js ts -o architecture.txt\n# Ask AI: \"Analyze the architecture and suggest improvements\"\n```\n\n## \u2699\ufe0f Configuration\n\n### Configuration Files\nprepdir looks for configuration in this order:\n1. Custom config (via `--config`)\n2. Local: `.prepdir/config.yaml`\n3. Global: `~/.prepdir/config.yaml`\n4. Built-in defaults\n\n### Create Configuration\n```bash\n# Initialize local config\nprepdir --init\n\n# Or create manually\nmkdir .prepdir\ncat > .prepdir/config.yaml << EOF\nEXCLUDE:\n DIRECTORIES:\n - .git\n - node_modules\n - __pycache__\n FILES:\n - \"*.pyc\"\n - \"*.log\"\nSCRUB_HYPHENATED_UUIDS: true\nSCRUB_HYPHENLESS_UUIDS: true\nREPLACEMENT_UUID: \"00000000-0000-0000-0000-000000000000\"\nEOF\n```\n\n### Default Exclusions\n- **Version control**: `.git`\n- **Cache files**: `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`\n- **Build artifacts**: `dist`, `build`, `*.egg-info`\n- **IDE files**: `.idea`, `.vscode`\n- **Dependencies**: `node_modules`\n- **Temporary files**: `*.pyc`, `*.log`\n- **prepdir outputs**: `prepped_dir.txt` (unless `--include-prepdir-files`)\n\n## \ud83d\udd12 Privacy & Security\n\n### UUID Scrubbing\nBy default, prepdir protects your privacy by replacing UUIDs with placeholder values:\n\n```python\n# Original\nuser_id = \"123e4567-e89b-12d3-a456-426614174000\"\n\n# After scrubbing \nuser_id = \"00000000-0000-0000-0000-000000000000\"\n```\n\n**Control UUID scrubbing:**\n- CLI: `--no-scrub-uuids` or `--replacement-uuid <uuid>`\n- Python: `scrub_hyphenated_uuids=False` or `replacement_uuid=\"custom-uuid\"`\n- Config: Set `SCRUB_HYPHENATED_UUIDS: false` or `REPLACEMENT_UUID: \"custom-uuid\"`\n\n### Unique Placeholders (New in 0.14.0)\nGenerate unique placeholders for each UUID to maintain relationships:\n\n```python\ncontent, uuid_mapping = run(\n directory=\"/path/to/project\", \n use_unique_placeholders=True\n)\nprint(\"UUID Mapping:\", uuid_mapping)\n# Output: {'PREPDIR_UUID_PLACEHOLDER_1': 'original-uuid-1', ...}\n```\n\n## \ud83d\udd27 Advanced Features\n\n### Command Line Options\n```bash\nprepdir --help\n\n# Key options:\n-e, --extensions File extensions to include\n-o, --output Output file name\n--all Include all files (ignore exclusions)\n--include-prepdir-files Include prepdir-generated files\n--no-scrub-uuids Disable UUID scrubbing\n--replacement-uuid Custom replacement UUID\n--config Custom config file\n-v, --verbose Verbose output\n```\n\n### Python API Reference\n```python\nfrom prepdir import run, validate_output_file\n\n# Full API\ncontent, uuid_mapping = run(\n directory=\"/path/to/project\", # Target directory\n extensions=[\"py\", \"js\"], # File extensions\n output_file=\"output.txt\", # Save to file\n scrub_hyphenated_uuids=True, # Scrub (hyphenated) UUIDs\n scrub_hyphenless_uuids=True, # Scrub hyphenless UUIDs\n replacement_uuid=\"custom-uuid\", # Custom replacement\n use_unique_placeholders=False, # Unique placeholders\n include_all=False, # Ignore exclusions\n include_prepdir_files=False, # Include prepdir outputs\n verbose=False # Verbose logging\n)\n\n# Validate output\nresult = validate_output_file(\"output.txt\")\n# Returns: {\"is_valid\": bool, \"errors\": [], \"warnings\": [], \"files\": {}, \"creation\": {}}\n```\n\n## \ud83d\udcca Logging & Debugging\n\nControl verbosity with environment variables:\n```bash\nLOGLEVEL=DEBUG prepdir -v\n```\n\nValid levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`\n\n## \ud83d\udcc8 What's New\n\n### Version 0.14.1 (Latest)\n- Fixed typos in README and CHANGELOG\n\n### Version 0.14.0\n- \u2728 **Unique UUID placeholders** - Maintain UUID relationships with unique placeholders\n- \ud83d\udd27 **Enhanced validation** - Improved validation of prepdir-generated files\n- \ud83c\udfaf **Lenient parsing** - More flexible delimiter parsing for edited files\n\n### Version 0.13.0\n- \ud83d\udc0d **Python library support** - Use `from prepdir import run`\n- \u2705 **File validation** - Validate prepdir output files\n- \ud83e\uddea **Testing improvements** - Better test isolation\n\n[View complete changelog](docs/CHANGELOG.md)\n\n## \ud83e\udd14 FAQ\n\n<details>\n<summary><strong>Q: What project sizes can prepdir handle?</strong></summary>\nA: Effective for small to moderate projects (thousands of files). Use file extension filters for larger projects. The limitation will more likely be what the LLM can handle. \n</details>\n\n<details>\n<summary><strong>Q: Why are my prepdir output files missing?</strong></summary>\nA: prepdir excludes its own generated files by default. Use <code>--include-prepdir-files</code> to include them.\n</details>\n\n<details>\n<summary><strong>Q: Why are UUIDs replaced in my output?</strong></summary>\nA: Privacy protection! prepdir scrubs UUIDs by default. Use <code>--no-scrub-uuids</code> to disable.\n</details>\n\n<details>\n<summary><strong>Q: Can I use prepdir with non-code files?</strong></summary>\nA: Yes! It works with any text files. Use <code>-e txt md</code> for specific types.\n</details>\n\n<details>\n<summary><strong>Q: How do I upgrade from older versions?</strong></summary>\nA: For versions <0.6.0, move <code>config.yaml</code> to <code>.prepdir/config.yaml</code>. Most upgrades are seamless.\n</details>\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\ngit clone https://github.com/eyecantell/prepdir.git\ncd prepdir\npdm install # Install dependencies\npdm run prepdir # Run development version\npdm run pytest # Run tests\npdm publish # Publish to PyPI\n```\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Love prepdir?** Give it a \u2b50 on [GitHub](https://github.com/eyecantell/prepdir)!",
"bugtrack_url": null,
"license": "MIT",
"summary": "Directory traversal utility to prepare project contents for review",
"version": "0.16.0",
"project_urls": {
"Documentation": "https://github.com/eyecantell/prepdir#readme",
"Issues": "https://github.com/eyecantell/prepdir/issues",
"Repository": "https://github.com/eyecantell/prepdir"
},
"split_keywords": [
"ai",
" artificial intelligence",
" code review",
" directory traversal",
" file content",
" project documentation",
" code sharing",
" developer tools",
" large language models",
" llm",
" project structure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a76db4a24ce75711a63313c5345eab498f3373edf89a4e054778653195cc5e0",
"md5": "f32a15b35ec926706ef42fab4414d202",
"sha256": "96dd0f884d4842215e4926231f1e6f537baa51222812f96ec476dfa54ba55d0c"
},
"downloads": -1,
"filename": "prepdir-0.16.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f32a15b35ec926706ef42fab4414d202",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 32638,
"upload_time": "2025-07-15T02:36:30",
"upload_time_iso_8601": "2025-07-15T02:36:30.354973Z",
"url": "https://files.pythonhosted.org/packages/7a/76/db4a24ce75711a63313c5345eab498f3373edf89a4e054778653195cc5e0/prepdir-0.16.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5bc1037aeb192953ebad2512c74a37625e5eb1af7c844814ee2d32ebdb1bad8a",
"md5": "fc83adbe5215aa1a3025cdb75f03b76a",
"sha256": "d03ba04b45456a8115dedf6b272914ffd7099d039c1c51c234ab702fac59e073"
},
"downloads": -1,
"filename": "prepdir-0.16.0.tar.gz",
"has_sig": false,
"md5_digest": "fc83adbe5215aa1a3025cdb75f03b76a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 52731,
"upload_time": "2025-07-15T02:36:31",
"upload_time_iso_8601": "2025-07-15T02:36:31.580098Z",
"url": "https://files.pythonhosted.org/packages/5b/c1/037aeb192953ebad2512c74a37625e5eb1af7c844814ee2d32ebdb1bad8a/prepdir-0.16.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 02:36:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eyecantell",
"github_project": "prepdir#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "prepdir"
}
JSON
