You clone a repo you've never seen before and you want to understand it. Not the code, not yet. The shape of the project. Who's been working on it? How often? Is it one person pushing daily or three people who show up once a month? Are there stale branches? When was the last release? What files change the most?

Git has answers to all of this, scattered across a dozen commands. git log --format with the right incantation gives you commit frequency. git shortlog -sn gives you contributor rankings. git branch -v shows branches but not staleness. git tag gives you release names but not cadence. None of it is visual. None of it is fast. And none of it lives in one place.

gittop puts it in one place.

What Is gittop?

gittop is a terminal UI for git repository statistics, built in Go by hjr265 (Mahmud Ridwan). You run gittop in a repo and it scans the commit history, then drops you into a seven-tab dashboard: Summary, Activity, Contributors, Branches, Files, Releases, and Commits. Each tab is a different lens on the same data. Switch tabs with number keys, zoom time ranges with +/-, filter by author or path or branch with a query language, and navigate everything with vim keys.

The whole thing is about 6,500 lines of Go, a month old, and sitting at 119 stars. The author wrote a blog post about building it with agentic coding tools, which makes the project an interesting artifact on two levels: it's a useful tool, and it's a case study in what agent-assisted development produces.

The Snapshot

Under the Hood

gittop is built on the charmbracelet stack: bubbletea for the TUI framework, bubbles for input widgets, lipgloss for styling. The Elm-style Model/Update/View architecture is clean and consistent across all seven tabs. Each tab implements a Page interface with Init, Update, and View methods, and the main model dispatches messages to the active page. If you've built anything with bubbletea before, the code will feel immediately familiar.

The other major dependency is go-git, which gives gittop pure-Go access to the git object store. No shelling out to git log, no parsing CLI output. The repository is opened once, commits are walked once at startup, and everything else (branches, tags, file health) loads lazily when you switch to the relevant tab. That lazy-loading design keeps startup fast even on large repos.

The surprise is the filter system. gittop ships a full query language built with participle, a parser-combinator library. You can type author:"alice" and path:*.go and branch:main into the filter bar and it compiles that into an AST, evaluates it against every commit, and recomputes all the statistics in real time. Boolean operators, parenthetical grouping, negation, glob patterns on file paths. For a one-month-old side project, that's a lot of parser.

The rendering is thoughtful too. Area charts use braille characters by default, packing two data points per terminal cell with sub-cell precision. The code maps values to braille dot patterns directly: left-column pins for odd indices, right-column for even, bottom to top. Each chart row gets a gradient color from the active theme. There's a block-character fallback for terminals that don't render braille well, and the horizontal bar charts in the Activity and Contributors tabs use fractional block characters for smooth sub-character precision. You can toggle rendering modes in the options menu. The whole thing respects your terminal's color profile (ANSI256 vs truecolor) and persists your preferences to ~/.config/gittop/config.toml.

The dependency story is clean. Six direct dependencies: the three charmbracelet packages, go-git plus go-billy for filesystem abstraction, and participle for the filter parser. That's it. No framework bloat, no utility grab-bags. The go.sum is mostly transitive deps from go-git's crypto and SSH support.

The rough edge is testing. Before our contribution, the project had two test files: filter_test.go (72 lines testing the parser) and mailmap_test.go (54 lines testing .mailmap resolution). That's it. The core data pipeline in stats.go, which handles commit aggregation, time bucketing, health data computation, and date range filtering, had zero coverage. For a project built with agentic tools, this tracks: agents are good at producing working code, less good at producing tested code.

The Contribution

The obvious gap was test coverage, so that's what we went after. stats.go is 548 lines of pure data functions: CommitsToDailyStats aggregates commits into daily counts and fills date gaps, AggregateStats buckets daily data into weekly/monthly/yearly periods, bucketKey handles the calendar math for each granularity, BuildHealthData combines file line counts with commit-derived churn and author data. All pure functions, all taking structs and returning structs, all testable without touching a git repository.

We wrote 22 test cases covering seven functions. The AggregateStats tests verify that weekly bucketing groups by Monday (with Sunday correctly mapping to the previous week), monthly by the first of the month, and yearly by January 1st. The BuildHealthData tests verify both filtered and unfiltered modes, checking that churn counts, author counts, and last-changed dates are computed correctly, and that empty inputs produce the right zero values. The CommitsToDailyStats tests verify gap-filling (days with no commits still appear with count zero) and edge cases like empty input.

One thing we caught during review: CommitsToDailyStats fills from the earliest commit to time.Now(), so the output length of any test grows by one entry per day. You can't pin the exact output without injecting a clock, and refactoring the function signature felt out of scope for a tests-only PR. We noted it in a comment on the PR. The proper fix would be a small production code change, which is the kind of thing a second PR could handle if the maintainer is interested.

Getting into the codebase was fast. The flat file layout means every source file is in the root directory. There's no cmd/ or internal/ to navigate. Open stats.go, read the types, read the functions, write tests. The existing test files established a clear convention: table-driven tests with the standard testing package, no external assertion libraries. We matched that style.

PR #6 is open. Based on the maintainer's track record (all four prior issues resolved same-day, external PRs merged within hours), we expect a quick turnaround.

The Verdict

gittop is for anyone who wants to understand a git repository's history without memorizing a dozen git log format strings. If you review a lot of repos, onboard to new codebases regularly, or just like seeing your own commit patterns visualized, this does the job in a single command.

The project is a month old and moving fast. Five releases in three weeks, responsive maintainer, external contributions already landing. The agentic origin is interesting but not a limitation: the code is clean, the architecture is sound, and the filter system shows real design ambition. What it needs now is the kind of test coverage that makes future contributors confident they aren't breaking things.

If gittop hits a Homebrew core formula and a few more people write about it, this is a 1,000-star project by the end of the year. It solves a real problem, it looks good doing it, and the maintainer clearly cares.

Go Look At This

Run go install github.com/hjr265/gittop@latest, point it at your biggest repo, and flip through the tabs. The Activity heatmap alone is worth the install.

Star the repo. If you want to contribute, the codebase is small enough to read in a sitting. Here's our test coverage PR if you want to see what getting into the code looks like.

This is Review Bomb, a series where I find under-the-radar projects on GitHub, read the code, contribute something, and write it up. If you know a project that deserves more eyeballs, drop it in the comments.

---

This post was originally published at wshoffner.dev/blog. If you liked it, the Review Bomb series lives there too.