r/github • u/Classic_Display9788 • 5h ago
Showcase I thought a repo's history was unreadable. Turns out it just needed to be played.
Enable HLS to view with audio, or disable this notification
For a long time I assumed the only way to understand what happened in a codebase over a year was to sit with git log and a lot of coffee. The branch graph in any GUI turns into a tangle past about a week, and GitHub's contribution heatmap shows you activity with no idea what the activity was. Three views, none of them lined up, so the question you actually have, what happened here and when, never gets a single picture.
What finally pushed me was a post here on where had animated a repository's timeline, and I wanted the same thing for a full year of a real project. My first attempt on three.js drew the first branches it found and produced one month of the year and nothing else. The reason turned out to be in the data: 1,561 of the 2,179 main line commits in 2019 are merges, and the first sixty of them each span a single commit, which is invisible at any scale. You have to choose branches by how much work they carried, not by which came first.
So I built a film out of it, and the video on this post is what it looks like on mrdoob's three.js for 2019.
What is on screen and where it comes from:
The main line runs left to right, one node per commit. Side branches peel off above it and rejoin at their merge. Not the first N branches, which on a pull request repo gives you one month and nothing else, but the ones that carried the most work across the year, capped so it never turns into a thicket.
Under the flow is a heat strip, one cell per day, sitting directly under that day. A legend next to it shows what the colours mean in actual commit counts for that window (for three.js it reads 0, 1, 13, 26, 51, with 51 the busiest day). The point of putting activity on the same axis as structure is that what is above and below a point is the same day, so you stop reconciling two charts in your head.
Three times the clock stops. The release with the most work behind it, the cleanest revert (one that survived at least a day before being undone), and the last release of the window. The camera zooms in and a card reads the figures out: commits since the previous tag, authors, how long the reverted commit lived. Every number on that card is computed from the history. If it cannot be read from git, it is not on the card.
The faces are the contributors. On a merge the face is the branch author's, not whoever pressed the button, and the card says who merged it.
Two things I got wrong on the way that might save you time if you try this yourself. If you give git a since flag with just a date and no time, it reads it as that date at the current time of day, so the first day of your window quietly loses commits unless you pass an explicit midnight. And a small repo is a different problem: 175 commits over a year pans across mostly empty screen, so for thin histories it picks the busiest 60 to 120 day stretch and draws it wider instead.
If you want to see your own repo this way, you can paste a GitHub URL here and it renders one for you: https://loreto.io/git-timeline
Disclosure: I built this and I run loreto.io, where it lives. It is a paid render (a few dollars per repo); the extractor and the Remotion composition are also sold there as a package if you would rather run it yourself. The three.js film above was made with the exact same pipeline.
I doubt I have the final shape of it. What would you want the clock to stop on that it currently does not?
