README
¶
gitling
A terminal-native, at-a-glance summary of a git repository: recent activity,
top contributors, and codebase growth. Run it once at the start of a session to
orient yourself — it's not a replacement for git log or a full TUI.
gitling
Install
go install github.com/lcondliffe/gitling/cmd/gitling@latest
Or grab a prebuilt binary for your platform from the
latest release and put
it on your PATH.
Output
Four panels, single screen:
- Repo vitals — branch, ahead/behind upstream, dirty files, stashes, branches.
- Activity heatmap — GitHub-style contribution grid (default last 14 weeks), 5-step intensity, today's cell marked with a hollow square. Total commits and current streak below.
- Top contributors — up to 5 authors by commit count in range, with bars.
- Codebase growth — total LOC, 6-month percent change, a trend sparkline, and the hottest files by churn.
Usage
gitling # default dashboard (last 14 weeks)
gitling --since 30d # override the range for all sections (d, w, mo, y)
gitling --no-color # plain output, no ANSI escape codes
Color is also auto-disabled when stdout isn't a terminal or NO_COLOR is set.
How it works
- gitdata shells out to
git log --numstatand a handful of cheap plumbing commands. Author date is used for bucketing. - aggregate rolls commits up into per-day buckets (counts, line deltas,
per-author and per-file tallies). Range queries sum the days in range, so
changing
--sincenever invalidates the cache. - cache persists the rollup as a gob file under
.git/gitling-cache/, keyed by the last HEAD seen. Each run only walks commits newer than the last, making repeat runs effectively instant. - render draws everything with 256-color ANSI chosen to read on both light and dark backgrounds.
The layers are cleanly separated: the git backend (currently shell-out, a go-git backend could replace it) and the cache (gob, could become sqlite) are each swappable without touching the others.
Build
go build ./cmd/gitling
Pure Go standard library — no external dependencies.
Releases
Tagging a commit vX.Y.Z triggers the release workflow, which cross-compiles
binaries (linux/darwin/windows, amd64/arm64), attaches them with a
checksums.txt, and publishes a GitHub Release with auto-generated notes:
git tag v0.1.0
git push origin v0.1.0
Status
v0.1. Drill-down subcommands (--graph, --churn, --contributors,
--branches) are reserved but not yet implemented.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gitling
command
Command gitling prints a compact, at-a-glance dashboard for the git repo in the current directory: repo vitals, an activity heatmap, top contributors, and codebase growth.
|
Command gitling prints a compact, at-a-glance dashboard for the git repo in the current directory: repo vitals, an activity heatmap, top contributors, and codebase growth. |
|
internal
|
|
|
aggregate
Package aggregate turns raw commits into the per-panel metrics the dashboard needs, and holds the in-memory shape that the cache persists.
|
Package aggregate turns raw commits into the per-panel metrics the dashboard needs, and holds the in-memory shape that the cache persists. |
|
cache
Package cache persists derived aggregates so repeat runs only process commits newer than the last one seen.
|
Package cache persists derived aggregates so repeat runs only process commits newer than the last one seen. |
|
gitdata
Package gitdata is the git interaction layer for gitling.
|
Package gitdata is the git interaction layer for gitling. |
|
render
Package render draws the dashboard to an io.Writer.
|
Package render draws the dashboard to an io.Writer. |