RPO: Repository Participation Observer

A Python library to help you analyze and visualize Git repositories. Ever wondered who has most contributions? How participation has changed over time? What are the hotspots in your code that change frequently? Who has the highest bus factor? rpo can help.

NOTE: This is alpha software under active development. There will be breaking changes.

Install

pip install rpo

Wheels bundle a compiled Rust extension, so there is no toolchain to set up and no git binary is shelled out to.

Usage

import rpo

ra = rpo.RepoAnalyzer("./path/to/git_repo")

ra.summary()
ra.contributor_report(identify_by="email", limit=10)
ra.file_report(limit=10)
ra.blame_report()
ra.punchcard()

Walk options are set once, on the analyzer, and apply to every report — mirroring the Rust builder:

ra = rpo.RepoAnalyzer(
    path,
    exclude_globs=["docs/**", "**/*.lock"],
    ignore_bots=True,
    first_parent_only=False,
)

Report options are keyword arguments:

ra.contributor_report(aggregate_by="committer", identify_by="email", limit=5)

Reports return polars DataFrames and print nothing, so they compose with your own analysis:

import polars as pl

(ra.file_report()
   .filter(pl.col("contributors") == 1)
   .sort("lines", descending=True))

The raw frames

For anything the built-in reports do not cover, take the frames directly. commits, file_changes, blame, and blame_over_time mirror the Rust library's terminals:

analysis = rpo.analyze(path, snapshots="monthly")
analysis.commits          # one row per commit
analysis.file_changes     # one row per (commit, file)
analysis.blame            # per-line authorship at HEAD
analysis.blame_over_time  # ...at each snapshot

Identities are canonicalized through .mailmap by the engine, so reports group on canonical_author_name, canonical_committer_email, and so on. File paths are path; datetimes are UTC milliseconds.

Charts

Plotting is an explicit call, never a side effect of running a report:

rpo.plotting.blame(ra.blame_report(limit=15), "img/blame.png")
rpo.plotting.cumulative_blame(ra.cumulative_blame(), "img/cblame.png")
rpo.plotting.punchcard(ra.punchcard(), "img/punchcard.png")

Any report frame also works directly with Altair through polars' .plot accessor.

Errors

Failures from the engine surface as typed exceptions, all subclassing rpo.RpoError: NotARepositoryError, InvalidGlobError, RevisionNotFoundError.

Examples

Runnable scripts live in examples/, covering the frames, every report, filtering, blame over time, charts, and custom polars recipes. They default to analyzing this checkout:

python examples/01_quickstart.py
python examples/02_reports.py ~/src/some-other-repo

Command line

There is no python CLI. The command-line tool is rpo-cli, installed separately:

cargo install rpo-cli
rpo summary -r ./path/to/repo

Features

• Automatically generate aliases that refer to the same person
• Support analyzing by glob
• Support excluding by glob
• Produce blame charts
• Optionally ignore merge commits
• Optionally ignore whitespace (awaiting upstream gix support)
• Identify major refactorings
• Fast execution, even on giant repositories (the engine is Rust)

Performance

The goal is for the library to work even on the largest libraries. In general, the performance is proportional to the number of authors, commits, and files being considered in the aggregations.

The authors regularly test using the cpython repository, which contains over 1,000,000 objects. That takes a while.

TODO: Performance graphs

Similar Projects and Inspiration

• GitPandas
• git-truck
• busfactor
• bus-factor-explorer
• git-of-theseus
• hercules

References

Git Commands

These are useful for validating results reported here. The git man pages for various commands is helpful reading.

All the files edited in a revision

git diff-tree --no-commit-id --name-only HEAD~1 -r

All the files present at a particular revision

git ls-tree -rlt HEAD

All commits reachable from a revision

git rev-list HEAD --count

Count all commits reachable from a revision

git rev-list HEAD --count

All commits that touch a particular object (tree in this case)

git rev-list HEAD img

All files at each commit

git rev-list HEAD | xargs -r -I % git ls-tree -rt --name-only %

git cat-file --batch-all-objects --batch-check --unordered

git rev-list --all --objects --filter=object:type=blob HEAD | git cat-file --batch-check="%(objectname) %(objecttype) %(rest) %(deltabase)"

git log --follow --pretty=format:%H -- FILE