dircontextgen 0.1.1
Generate directory trees with .gitignore support
License: Apache-2.0
Requires Python: >=3.12

# dircontextgen

Generate rich documentation of your project's directory structure with smart filtering capabilities. This tool combines the power of `.gitignore` patterns with additional filtering options to create comprehensive documentation of your codebase.

## Features

- 🌲 Creates detailed directory trees
- 📄 Includes file contents in the documentation
- 🔍 Smart filtering using `.gitignore` patterns
- 🎯 Advanced filtering with `.dirfilter` rules
- 👀 Peek mode for sensitive files
- 🛠️ Built-in diagnostics tools
- 🖥️ Optional GUI interface (WIP)

## Requirements

- Python 3.12+

## Installation

```bash
pip install dircontextgen
```

For development or GUI features:

```bash
# Install with development dependencies
pip install dircontextgen[dev]

# Install with GUI support
pip install dircontextgen[gui]
```

## Quick Start

Basic usage - document current directory:
```bash
dircontextgen
```

Generate documentation for a specific path and save to a file:
```bash
dircontextgen -p /path/to/project -o documentation.md
```

## Configuration

### Using `.gitignore`

The tool respects your existing `.gitignore` patterns. Files and directories that match these patterns will be excluded from the documentation.

Example `.gitignore`:
```
# Python
__pycache__/
*.pyc
venv/

# Project specific
secret.key
temp/
```

### Using `.dirfilter`

`.dirfilter` files provide additional control over what appears in your documentation. They can override `.gitignore` rules and specify special handling for certain files.

Example `.dirfilter`:
```
[ignore]
# Additional files to exclude
private/
*.log

[target]
# Files to include even if ignored by .gitignore
important_config.yaml
docs/*.md

[peek]
# Files to include in tree but hide contents
secrets.env
credentials.json
```

#### Sections:

- `[ignore]`: Files/directories to exclude (highest priority)
- `[target]`: Files to force-include even if ignored
- `[peek]`: Files to show in the tree but hide contents

### Pattern Priority

1. `.dirfilter` [ignore] patterns (highest)
2. `.dirfilter` [target] patterns
3. `.gitignore` patterns
4. `.dirfilter` [peek] patterns

## Advanced Usage

### Maximum Depth

Limit the directory traversal depth:
```bash
dircontextgen --max-depth 3
```

### Debug Mode

Enable detailed logging:
```bash
dircontextgen --debug
```

### Diagnostics

Run pattern diagnostics to check for conflicts:
```bash
dircontextgen --doctor
```

### GUI Mode (Experimental)

Launch the graphical interface:
```bash
dircontextgen --gui
```

## Output Format

The generated documentation includes:

1. Directory structure in tree format
2. File contents with clear separators
3. Debug information (when enabled)

Example output:
```markdown
# Project Documentation

## Directory Structure
```
├── src
│   └── myproject
│       ├── __init__.py
│       └── main.py
├── tests
│   └── test_main.py
└── README.md
```

## File Contents

File: src/myproject/main.py

--------------------------------------------------------------------------------

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

--------------------------------------------------------------------------------
```

## Contributing

Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/dircontextgen.git
   cd dircontextgen
   ```

2. Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # or
   venv\Scripts\activate  # Windows
   ```

3. Install development dependencies:
   ```bash
   pip install -e .[dev]
   ```

4. Run tests:
   ```bash
   pytest
   ```

## License

This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

Special thanks to:
- The `pathspec` library for gitignore pattern matching
- The Python `click` library for CLI interface