The research project that shaped gitpulse was simple to describe and slow to do: run the same set of measurements across a large number of repositories and look for the patterns that hold. The repositories were a mix of my own projects, client work I had permission to analyze, and public repositories from a range of stacks and team sizes. The results were not a leaderboard — no top repositories, no rankings, no shame — they were a set of distributions, and the distributions are where the surprises were.
Hotspot concentration held across nearly every repository: a small fraction of files carried the majority of the churn, and the fraction was more consistent across repositories than any per-repository metric was, which is the finding that changed the design. Commit patterns correlated with team size more than with team quality: small teams look erratic, large teams look steady, and the middle is where the interesting data is. The branch ratio was the most stable metric in the entire study — teams do not change their shipping process, they change their people, and the history records the people, not the process, which is the finding git blame never shows you, because blame shows the hands and not the process. This article is the summary of what the data said, with the specific distributions and the design decision each one produced. The lying was not in the blame; it was in the question. The right question is the article; the data is the evidence.
I did not set out to build gitpulse. I set out to fix a specific problem, and the tool is the scar tissue from fixing it properly. This is the story in the order it actually happened: the incident, the first attempt that did not work, the constraint that shaped the design, and the decision I would make differently if I were starting over. None of it is polished, because the polished version would be a press release, and I would not trust a press release either. If you are deciding whether to use @wuchunjie/gitpulse, the build story is the most honest document about what you are getting — including the parts that are limitations, which the marketing page would never name.
Pairing gitpulse With dotguard in One Pipeline
A repository has two kinds of health: structural and security, and they are measured by different tools. One tells you whether the code is organized and maintained — hotspots under control, contributors distributed, branches reviewed. The other tells you whether the repository is leaking — secrets in configs, tokens in history, credentials in compose files. Running both in the same weekly pass is a complete repository health check in under a minute, and the outputs are complementary: a hotspot in a config file that the secret scanner also flags is a refactoring task with a security deadline. Two small CLIs, no shared infrastructure, one habit. That is the whole architecture of the pipeline, and it is the kind of architecture that survives because nothing in it needs to be maintained. The weekly pass becomes the meeting the team does not have to schedule: the file is the agenda, the findings are the action items, and the rotation of the week is the follow-up. Infrastructure this small is not a platform. It is a reflex, and reflexes are what teams actually keep.
Contributor Impact: Measuring What Actually Ships
Commit count is the most common contributor metric and the least useful. A person who makes two hundred small commits to one file is not contributing two hundred times more than a person who makes twelve commits that each change a module. The analytics weigh contributions by impact: lines changed across distinct files, churn on hotspots, and the span of the codebase touched. The result is a much better answer to the onboarding question — who owns what — and the succession question — what happens if this person leaves. The tool is not a performance review; anyone who uses it that way is using it wrong. But it is a map of where the institutional knowledge actually lives, which is a map every team should have before it needs it. The impact ranking is that map: the people at the top are the load-bearing walls of the codebase, and knowing which walls they are is not management overhead. It is structural engineering.
When Analytics Are the Wrong Tool
Honesty section: repository analytics are not for every repository. A new project with two weeks of history has no patterns to analyze — the hotspots are noise, the commit shape is just one person working, and the branch ratio is undefined. A solo project where you are the only contributor and you already know the codebase has little to tell you. And a repository where the team will use the output as a performance signal will get a distorted version of the truth, because the data was never collected for that purpose. The right use is a diagnostic: a repository you are inheriting, a repository that feels slower than it should, a repository you are about to present to stakeholders. Use it as a stethoscope, not as a scoreboard. The stethoscope tells you where to listen; the scoreboard tells you who to blame, and the blame is never in the data. Knowing which instrument you are holding is the whole skill, and the wrong instrument, used with confidence, is worse than no instrument at all.
Branch Strategy: The PR-versus-Direct-Push Ratio
How does your team actually ship? The honest answer is in the history, not in the process document. The analytics measure the ratio of changes that arrive via merge — through review — versus changes that land on the branch directly. The number is not moral; direct push is fine for docs, dependencies, and solo work. But the shape of it tells you how much review your code actually gets. A repository where the large majority of commits are direct pushes has a code review process that exists in the wiki, not in the history. The compare flag lets you look at the ratio between two branches, which answers the practical question: is the integration branch cleaner than the trunk, or did the branching experiment produce more direct landings than the mainline? The ratio is a process fact, and process facts are the kind of thing you cannot get from a meeting. The meeting tells you what the process is supposed to be. The history tells you what it is.
CSV Out: Health Reports Without a Dashboard
The tool can export its findings as CSV, and that one flag is the answer to the dashboard question. The standard objection to CLI analytics is that nobody will read the output in a terminal. Fair. So the output becomes a file: a health report, attached to a message, emailed to the team on the first of the month, dropped into a spreadsheet that the tech lead already maintains. No server, no subscription, no infrastructure project. The data leaves your machine only when you decide it should, and the format is one that every tool you already have can open. For most teams, the right analytics infrastructure is a file and a habit, not a platform. The file is the report; the habit is the monthly export and the five-minute read. Everything else — the dashboards, the integrations, the subscriptions — is what you add when the file-and-habit version stops being enough, which for most small teams is never, and for the teams where it is, the CSV is the import format they will thank you for.
Onboarding a New Repo in 60 Seconds
The worst moment in a developer's life is opening a repository they have never seen: no documentation, a multi-year history, and a codebase that looks the same in every folder. The analytics turn that moment into a sixty-second orientation. The hotspots tell you where the action is — start reading there, not at the README. The contributor impact tells you who to ask when the code does not make sense. The branch strategy tells you how changes actually get in, which is the one process fact that documentation never gets right. Inherited projects are the common case, not the exception: new job, new team, acquired codebase, open-source contribution. A tool that compresses the first hour into the first minute pays for itself on the first use. The sixty seconds buy you something rarer than time: a map, so the first day is spent building context instead of stumbling through directories hoping the important file announces itself.
Hotspots: Finding the Technical Debt Magnets
Every codebase has a handful of files that attract change the way a drain attracts water: the config that every feature touches, the utility that every module imports, the model that every migration reshapes. The analytics surface these as file hotspots — the files with the highest change frequency over your chosen period. The value is not the list itself; it is what the list tells you. A hotspot that is growing is a refactoring candidate with a priority attached. A hotspot that is stable is just a busy file. And a new hotspot appearing this month is an early warning that a design decision is about to become a migration project. Refactoring is cheaper when it is scheduled than when it is forced, and the hotspot list is the schedule. Read it monthly, and the debt magnets get addressed while they are still magnets instead of after they become the reason the release slipped.
What Measuring Lots of Repos Taught Me
After running the same set of measurements across a large number of repositories — my own projects, client work, and public repositories from a range of stacks and team sizes — a few patterns held up consistently. Hotspots concentrate: a small fraction of files accounts for the majority of churn in almost every codebase. Commit patterns correlate with team size more than with team health: small teams look erratic, large teams look steady, and the middle is where the interesting data is. And the branch ratio is more stable over time than anyone expects — teams do not really change their shipping process, they change the people. The tool was designed to answer one question per repository. Measuring hundreds of repositories let the data answer a question I had not thought to ask: the shape of a codebase is more determined by its size and its people than by its technology, and the technology shows up mostly in the noise. The design decisions that followed — the default period, the impact weighting, the ratio as a headline metric — are all consequences of those patterns.
Reading a Quarter: The Long View
The monthly view is for the pulse; the quarterly view is for the story. Extend the period to a quarter and you can see the arc of a release: the hotspot that built up through the quarter, the contributor who carried the middle two months, the week where the commit pattern broke. That view is where hiring and attrition show up. A new contributor ramping is visible as a growing impact curve. A person leaving is visible as a curve going flat, often weeks before the announcement. And a release that was supposed to be a sprint shows up as a commit pattern that never recovered. None of this requires a dashboard or a database. It is version control history, which you already have, read by a tool that knows which questions to ask. The quarter is the right window for most organizational questions, because a month is noise and a year is archaeology. A quarter is a story with a beginning and an end, and the report reads it for you.
The 30-Second Report
Run the tool with no arguments in a repository and you get the current month, summarized: the hot files, the commit shape, the branch behavior, the top contributors by impact rather than commit count. Thirty seconds from typing the command to having a picture of the repository that the log would take an hour to assemble by hand. The design goal was a report you would actually read, which means short enough to fit on a screen and dense enough that each line earns its place. I use it as a standing habit: first command of the week in any repository I am active in, the same way some developers start with status. The habit is the point. A report that takes ten minutes to generate gets run once a quarter. A report that takes thirty seconds gets run every Monday. The frequency is the feature, because the value of repository analytics is in the delta — what changed since last week — and the delta is only visible if you look often enough to see it move.
Commit Patterns and the Burnout Signal
Commits have a rhythm, and the rhythm is a health metric. The analytics look at when commits happen — by hour, by day of week, by streak — and the pattern is more honest than any survey. A team that commits steadily on weekdays is one kind of team. A team whose commits spike on Friday nights and Saturday mornings is another, and the difference is visible in the data without asking a single person how they are doing. I am not saying commit timing equals wellbeing; it is a signal, not a verdict. But it is a signal that a manager who only looks at velocity will never see, and it is exactly the kind of information that is cheap to collect and expensive to guess at. The right use is the trend, not the snapshot: one busy weekend is a fact, four busy weekends in a row is a pattern, and the pattern is the conversation worth having, had with data instead of with hunches, before the hunches become resignations.
The takeaway
That is the version of events, unedited. If you are reading it to decide whether to use @wuchunjie/gitpulse, the most useful paragraph is the one about the constraint that shaped the design — that is where the tool's character comes from, and character is what you are actually adopting when you adopt a tool. The repository at https://github.com/wuchunjie00/gitpulse has the code, the issues, and the discussions; the fastest way to vote with your hands is npx @wuchunjie/gitpulse. And if the story made you want to see the rest — how dotguard, gitpulse, and snippetx came out of the same habit — each of them has its own build story. ko-fi.com/wuchunjie if any of it was useful. The stories are the documentation that survives, because people remember the story and forget the feature list.
Top comments (0)