Back to insights

Getting to Know Your Repository with git-spark

November 21, 202613 min read

git-spark turns a repository's commit history into an interactive report, a health check, and sprint comparisons. This walk-through covers the 2.0 release, the commands I reach for, and the limits I learned on my own repo.

Development Series — 24 articles
  1. Decorator Design Pattern - Adding Telemetry to HttpClient
  2. NuGet Packages: Benefits and Challenges
  3. Mastering Git Repository Organization
  4. CancellationToken for Async Programming
  5. Git Flow Rethink: When Process Stops Paying Rent
  6. Understanding System Cache: A Comprehensive Guide
  7. Guide to Redis Local Instance Setup
  8. Creating a PHP Website with ChatGPT
  9. TaskListProcessor - Enterprise Async Orchestration for .NET
  10. Harnessing the Power of Caching in ASP.NET
  11. Fire and Forget for Enhanced Performance
  12. Building Resilient .NET Applications with Polly
  13. The Singleton Advantage: Managing Configurations in .NET
  14. Troubleshooting and Rebuilding My JS-Dev-Env Project
  15. Generate Wiki Documentation from Your Code Repository
  16. My Journey as a NuGet Gallery Developer and Educator
  17. Architecting Agentic Services in .NET 9: Semantic Kernel
  18. The Building of React-native-web-start
  19. TailwindSpark: Ignite Your Web Development
  20. Evolving PHP Development
  21. Modernizing Client Libraries in a .NET 4.8 Framework Application
  22. Building Git Spark: My First npm Package Journey
  23. Dave's Top Ten: Git Stats You Should Never Track
  24. Getting to Know Your Repository with git-spark

Filed under Pragmatic architecture and modernization

Topic cluster

Software Development Patterns

.NET development, API integration, implementation patterns, and the trade-offs that show up in working code.

The record nobody reads

Every repository keeps a detailed record of how it was built: who changed what, when, how often, and how much. Most of the time that record gets opened one commit at a time with git log, so the larger patterns stay hidden. Which files keep changing? Does the work come in a steady stream or in bursts? How many people could keep this project alive?

I built git-spark to answer those questions from the history alone. It started as a weekend project and became my first npm package, a story I told in Building Git Spark. It's an open-source Node.js CLI and library. One command produces a self-contained, interactive HTML dashboard. Others give a quick health check, compare sprints, or export raw data for your own tooling.

It relies only on Git commit data. It doesn't connect to your issue tracker, CI, or code host, and every metric says what Git can and cannot tell you. That rule hasn't moved since the first release. What has moved is everything around it, so this is a walk through the 2.0 line and the commands I reach for when I want to know a repo.

What changed in 2.0

Version 2.0.0 shipped in October 2026, and 2.0.2 followed on November 21. For anyone upgrading, three changes matter.

The breaking one is the runtime. git-spark now requires Node.js 26 or newer, up from 22. If an older CI image pins Node 22, the install will fail until it moves.

The periods command is new to anyone on npm. It was built for 1.4.0, but that version's publish failed with an authentication error and never reached the registry, so 2.0.0 is the first published release that has it. The same is true of shallow-clone detection, which warns when a checkout may be missing history.

The rest is correctness. Version 2.0.1 fixed --days silently dropping recent commits when the window reached back past the first commit and local and UTC dates disagreed, which happens in US evenings. It also stopped the install from triggering npm's "install scripts blocked" warning. Since 2.0.2, every release posts a release history page and a GitHub Release from the changelog automatically.

Your first report in about a minute

Every command in this article works the same in bash, zsh, and PowerShell. Check your Node.js version first, since git-spark needs 26 or newer:

bash
node --version

Install the CLI globally:

bash
npm install -g git-spark

Then run it from the root of any repository:

bash
git-spark html --days 90 --open

That analyzes the last 90 days, writes reports/git-spark-report.html, and opens it in your browser. The report is a single file with no external calls, so you can email it or attach it to a ticket. To analyze a repository without changing into it, add --repo with its path:

bash
git-spark html --days 90 --open --repo ../some-other-repo

If you'd rather not repeat your flags, save them. This wizard asks how many days to analyze, which output format you prefer, and which file extensions to skip, then writes a .git-spark.json file that later runs pick up (add --yes to accept the defaults):

bash
git-spark init

If a run fails or the numbers look wrong, this checks Git, Node.js, and the repository before you go hunting:

bash
git-spark validate

The HTML report

The HTML report is where I start: one page that answers "what has been happening here?" Its sections, in order:

SectionWhat it tells you
Current Repository StateSize and shape of the repo today: file extensions, file categories, and a directory breakdown
SummaryCommits, contributors, files touched, the Repository Activity Index, and bus factor for the window
Top ContributorsCommits, lines changed, and files touched per author
Team Activity PatternsAggregate patterns such as commit distribution and code volume across the team
File Activity HotspotsThe files and directories that change most often
Author Activity DetailsA profile per contributor
Daily TrendsA day-by-day trend chart, a contributions calendar heatmap, and detailed daily tables
Measurement LimitationsWhat these numbers can and cannot tell you

The page has a persistent dark-mode toggle, "Show more" paging on long tables, and section navigation. Its charts are native SVG with no external libraries. It ships with a strict Content Security Policy that uses SHA-256 hashes instead of unsafe-inline, so it is safe to open from anywhere.

Two flags change what you see. --serve serves the report from a local web server instead of a file, which helps when a browser or security tool blocks local HTML files. --port picks the port (the default is 3000):

bash
git-spark html --days 90 --serve --port 8080

--heavy turns on more expensive analyses for a deeper look. Expect it to take longer on a large history:

bash
git-spark html --days 90 --heavy --open

A health check in the terminal

When I want an answer without opening a browser, health summarizes the last 30 days in a terminal box:

bash
git-spark health

Here is what it printed on the git-spark repository itself:

output
🏥 Repository Health Check

Overall Health: 75%
Governance Score: 66%
Risk Level: LOW
Bus Factor: 50%
Active Days: 1

It's a good habit for the first few minutes in an unfamiliar repo: is this project active, and does more than one person work on it? For more detail without the HTML, this prints the full analysis as tables in the terminal:

bash
git-spark --days 30 --format console

Comparing sprints with periods

git-spark periods splits recent history into equal, non-overlapping windows and compares them side by side: commits, churn (lines added plus removed), net lines, files changed, and active authors. --period-days sets the window and --periods sets the count. This compares the last four two-week sprints on the git-spark repo:

bash
git-spark periods --period-days 14 --periods 4
output
Period     Date Range                Commits  Churn   Net Lines  Files  Authors
Period 1   2026-09-26 → 2026-10-10   0        0       +0         0      0
Period 2   2026-10-10 → 2026-10-24   14       52,372  +42,002    426    2
Period 3   2026-10-24 → 2026-11-07   0        0       +0         0      0
Period 4   2026-11-07 → 2026-11-21   7        10,018  +2,590     112    2

The table makes the project's rhythm obvious: it moves in bursts around releases. Period 2 holds the 2.0.0 release, with 14 commits and 426 files touched. The two empty sprints are the quiet time on either side.

By default the last period ends now. To line the windows up with your sprint calendar, anchor the last one to a sprint's end date with --until:

bash
git-spark periods --period-days 14 --periods 4 --until 2026-11-14

To compare a branch other than the one you have checked out, add --branch:

bash
git-spark periods --period-days 14 --periods 4 --branch develop

To drop the comparison into a retro or status update, write it as Markdown (or html) to a folder:

bash
git-spark periods --period-days 14 --periods 4 --output-format markdown --output ./reports

If the repo is a shallow clone, git-spark warns you, because older periods may be missing commits that were never fetched.

Slicing the history

A whole-repo report answers "what's happening?" Filters answer narrower questions. They're passed straight to git log, so they behave the way Git does:

FlagQuestion it answersExample
--days / --since / --untilWhat happened in this window?--since 2026-01-01 --until 2026-03-31
--branchWhat's happening on this branch?--branch develop
--authorWhat has this person been working on? Matches name or email, like git log --author--author [email protected]
--pathHow active is this part of the codebase?--path src/core
--exclude-extensionsWhat does the code alone look like, without docs or lockfiles?--exclude-extensions .md,.json
--timezoneWhen does activity happen in your local time?--timezone America/Chicago

Every filter combines with every report command. The recipes at the end of this article put them together into full commands.

--exclude-extensions makes the biggest difference of the set on repos with lots of documentation or generated files. On the git-spark repo, Markdown touches far more files than TypeScript, so excluding .md gives a much truer picture of code churn.

Two options change the tone of the report. --redact-emails hides email addresses, which matters before you share a report outside the team. --teamwork removes the individual contributor sections and keeps the team-level view.

The extension, timezone, redaction, and teamwork flags belong to the main command, so use the --format html form when you combine them:

bash
git-spark --days 90 --format html --exclude-extensions .md --redact-emails --open

Exporting and automating

The same analysis comes in five formats through --format: html, json, csv, markdown, and console. JSON is the one to use when you want to build on the numbers: chart them in your own dashboard, diff two months, or feed them to another tool. This writes the last 30 days to a data folder:

bash
git-spark --days 30 --format json --output ./data

Markdown fits neatly into a wiki page or a pull request description:

bash
git-spark --days 30 --format markdown --output ./reports

CSV opens directly in a spreadsheet when someone wants to sort and filter the tables themselves:

bash
git-spark --days 30 --format csv --output ./reports

git-spark is also a Node.js package. The analyze() helper returns the full report object, which you can query directly:

typescript
import { analyze, exportReport } from 'git-spark';

const report = await analyze('/path/to/repo', { days: 30 });

console.log(`${report.repository.totalCommits} commits`);
for (const file of report.hotspots.slice(0, 5)) {
  console.log(`${file.path}: ${file.commits} commits, churn ${file.churn}`);
}

await exportReport(report, 'html', './reports');

For more control, the GitSpark class takes the same options (repoPath, since, until, branch, author, path, timezone, heavy) plus an optional progress callback.

A scheduled GitHub Actions job can produce a fresh report every week and keep it as a build artifact. The one setting that matters is fetch-depth: 0. The default shallow checkout has only the latest commit, so the report would be nearly empty.

yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # full history
- uses: actions/setup-node@v4
  with:
    node-version: '26'
- run: npm install -g git-spark
- run: git-spark --days 30 --format html --output ./reports
- uses: actions/upload-artifact@v4
  with:
    name: git-spark-report
    path: ./reports/

git-spark does this for itself: each release tag regenerates the live sample report on its docs site.

Reading the numbers honestly

The rule I built git-spark around is that it never invents a metric Git can't support, and each report ends with a section on its own limitations. The most useful thing the report teaches is often what not to conclude.

Git can't see code reviews, pull request metadata, issues, deployments, test results, team structure, or actual working hours. A commit timestamp shows when someone committed, not when they worked. Within what Git can see, these are the traps I watch for:

  • Identities aren't people. Authors are counted by email address. One developer with a work and a personal email counts as two, and bots such as Dependabot or a docs workflow count too. On the git-spark repo, "5 contributors" is really me under three email identities plus two bots. The reported bus factor of 20% (1 of 5 identities) overstates the team. The real bus factor is 1.
  • Bus factor is about churn. git-spark's bus factor is the smallest number of author identities that together account for half of all lines changed. One large generated-file commit can skew it.
  • Line counts include noise. Lockfiles, generated reports, and docs inflate churn. --exclude-extensions keeps the focus on code.
  • Merge style hides history. Squash merges collapse a pull request into one commit, so commit counts understate how much review and iteration happened.
  • Shallow clones hide history. A CI checkout without fetch-depth: 0 produces a near-empty report.

Two traps in 2.0.2 are my own bugs, and both are already fixed on main for the next release. --path takes a directory, so --path src/core works but --path "src/**" fails validation. And --branch combined with --path analyzes the current branch instead of the one you asked for, so run those two separately until the fix ships.

That bus factor shows the whole problem in one number: correct for what it counted, and still wrong about my project. That gap is why I treat the report as a starting point for questions. It's well suited to onboarding, retrospectives, and spotting risky hotspots. It's poorly suited to ranking or reviewing individual people, a point I made at more length with the Engineering Zoo.

Recipes for common questions

Each recipe is one command, ready to paste from the root of the repository. Values like the dates, path, branch, and email are examples to swap for your own.

I just joined this repo. What matters here?

bash
git-spark html --days 180 --open

Six months is long enough to see the hotspots and the regular contributors, and short enough that the picture is still current.

Is this project alive, and who keeps it running?

bash
git-spark health

The last 30 days in one box: activity, risk level, and bus factor. Read the bus factor alongside the identity trap above before drawing conclusions about the team.

How did this sprint compare with the last three?

bash
git-spark periods --period-days 14 --periods 4

Four two-week windows side by side, newest last. Change 14 to your sprint length.

Which files keep changing, ignoring docs and lockfiles?

bash
git-spark --days 90 --format console --exclude-extensions .md,.json

Terminal tables for the last quarter with Markdown and JSON left out, so the hotspot list shows code churn instead of documentation edits.

What changed in one area last quarter?

bash
git-spark html --since 2026-07-01 --until 2026-09-30 --path src/core

A fixed date range limited to one directory. In 2.0.2, give --path a directory, not a ** glob.

What has one person been working on?

bash
git-spark html --days 60 --author [email protected]

Matches name or email the way git log --author does. If someone commits under several emails, run it once per identity.

What happened on the release branch?

bash
git-spark html --branch release/2.x --days 30

Analyzes the branch without checking it out. In 2.0.2, leave --path off when you use --branch.

I want a report to share outside the team.

bash
git-spark --days 90 --format html --redact-emails --teamwork --open

Email addresses hidden and the per-person sections removed, leaving the team-level view.

I need the raw numbers for my own dashboard.

bash
git-spark --days 30 --format json --output ./data

The full report object as JSON, the same shape the library's analyze() returns.

I want a sprint summary for the retro doc.

bash
git-spark periods --period-days 14 --periods 2 --output-format markdown --output ./reports

This sprint against the last one, as a Markdown table ready to paste into the retro notes.

Try it on two repos

Pick one repository you know well and one you don't, and run git-spark html --days 180 --open on each. On the familiar one, check whether the hotspots and patterns match what you know. That's how you learn which numbers to trust. On the unfamiliar one, you'll have a map of where the activity is within a minute. Where the two disagree with your expectations is usually where the history has something to teach.

The git-spark site has the full documentation, and the source and issue tracker are on GitHub. This article reflects git-spark 2.0.2.

Explore More

Working through something similar?

If this maps to something you're working on, I'm glad to compare notes. Start with the system and the constraint that matters most.