treeignore 0.5.3
A tree view command-line utility that filters files/folders based on a .gitignore
Requires Python: >=3.6
Keywords: gitignore, tree, directory, visualization, CLI, AI, LLM

# TreeIgnore

[![PyPI version](https://badge.fury.io/py/treeignore.svg)](https://pypi.org/project/treeignore/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TreeIgnore is a Python command-line utility that prints a tree-style view of the current directory while ignoring files and folders specified in a `.gitignore` file located at the base folder.

## Features

- **Recursive Listing:** Displays the directory tree recursively.
- **Gitignore Filtering:** Reads the `.gitignore` file from the base folder to filter out files and folders.
- **Easy to Use:** A simple command-line tool that can be executed from any directory.
- **AI-Friendly Output:** Perfect for AI tools and LLMs by providing clean project structure without noise from build artifacts, dependencies, or cache files that would unnecessarily consume context windows.

## Why TreeIgnore?

TreeIgnore is particularly valuable when working with AI tools and Large Language Models (LLMs). By respecting `.gitignore` patterns, it provides a clean, focused view of your project's actual source code and important files, filtering out:

- Build artifacts and cache directories
- Dependencies and virtual environments
- IDE configuration files
- System-specific files

This focused output helps prevent context window bloat when sharing project structures with AI tools, ensuring they can focus on the relevant code and documentation rather than getting distracted by temporary or generated files.

## Installation

Install from PyPI:

```bash
pip install treeignore
```

For development, install directly from the repository:

```bash
git clone https://gitlab.com/CochainComplex/treeignore.git
cd treeignore
pip install -e .
```

## Usage

Navigate to the base folder (the folder containing your `.gitignore` file) and run:

```bash
treeignore [path] [options]
```

The tool will display a tree-style view of the specified directory (or the current directory if none is provided), filtering out any files or folders that match the patterns in the `.gitignore` files.

### Command-line Options

| Option          | Alias | Description                                         |
|-----------------|-------|-----------------------------------------------------|
| `--level <num>` | `-L`  | Descend only `<num>` directories deep.              |
| `--dirs-only`   | `-d`  | List directories only.                              |
| `--full-path`   | `-f`  | Print the full path prefix for each file.           |
| `--all`         | `-a`  | List all files, including hidden ones (dotfiles).   |
| `--show-perms`  | `-p`  | Print file permissions (Unix-like systems).         |
| `--show-size`   | `-s`  | Print file size in bytes.                           |
| `--no-indent`   | `-i`  | Don't print indentation lines.                      |
| `--noreport`    |       | Omit the final file/directory count report.         |
| `--no-ignore`   |       | Disable `.gitignore` filtering (show all files).    |
| `--version`     |       | Show version information and exit.                  |
| `path`          |       | Optional directory path to list (default: current). |

### Examples

**Basic Usage (Current Directory):**
```bash
treeignore
```

**List only directories, up to 2 levels deep:**
```bash
treeignore -L 2 -d
```

**Show all files (including hidden) with full paths:**
```bash
treeignore -a -f
```

**Show files in a specific directory, ignoring gitignore rules:**
```bash
treeignore path/to/your/project --no-ignore
```

### Example Comparison (Standard `tree` vs `treeignore`)

Here's how a typical Python project looks with the standard `tree` command:

```
myproject/
├── .git/
│   ├── HEAD
│   ├── config
│   └── ... (many more files)
├── .pytest_cache/
│   └── ... (cache files)
├── __pycache__/
│   └── main.cpython-39.pyc
├── venv/
│   ├── bin/
│   ├── lib/
│   └── ... (hundreds of files)
├── .gitignore
├── main.py
├── requirements.txt
└── tests/
    ├── __pycache__/
    │   └── test_main.cpython-39-pytest.pyc
    └── test_main.py
```

And here's the same project with `treeignore`:

```
myproject/
├── .gitignore
├── main.py
├── requirements.txt
└── tests/
    └── test_main.py
```

As you can see, `treeignore` provides a clean view focusing only on the essential project files, making it perfect for documentation, project sharing, and AI tool interactions.

## Development

This project uses modern Python tooling:
- `black` for code formatting
- `isort` for import sorting
- `mypy` for type checking

To set up the development environment:

1. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

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

3. Build the package:
```bash
python -m build
```

4. Run tests:
```bash
python -m pytest
```

## Publishing to PyPI

1. Build the distribution:
```bash
python -m build
```

2. Upload to PyPI:
```bash
python -m twine upload dist/*
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. (Current version: 0.5.0)

## Author

Alexander Warth - [warth.ai](https://warth.ai)

## Links

- [GitLab Repository](https://gitlab.com/CochainComplex/treeignore)
- [Issue Tracker](https://gitlab.com/CochainComplex/treeignore/-/issues)
- [PyPI Package](https://pypi.org/project/treeignore/)