Skip to content

V1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@mattbriggs mattbriggs released this 16 Aug 20:41
v1.0.0
a02f697

Progress Tree v1.0.0

First stable release of Progress Tree.

Progress Tree is a lightweight command-line utility for creating structural snapshots of software repositories. It recursively scans a project, generates a readable ASCII directory tree, and reports basic project metrics including directory count, file count, lines of code, and scan time.

The tool is designed around three deliberately simple questions:

  1. What is actually in this project?
  2. How big is it?
  3. What should be ignored so the useful structure is not buried in noise?

This is especially useful in AI-assisted development, where repositories can grow quickly and understanding what has actually been created can become surprisingly nontrivial.

Highlights

  • Recursive ASCII directory tree generation
  • File, directory, and line-of-code metrics
  • Timestamped project reports
  • Gitignore-style exclusion rules through tree_ignore.txt
  • Custom ignore-file support
  • Optional fast scanning without line counting
  • Configurable progress reporting for larger repositories
  • Output directly to stdout or to a report file
  • Configurable logging and log-file output
  • Safe handling of symbolic links
  • Python API for programmatic scanning and report generation
  • Zero runtime dependencies beyond the Python standard library
  • Unit-test suite using pytest

Command-Line Interface

After installation, the progress-tree command can be run directly:

progress-tree

Scan another project:

progress-tree --root ~/projects/my-app

Print the report directly to the terminal:

progress-tree --root ~/projects/my-app --stdout

Skip line counting for a faster structural scan:

progress-tree --no-lines

Use a custom ignore file:

progress-tree --ignore-file .treeignore

Report Output

A Progress Tree report contains:

  • generation timestamp
  • scanned repository root
  • ASCII representation of the project hierarchy
  • directory count
  • file count
  • total lines of code
  • scan duration

The resulting text file can serve as a lightweight development artifact, repository inventory, project snapshot, or context document for an AI coding session.

Python API

Progress Tree can also be incorporated into other Python tools using its public scanning and reporting components, including:

  • TreeScanner
  • ScanResult
  • ScanMetrics
  • ReportBuilder
  • configurable ignore strategies

This allows repository inspection to become part of a larger development, documentation, or context-engineering workflow.

Requirements

  • Python 3.10 or later
  • No runtime dependencies

Development dependencies are limited to pytest and pytest-cov.

Why Progress Tree?

Modern development tools are very good at producing more code. AI coding systems have made them dramatically better at it.

Understanding the resulting repository is a separate problem.

Progress Tree deliberately does not generate, refactor, evaluate, or explain code. It provides a deterministic structural view of what exists so that developers can periodically inspect the thing they are actually building.

It is infrastructure for understanding the codebase rather than another mechanism for making the codebase larger.

Version

1.0.0

This release establishes the initial stable CLI, report format, scanning model, ignore behavior, and Python API for future Progress Tree development.

Assets 2
Loading