File Type Breakdown: The Fastest Way to Understand a Codebase's Shape

You get handed an unfamiliar codebase. The README is three paragraphs old. The folder structure is a lie (it describes intent, not reality). Where do you start?

I start with the file type breakdown — the distribution of the codebase's mass by extension. It's the fastest honest map of what the project is, and it takes one command:

npx @wuchunjie/gitpulse .

The relevant block:

  File Type Breakdown
    .ts     ############################################ 412
    .tsx    ############################ 301
    .test.ts  ######## 84
    .md     ### 21
    .json   ## 14
    .sql    # 6
    .yaml   # 3

That's the shape. And the shape answers questions the folder structure can't.

What the breakdown tells you

1. The real center of gravity. A repo organized as src/components/, src/services/, src/utils/ sounds balanced. The breakdown might show 85% of the mass in one extension cluster — and if you cross-reference with the directory, you'll often find the "balanced" structure is mostly thin wrappers around one thick core. The mass is where the behavior is. Read the mass first.

2. The test story, instantly. The ratio of test files to source files is the single fastest proxy for "does this codebase trust itself?" 84 test files against 713 source files is a ~12% test ratio — real, not exhaustive. A repo with zero .test.* files and 500 source files is telling you its verification strategy is "the deploy works." Neither is automatically wrong, but both are information, and you get it in one second from the breakdown.

3. The hidden complexity. The small extensions are often the interesting ones. A 6 .sql in a TypeScript project is a migrations cluster — read it, because it tells you the data model the app actually runs on, which is more current than any README. A 3 .yaml might be the deploy config, which is where "it works on my machine" lives. The breakdown points you at the small files that carry outsized weight.

4. The generation ratio. A large .svg, .png, or generated-code share tells you how much of the repo is produced rather than written. Generated code has different maintenance semantics — you don't debug it, you fix the generator. Knowing the ratio up front means you don't spend an afternoon reading a file you should have regenerated.

Why it beats tree and the README

tree shows you the organization — how the author chose to arrange things. The breakdown shows you the composition — what things are actually made of. Organization is opinion; composition is fact. A repo can be beautifully organized and mostly dead code; a repo can be chaotic and 90% live logic. The extension mass is the one thing the author can't spin.

The README is a marketing document. The breakdown is a census. When they disagree — and they often do, especially in repos maintained for years — the census wins.

How I use it in the first 10 minutes

The sequence, on an unfamiliar repo:

1. npx @wuchunjie/gitpulse . — read the contributor graph (who's here) and the file breakdown (what's here). Two blocks, ten seconds.
2. Identify the mass extension. That's the language of the project, even if the folder names suggest something else.
3. Identify the small-but-critical extensions (.sql, .yaml, .prisma, .graphql). Those are the load-bearing details.
4. Open the biggest file in the mass extension and the biggest file in a critical small extension. Two files, and you have the project's center of gravity and its foundation.

Then, and only then, the README, the issue tracker, and the architecture doc. By the time you read them, you're reading with a map, not building one.

The tool

gitpulse is a zero-dependency Node script. It reads the local .git directory — the file type breakdown comes from the committed file list, so it reflects the repo's actual shape, not your working directory's current mess. Nothing is uploaded; the whole analysis is local.

It's not a substitute for reading the code. It's the ten seconds that tells you where to read. On a codebase you'll work in for weeks, that's the highest-leverage minute of the first day.

npx @wuchunjie/gitpulse

---

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	npx scaffoldx-cli
dotguard	Scan .env files for exposed secrets	npx @wuchunjie/dotguard
gitpulse	Git repo analytics in your terminal	npx @wuchunjie/gitpulse
snippetx	Terminal code snippet manager	npx @wuchunjie/snippetx

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.