stats

module

v0.0.0-...-b60f55f Latest Latest Go to latest Published: Jul 4, 2026 License: GPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/agoodkind/stats

Links

Open Source Insights

README ¶

GitHub stats in Go

stats-gh is a Go CLI that collects GitHub profile statistics and writes three SVG assets (overview, language breakdown, top-repos cards) for your profile README. Every aggregation rule, scoring weight, and display option is driven by config.toml.

Outputs

File	Contents
`generated/overview.svg`	Header card with totals: Stars, Forks, All-time contributions, Lines of code changed, profile and repository views, public repos you own, open-source repos you contribute to.
`generated/languages.svg`	Language breakdown across your active owned repos (optionally folded in with externals). Percentages are compressed so a single dominant language doesn't crowd out the rest.
`generated/top_repos.svg`	2-column card grid of your top repos. Each card shows the name, primary-language dot, description, star count, and last-pushed-ago.
`generated/views_history.json`	Persisted profile-view counter plus per-repo daily traffic counts; the bot commits this alongside the SVGs so the views number accumulates across runs.
`diagnose` subcommand stdout	One line per repository with the inclusion reason and recency weight. Not committed; for debugging.

Configuration knobs

Every section is optional; defaults below are applied to anything you omit.

`[github]`

Key	Default	Effect
`token`	env `GH_TOKEN` then `GITHUB_TOKEN`	PAT used for every GitHub API call. `GH_TOKEN` takes priority so a personal token overrides the limited GitHub Actions default.
`actor`	env `GH_ACTOR` then `GITHUB_ACTOR`	GitHub login the stats are computed for.

`[logging]`

Key	Default	Effect
`level`	`"INFO"`	slog level: `DEBUG`, `INFO`, `WARN`, `ERROR`.

`[recency]`

Each commit you authored is weighted as max(floor, 0.5 ^ (commit_age / half_life)). The weighted sum drives the top-repos score and scales each repo's language-byte contribution.

Key	Default	Effect
`half_life`	`"3y"`	How long a commit takes to count for half. Accepts `"<years>y"` or any `time.ParseDuration` string (`"180d"`, `"8760h"`). Larger = older commits count more.
`floor`	`0.05`	Per-commit weight floor: a commit can never count for less than this. Set to `1.0` to disable recency entirely; `0` to let old commits go to zero.

`[owned]`

Inclusion rules for the public repos you own. A repo that fails any rule gets dropped from the Stars / Forks / "Public repos I own" counts, the language stats, and the top-repos cards.

Key	Default	Effect
`exclude_archived`	`true`	Drop archived repos.
`exclude_disabled`	`true`	Drop disabled (suspended) repos.
`exclude_forks`	`true`	Drop repos you forked from someone else.
`require_languages`	`true`	Drop repos GitHub has no language data for (typically empty repos).
`excluded_repos`	`[]`	Full `owner/name` strings to drop.
`excluded_langs`	`[]`	Case-insensitive language names to drop from the language chart.

`[contributed]`

External repos you've committed to but don't own (GitHub's repositoriesContributedTo set). External repo names never render in any SVG — only aggregate numbers and language bytes can flow through.

Key	Default	Effect
`include`	`"all"`	`"all"` includes private (SSO-gated) externals in the "Open-source repos I contribute to" tally. `"public-only"` filters them out.
`include_in_loc`	`true`	Sum external commit additions/deletions into "Lines of code changed". Requires the PAT to be SSO-authorized for the org for private externals.
`include_in_languages`	`true`	Roll external repos' language bytes into the Languages chart (e.g. a Ruby work repo lifts the displayed Ruby %).

`[top_repos]`

The card grid.

Key	Default	Effect
`limit`	`6`	Number of cards rendered. 2 columns wide, so an odd number leaves the last row half-empty.
`star_coefficient`	`2.0`	`score = log10(1 + weighted_commits) + star_coefficient * log10(1 + stars)`. Higher → popularity outliers dominate; `1.0` balances commits and stars; `0` ignores stars entirely.

`[languages]`

Key	Default	Effect
`compression`	`"sqrt"`	Curve applied to weighted byte totals before percentages are computed. `"linear"` shows raw ratios (one dominant language stays dominant). `"sqrt"` makes smaller languages visible. `"log"` is the most aggressive flattening.

Views Counter

The views number on the Overview is the current Komarev profile-view badge count plus every repository traffic daily count persisted in generated/views_history.json. GitHub's traffic API only exposes the trailing 14 days, so the bot still commits the history file after each run.

Full example

[github]
actor = "agoodkind"

[logging]
level = "INFO"

[recency]
half_life = "3y"
floor = 0.05

[owned]
exclude_archived = true
exclude_disabled = true
exclude_forks = true
require_languages = true
excluded_repos = []
excluded_langs = []

[contributed]
include = "all"
include_in_loc = true
include_in_languages = true

[top_repos]
limit = 6
star_coefficient = 2.0

[languages]
compression = "sqrt"

Commands

go run ./cmd/stats-gh -config ./config.toml generate    # write SVGs to generated/
go run ./cmd/stats-gh -config ./config.toml diagnose    # print per-repo inclusion decisions
go run ./cmd/stats-gh -config ./config.toml version     # print build version
make check                                               # lint + format gates
make generate                                            # shorthand for the generate command

Attribution

This project derives from jstrieb/github-stats by Jacob Strieb and keeps the project under the GNU General Public License v3.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
stats-gh command Command stats-gh is the CLI entry point that loads configuration, wires up the GitHub client, and dispatches to the requested subcommand (generate / diagnose / version).	Command stats-gh is the CLI entry point that loads configuration, wires up the GitHub client, and dispatches to the requested subcommand (generate / diagnose / version).
stats-gh-readme-cache command Command stats-gh-readme-cache updates profile README image URLs with a cache key so GitHub refreshes generated SVG assets.	Command stats-gh-readme-cache updates profile README image URLs with a cache key so GitHub refreshes generated SVG assets.
internal
app Package app is the stats-gh control plane: it parses the requested subcommand and dispatches to the collector + renderer or to the diagnostics formatter.	Package app is the stats-gh control plane: it parses the requested subcommand and dispatches to the collector + renderer or to the diagnostics formatter.
collector Package collector aggregates GitHub-sourced repository data into the rendered StatsSummary and diagnostics report, applying repo-exclusion and recency-weighting rules along the way.	Package collector aggregates GitHub-sourced repository data into the rendered StatsSummary and diagnostics report, applying repo-exclusion and recency-weighting rules along the way.
config Package config loads stats-gh runtime configuration from a TOML file and resolves GitHub credentials from environment-variable fallbacks.	Package config loads stats-gh runtime configuration from a TOML file and resolves GitHub credentials from environment-variable fallbacks.
githubapi Package githubapi wraps the GitHub REST and GraphQL APIs that stats-gh uses, including a rate-limit-aware HTTP transport and typed query helpers.	Package githubapi wraps the GitHub REST and GraphQL APIs that stats-gh uses, including a rate-limit-aware HTTP transport and typed query helpers.
logging Package logging is the stats-gh slog setup: it builds the structured logger, sets it as the process default, and exposes context-carrying helpers.	Package logging is the stats-gh slog setup: it builds the structured logger, sets it as the process default, and exposes context-carrying helpers.
model Package model defines the data shapes shared across the GitHub fetch, aggregation, rendering, and diagnostics layers of stats-gh.	Package model defines the data shapes shared across the GitHub fetch, aggregation, rendering, and diagnostics layers of stats-gh.
output Package output wraps stdout/stderr writes so call sites do not have to import os and fmt directly.	Package output wraps stdout/stderr writes so call sites do not have to import os and fmt directly.
profilecounter Package profilecounter reads the profile-view badge that the profile README renders and turns its SVG value back into a numeric counter.	Package profilecounter reads the profile-view badge that the profile README renders and turns its SVG value back into a numeric counter.
readmecache Package readmecache rewrites profile README stats image URLs so GitHub refreshes cached raw SVG assets after generated images change.	Package readmecache rewrites profile README stats image URLs so GitHub refreshes cached raw SVG assets after generated images change.
render Package render turns a collected StatsSummary into the overview, languages, and top_repos SVG files written under generated/.	Package render turns a collected StatsSummary into the overview, languages, and top_repos SVG files written under generated/.
version Package version exposes the binary's build-stamped version string, overridden at link time via -ldflags.	Package version exposes the binary's build-stamped version string, overridden at link time via -ldflags.
viewshistory Package viewshistory persists per-repo daily traffic counts so the Overview SVG can show a lifetime view total instead of GitHub's rolling 14-day window.	Package viewshistory persists per-repo daily traffic counts so the Overview SVG can show a lifetime view total instead of GitHub's rolling 14-day window.