A project that needs a refactor announces it in the git history before it announces it in the code, and the six signals below are the announcements, each one a pattern in the commit data that the code review does not see and the standup does not discuss. The signals are not a score; they are a set of early warnings, and the value is in the combination, because one signal can be noise and three signals in the same file is a diagnosis. The analytics tool is the instrument that reads the signals, and the reading is the skill, because the numbers without the reading are just numbers.
The first signal is the deepening hotspot, the file whose change rate is increasing month over month instead of staying flat, which is the difference between a busy file and a failing one. The second is the revert cluster, the group of commits that undo each other in the same area, which is the signature of a change that was made without understanding the area. The third is the branch divergence, the gap between the working branch and the main branch growing past the point where the merge is mechanical. The remaining three are in the section below, and the section ends with the combination rule: one signal is a note, two is a conversation, three in the same area is a refactor decision, and the refactor that starts from the data is cheaper than the refactor that starts from the incident, which is the entire argument for reading the signals at all.
The list is the format, and the format is the promise: each entry is one thing, one use case, and one honest note, and the three are the unit the list is made of. The entries are ordered by the weight they carry in actual use, not by the order they were discovered, because the discovered order is the story and the weight order is the tool. The entries come from gitpulse, Git analytics in your terminal: file hotspots, commit patterns, branch strategy, contributor impact., and the tool is the context for the list, because the list is the tool's shape made explicit, and the explicit is the part the feature page does not do, and the does-not-do is what the list is for. The section below is the list, and the list is the section.
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.
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.
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.
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.
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.
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.
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.
Branch Strategy as a Number
The branch strategy is a process fact, and the process fact becomes a number when the report counts the pull-request commits against the direct-push commits over the period. The ratio is the strategy: a team that merges through pull requests shows the ratio in one direction, a team that pushes to main shows it in the other, and the mixed team shows the split, and the split is where the policy lives, because the policy is usually by area instead of by rule, and the area is what the ratio reveals when the report breaks the split down by directory. The number is not the verdict. The verdict is the conversation the number starts, and the conversation is the one that used to take the meeting and now takes the slide, because the slide is the last three periods of the ratio, and the three periods show the trend, and the trend is what the policy argument is about. The number ends the fight by making the fight about the trend instead of the memory.
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.
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 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.
The takeaway
The list is the section, and the section is done, which means the entries are the content and the content is the part the reader scans. gitpulse is the tool behind the list: Git analytics in your terminal: file hotspots, commit patterns, branch strategy, contributor impact. The install line is npx @wuchunjie/gitpulse, and the line is the part that makes the entries runnable, because the runnable is what the list entry promises and the promise is the part the reader checks. The repository is https://github.com/wuchunjie00/gitpulse, and the repository is where the next entry goes, because the next-entry is the part the list that stops growing loses, and the loses is what the maintained list does not.
Top comments (0)