folder-crawl 0.2.0

A CLI tool to display folder structure and contents with gitignore-style filtering

folder-crawl

folder-crawl is a powerful command-line tool that displays directory structure and file contents with gitignore-style pattern matching. Perfect for sharing codebases with LLMs, documentation, or quick project exploration.

Features

• 📁 Display directory tree structure with file sizes
• 📝 Show contents of text files inline
• 🎯 Gitignore-style pattern matching via pathspec
• 🔍 Automatic .foldercrawlignore support, opt-in .gitignore
• 🚫 Smart default ignores (node_modules, pycache, etc.)
• 👁️ Optional hidden file inclusion
• ⚡ Configurable output limits and depth
• 🎨 Clean, readable markdown-compatible output

Installation

Install from source:

git clone https://github.com/juliusolsson/folder-crawl.git
cd folder-crawl
pip install .

Or install in development mode:

pip install -e .

Quick Start

# Display current directory with default ignores
folder-crawl

# Display specific directory
folder-crawl /path/to/project

# Ignore additional patterns
folder-crawl -I "*.log|*.tmp|cache/"

# Show hidden files
folder-crawl --hidden

# Structure only (no file contents)
folder-crawl --no-contents

# Limit depth
folder-crawl --max-depth 2

Usage

folder-crawl [OPTIONS] [PATH]

Arguments

• PATH: Directory to crawl (default: current directory)

Options

Option	Description
-I, --ignore PATTERN	Gitignore-style patterns (pipe-separated or multiple flags)
--set-default	Save the -I/--ignore patterns to .foldercrawlignore
--ignore-file PATH	Path to ignore file (can be repeated)
--gitignore	Also read .gitignore patterns (opt-in)
--no-default-ignore	Don't use default patterns and .foldercrawlignore
--hidden	Include hidden files and directories
--no-contents	Show structure only, no file contents
--max-bytes N	Max bytes to display per file (default: 50000)
--max-file-size N	Max file size to process (default: 1000000)
--max-depth N	Maximum directory depth to traverse
-v, --version	Show version

Examples

Basic Usage

# Current directory with smart defaults
folder-crawl

Custom Ignore Patterns

# Multiple patterns with pipe separator
folder-crawl -I "*.log|*.tmp|cache/"

# Multiple -I flags
folder-crawl -I "*.log" -I "*.tmp" -I "cache/"

# Use custom ignore file
folder-crawl --ignore-file .myignore

# Save patterns as default for this directory
folder-crawl -I "__pycache__|*.pyc|build/|*.egg-info/" --set-default .

# Future runs will use the saved patterns automatically
folder-crawl .

Control What's Displayed

# Include hidden files (.env, .git, etc.)
folder-crawl --hidden

# Structure only, no file contents
folder-crawl --no-contents

# Limit content output per file
folder-crawl --max-bytes 10000

# Limit directory traversal depth
folder-crawl --max-depth 2

Working with Git Projects

# Default: uses .foldercrawlignore but NOT .gitignore
folder-crawl

# Opt-in to also use .gitignore
folder-crawl --gitignore

# Skip all default ignores (including .foldercrawlignore)
folder-crawl --no-default-ignore

Ignore Patterns

folder-crawl uses gitignore-style patterns powered by pathspec:

• *.log - Match all .log files
• cache/ - Match directories named cache
• **/test_*.py - Match test files in any directory
• !important.log - Negate pattern (include important.log)

Pattern Priority

1. Command-line patterns (-I flags)
2. Custom ignore files (--ignore-file)
3. .gitignore (only when --gitignore is specified)
4. .foldercrawlignore (unless --no-default-ignore)
5. Default patterns (unless --no-default-ignore)

Default Ignore Patterns

By default, folder-crawl ignores:

• Version control: .git/, .svn/, .hg/
• Dependencies: node_modules/, venv/, *.egg-info/
• Build artifacts: dist/, build/, __pycache__/
• IDE files: .idea/, .vscode/, *.swp
• OS files: .DS_Store, Thumbs.db
• Compiled: *.pyc, *.pyo, *.so, *.dll

.foldercrawlignore

Create a .foldercrawlignore file in your project root for project-specific ignores:

# Custom project ignores
data/
*.secret
config/local.yml
temp/

Output Format

folder-crawl produces clean, markdown-compatible output:

📁 /path/to/project
============================================================

## Structure:

project/
├── src/
│   ├── main.py (2.5KB)
│   └── utils.py (1.2KB)
├── tests/
│   └── test_main.py (3.1KB)
└── README.md (4.2KB)

## File Contents:

### src/main.py
```python
def main():
    print("Hello, World!")

src/utils.py

def helper():
    return 42

## Use Cases

- 📤 **Share code with LLMs**: Perfect format for ChatGPT, Claude, etc.
- 📚 **Documentation**: Generate project structure docs
- 🔍 **Code review**: Quick project overview
- 🚀 **Onboarding**: Help new team members understand project layout
- 🐛 **Debugging**: Share relevant code context in issues

## License

MIT License. See [LICENSE](LICENSE) file for details.

## Author

**Julius Olsson**
Email: [[e-mail]](mailto:[e-mail])

---

*Built for developers who need to share code context efficiently.*