🎁 git-recap

Spotify Wrapped, but for your git history.

An animated, shareable story of your code — generated 100% locally in one command. No account. No API key. No upload. Zero dependencies.

npx git-recap · run it in any repo · scroll through it

| The story (up to 11 slides) | Every day you showed up | | --- | --- | | | | | Who did the work | The verdict 👏 | | | |

And the share card — generated as recap.svg, made to be embedded in your README:

Why this spreads

Wrapped-style recaps are the most shared format on the internet (Spotify proved it). Every card someone posts — in a README, a tweet, a standup slide — is an ad for the tool. git-recap is built around that loop:

1. The story — recap.html, a full-screen animated recap of any repo: your heatmap, power hours, language donut, ride-or-die files, commit lingo ("fix" ×321), 3AM commits, and a personality verdict with confetti.
2. The card — recap.svg, a 1200×630 digest. Perfect size for a README and for the repo's social preview image. This is the piece that self-propagates: every README it lands in markets the tool to everyone who visits.
3. The end card — the story ends with npx git-recap, so every share teaches the next person how to make their own.

Quick start

cd your-project
npx git-recap

That's it. It writes to ./git-recap/:

| File | What it is | | --- | --- | | recap.html | The animated story. Opens in your browser and scrolls like a page. | | recap.svg | Share card for your README / social preview. | | recap.json | The raw stats — do whatever you want with them. |

Options

npx git-recap [repo-path] [options]

--year 2025        # wrap a single year
--since / --until  # any git date range
--author "name"    # wrap one person's year
--theme synth      # night (default) · synth · forest
--out <dir>        # output elsewhere
--no-open          # don't launch the browser
--json             # stats to stdout, for scripts

Put your year in your profile README (the viral bit)

npx git-recap ~/$YOUR_REPO --year 2025 --no-open
cp $YOUR_REPO/git-recap/recap.svg .

![My year in code](./recap.svg)

Auto-refresh it with GitHub Actions

name: recap
on:
  schedule: [{ cron: "0 9 1 1 *" }]   # every Jan 1
  workflow_dispatch:
permissions: { contents: write }
jobs:
  wrap:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }        # full history
      - uses: actions/setup-node@v4
      - run: npx -y git-recap . --year $(date -d "last year" +%Y) --no-open --out .
      - run: |
          git config user.name "recap-bot" && git config user.email "[email protected]"
          git add recap.svg && git commit -m "wrap: $(date -d 'last year' +%Y)" || exit 0
          git push

What it computes

Everything from one git log --numstat pass over your history:

• Commit volume, active days, averages, +/− line counts
• 52-week heatmap, longest streak, current streak, busiest day/month
• Power-hour clock (24-hour radial chart) and weekday rhythm
• Language ranking by lines written (60+ extensions recognized)
• Ride-or-die files by churn
• Commit lingo — top verbs, "wip" count, emoji commits, your longest message
• Ghost hours — commits between midnight and 5am
• Your verdict — one of 9 deterministic coding personalities

Privacy

Everything runs on your machine with the git binary you already have. There is no server, no telemetry, no network call. It reads, it computes, it writes three files. Read the whole source — it's ~1,400 lines with zero dependencies.

Contributing

PRs welcome — verdicts, themes, and languages are all data-driven tables, so adding one is a great first issue.

License

MIT © 2026 sutharsan