Project Tree

Project Tree is a small, deterministic utility that generates a Markdown representation of a project’s directory structure.

Features

• Generates a deterministic Markdown project tree
• Uses a simple, explicit ignore system based on exact name matching
• Optional watch mode for continuous regeneration
• Minimal, testable design

Installation

Simply run:

pipx install project-tree

Or if you already have UV installed, simply run:

uv tool install project-tree

Getting Started

Run projtree from your project root to generate structure.md.

projtree

Usage

Run projtree with --help to see the full command reference, options, and example output.

projtree --help

Or see the usage documentation for the full command reference, options, and example output.

Ignore System

• Built-in defaults include common directory and file names (e.g. .git, __pycache__, node_modules)
• A .projtreeignore file in the project root is supported
• For normal runs, CLI --ignore arguments are merged with project and built-in ignores
• In --watch mode, CLI --ignore values are also forwarded, so watching uses built-in defaults, .projtreeignore, and any CLI-supplied ignores
• Ignore rules match exact names anywhere in the tree (e.g., src ignores any file/dir named src at any depth)
• Ignore entries are treated as exact names, not paths. For example, target works, but src/target does not match nested paths
• No globbing, wildcards, or pattern-based matching in v1
• If the output file is under the project root, its file name is also added to the ignore set to prevent regeneration loops

Example .projtreeignore:

.venv
__pycache__
build
dist

Running Tests

If you installed development dependencies:

pytest

All generator tests assert against full output to enforce deterministic structure. Watcher tests are intentionally minimal and validate regeneration behavior only.

License

This project is licensed under the MIT License. See LICENSE for details.