Appearance
Age
This lens answers: how much of the code has gone cold, where is it, and which of it does nobody still around know? It dates every file by its last change, however long ago that was, not just changes in the analyzed period.
Its biggest limit is that a change is any commit that touched the file. A formatting sweep, a license header or a bot's edit resets the clock as much as real work does, and a moved file looks as new as the move. So a low number can mean "recently swept," not "recently understood." Cold doesn't mean bad either: stable code stops changing. The lens only asks for a decision in the two cases described below, dormant packages and orphaned files.
Reading the numbers
| What you see | What it means |
|---|---|
| "60% of source lines unchanged for a year or more (5,471 of 9,181)" | The inspector's headline, and the heading of the Warm and cold form. It adds up every line of each source file, as the file stands now, blanks and comments too. Tests aren't counted here, even with the Tests switch on. |
| "76 files (5,471 lines) unchanged for a year or more; the median one has 71 lines." | How much is cold, and how thick it is. A small median means the cold is mostly small files. A large one means there are whole modules nobody has changed. |
| "services/fax-gateway/ has had no source change in 5.5 years (9 files): archive it, delete it, or say why it stays." | A dormant package: see Dormant packages. The time is since the newest change to any source file in it. |
| "38 cold files (2,173 lines) have nobody left who changed them, most in services/ledger/ and libs/money/." | Orphaned files: see Who counts as left. "Most in" names the one or two packages with the most orphaned lines, so it can read "most in app/" when there's only one package to name. If every orphaned file is empty, it names none. |
| "29 files changed this year after a year or more untouched, the longest Posting.kt after 5.8 years: check that whoever changed it knew it." | Woken files. "This year" means the 365 days before the analyzed commit, not the calendar year. It's a nudge and not a warning: GitRelic doesn't treat these changes as risky. |
| "3 fixture or generated files left out." | Files the lens never shows. Despite the wording, this count also includes project plumbing such as package.json, pyproject.toml or a LICENSE. |
| "Nothing is a year old: the oldest file, models.py, last changed 8 months ago." | Replaces the cold line when no source file is cold. It's common in a young repository, and it can also follow a sweep (see the Go example). |
| "Ages cover the analysis window only: the history before it couldn't be read, so files untouched in the window are missing." | The read of older history failed, often from a timeout on a huge repository. Everything else on the lens is then incomplete: see If older history can't be read. |
| "dormant · 5.5 years" | Under a package's name in Strata, at its total in Warm and cold, and in Coldest packages. |
| "3,450 cold lines", "3,450 cold · 902 orphaned" | A package's cold lines, and how many of those are in orphaned files. With the Tests switch on, these include test lines. |
| "nothing cold" | Every file in this package changed within the last year. |
| "Last changed 4.3 years ago · orphaned" | The row on a file's card under Flagged by, in the warning color when the file is orphaned. A woken file reads "3 months ago · woke after 8.3 years". |
| "1 dormant", "95% cold" | The Overview's reading for this lens: the dormant count if there are any, otherwise the cold share. It shows "—" with no source lines. |
| The badge on this lens | The number of dormant packages. One is enough to fire it. Old files alone never badge. |
The five bands. Each file falls in one, by days since its last change. The last three are cold.
| Band | Days since last change | Cold? |
|---|---|---|
| Under 3 months | under 90 | no |
| 3–12 months | 90–364 | no |
| 1–2 years | 365–729 | yes |
| 2–4 years | 730–1,459 | yes |
| 4+ years | 1,460 or more | yes |
The bands are fixed lengths of time, and they mean the same in every repository. They describe age, and don't grade it as good or bad.
How times are written. Under 60 days reads in days, under two years in months, and two years or more in years: "12 days," "13 months," "3.4 years." A file at 400 days is cold and reads "13 months."
Four example repositories
These repositories are invented, but each result is what GitRelic reports for commits like these. Each was run on a synthetic git history.
A young Python app
0% of source lines unchanged for a year or more (0 of 733)
Nothing is a year old: the oldest file, models.py, last changed 8 months ago.
1 fixture or generated file left out.
What it means: there's nothing to decide yet. The app is younger than a year, so nothing can be cold and nobody can be orphaned. The one file left out is pyproject.toml, which is plumbing despite the wording.
What to look at: nothing here. Come back when the repository has more history.
A Kotlin monorepo in middle age
60% of source lines unchanged for a year or more (5,471 of 9,181)
76 files (5,471 lines) unchanged for a year or more; the median one has 71 lines.
services/fax-gateway/ has had no source change in 5.5 years (9 files): archive it, delete it, or say why it stays.
38 cold files (2,173 lines) have nobody left who changed them, most in services/ledger/ and libs/money/.
29 files changed this year after a year or more untouched, the longest Posting.kt after 5.8 years: check that whoever changed it knew it.
3 fixture or generated files left out.
What it means: 60% isn't the problem, since a mature codebase is often mostly cold. The fax gateway is the decision here: no source change in 5.5 years, and everyone who changed it has gone quiet. services/ledger/ is the more interesting package. It has 3,450 cold lines and 902 orphaned, while also being worked on, so people are changing it next to code nobody around has touched.
What to look at: in Strata, a thick layer of dots far to the right in ledger means whole areas are cold, not a few leftovers. In the table, search ledger and read the Orphaned by column to see who could still be asked. Woken files aren't urgent, but 27 of the 29 here came from two large commits, so read them as two events.
A Rails app in one folder
95% of source lines unchanged for a year or more (6,105 of 6,407)
65 files (6,105 lines) unchanged for a year or more; the median one has 91 lines.
20 cold files (1,790 lines) have nobody left who changed them, most in app/.
What it means: this repo looks very cold, and nothing is dormant. There's one package, app/, because a package is a top-level folder when the repository declares no workspaces, and two files in it changed recently. One recent source change is enough to keep a whole package awake, so the dormant check can't see a dead area inside it.
What to look at: the table. Search app/controllers or app/models to find areas that have gone cold together, since neither form can split them out.
A Go service after a license-header sweep
0% of source lines unchanged for a year or more (0 of 3,103)
Nothing is a year old: the oldest file, session.go, last changed 3 months ago.
31 files changed this year after a year or more untouched, the longest session.go after 8.3 years: check that whoever changed it knew it.
What it means: this reads as a healthy young codebase, and it's an eight-year-old one. One commit touched every file three months ago, which made every file warm, nothing cold, nothing orphaned, and nothing dormant. The woken line is the clue: when nearly every file woke up, a sweep is a likelier cause than real work. The table confirms it, with those files all showing the same days since change.
What to look at: git log on a couple of the files. Age can't see past a sweep, so a repository that has had one needs another way to judge what's still understood. See Experts for who has really worked on a package.
How it's measured
GitRelic takes every file in the analyzed commit and looks for the commits that changed it.
A file's age doesn't depend on the window
Most lenses only read the analyzed period, which is the last 12 months by default, counted back from the newest commit analyzed. Age reads that period and also all the history before it. A commit near the boundary can appear in both reads, and it counts once.
So --since doesn't change Age. A file's date, age and band, and whether it's orphaned, woken or in a dormant package, come out the same with a 2-month window, a 12-month window or --since all. The one exception is a history with commits dated far out of order, where git's date filters can miss one.
Ages count back from the newest commit in the analysis, not from today. Running the same commits next month gives the same answer. It also means that with --since all, a repository nobody has touched in three years still has files "under 3 months": they're new compared with its last commit, not compared with today. If nothing was committed inside the window, there's no report at all, and GitRelic says No commits found since "12 months ago". Try a broader time range or use --since all.
Dates are author dates. A rebase or cherry-pick keeps the original author date, so a file changed by a rebased commit last week can read as years old.
Merge commits aren't read. Work on a branch counts on the date it was written, not the date it merged.
Which files are in scope
Only files that exist in the analyzed commit. A deleted file has no age, though the commits that touched it still show who was active.
| Files | In Age? |
|---|---|
| Source: anything not in the rows below, including docs, data and config that isn't on the plumbing list | Yes, in every count |
Tests: __tests__/, tests/, Tests/, *.Tests/, src/test/ and cypress/ folders, test/ or spec/ at the repository's root or a package's, and files like foo.test.ts, foo_test.go, test_foo.py or FooTest.java | Only with the Tests switch on, and always in the table. A test/ folder deeper in the tree, as in lib/test/, counts as source. |
Fixtures: __fixtures__/, fixtures/, testdata/, __snapshots__/, __mocks__/, .snap files | No, only in the left-out count |
Generated: vendor/, third_party/, __generated__/, *.generated.*, *.pb.go, *_pb2.py | No, only in the left-out count |
| Plumbing: manifests, changelogs, licenses, CI and tool configuration | No, only in the left-out count |
Ignored: images, fonts, videos, PDFs, source maps, minified files, lockfiles, top-level dist/ and coverage/, and a few files such as CONTRIBUTING.md | Not read at all, and not in any count |
--include-fixtures changes nothing here, as Age keeps its own rule whatever that flag says.
"Source" is broad. A folder of Markdown or a large JSON file counts as source, and its lines count toward the cold share. Binary files that aren't on the ignored list, and empty files, count as files with 0 lines.
A file no commit reached doesn't appear: no dot, no table row and no Last changed row on its card. It isn't in the left-out count either. With full history this is rare, the usual case being a file added only inside a merge commit.
Who counts as left
A cold file is orphaned when every person who changed it has gone a year without a commit.
- "Who changed it" means people who authored a commit touching the file, at any time in history. Three kinds of commit don't count: those by bots, those by AI agents, and sweeping commits of more than 20 files. A mass rename doesn't make you someone who knows the file.
- "Gone a year" means no commit of any kind, on any file, in the 365 days before the analyzed commit. A sweeping commit by someone does count as them being active. Exactly 365 days counts as gone.
- One recent person saves the file. Someone who fixed one typo in it, and still commits elsewhere, keeps it from being orphaned, however little they know it.
- The same person under two emails is one person, merged across all of history (unless you run with
--no-merge-identities). - Co-authors don't count, either as someone who changed the file or as being active. Only the commit's author does.
The table's Orphaned by column and the tooltip name up to three people, those with the most changes to the file first. There may be more than three. A person goes by the name on their latest commit.
A file with no qualifying author is never orphaned. A file only bots, AI agents or sweeping commits changed reads as plain cold, even though nobody around knows it. In a one-person repository nothing is orphaned as long as that person made a commit in the last year, which they will have if they made the newest commit.
Dormant packages
A package is dormant when all of these hold:
- It has 5 or more source files in the analyzed commit. Fewer than that never badges, however old.
- No source file in it has changed in a year. A test, fixture or plumbing change doesn't keep it awake, but one source change does.
- It's a package at all. Files at the root of the repository, and dot-folders such as
.storybook/, are shown as rows but can't be dormant.
A package is one of the repository's own declared workspaces, else packages/*, apps/*, libs/* or services/*, else the top-level folder. So a pkg/ or src/ folder is one package however large, and a docs/ folder of five old Markdown files can come up as dormant. When it does, "say why it stays" is the right answer.
Age doesn't require anyone to have left. A package can be dormant while everyone who wrote it is still committing elsewhere.
Woken files
A file is woken when it isn't cold, and there was a gap of a year or more just before one of its changes in the last year. The gap shown is for its most recent such change. A brand-new file has no earlier change, so it isn't woken. Any commit wakes a file, including a bot's or a sweep.
If older history can't be read
If the read times out or fails, GitRelic reports on the window alone and shows the warning above. A file untouched in the window is then missing altogether, so the cold share usually reads too low, and dormant packages and orphaned files can't be trusted: only the window's commits say who changed what and who is active. --git-timeout raises the limit.
In the dashboard
Find this lens under Code Health. It has two forms, sharing the same rows: up to 14 packages, most cold lines first, with "+3 more packages in the table (T)" for the rest. A dormant package past the 14th row is still named in the findings.
- Strata (the default) has one row per package, with one dot per file. A dot's position is the time since its last change, on a square-root scale, with ticks from 3 months up to 16 years as far as the data goes, so the last year gets room and a decade still fits. Its size is its lines, and older files are brighter. The side past a year is shaded and labeled "cold: unchanged for a year or more". Orphaned files wear an accent ring, a dormant row is tinted, and each row names its oldest file. A row's name leaves off
packages/. Hover a dot for its path, age, lines, who it was orphaned by or how long it slept. Use this form to tell whether a package's cold is a few old files or a whole layer. - Warm and cold (the corner toggle) has one bar per package, split at a center axis: lines changed within a year to the left, cold lines to the right by band, the oldest outermost. Every row shares one scale, so this is the form that says how much. The half-height accent at the far right is the package's orphaned lines. It shows how many, and doesn't mean they're the oldest ones. Hover a bar for the package's totals and its newest source change.
- The Tests switch ("Tests hidden" / "Tests shown") in the stage's corner adds test files to both forms, as fainter dots and more lines in the bars. It's off by default and remembered in your browser. It changes the rows and their totals. It doesn't change the headline or the findings, which stay on source files, or which packages are dormant.
- The inspector, with nothing selected, leads with the cold share, then the findings quoted above, then Coldest packages: up to five, with a dormant one in the accent.
- The table (
T) lists every source and test file, oldest first, whichever way the Tests switch is set: days since change, Last changed band, lines, Orphaned by, Kind and package. Its tiers are Under a year, 1–2 years, 2–4 years and 4+ years: the two warm bands share one tier. The table doesn't mark dormant packages. - The time strip under the picture covers commits in the analyzed period only. A cold file can show its age here and light nothing in the strip.
- The Overview shows the reading above and lists dormant packages, then orphaned source files. The portfolio page lists a Dormant packages count per repository. Don't confuse it with the portfolio's "dormant" pill, which means a whole repository with nobody active.
On a small repository, most findings simply don't appear. With no source files, Strata says "No file has a recorded change" while the Tests switch is off, and the Warm and cold heading says "No source lines to age." The inspector reads "0%" and, if it has no findings at all, "No tracked file has a history." In a repository with only tests, those messages overstate it: turn the switch on, or open the table, and the files are there with their ages.
What it can't tell you
- Whether anyone understands the code. A recent change is the only evidence it has. A sweep, a formatting pass, a bot's edit or a one-line fix all make a file warm and clear its orphaned status.
- What's cold inside a file. A file has one age. One changed line makes all of its 5,000 lines warm.
- Where a file came from. Renames aren't followed. A moved file's clock starts at the move, and so does its list of who changed it, so a file written by someone long gone and moved by someone still here isn't orphaned. A package that was just moved looks fresh. See Renames.
- Whether "left" means left. It means no commits. Someone who reviews code, manages the team or moved to another repository counts as gone. Someone who only merges PRs does too, since merge commits aren't read.
- Anything in a shallow clone. Git treats the clone's oldest commit as having added every file, so every file older than that reads as changed on that date, with no warning. A
--depth 1clone shows every file as "0 days" old. Analyze a full clone. - Whether cold code matters. Age sees no usage. A cold package might be finished and depended on everywhere, or dead. That's why a dormant package's finding offers three answers.
Related
- Experts — who to ask about a package. Its "untouched for a year" count isn't the same as dormant packages here: Age needs 5 or more source files in the analyzed commit, and looks only at source changes.
- Ownership — how much of each package rests on one person, and whether they went quiet.
- Hotspots — the opposite end: where the changes are concentrated now.
- Renames — what a move does to each lens. Here, it resets a file's age.
- Risk — doesn't rate a file no person changed in 180 days. It counts only people's commits, so a file a bot bumped last week can be young here and quiet there.