Skip to content

Coupling ​

This lens answers three questions from the commit history: which packages change together, what changes with a file, and how far does a change to a file usually reach? That last number is the file's blast radius.

Its biggest limit: it sees commits, not code. Two files are coupled when they change in the same commit, whether or not one depends on the other. And a real dependency that rarely changes never shows up. Read every link as "these change together," and open the files to learn why.

Reading the numbers ​

What you seeWhat it means
"crates/wire-client and crates/wire-server changed together in 14 commits (50% of crates/wire-server’s)"The strongest link between two packages, meaning the most shared commits. 14 commits changed at least one file in each. That's 50% of the commits of whichever package has fewer.
"most often decode.rs with encode.rs (14)"The pair of files most behind that link, and their shared commits. It's left out when no pair of files qualifies: a link can come from different files each time.
"3 files in 3 packages always change together"A family of files spread across packages. "Always" is stronger than the rule, which is 60% of the busier file's commits (see Families). The finding covers the largest such family only.
"None of 5 files usually change with 10 or more others, the widest decode.rs (1 per change)"How many files with a blast radius have one of 10 or more, and which is widest. The count on the inspector's card is the same number.
"1 more has under 8 commits to say"Files changed in the analyzed period with too few commits for a blast radius. Files with no counted commits in the period aren't in this number.
"widen the window (--since all) for more"The report covers part of the history, the last 12 months by default, so more history may rate more files. It's not shown when the report already covers everything.
"3 links to root-level files or dot-folders (release bumps, CI config) are left off the ring"Links involving the repository root or a folder starting with a dot aren't drawn. Despite the wording, manifests, changelogs and CI configuration are already out of every count here, so these links come from other files, such as a root README.md.
A package's "2 links · 42 commits"Chords drawn to it, and the commits that changed at least one of its counted files.
A partner's "14 shared · 20 own"In a file's ripple: commits it shares with the selected file, and the partner's own commits.
"14 of the 24 commits that changed decode.rs changed it too (58%)"A partner's tooltip. The percentage is out of the selected file's commits, and decides how close the partner sits.
"encode.rs (14 of 24 commits)"The Coupled With row on a file's card: its partner with the most shared commits, out of the selected file's commits. When partners tie, it can name a different file from Changes with.
"14× · 70%"The Changes with section on a file's card: shared commits, and their share of the quieter file's commits. It can differ from the 58% above because it divides by a different file (see the same pair, two percentages).
"13 other files its commits usually change (the median of 10)"A file's blast radius, from its 10 counted commits.
"13 other files per change"The same number on the file's Flagged by row, shown as a warning from 10 up.
The table's "Files per change"The blast radius again. It counts the other files in a commit, so the file itself isn't included.

The table's tiers group files by blast radius: Under 3, 3–5, 6–9 and 10 or more. They describe how wide a change usually goes, and don't mean good or bad.

Four example repositories ​

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

A Rust workspace with a protocol split in two ​

crates/wire-client and crates/wire-server changed together in 14 commits (50% of crates/wire-server’s), most often decode.rs with encode.rs (14).

None of 5 files usually change with 10 or more others, the widest decode.rs (1 per change); 1 more has under 8 commits to say; widen the window (--since all) for more.

What it means: half of the server crate's commits also changed the client crate, all through one pair of files. No import is needed for this to show: one file encodes a message format and the other decodes it, so changing one means changing the other.

The second line looks like the opposite, but it answers a different question. Blast radius is about how many files a change reaches, and here it's only one. Coupling can be strong and narrow.

What to look at: select decode.rs. Its ripple shows encode.rs at "14 shared · 20 own," in the accent because it's in another package. The file card suggests "Change it with encode.rs open." A shared definition of the message format would be the usual way to cut this link, if it's worth cutting.

A Go repo with the same file in three services ​

services/billing and services/orders changed together in 9 commits (38% of services/billing’s), most often retry.go with retry.go (9).

3 files in 3 packages always change together (retry.go, retry.go and 1 more): one change, made in 3 places.

None of 5 files usually change with 10 or more others, the widest retry.go (2 per change); 3 more have under 8 commits to say; widen the window (--since all) for more.

3 links to root-level files or dot-folders (release bumps, CI config) are left off the ring.

What it means: the second line is the find. Each retry.go has 12 commits and shares 9 with each of the others, so "always" here means 75%. In the other 3 commits, one service's copy changed alone: either a real difference between services, or a fix that never reached the others.

The first line names billing and orders, but billing and shipping also share 9 commits, and that's 75% of shipping's. When links tie on commits, the finding just takes the first by name, so check the brightest chord too.

What to look at: the commits where a copy changed alone. Findings and chords use file names only, so hover a partner in a file's ripple for its full path. The last line comes from a root README.md, a .golangci.yml and a .deploy folder here, not from releases.

A Python app where a few files pull in many ​

2 of 4 files usually change with 10 or more others, the widest base.py (13 per change); 13 more have under 8 commits to say; widen the window (--since all) for more.

The ring holds one dot and the message "One package: no change crosses a boundary."

What it means: all the code is under app/, and nothing declares a workspace, so GitRelic sees one package. The ring has nothing to say, and blast radius has a lot. Selecting settings.py shows "13 other files its commits usually change (the median of 10)," and its bars have two humps: 3 commits changed it alone, and 7 changed it along with 13 others.

A 150-file reformat also happened in this history. It isn't in any of these numbers, because a commit that touches more than 20 counted files is left out.

What to look at: the 7 wide commits, not the median alone. A file that's edited alone 3 times in 10 can be changed in isolation, so ask what makes the other 7 wide. The file's partners, in its ripple, are the place to start.

A young TypeScript repo ​

No file has the 8 commits a blast radius needs; widen the window (--since all) for more.

The ring holds its packages and the message "No two packages changed together 3 or more times."

What it means: not enough history to say anything, which isn't the same as no coupling. The two packages shared 2 commits, one short of a link. If the whole repository is younger than the analyzed period, widening it changes nothing. With --since all the finding reads "No file has the 8 commits a blast radius needs." with no suggestion.

How it's measured ​

GitRelic reads the commits of the analyzed branch in the analyzed period, the last 12 months by default (--since changes it, and --since all means the whole history). Each commit goes through the same steps:

Counted files are the ones that:

  • Exist in the analyzed commit. Files deleted since don't count, and neither does a file's old path after a rename.
  • Aren't project plumbing: manifests and lockfiles (package.json, Cargo.lock, go.sum), changelogs and licenses, CI and tool configuration. A release commit bumping every package.json isn't coupling. Nothing brings these back.
  • Aren't fixtures or generated: snapshots, fixtures/ and testdata/ folders, vendor/, *.min.js, *.pb.go. --include-fixtures brings these back.

Tests count, and so do docs. Everyone's commits count too, including bots.

The 20-file line applies after that filter. A commit changing 20 source files and 6 lockfiles and changelogs is counted. A commit changing 21 source files isn't. Such a commit is usually a reformat or a mass rename, and would tie everything to everything. Fix rate and Parallel Dev draw the same line.

Because of these rules, a file's commit count here can be lower than on other lenses.

File pairs and families ​

A pair is two files that share at least 3 commits, where those are at least 30% of the quieter file's commits. A pair's strength is that percentage.

The same pair, two percentages. Say decode.rs has 24 commits, encode.rs has 20, and they share 14:

WhereNumberDivides by
Changes with on the file card70%The quieter file (14 of 20)
Tooltip with decode.rs selected58%The selected file (14 of 24)
Tooltip with encode.rs selected70%The selected file (14 of 20)

Strength can flatter a file that rides along. A file with 3 commits, all shared with a file that has 50, is a pair at 100%. Selected on the busy file's ripple, that partner reads 6% and sits far out.

A family is stricter, and looks at the busier file, so riding along doesn't qualify: at least 4 shared commits, and at least 60% of the busier file's commits. Pairs that pass are joined into groups, so A with B and B with C makes one family of three even if A and C alone wouldn't pass. Families only appear as a finding, for the largest one spanning two or more packages, none of them the root or a dot-folder. Its names show the first two files alphabetically.

A file's package is one of the repository's own declared workspaces (pnpm-workspace.yaml, package.json workspaces, lerna.json, Cargo.toml, go.work or Nx), the deepest that contains it. Otherwise it's packages/*, apps/*, libs/* or services/*, and otherwise the top-level folder. Files directly in the root belong to the root.

A commit counts once for each package it changed. A link is two packages with at least 3 shared commits, and its share is those commits out of the commits of whichever package has fewer. A link doesn't need a qualifying pair of files. When there isn't one, the chord's tooltip says "no single pair of files changes together strongly enough to list (3 shared commits, 30% of the quieter file’s)."

Blast radius ​

A file's blast radius is the number of other files its commits usually change. A blast radius of 12 means that in a typical commit to this file, 12 other files changed too. It's counted in files, so 12 means the same on any repository.

To work it out, GitRelic takes each of the file's counted commits and notes how many other counted files changed in it. The blast radius is the median of those numbers, and with an even count it takes the upper of the two middle values.

  • Why a median. An average lets one wide commit decide the number. A median isn't moved by a single wide commit.
  • A file needs 8 commits. Under that, it gets no blast radius and counts toward "under 8 commits to say." Fix rate explains where the 8 comes from. Only counted commits reach it, and bots' commits count, so a file can be rated here and not on Ownership, which counts people's commits, or the other way round, because Ownership keeps commits this lens leaves out as too wide.
  • It tops out at 19. A counted commit has at most 20 files, so at most 19 others. The last bar in a file's chart, labeled "19+," is exactly 19.
  • The bars matter as much as the median. A file's chart shows its commits by how many other files each changed, with a line at the median. One hump means it behaves the same each time. Two mean it has two kinds of change, which the median hides, as in the Python example above.
  • High isn't automatically bad. A wide file costs coordination, and a regression there can reach far. But a registry that lists every feature is wide by design, and a test file that always changes with its source adds 1 to the source's count.

Blast radius counts how many files, not which. A file that changes with three different files each time has the same number as one that changes with the same three. The file's partners, in its ripple, say which ones recur.

In the dashboard ​

Find this lens under Ownership & Knowledge. On the Repo map, its line counts the chords, such as "2 package links."

  • The ring is the main picture. The busiest packages sit around it, up to 20, in name order, each sized by its commits, and a note says how many quieter ones aren't drawn. A chord between two packages is as wide as their shared commits, and brighter the bigger their share of the smaller package's commits. So thick and dim means a lot of shared commits between busy packages, and thin and bright means a small package tied closely to another. The root and dot-folders are left off, and links to a package not drawn are left off too. Hover a chord for up to four file pairs behind it, most shared commits first.
  • Selecting a package lights its chords, names the commits it shares with each partner ("14 commits with wire-client") and fans out up to eight of its files most tied to other packages. A fanned file's tooltip counts co-changes, such as "14 co-changes with 1 file in other packages." That's summed over file pairs, so one commit changing three files elsewhere counts three times. It reads only the pairs behind the chords, so it's a lower bound. When one workspace sits inside another, the outer package's fan can show the inner one's files instead of its own.
  • A file's ripple. Select a fanned file, or any file from search or another lens, and the ring fades behind it. The file sits in the middle with up to 16 partners around it, those with the most shared commits. A partner sits closer when more of the selected file's commits include it, and is bigger when it has more shared commits than the others. Partners in another package are in the accent color. A file with no partner says "No file changes with invoice.py strongly enough to draw." A file with no counted commits in the period has no ripple, so the ring stays.
  • The inspector, with nothing selected, leads with the count of files with a blast radius of 10 or more, a histogram of every rated file by blast radius with the wide end in the accent, the findings quoted above, and the widest five files. With a file selected, it adds:
    • a Blast radius section, with the number and the file's bars
    • Changes with, the top four partners
    • Blast Radius and Coupled With rows under Flagged by
    • possibly a What to do line, such as "Change it with encode.rs open," for a partner with 3 or more shared commits and a strength of 50% or more
  • The time strip under the picture shows all commits per week, and with a selection, the selection's. It counts every commit to the file or package, including wide ones left out above, so it can show more than the lens's count.
  • The table (T) lists every file with a blast radius, widest first: files per change, commits, the file it changes with most, and its package. Files under 8 commits aren't in it.

The ring can also show one of these messages instead of chords:

MessageWhy
"One package: no change crosses a boundary"Only one package is on the ring.
"No two packages changed together 3 or more times"There are packages, but no links.
"No package to draw: every change is to root-level files or dot-folders"Everything counted is outside the ring.
"This report has no package data"It says the report came from an older GitRelic, which is one cause, and running it again fixes that. The same message appears on a fresh run when no commit in the period had a counted file, for example if all of them changed only plumbing or more than 20 files. Widen the period if so.

What it can't tell you ​

  • Why two files change together. It might be a real dependency, one feature touching both, or a habit. The file pairs say where to look, not what you'll find.
  • Dependencies that don't change. A file everything imports but nobody edits has no partners and a low blast radius. This lens measures past edits, not what would break if you edited it.
  • About commits it leaves out. A large refactor over 20 files is invisible, even when it's the most telling change of the year. So is the coupling inside it.
  • Across different commit habits. A team that squashes each feature into one commit couples everything in it, up to the 20-file line, and past that the whole feature disappears. A team that commits file by file looks barely coupled. Compare repositories with care, and read a change in habits as a change in the numbers.
  • Across renames. A file's count starts at its current path, so its commits under an old name aren't counted, and neither are the pairs they formed. A recently renamed file can look quiet. See Renames.
  • About files since deleted. "Other files" means files that still exist. A commit that also touched ten files removed later counts ten fewer.
  • Hotspots — where change and size meet. Its file view shows the same Blast radius and Changes with numbers, marked from a blast radius of 10 or a strength of 50%.
  • Cursed Files — the Risk lens: files that stack several warning signs. Blast radius and coupling aren't part of its score, but its Root causes form uses the same file pairs to find what keeps changing with risky files.
  • Churn — its lockstep groups are a stricter version of a family: three or more source files changing commit for commit.
  • Parallel Dev — people editing the same files in the same week. Coupling is files changing in the same commit, whoever made it.
  • Ownership — how much of each package rests on one person, which matters more when its files reach far.
  • Renames — what a move does to a file's history, which this lens doesn't follow.

Released under the MIT License.