Comparing two branches turns git analytics from a mirror into a telescope. A single branch only shows you where the team is; the comparison shows you how it got there and where the two lines are about to collide. The command takes a range, main to develop in the example, and the report is the difference: what is moving on develop that main does not know about yet, and how the movement is distributed. The commit split between the branches is the merge-debt signal, and the contributor split tells you whether the divergence is one person's feature branch or the team's working line.
The practical reads are specific. If develop carries a lot of small commits from many people, the merge back to main will be a negotiation, and the branch should probably have been shorter. If the divergence is one large feature from one person, the merge is mechanical and the risk is in the review, not the rebase. If the same files are hot on both branches, the collision is coming, and the cheap fix is a merge now, while the histories are still cheap to reconcile. None of this is visible from a branch list in a GUI; the list tells you the branches exist, and the comparison tells you what the relationship between them costs. The range is the whole interface, and the report answers the question that usually takes a thirty-minute meeting: are we about to have a bad merge, and if so, why.
This is the hands-on section, and it is written as the run goes, which means the commands are in the order they are typed and the output is the output that came back, including the parts that look like errors and are not. gitpulse is Git analytics in your terminal: file hotspots, commit patterns, branch strategy, contributor impact. The install line is npx @wuchunjie/gitpulse, and the repository is https://github.com/wuchunjie00/gitpulse if you want to read the source before you run it, because the reading is the option, not the requirement, and the requirement is the run. Each step below is short enough that a copy-paste session can follow it without losing the thread, and the thread is the part that the long tutorial loses, and the loses is what sends the reader to a different tab.
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 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.
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.
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.
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.
Reading a Report You Did Not Author
The report is a tool for the person who is not the committer, and the non-author is the larger audience: the tech lead reading the team's repository, the new developer reading the project they just joined, the reviewer reading the area before the review. The reading skill for the non-author is the same three passes the author uses, and the passes are the structure. First pass is the shape: the total volume, the active files, the contributor count, and the shape is the one-paragraph summary of the project's state. Second pass is the concentration: the hotspots, the areas where the energy is, and the concentration is the map of where the project is spending itself. Third pass is the change: the period over period delta, and the delta is the direction, and the direction is the part the summary needs, because the summary without the direction is the photograph, and the photograph is what last month's summary was. The three passes take the length of the report, and the report is the part that does not need the author present.
The Compare Range: Two Branches, One Answer
The compare flag takes a range and answers the question the branch list cannot: what is the relationship between the two branches, and what does the relationship cost? The main-to-develop range is the classic one, and the report is the difference: the commits on develop that main does not have, the distribution of the commits by person, the files that are hot on both sides. The hot-on-both is the collision warning, and the collision warning is the part that saves the bad merge, because the bad merge is the merge where both branches changed the same lines, and the same lines are what the report flags before the merge attempt. The range is also the feature review input, when the question is what did the feature branch change and who will need to know, and the answer is the file list with the contributor column, and the file list is the review scope, and the review scope is what the range computes instead of the human who has to walk the diff. The one command is the answer the meeting used to build by hand.
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.
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.
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.
The takeaway
The run is the proof, and the proof is the part the tutorial is. gitpulse gives you Git analytics in your terminal: file hotspots, commit patterns, branch strategy, contributor impact. and the giving is one command: npx @wuchunjie/gitpulse. The repository, https://github.com/wuchunjie00/gitpulse, is where the source lives and the issues go, and the goes is the part that the stuck reader uses, because the stuck is the part the tutorial cannot see from here. The path above is the one that was run and the run was clean, and the clean is the part that the next run inherits, and the inherits is what the tutorial buys for the reader who follows it to the end.
Top comments (0)