Appearance
Churn
This lens answers: where does change concentrate, and how does each file change? It ranks files and packages at once, because they pull apart: a package can have a lot of changes spread thinly over many files, or a few files changed over and over.
Its biggest limit is that it counts commits, not effort or trouble. A one-line typo fix and a 1,000-line refactor each count as one commit, and a file that changes a lot may simply be where the work is. Churn says where to look, not what's wrong there.
Reading the numbers
| What you see | What it means |
|---|---|
| A dot | One file, placed across by its commits in the analyzed period, on a log scale. The small sideways spread and the up-and-down position within a row carry no meaning: they keep files with equal counts from landing on one spot. |
| A dot's color and size | Its churn category, or small and grey if it has one or two commits. |
| "one or two commits" | The grey band at the left. These files are drawn grey whatever their category. |
| A row, such as "services/billing/ 112" | One package and its total changes. Each row names its busiest file, and its shading follows the total. |
| "112 changes across 7 files" | Changes are per file: a commit touching three files is three changes, so this isn't a count of commits. |
| "1 with one or two commits" | How many of the row's files sit in the grey band. |
| "+4 more packages in the table (T)" | Up to 12 packages are drawn, those with the most changes. The rest are in the table. |
| "16 changes per file in services/billing/, across 7 files" | The inspector's big number: the package with the most changes per file, among packages with 5 or more files. If no package has 5 files, it shows the package with the most changes. |
| "+400 −320 lines" | Lines added and deleted in the analyzed period. These count everyone's commits, bots included, and a file's first commit counts as lines added. |
| growing, shrinking, tweaking, rewriting | The file's character: how its lines change. No tag means no line counts, as with a binary file. |
| "4 files change commit for commit (…): one change, made 4 times." | The biggest lockstep group. It usually means one edit is being repeated by hand. |
| "26 commits · 20 in the recent half" | Rhythm's tooltip: the file's commits by people and AI agents, then how many commits to it fell right of the line down the middle. The second number includes bots, so it can be the larger one. |
| Rewrite Ratio 0.92 | A row on the file card: the smaller of lines added and deleted, divided by the larger. Near 1 means balanced. It shows for any file with line counts, even one line added and one deleted, so on its own it isn't a verdict. See Rewrite score. |
| Churn Trend accelerating | A row on the file card, plus a badge when accelerating: most of the file's commits fall in the recent half. Only files with 8 or more commits have one. See Velocity. |
| "5 commits, under the 8 a verdict needs; widen the window (--since all) for more" | The Sample row. It counts people's commits only, so it can sit beside a trend or a rewriting tag: see the TypeScript example. The advice to widen appears whenever the run has a time limit, which is the default, even if there's no older history to find. |
| "45 commits, top file" | The lens's reading on the Code Health card: the most-changed file's commits. That file can be a test, which the swarm doesn't draw. |
| File changes, on a selected package's card | Changes to every file in the package, tests and fixtures included, so it can be higher than the row's number. |
Churn categories
Each file gets a churn score: its commits as a share of the most-changed file's commits, rounded, so the top file is 100.
| Category | Score |
|---|---|
| Hot | 76–100 |
| Warm | 41–75 |
| Cold | 11–40 |
| Frozen | 0–10 |
The categories are relative to the repository, and they say nothing about how much is a lot. In a quiet project, 5 commits can be hot. The top file also doesn't have to be one the swarm draws: a test or fixture can set the 100, leaving no drawn file hot.
Four example repositories
These repositories are invented, but each result is what GitRelic reports for commits like these.
A Python platform where the busiest package isn't the hardest hit
services/ingest/ has the most changes (165 changes across 42 files, 3.9 each); services/billing/ churns hardest per file (112 changes across 7 files, 16 each).
4 files change commit for commit (rates_ca.py, rates_eu.py and 2 more): one change, made 4 times.
What it means: the two packages have similar totals and opposite shapes. services/ingest/ is a wide, low cloud: no file has more than 6 commits, which is what steady work across a package looks like. services/billing/ is a few dots far to the right, and the second line says why. Four rate files have 22 commits each, every one of them shared, so 88 of the package's 112 changes are the same edit made four times.
What to look at: select rates_us.py. Its card says "Coupled With: rates_ca.py (22 of 22 commits)", and What to do says "Change it with rates_ca.py open." The better question is whether four files need to exist.
A TypeScript web app with every character
Hovering the dots in its one row (src/, 53 changes):
| File | Commits | Lines | Character |
|---|---|---|---|
form.tsx | 14 commits | +840 −770 | rewriting |
client.ts | 12 commits | +480 −24 | growing |
format.ts | 10 commits | +50 −30 | tweaking |
compat.ts | 9 commits | +9 −360 | shrinking |
strings.ts | 5 commits | +100 −100 | rewriting |
rules.ts | 3 commits | +390 −390 | tweaking |
What it means: form.tsx is the one to read first. Its lines keep being replaced, and What to do says so: "Settle the design first: code here doesn’t stick. 770 lines deleted for 840 added."
The last two rows look backwards, and each teaches something:
rules.tsmoved 780 lines and is only "tweaking". Three commits are under the 8 a rewrite score needs, so it can't be rewriting however balanced its lines are. Tweaking means "none of the others", not "small".strings.tshas 5 commits and is "rewriting". People made those 5, and a dependency bot made 4 more. The commits column counts people, while the rewrite score counts every commit, so 9 reach the floor. Its card shows both "Sample: 5 commits, under the 8 a verdict needs" and "Churn Trend: accelerating", and Rhythm's tooltip reads "5 commits · 9 in the recent half". Each number is true of different commits. Before acting on this file, check who's been changing it.
A Go service with one file speeding up
| File | In Rhythm | Trend facet in Hotspots |
|---|---|---|
queue.go | 26 commits · 20 in the recent half | accelerating · 20 of 26 recent |
retry.go | 13 commits · 2 in the recent half | decelerating · 2 of 13 recent |
pg.go | 10 commits · 6 in the recent half | stable · 6 of 10 recent |
What it means: queue.go's bars bunch up right of the line. It's also large, so What to do adds: "Split it before it grows further. 1,558 lines; 20 of 26 commits in the recent half." retry.go is the reverse: work that mostly stopped halfway through. It's also tagged rewriting, but that may be history by now, so check when those lines moved. pg.go, at exactly 60% recent, is the top of what still counts as stable.
Why no dot is hot: queue.go is warm with 26 commits, because queue_test.go has 45 and sets the scale. Tests aren't drawn in the swarm, so nothing in the picture looks hot, while the lens's reading on the Code Health card says "45 commits, top file". The order of the dots is still right. Trust their positions over their colors here.
A small Kotlin tool with one author
src/ leads on changes: 9 changes across 2 files, 4.5 each.
| File | Tooltip | Category |
|---|---|---|
src/Main.kt | 5 commits, +152 −12 lines, growing | Hot |
src/Parser.kt | 4 commits, +750 −450 lines, tweaking | Hot |
README.md | 3 commits, +38 −0 lines, growing | Warm |
What it means: "hot" here is only "near the top of this repository", and the top is 5 commits. Nothing reaches 8 commits, so no file has a rewrite score or a trend. Each card shows the Sample row instead: "5 commits, under the 8 a verdict needs; widen the window (--since all) for more". Rhythm still draws all three files, so the bars are there to read.
Two more things to notice. Parser.kt was created in this period, so its +750 includes the 300 lines of its first commit. And README.md is on the chart in the (root) row because documentation counts as source, while the build.gradle.kts changed alongside Parser.kt is plumbing and stays out.
What to look at: this project's whole history already fits in the period, so the suggested --since all won't add anything here. On a project this young, the commit counts are the whole story.
If no source file changed at all, as when a period's commits touched only tests and manifests, the swarm and table are empty and the inspector says "No source file changed in this window."
How it's measured
GitRelic reads the files and line counts of each commit in the analyzed period, on the analyzed branch. That's the last 12 months by default. Change it with --since, such as --since 2026-01-01, or use --since all for the whole history. Churn, the rewrite score and velocity all read this same period.
Each number counts different commits, because each asks something different:
| Number | Whose commits count | Needs |
|---|---|---|
| Commits, row totals, churn score and category | People and AI agents. Bots are left out first. | Nothing |
| Lines added and deleted, character | Everyone, bots included | Nothing |
| Rewrite score | Everyone, bots included | 8 commits |
| Velocity | Everyone, bots included | 8 commits |
| Rhythm's bars and "in the recent half" | Everyone, bots included | Nothing |
| Lockstep | Everyone, bots included. Commits touching more than 20 files are skipped. | 5 shared commits |
A commit count is about what people work on, so a weekly dependency bump shouldn't set the scale. Lines and pace are about the file, whoever moved it. See what counts as a bot. An AI agent's own commits count like a person's. The --json report gives the number of bot commits left out.
Always left out:
- Merge commits, since the commits on the merged branch already count.
- Files no longer in the analyzed commit. Deleted files don't appear, even if they changed often.
- Noise: images, video, PDFs, fonts, WebAssembly, minified files and source maps;
dist/,coverage/,.next/and.claude/at the top level; and a few named files such as lockfiles andCONTRIBUTING.md. - Project plumbing: package manifests, lockfiles, changelogs, licenses, and CI and tool configuration (
package.json,Cargo.toml,go.mod,CHANGELOG.md,.github/,tsconfig.json,vite.config.ts). A release commit bumps these all at once.--include-fixturesdoesn't bring them back.DockerfileandMakefilearen't plumbing, because people write those.
Counted, but not drawn. Tests, fixtures and generated code have churn scores and can set the top of the scale, but the swarm, Rhythm, the findings and the table show source files only. Source means anything not sorted into another group, documentation included.
- Tests: files in
__tests__/,tests/,Tests/,*.Tests/,src/test/orcypress/, and names likefoo.test.ts,foo.spec.ts,foo.test-d.ts,handler_test.go,user_spec.rb,test_foo.py,conftest.py,FooTest.javaorBarTests.cs. - Fixtures: files in
__fixtures__/,fixtures/,fixture/,testdata/,__snapshots__/or__mocks__/, and.snapfiles. - Generated: files in
__generated__/,vendor/orthird_party/, and names likefoo.generated.ts,foo.pb.go,foo_pb2.pyorfoo.g.dart.
A folder called test/ or spec/ counts as tests at the repository's root or a package's root. Deeper, as in lib/test/, its files are source unless their names match.
Packages are the repository's own declared workspaces, else packages/*, apps/*, libs/* or services/*, else the top-level folder. Files at the root share a (root) row. Swarm labels drop a leading packages/.
Renames. A file's count starts at the commit that renamed it, and that commit counts. Earlier commits belong to the old path, which no longer exists, so they don't appear. A file changed 6 times, renamed, and changed 3 more times shows 4 commits. The file card has a Renames row when this has happened.
Character
Character sorts a file by its lines added and deleted in the analyzed period:
So tweaking covers everything left over: lines that are fairly balanced, without a score of 70. That includes small edits, and also any balanced file under the 8-commit floor, however many lines it moved. A file with +150 −120 over 6 commits is tweaking, while the same lines over 10 commits score 80 and are rewriting.
Lockstep
Lockstep finds files that change commit for commit. Two source files are a pair when they share at least 5 commits, and those shared commits are at least 90% of both files' commits. Pairs that overlap join into a group, and a group needs 3 or more files. The inspector names the biggest group. Rhythm marks every group with at least two of its files on screen.
Rewrite score
The rewrite score is a 0–100 measure of whether a file's lines keep being replaced, rather than mostly being added or mostly being removed. High means code that doesn't stick. It has no picture of its own, and the dashboard never prints the number. You see its effects, listed below.
It starts from the file's total lines added and deleted in the analyzed period:
ratio = smaller total ÷ larger total, to two decimals
confidence = smaller total ÷ 30, at most 1
score = ratio × 100 × confidence, roundedThe ratio is the balance. Confidence holds a file down until at least 30 lines have moved on its smaller side, so that a few one-line edits can't score 100.
| File | Commits | Added | Deleted | Ratio | Score | Character |
|---|---|---|---|---|---|---|
checkout.tsx | 14 | 840 | 770 | 0.92 | 92 | rewriting |
rates.py | 10 | 90 | 70 | 0.78 | 78 | rewriting |
dashboard.php | 10 | 300 | 200 | 0.67 | 67 | tweaking |
flags.rb | 10 | 10 | 10 | 1.00 | 33 | tweaking |
seed.sql | 10 | 800 | 50 | 0.06 | 6 | growing |
rules.ts | 3 | 390 | 390 | 1.00 | none | tweaking |
The scale has one line, at 70. A score of 70 or more counts as high, and there are no other tiers. Below it nothing is flagged, so 67 and 6 get the same silence, though their ratios and lines still differ.
The commit floor is 8 commits in the analyzed period, counting every commit to the file, bots included. Under it there's no score at all, while the line counts and the ratio stay. One large rewrite is a rewrite and not a pattern, and one version bump is a perfectly balanced change of one line. Fix rate and other per-file verdicts share the number. Because this one counts bots and some others don't, a file can have a score and still be under the floor for ownership.
Where it shows:
- The character tag: a score of 70 or more is rewriting, in the swarm's tooltip, in Rhythm and in the table.
- The Rewrite ratio facet in Hotspots: it appears only on files with a score, as "0.92 · 770 deleted, 840 added", and is drawn in the accent at 70 or more. The number is the ratio, not the score.
- The file card's Rewrite Ratio row: the ratio, for any file with line counts, with or without a score. A ratio of 1.00 can come from one line added and one deleted, so check the lines before reading much into it. The row opens this lens.
- What to do: at 70 or more, "Settle the design first: code here doesn’t stick." It's the last rule in the list, and the card shows at most three actions, so a file with other problems may not get to it.
- The
--jsonreport holds the score itself, and a summary such as "1 of 5 files with 8+ commits has a high rewrite ratio (code that doesn't stick)", or "No file has the 8+ commits a rewrite ratio needs".
How to read it: rewriting is a reason to read the file's commit history, where you'll see whether the same lines kept moving. If they did, the design probably hasn't settled, and a refactor or a conversation will do more than another edit.
Velocity
Velocity asks whether a file's commits fall mostly in the recent half of the analyzed period. It has no picture of its own, and its score isn't printed. Churn's Rhythm form shows the same idea as bars.
GitRelic finds the moment halfway between the first and last commit it read, across the whole repository, and takes the share of each file's commits after it:
| Share in the recent half | Trend |
|---|---|
| Over 60% | accelerating |
| 40–60% | stable |
| Under 40% | decelerating |
A file needs 8 or more commits in the analyzed period, bots included. Under that it has no trend, since 3 commits that all land late read as 100% and mean nothing. Tests and generated files get a trend too, but plumbing doesn't.
Where it shows:
- The file card: a Churn Trend row for any rated file, and an "accelerating" badge.
- The Trend facet in Hotspots: "accelerating · 20 of 26 recent", drawn in the accent when accelerating.
- Risk: an "accelerating" mark beside a file's bar. It adds nothing to the score.
- What to do: an accelerating file of 1,000 lines or more gets "Split it before it grows further."
- The
--jsonreport holds the score, and a summary such as "1 file accelerating, 1 decelerating", or "No file has the 8+ commits a trend needs".
How to read it: the halves are of the commits' span, not of the calendar. If a repository's first commit in the period was 3 months ago, the line is about 6 weeks ago. And it's about timing rather than rate: a file created after the halfway point, with 8 commits since, reads as accelerating because it has no older half. Check the file's first commit before reading much into it.
Rhythm may not agree exactly. Rhythm splits by whole weeks or months and velocity at an exact moment, so "in the recent half" can differ by a commit or two near the line. Rhythm also draws files under the floor, which have no trend.
In the dashboard
Find this lens under Code Health.
- The swarm is the main picture. Each package is a row, those with the most changes first, and each source file is a dot in its row, placed by commits on a log scale. Hover a dot for its commits, lines and character, or a row for its total, its file count and its files with one or two commits. Click a row to select the package, or a dot to select the file.
- Rhythm (the corner toggle) shows the 16 source files with the most commits, one row each, as their commits week by week. Past two years of history, the bars are months. It needs the commit history, so it draws once that has loaded.
- The line down the middle splits the bars in half. Most bars right of it means speeding up, and most left of it means slowing down. The bars run from the first commit in the period to the last.
- To the right of the bars, lines deleted grow left from an axis and lines added grow right, on a square-root scale, followed by the file's character.
- Linked rings in the left margin mark lockstep files, with a group's rings joined by a line.
- Hover a row for its commits, the recent half, its lines and its character, or a bar for that week's or month's commits. Click a file's dot to select it. Clicking elsewhere on a row selects nothing.
- The time strip under the picture shows commits week by week, and a selection's when there is one. Rhythm's weeks line up with it.
- The inspector, with nothing selected, leads with the changes-per-file number, then the findings quoted above, then the five busiest packages. A selected file's card adds the rows described in Rewrite score and Velocity, and its What to do.
- The table (
T) lists every source file: commits, lines added, lines deleted, character and package, most commits first. Its tiers are the churn categories: Frozen, Cold, Warm and Hot.
What it can't tell you
- How much a commit changed, or why. A one-line fix and a large refactor each add one commit. A reformat touching 300 files adds one to every one of them. The line counts help, but they're totals for the whole period.
- Whether change is bad. A busy file may be the product's best-loved feature. Pair this with Fix rate to see whether the changes hold.
- What the lines meant. The rewrite score sees line counts. Renaming something throughout a file adds and deletes the same number of lines and scores like a rewrite, with no logic changed. A file that gained 100 lines and lost 100 unrelated ones scores the same as one whose new lines were replaced.
- The history behind a rename. Commits before a rename aren't counted for the file, so a recently renamed file looks quieter than it is.
- Anything about deleted code. A file that churned badly and was then removed doesn't appear.
- How one repository compares to another. Churn scores are relative to each repository's top file.
- About bots it doesn't recognize. Bots are recognized by email address, so one that isn't on the list counts as a person and can set the scale.
- Much about a short period. Fewer commits mean fewer files reach the floor. Use at least a few months of history when the rewrite score is the question.
Related
- Hotspots combines commits with size, for files that are both busy and big. A selected file's facets include its trend and rewrite ratio.
- Risk uses Churn's commit counts, on its own scale: the busiest file it rates scores 100, so a busy test or data file doesn't lower its scores. Over 40 earns 15 points, rising evenly to 35 at 100. Its 20 most-changed rated files are among its candidates, and a file needs 8 commits by people to be scored. Its other points come from ownership or many authors, fix commits and parallel edits. It rates only source files that changed in the last 180 days, so a file can top Churn and be missing there. The rewrite score, velocity and coupling add no points.
- Fix rate asks whether a file's changes needed a fix soon after, and explains the shared 8-commit floor.
- Coupling covers files that change together, more broadly than lockstep's strict rule.
- Ownership asks who wrote the files that churn.
- Tests covers the test files this lens doesn't draw.
- Renames explains what a rename does to these numbers.