📊 Plot Py Repo

Visualise Python repository evolution through Git history.

Context is everything with coding with LLMs. Visualise your repo to understand where and how the context is spread. Use existing charts, add your own, or analyse the raw data. See demo output.

Example Charts

Generated by analysing the youtube-to-xml repository.

📈 What It Tracks

Traverses Git history commit-by-commit, analysing Python files in src/ and tests/ directories (excludes __init__.py files). Comments and docstrings are considered documentation (not code) and classified together as "code comments".

How lines are counted

Key principles:

• Total lines — matches what you see in your IDE (includes blank lines)
• Docstring lines — Module, class, and function docstrings identified via AST
• Comment lines — Standalone # comments only (inline comments count as code)
• Code lines — Everything else, including blank lines

📦 Install

(1) First, install the uv Python package and project manager from here.

(2) Then, install plot-py-repo to make it accessible from anywhere in your terminal:

uv tool install git+https://github.com/michellepace/plot-py-repo.git

🚀 Usage

Analyse any Python repository:

# Analyse current directory
plot-py-repo

# Analyse specific repository
plot-py-repo /path/to/your-repo

# Regenerate charts from existing CSV
plot-py-repo --csv history.csv

# Save outputs to custom directory
plot-py-repo --output-dir ./reports

# View all options
plot-py-repo --help

Example Output Files:

• repo_history.csv - Complete Git history data
• repo_evolution_commit.webp - Timeline chart showing growth
• repo_breakdown.webp - Bar chart showing file sizes

🛠️ Development

Clone and set up:

git clone https://github.com/michellepace/plot-py-repo.git
cd plot-py-repo
uv sync
uv run plot-py-repo /path/to/repo

Quality checks:

uv run ruff check --fix           # Lint and auto-fix
uv run ruff format                # Format code
uv run pyright                    # Type check
uv run pytest                     # Run all tests
uv run pre-commit run --all-files # Run all hooks

Tech Stack: Python 3.13+, Plotly Express, Pandas, Kaleido • See CLAUDE.md

Test Driven Development: 59 tests (5 slow, 54 unit, ~14 seconds)

🏗️ Architecture

  🔄 DATA FLOW: Git Repo → CSV → DataFrame → WebP Charts
  --

  ┌─────────────────────────────────────────────────────────────┐
  │                          cli.py                             │
  │              Parse args & orchestrate workflow              │
  └───────┬─────────────────────────────────────┬───────────────┘
          │                                     │
          │ Git Analysis                        │ Visualisation
          ▼                                     ▼
  ┌──────────────────┐              ┌─────────────────────────┐
  │  git_history.py  │              │     visualise.py        │
  │                  │              │                         │
  │  Walk commits,   │              │  Load CSV, filter,      │
  │  extract files,  │─────CSV─────▶│  delegate to charts     │
  │  classify lines, │              │                         │
  │  write CSV       │              └────────┬────────────────┘
  └────────┬─────────┘                       │
           │                                 │
           │ uses                            │ calls
           ▼                                 ▼
  ┌──────────────────┐              ┌─────────────────────────┐
  │  count_lines.py  │              │     chart_*.py          │
  │                  │              │   (3 modules)           │
  │  Pure function:  │              │                         │
  │  classify Python │              │  Transform data,        │
  │  lines into      │              │  create Plotly charts,  │
  │  code/docs/      │              │  save as WebP           │
  │  comments        │              │                         │
  └──────────────────┘              └────────┬────────────────┘
                                             │ uses
                                             ▼
                                    ┌─────────────────────────┐
                                    │       theme.py          │
                                    │                         │
                                    │  Shared theming &       │
                                    │  image export helpers   │
                                    └─────────────────────────┘

See docs/architecture/arch-03.md for detailed implementation patterns.