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 command reference and options.

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

Tree-format tests assert against full output; a separate test checks repeatability. Watcher tests cover event filtering, renames, ignore-rule reloads, and one live regeneration smoke test.

License

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