The repository looked healthy, and the healthy is what the surface showed. The surface is the build passing, the tests passing, the commit rate steady, and the steady is the health, and the health is what the dashboard shows, and the showing is what the hotspot does not.
The hotspot check is what the surface did not include, and the not-including is the finding. The finding was the file the surface did not flag, and the file is the auth module, and the auth module is where the churn was, and the churn is what the steady commit rate hid, because the steady rate is the total, the total is what the distribution does not show, and the not-showing is the concentration. The concentration was in the auth module, and the auth module is where the churn means something, because the churn in the auth is the security surface, and the security surface is what the healthy repository did not show. The section below is the repository in detail: the surface, the hotspot, the concentration, and the lens the hotspot adds to the surface, because the lens is the health check, and the lens is what the dashboard does not have.
The security section reads like an audit, because it is one: the asset, the threat, the control, and the residual risk, in that order, and the order is the part the fear-based security writing skips, because the skip is what makes the fear do the arguing. The asset here is the data the workflow touches, and the touches is the part that gitpulse changes, because the changes is Git analytics in your terminal: file hotspots, commit patterns, branch strategy, contributor impact.. The threat is the specific one for this workflow, and the specific is the part the section names before it names the control, because the named threat is what the control answers. The residual risk is stated at the end, because the stated residual is the part that makes the rest of the section the honest one.
The 2>/dev/null Bug: How I Learned to Test Where Users Are
A recent release was a fix for a bug that had been silently present for three months: a shell redirect that is fine on Linux and macOS and quietly wrong on Windows, where stderr handling behaves differently. The tool ran, produced output, and the bug only showed up as missing data for a subset of users on a subset of platforms. The lesson is not that I made a mistake. The lesson is that a CLI tool's test matrix has to include the platform where your users are, not the platform where you are. Three months of silent wrongness is longer than most bugs survive in a well-tested product, and the fix was one line. But finding it required a user report, not a test. That gap — between the platforms you test on and the platforms your users run on — is the most expensive gap in a cross-platform CLI, and it is the one that never shows up in your own usage because your machine is the one platform that always works. The fix was a line. The lesson is a test matrix.
The CSV Export: When the Report Leaves the Terminal
The export flag is the bridge between the measurement and the conversation, and the bridge is the part that changes who sees the data. In the terminal the report answers the question that prompted the run. In the spreadsheet the report sits next to last month's report and the month before, and the sitting-together is the trend, and the trend is the question that one report cannot answer. The export format is the spreadsheet format on purpose, because the spreadsheet is the tool the non-developer on the team already has, and the already-has is the part that makes the data reachable. The workflow is small: one row per period, the columns that survive comparison, the shared sheet that the standup reads. The data in the standup is the last three rows, and the last three rows are the trend in miniature, and the trend in miniature is the part the status report never had, because the status report is the current row only, and the current row only is the view without the direction.
The Hotspot Table, Column by Column
The hotspot table is the center of the report, and the columns are worth reading in order, because the order is the reading. The first column is the file, and the file is the unit of the measurement, which is the unit the team thinks in, because the team argues about files instead of commits. The second column is the change count in the period, and the count is the energy measurement, and the energy is what the file is spending. The third column is the distinct contributors, and the contributors are the coordination cost, because the file that five people touch is the file that five people wait on. The fourth column is the revert share, and the revert share is the understanding cost, because the reverts are the changes that did not stick, and the not-sticking is the signal that the area is not understood. The four columns together are the diagnosis, and the diagnosis is the part the single-column view, the change count alone, does not give, because the count without the context is the number that argues for itself.
What git log Can't Tell You
The log answers one question: who changed what, and when. It is a great question, and it is not the question. The question that actually predicts trouble is: where is the codebase accumulating damage? A file that changes forty-seven times a month is a hotspot no matter how clean each individual commit looks. A team whose commits cluster on late weekend hours is a team that is running hot no matter how green the pipeline is. The log shows you the events; the analytics show you the patterns underneath the events. That difference is the difference between a log and an analysis, and it is the reason a tool that reads your entire history and summarizes the shape of it is a different category of instrument from the version control system itself. The events are facts; the shape is the information. This article is about the shape, and about how to get it in thirty seconds instead of an afternoon of log-reading.
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.
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.
The Contributor Impact View
The contributor view is the people axis of the report, and the axis is the part the team reads with the most attention, because the axis is the one that names the person. The view measures the contribution per person over the period: the commit count, the file reach, the area concentration. The file reach is the interesting column, because the file reach is the breadth of the knowledge, and the breadth is what the onboarding needs, when the question is who knows the auth module, the answer is the person whose reach covers it. The area concentration is the second column, and the concentration is the depth, and the depth is what the refactor assignment needs, when the decision is who rewrites the hotspot, the answer is the person whose concentration is in the hotspot. The two columns together are the knowledge map, and the knowledge map is the onboarding answer and the refactor answer and the bus-factor answer, and the three answers are the three meetings the map replaces.
The Period Flag: Why Since When Is the Whole Interface
The analytics question is always a question about a window, and the period flag is the window. The month view answers the what-is-happening-now question, the quarter view answers the what-has-been-tending question, and the year view answers the what-is-this-project question. The same repository reads completely differently in the three windows, and the different reads are the feature, because the feature is the time axis, and the time axis is what the log command does not give you without the date math and the merge-commit handling that the one-liner gets wrong on the third try. The default period is the choice the tool makes for you, and the default is the quarter, because the quarter is the window where the pattern shows and the noise is still low. The flag is the escape hatch for the specific question, and the specific question is the one the standup raised, and the standup question is the one the report should answer in one command instead of one afternoon.
Commit Patterns: The Weekday, the Weekend, and the Hour
The commit pattern section reads the when, and the when is the part of the data that the status report never captures, because the status captures the what and the what is what the developer says happened. The weekday distribution is the baseline, and the baseline is the expected shape of the work. The weekend ratio is the cost signal, and the cost signal is the fraction of the commits that landed outside the working week, and the fraction is the number that the standup should see, because the standup is the meeting where the schedule gets fixed. The hour distribution is the third read, and the hour is the part that shows the late-night cluster, and the late-night cluster is the deadline signature, and the deadline signature is the pattern that repeats until the deadline stops being the deadline. The three reads are the same data three ways, and the three ways are the difference between the activity report and the cost report, and the cost report is the one the team can act on.
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.
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.
The takeaway
The security section ends where the architecture ends: at the boundary the tool does not cross. gitpulse is Git analytics in your terminal: file hotspots, commit patterns, branch strategy, contributor impact., installed with npx @wuchunjie/gitpulse, source at https://github.com/wuchunjie00/gitpulse. The boundary is the part the threat model respects, because the respects is the control, and the control is the part the residual risk is measured against. The reader who runs the tool runs the boundary, and the runs is the part the claim becomes the behavior, and the behavior is what the security section is for, because the for is the practice, and the practice is the habit with the check in it.
Top comments (0)