Skip to content

Hotspots ​

This lens answers: which files are both busy and big? A large file nobody touches costs little day to day, and a tiny file edited every week is cheap to edit. A file that is both is where reviews drag and regressions can hide, which makes it a good first place to look when you're deciding where to spend refactoring time.

Its biggest limit is that the score is relative. The top file in a repository scores 100 and everything else is scaled to it, so a quiet repository still has a "critical" file. Use the score to rank files within one repository. It doesn't say a file is bad, and it can't be compared between repositories.

Reading the numbers ​

What you seeWhat it means
A score from 0 to 100How a file's commits and lines combine, relative to the top file in this repository. See How it's measured.
Critical, Warning, Moderate, LowThe score's tiers: 75 or more, 50–74, 25–49 and under 25. They're positions in this repository's ranking, not verdicts.
"1 critical, 3 warning, of 88 scored files"The headline. Scored files are the ones that changed in the analyzed period and still exist, not every file in the repository.
"ledger.py is the hottest file: 48 commits across 6,432 lines."The top file and the two numbers behind its score.
"Two kinds of heat: 4 large files that keep changing, and 1 under 300 lines hot on churn alone, like flags.py (44 commits, 224 lines)."Among files scoring 25 or more, some have 1,000 lines or more and some have under 300. The small ones call for a different question: why do they change so often? The line appears only when both kinds exist.
"services/payments/: 7 of its 15 files score 25 or more; services/legacy/ has 1 of 61."The package with the largest share of its own files at 25 or more, which needs at least 3 such files and a share of at least 20%. The biggest package is added for contrast when its share is under a quarter of that. Files at the repository's root are left out of this line.
The curves marked 25, 50 and 75Every point on a curve has the same score. They bend because a bigger file needs fewer commits to reach that score. A file past the 75 curve is critical.
Shaded cells, "N files scoring under 25"Files drawn as density rather than dots. The tooltip gives their range of commits and lines.
"15 files · 7 at 25+"A package's heading in By package: its scored files, and how many score 25 or more.
"No file scores 25 or more: nothing here is both busy and big."Nothing cleared the lowest tier, and there are no findings. In practice, the files that changed have one line each.

A selected file's facets ​

Select a file in the field and it fans out its facets. Each one is a different reading of the same file. A facet in the accent color is worth a second look. Being in the accent says nothing about the file's score: a big file that barely changes is still hot on Size.

FacetExampleWhat it meansIn the accent when
Churn"48 commits · 25% of all"Commits to the file by people and AI agents. The share is out of all commits in the analyzed period, bots included.Never
Size"6,432 lines"Lines in the analyzed commit.1,000 lines or more
Owners"2 people · Ana Ruiz 94%"How many people committed to it, and the top author's share of those commits.With 8 or more commits: one author, or a top author at 90% or more
Changes with"ledger_types.py · 36×"The file it shares the most commits with. A partner needs at least 3 shared commits, making up at least 30% of the rarer file's commits. Commits touching more than 20 files don't count.That partner shares at least 50% of the rarer file's commits
Trend"accelerating · 34 of 48 recent"How many of its commits fall in the recent half of the analyzed period, measured from the period's first commit to its last: accelerating above 60%, decelerating below 40%, otherwise stable. Needs 8 commits.Accelerating
Blast radius"2 files per change"The median number of other files changed in the same commit. Needs 8 commits, not counting commits touching more than 20 files.10 or more
Rewrite ratio"0.78 · 1,488 deleted, 1,920 added"A ratio from 0 to 1: the smaller of lines added and deleted, divided by the larger. Near 1, what gets added is about as much as what gets removed. Needs 8 commits.Its rewrite score is 70 or more (see below)
Root causes"changes with 2 risky files" or "reached by 1 hub"Its place in Risk's Root causes. A hub is a source file that keeps changing with risky files; a risky file is cursed or a near miss. Other files have no such facet.The count is 2 or more
Last touched"today"Days since its last commit, counted back from the newest analyzed commit, not from the day you ran GitRelic. "Today" means the same day as that commit.Never
Sample"7 commits, under the 8 a verdict needs"Appears when the file has under 8 commits by people, and explains why other facets are missing or not hot.Never

The rewrite ratio and the rewrite score are on different scales. The fan prints the ratio, from 0 to 1. The accent comes from the score, from 0 to 100: the ratio times 100, scaled down when the smaller side is under 30 lines. So a ratio of 0.78 with plenty of lines is a score of 78 and hot, and any ratio under 0.70 can never be hot. A high ratio on few lines isn't hot either: "1.00 · 8 deleted, 8 added" scores 27.

A missing facet means something too. A facet appears only when its analyzer reports the file:

  • Under 8 commits: Trend, Rewrite ratio and Blast radius are absent, Owners never reaches the accent, and Sample says why. The tooltip adds "widen the window (--since all) for more" unless you're already analyzing all of history.
  • Sample and the others can appear together. Sample counts commits by people. Trend, Rewrite ratio and Blast radius count every commit, bots included. A file with 5 commits by people and 3 by a release bot shows "5 commits, under the 8 a verdict needs" beside "accelerating · 7 of 8 recent".
  • Test fixtures, snapshots and generated code have a score but no Owners, Changes with, Blast radius or Sample, unless you run with --include-fixtures.

Three example repositories ​

These repositories are invented, but each result is what GitRelic reports for commits like these.

A Python service with a file that does too much ​

1 critical, 3 warning, of 88 scored files

ledger.py is the hottest file: 48 commits across 6,432 lines.

Two kinds of heat: 4 large files that keep changing, and 1 under 300 lines hot on churn alone, like flags.py (44 commits, 224 lines).

services/payments/: 7 of its 15 files score 25 or more; services/legacy/ has 1 of 61.

ledger.py fans out like this:

FacetReadingIn the accent
Churn48 commits · 25% of all
Size6,432 linesyes
Owners2 people · Ana Ruiz 94%yes
Changes withledger_types.py · 36×yes
Trendaccelerating · 34 of 48 recentyes
Blast radius2 files per change
Rewrite ratio0.78 · 1,488 deleted, 1,920 addedyes
Root causesreached by 1 hub
Last touchedtoday

What it means: this is the classic hotspot. It's large, it's picking up speed, nearly all of it is written by one person, and much of what gets added is later removed. Its score is 100 because it's the top file, but the facets are what make it worth acting on. flags.py scores 57 with only 224 lines, because it changed nearly as often. None of its facets are in the accent, so it's a smaller concern.

The last finding says the heat is concentrated: services/legacy/ has four times as many scored files, but nearly all of them were changed once by a single sweeping commit.

What to look at: the file card's What to do says "Split it before it grows further." (6,432 lines; 34 of 48 commits in the recent half) and "Change it with ledger_types.py open." The files it changes with (Coupling) are a good map of where to split it.

A Go service that is hot on churn alone ​

3 critical, 1 warning, of 9 scored files

flags.go is the hottest file: 70 commits across 140 lines.

Two kinds of heat: 1 large file that keeps changing, and 3 under 300 lines hot on churn alone, like flags.go (70 commits, 140 lines).

internal/: 3 of its 6 files score 25 or more.

ScoreFileCommits × lines
100internal/flags/flags.go70 × 140
90internal/flags/flags_prod.go65 × 120
90internal/flags/flags_staging.go65 × 120
58cmd/report/testdata/golden.json25 × 3,050
46cmd/report/report.go25 × 537
24cmd/server/main.go12 × 948
22internal/store/store.go10 × 2,750

What it means: the critical files are small. Size isn't why they're here: each one changed in over 40% of all commits, and the three of them move together. Selecting flags.go shows "Changes with: flags_prod.go · 65×" in the accent. A hand-edited fork moving in lockstep is one change made several times.

The one large file with a warning score is golden.json, a test fixture, and it's scored like any other file. It has no Owners or Changes with facet, because fixtures are left out of those. store.go has nearly the same size but only 10 commits, so it scores 22. Its Size facet is still in the accent: it's big, just not a hotspot today.

What to look at: ask why the flag files change so often. If a generator could produce the forks, there's one change to make instead of three. Don't spend time on golden.json unless the churn itself is the problem.

A small Rust crate ​

1 critical, 1 warning, of 4 scored files

lib.rs is the hottest file: 7 commits across 390 lines.

FacetReading on src/lib.rs
Churn7 commits · 64% of all
Size390 lines
Owners2 people · Ana Ruiz 86%
Last touched38 days ago
Sample7 commits, under the 8 a verdict needs

What it means: in a repository with 11 commits, the top file is still critical and still scores 100. The score has no minimum number of commits, because it's only a ranking. It's the facets that hold back: no Trend, no Rewrite ratio, no Blast radius, and Sample says why. parser.rs is "warning" on 4 commits, and that's not a warning about anything.

What to look at: the ranking still tells you which file gets the most attention. Don't read any urgency into the tier. If the crate has older history, --since all gives the facets more to work with.

How it's measured ​

The idea comes from Adam Tornhill's Your Code as a Crime Scene: how often a file changes shows where people work, and its size is a cheap stand-in for complexity.

  1. Churn score. A file's commits as a share of the most-changed file's commits, out of 100 (Churn).
  2. Size. Lines in the analyzed commit. Every line counts, including blanks and comments.
  3. Combine. Multiply the churn score by log₂ of the lines. The logarithm keeps size from swamping churn: 100 lines is 6.6, 1,000 is 10 and 10,000 is 13.3. Doubling a file's commits doubles its raw score, while doubling its lines adds one to the multiplier.
  4. Scale. Divide by the highest result in the repository and round, so the top file scores 100.

Here's how that works for the Python service above:

FileCommitsChurn scoreLineslog₂(lines)RawScore
ledger.py481006,43212.651,265100
flags.py44922247.8171857
api.py30631,46010.5166252

The top file doesn't have to be the most-changed file, or the largest. It's whichever has the highest product.

What gets scored. A file gets a score if it changed in the analyzed period, which is the last 12 months by default, and still exists in the analyzed commit.

  • Left out of the commit counts: bot commits and merge commits. AI agents' commits count as work. A file only bots touched has no score.
  • Left out of the score: files deleted before the analyzed commit; manifests, lockfiles, changelogs, licenses, CI and tool configuration; and noise such as images and build output. --include-fixtures doesn't bring any of these back.
  • Scored like anything else: tests, docs, test fixtures, snapshots and generated code.

Files with one line. log₂ of 1 is 0, so a file with one line scores 0, however often it changes. So does an empty file, or a binary file GitRelic can't count lines in. A VERSION file bumped in 41 commits scores 0. In a repository with little else in it, a 501-line file changed twice can be the top file and score 100; beside a file with real activity, the same file scores about 6. If every file that changed scores like that, everything is 0, and the lens prints "No file scores 25 or more: nothing here is both busy and big."

Packages. A package is one of the repository's own declared workspaces, else packages/*, apps/*, libs/* or services/*, else the top-level folder. Files at the root gather in "(root files)".

In the dashboard ​

Find this lens under Code Health. A badge appears on the rail when at least 3 files, and at least 5% of scored files, are critical.

  • The field is the main picture: commits across, lines up, both on log scales. Files scoring 25 or more are dots colored by tier, up to 400 of them, and the rest are shaded cells. The top eight are named in a column beside the plot, each with its score. Up and to the right is hot on both counts, far right and low down is hot on churn alone, and high up on the left is large but quiet.
  • Selecting a file in the field slides the plot left, and the file travels out to fan its facets. A faint ring marks where it sits in the plot, and any other dot is still a click away. A selected file scoring under 25 is drawn as a dot too. Hover a facet for what it means.
  • By package (the corner toggle) has one circle per package, sized by its files, with each file a dot and the hottest at the center. It answers where heat concentrates: the same count of hot files means opposite things in a small package and a huge one. The ten largest packages are drawn, plus any smaller one with three or more files at 25 or more, or with a critical file. The rest stand together as one empty grey circle, "+N more packages", whose tooltip names them; their files are in the table. Click a circle to select its package, which outlines it. This form doesn't fan.
  • The time strip under the picture lights the weeks a selected file changed.
  • The inspector, with nothing selected, shows the headline, the findings, how files spread across the tiers (bars on a log scale), and the top five with their commits × lines. A selected file's card adds its score, a "critical hotspot" or "warning hotspot" chip, and up to three actions under What to do. Those include "Split it before it grows further." at 1,000 lines or more and accelerating, "Change it with … open." for a partner sharing 50% or more, and "Settle the design first: code here doesn't stick." at a rewrite score of 70 or more.
  • The table (T) lists every scored file, hottest first: file, score, commits, lines and package.

What it can't tell you ​

  • How complex a file is. Lines are a rough stand-in. A long table of constants scores as large as a long state machine.
  • How much changed. A one-line fix and a 1,000-line rewrite each count as one commit. The rewrite score looks at lines added and deleted instead.
  • Whether a commit was really about this file. A sweeping commit counts once for every file it touches, so a mass reformat adds a commit to each. Changes with and Blast radius skip commits touching more than 20 files, but the score doesn't.
  • How one repository compares with another. The top file is 100 everywhere, and a quiet repository still has a critical file.
  • The history of a renamed file. Commits under an old path don't count toward the new one, so a renamed file starts again. See Renames.
  • Whether the churn is a problem. A hot file may simply be where the current project is happening. A file's history can't say whether the changes were wanted, and neither can a score. Check Fix rate to see whether its changes keep needing fixes.
  • Churn — the commit counts behind the score, by file and by directory, and the rewrite score.
  • Risk — risk from several signals at once: how often a file changes, how concentrated its ownership is or how many authors it has, whether its changes keep needing fixes, and parallel edits. It doesn't count size, so a top hotspot can sit under the cursed line, and it rates only source files changed in the last 180 days, so a quiet hotspot isn't rated at all.
  • Coupling — what a hotspot changes together with, and how wide its changes usually run.
  • Ownership — who could maintain a hotspot if its top author left.
  • Fix rate — how often a file's changes need a fix, and the 8-commit floor that per-file verdicts share.

Released under the MIT License.