treeignore

TreeIgnore

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:

pip install treeignore

For development, install directly from the repository:

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:

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):

treeignore

List only directories, up to 2 levels deep:

treeignore -L 2 -d

Show all files (including hidden) with full paths:

treeignore -a -f

Show files in a specific directory, ignoring gitignore rules:

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:

• Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

• Install development dependencies:

pip install -e ".[dev]"

• Build the package:

python -m build

• Run tests:

python -m pytest

Publishing to PyPI

• Build the distribution:

python -m build

• Upload to PyPI:

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.

• Fork the Project
• Create your Feature Branch (git checkout -b feature/AmazingFeature)
• Commit your Changes (git commit -m 'Add some AmazingFeature')
• Push to the Branch (git push origin feature/AmazingFeature)
• Open a Pull Request

License

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

Author

Alexander Warth - warth.ai

Links

• GitLab Repository
• Issue Tracker
• PyPI Package