Skip to content

Release Notes v0.12.0

This release adds the stats-report CLI command for generating aggregated statistics reports, multi-format rendering support, and enhanced profile command filtering options.

Highlights

  • Stats Report Command: New stats-report CLI command generates hierarchical reports from monthly JSON files
  • Multi-Format Output: Render reports as Markdown, HTML, or plain text
  • Hierarchical Aggregation: Automatic rollup from monthly → quarterly → annual statistics
  • Enhanced Filtering: New --visibility and --release-orgs flags for precise data filtering

New Features

Stats Report Command

Generate aggregated statistics reports from monthly JSON files:

# Generate Markdown report
gogithub stats-report --input-dir ./stats/ --output-md README.md

# Generate multiple formats
gogithub stats-report --input-dir ./stats/ \
    --output-json report.json \
    --output-md README.md \
    --output-html report.html

# Customize the report
gogithub stats-report --input-dir ./stats/ \
    --output-md README.md \
    --title "My GitHub Stats" \
    --show-details=false

The command reads monthly JSON files (generated by --output-monthly-dir) and aggregates them into a hierarchical structure with:

  • Annual totals
  • Quarterly breakdowns (Q1, Q2, Q3, Q4)
  • Monthly details

Output formats:

Format Description
JSON Machine-readable hierarchical data structure
Markdown Human-readable tables and sections
HTML Styled web page with responsive design
Text Plain text for terminal display

Visibility Filtering

Filter profile statistics by repository visibility:

# Public repos only
gogithub profile --user grokify --visibility public --output-monthly monthly.json

# Private repos only
gogithub profile --user grokify --visibility private --output-monthly monthly.json

# All repos (default)
gogithub profile --user grokify --visibility all --output-monthly monthly.json

Release Org Filtering

Count releases only from specific organizations:

# Only count releases from grokify and plexusone orgs
gogithub profile --user grokify \
    --include-releases \
    --release-orgs grokify,plexusone \
    --output-monthly monthly.json

Individual Monthly Files

Generate separate JSON files for each month:

# Creates grokify_github_public_2026-01.json, grokify_github_public_2026-02.json, etc.
gogithub profile --user grokify \
    --from 2026-01-01 --to 2026-03-31 \
    --visibility public \
    --output-monthly-dir ./stats/

Query Metadata

Output JSON files now include metadata for reproducibility:

{
  "metadata": {
    "username": "grokify",
    "from": "2026-01-01",
    "to": "2026-01-31",
    "visibility": "public",
    "includeReleases": true,
    "generatedAt": "2026-04-06T12:00:00Z"
  },
  "username": "grokify",
  "year": 2026,
  "month": 1,
  "monthName": "January",
  "stats": {
    "commits": 1091,
    "releases": 108,
    "additions": 744988,
    "deletions": 294379,
    "netAdditions": 450609,
    "repoCountContributed": 72,
    "repoCountCreated": 0
  }
}

New Types and Functions

profile package

StatsReport Types

// Hierarchical report structure
type StatsReport struct {
    Metadata ReportMetadata
    Years    []YearStats
}

type YearStats struct {
    Year     int
    Stats    AggregateStats
    Quarters []QuarterStats
}

type QuarterStats struct {
    Quarter int            // 1-4
    Year    int
    Label   string         // "Q1 2026"
    Stats   AggregateStats
    Months  []MonthStats
}

type AggregateStats struct {
    Commits, Issues, PRs, Reviews, Releases int
    Additions, Deletions, NetAdditions      int
    RepoCountContributed, RepoCountCreated  int
}

Aggregation Functions

// Load monthly files from directory
files, err := profile.LoadMonthlyFiles("./stats/")

// Build hierarchical report
report, err := profile.BuildStatsReport(files)

// Access data
total := report.TotalStats()
q1 := report.GetQuarter(2026, 1)
year := report.GetYear(2026)
latest := report.GetLatestQuarter()

Rendering Functions

// Render to Markdown
md, err := profile.RenderToMarkdown(report, profile.RenderOptions{
    Title:            "My Stats",
    ShowMonthDetails: true,
    ShowDataSource:   true,
})

// Render to HTML
html, err := profile.RenderToHTML(report, opts)

// Render to plain text
text, err := profile.RenderToText(report, opts)

// Write to file (auto-detects format)
err := profile.RenderToFile("report.md", report, opts)

MonthlyStats Type

type MonthlyStats struct {
    Year, Month          int
    MonthName            string
    Commits, Issues, PRs int
    Reviews, Releases    int
    Additions, Deletions int
    NetAdditions         int
    RepoCountContributed int
    RepoCountCreated     int
}

// Convert from MonthlyActivity
stats := activity.ToMonthlyStats()

// Get net additions
net := activity.NetAdditions()

// Get created repo count
count := activity.RepoCountCreated()

CLI Flag Summary

New flags for the profile command:

Flag Description
--visibility Filter by repo visibility: all, public, private
--release-orgs Comma-separated list of orgs to count releases for
--output-monthly-dir Output directory for individual monthly JSON files

New stats-report command flags:

Flag Description
-i, --input-dir Directory containing monthly JSON files (required)
--output-json Output JSON report file
--output-md Output Markdown report file
--output-html Output HTML report file
--output-text Output plain text report file
--title Custom title for the report
--show-details Include monthly detail sections (default: true)
--data-url URL for data source attribution
--regenerate-cmd Command to regenerate the data (shown in output)

Workflow Example

Complete workflow for generating quarterly statistics:

# 1. Generate monthly data files
gogithub profile --user grokify \
    --from 2026-01-01 --to 2026-03-31 \
    --visibility public \
    --include-releases \
    --release-orgs grokify,plexusone \
    --output-monthly-dir ./stats/

# 2. Generate aggregated report
gogithub stats-report \
    --input-dir ./stats/ \
    --output-json ./stats/report.json \
    --output-md ./stats/README.md \
    --title "GitHub Statistics - grokify" \
    --regenerate-cmd "gogithub profile --user grokify ..."

Dependencies

  • Updated github.com/mattn/go-runewidth from v0.0.21 to v0.0.22

Upgrade Notes

  1. No breaking changes: This release is fully backward compatible
  2. New output fields: Monthly JSON output now includes netAdditions, repoCountContributed, and repoCountCreated fields
  3. Metadata in output: All output files now include a metadata section with query parameters
go get github.com/grokify/gogithub@v0.12.0