Bus Factor Is a Number. I Compute It in 2 Seconds Before Onboarding.

#git #cli #devops #javascript

Every team has one person who could be hit by a bus. Most teams know this as a vibe. I'd rather have a number.

The bus factor of a codebase is the number of people who would have to vanish before the project stops functioning. A bus factor of 1 isn't a risk — it's a scheduled incident. The question is when, and who.

I've stopped treating this as a conversation you have once a year in a risk review. It's a measurement you take in two seconds, on every repo you touch.

Two seconds

I use gitpulse, a zero-dependency terminal tool that reads the git history of a repository and prints commit stats, a contributor graph, file breakdowns, and recent activity. No server, no account, no upload of your history — it runs against the .git directory on your machine.

$ npx @wuchunjie/gitpulse ./

  GITPULSE

  Total commits:   1
  Contributors:    1
  Active days:     1
  Files touched:   4

  Top Contributors
    ScaffoldX                 ################ 1

  File Type Breakdown
    .npmignore  ################ 1
    .md         ################ 1
    .js         ################ 1
    .json       ################ 1

  Recent Activity
    2026-05-17  ################################ 1

That's a bus factor of 1. I know before the first code review that if the author disappears, this repo is frozen. No negotiation needed.

What I do with the number

The measurement is only useful if it changes behavior. Here's my actual checklist when the contributor graph comes back thin:

Bus factor 1 on a load-bearing repo. I pair with the owner on the three hardest files in the codebase. Not a documentation exercise — I make them walk me through the design while I write a scratch test that encodes the decision. If they can't explain a file, the file is the real bus.
Bus factor 2, both on the same team. I flag it in the onboarding doc explicitly: "These two systems are owned by one team. Escalation path is X."
Contributors exist but activity is a single spike. The Recent Activity block tells you whether the repo is maintained or merely committed. A flatline for six months with a bus factor of 2 is worse than a steady single maintainer — at least the single maintainer knows the code.
File type breakdown shows 90% .ts but the scary logic is in 4 .sql migrations. gitpulse won't tell you where the risk is; it tells you what's there. The file breakdown is the map, the contributor graph is the census. Read them together.

Why terminal, why local

You can get contributor stats from GitHub's UI. I still use gitpulse for three reasons:

It works on any remote, including internal GitLab, Gitea, and bare mirrors that don't have a nice web UI.
It's the same tool on every machine. The output block pastes into a PR description, an onboarding doc, or a status report identically — no screenshots, no permission dance.
Nothing leaves the machine. For a client repo under NDA, running an analytics SaaS over the full history is a conversation I don't want to have.

The uncomfortable follow-up

Running the tool is the easy part. The hard part is the repo where the number is 1 and the one person is you. I'll write about what I do about that separately — short version: the fix is not documentation, it's making the second person's first PR land this week, not "next quarter."

Before your next onboarding, run it on the repo you're joining. Two seconds. The number will tell you more about the team's risk posture than the org chart did.

$ npx @wuchunjie/gitpulse

More Tools

Tool	What it does	Command
scaffoldx-cli	12 production-ready project templates in 3 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.

DEV Community