gitpulse

A one-screen health report for any git repository. It shows commit activity, top contributors, the files changing most often, the language mix, and how many TODO/FIXME markers are sitting in the tree. No dependencies, no AI, just Node and git.

Install

npm install -g @bobfromarcher/gitpulse

Or run it without installing:

npx @bobfromarcher/gitpulse

Usage

gitpulse [path] [options]

| Option | Description | Default | | --- | --- | --- | | --json | Emit raw JSON (pipe into jq, dashboards, CI) | | | --markdown, --md | Emit a Markdown report (good for a PULSE.md) | | | --since <days> | Window for activity, contributors and hot files | 90 | | --weeks <n> | Weeks shown in the activity sparkline | 26 | | --limit <n> | Rows per section | 5 | | --stale-days <n> | Idle threshold for the stale-branch list | 60 | | -h, --help | Show help | | | -v, --version | Show version | |

Examples

gitpulse                      # the repo you are standing in
gitpulse ../some-repo --since 30
gitpulse --markdown > PULSE.md
gitpulse --json | jq '.markers'

What it reports

• Activity: commits per week as a sparkline.
• Top contributors by commit count in the window.
• Hottest files: the files touched by the most commits, which is a decent proxy for risk.
• Languages: tracked files grouped by extension.
• Markers: counts of TODO, FIXME, HACK and XXX.
• Stale branches: local branches idle past your threshold.

It runs in well under a second on large repos and works offline. The whole tool is one Node file with no install footprint.

Development

git clone https://github.com/bobfromarcher/gitpulse
cd gitpulse
node test/test.js

CI runs the suite on Node 18, 20 and 22 across Linux, macOS and Windows.

License

MIT, bobfromarcher.