Example

gitstats . generates this gitstats report:

Check out the GitStats Gallery for live reports on the world’s largest open-source projects — auto-generated weekly.

Installation

pip install gitstats

Or, using uv (recommended):

uv pip install gitstats      # install into current environment
uvx gitstats .              # run instantly, no install required

gitstats is compatible with Python 3.10 and newer.

Usage

gitstats <gitpath> [<outputpath>]

If <outputpath> is omitted, reports are written to gitstats-report/ by default.

Analyze several repositories at once to get a portfolio overview — useful for seeing how all of a team’s projects are doing in one place:

gitstats repo1 repo2 repo3 <outputpath>

Each repository gets its full report in <outputpath>/<repo>/ along with a machine-readable summary.json, and an aggregate page at <outputpath>/index.html shows a sortable table of every repository — commits, authors, recent activity, lines of code and a health label — linking into the individual reports. Repositories that fail to analyze are listed on the page without stopping the run.

Add --serve to preview the generated report right away — gitstats starts a local web server and prints the URL (bound to 127.0.0.1 by default; pass --host 0.0.0.0 to expose it on your network, --port to pick a port):

gitstats --serve .

Use --verbose to show debug-level command logs, or --quiet to show only warnings and errors:

gitstats --verbose .
gitstats --quiet .

Run gitstats --help for more options, or check the documentation.

GitHub Action

Automate your gitstats report generation with the official GitStats Action.

- uses: shenxianpeng/gitstats-action@v1
  with:
    deploy-to-pages: true

With just one uses line, the Action generates a full gitstats report and deploys it to GitHub Pages automatically.

See the gitstats-action repository for detailed inputs, examples, and advanced usage (AI-powered reports, custom config, manual deploy, etc.).

Share Your Report with a Badge

Every report ships with a badge.svg next to index.html — a shields.io-style badge in the gitstats brand colors that shows live repository data (commit count by default). Because the badge lives inside the report directory, wherever you host the report the badge is served from the same URL, and it refreshes automatically every time the report is regenerated.

This repository eats its own dog food — these are live badges served from the demo report (click one):

The quickest way: the report’s Badges page. Open the published report and go to Badges in the nav (or “Badge for your README” under the repository name). Pick a style and a format — Markdown, reStructuredText or HTML — and press Copy next to the badge you want: the snippet already points at your report. The page reads the report’s address from its own URL; when it is opened from a local file, type the address in (your browser remembers it) or generate the report with --site-url:

gitstats --site-url https://reports.example.com/my-repo/ . gitstats-report

--site-url also prints the README badge in the run log, which is handy in CI.

Or write the snippet yourself. Embed it in your README so visitors can jump straight to the report:

[![GitStats](https://<your-report-url>/badge.svg)](https://<your-report-url>/)

Or in reStructuredText:

.. image:: https://<your-report-url>/badge.svg
   :target: https://<your-report-url>/
   :alt: GitStats report

Projects on GitHub — the easiest path is the GitStats Action with deploy-to-pages: true (see above). After the first run, the workflow’s job summary contains ready-to-copy badge markdown pointing at your GitHub Pages report, e.g. https://<owner>.github.io/<repo>/badge.svg.

Projects hosted elsewhere — publish the report output directory with any static hosting you already use (GitLab Pages, Netlify, an internal web server, …) and point the badge at it. For example, on GitLab CI:

pages:
  variables:
    GIT_DEPTH: 0   # CI clones are shallow by default: fetch all history
  script:
    - pip install gitstats
    - gitstats . public
  artifacts:
    paths:
      - public

then embed https://<group>.gitlab.io/<project>/badge.svg linking to https://<group>.gitlab.io/<project>/. The integration docs cover GitLab group badges, private GitLab projects and Bitbucket Pipelines.

gitstats -c badge_metric=last-commit \
         -c badge_label="my project" \
         -c badge_color=green \
         -c badge_style=terminal . gitstats-report

[![GitStats](https://img.shields.io/endpoint?url=https://<your-report-url>/badges/commits.json&style=for-the-badge&color=orange)](https://<your-report-url>/)

Repo Wrapped Card

Add --wrapped to also get a “Repo Wrapped” card: a square (1080×1080) SVG image written next to the report as wrapped-<year>.svg, made for sharing.

gitstats --wrapped .
gitstats --wrapped --wrapped-theme sunset .      # midnight (default), sunset or clean
gitstats --wrapped --wrapped-year 2025 .         # the card for another year
gitstats --wrapped --wrapped-output card.svg .   # write it to another file

The card is about one year, the current one by default, and every number on it is that year’s: commits, active days, longest streak, lines changed, contributors, releases (or new contributors, in a year without a release), the busiest month and weekday, the top contributor, the commits in each month and the part of the day most of them were made in. A year without commits gets no card: gitstats says so and names the last year that has any.

With several repositories, each one gets its card in its own report directory; --wrapped-output names a single file, so it only works with one repository.

What’s New in v2.0.0

v2.0.0 is a major release focused on modernizing the report UI and removing the Gnuplot dependency.

Terminal-inspired UI redesign

The entire report interface has been redesigned with a terminal / OpenCode-inspired aesthetic: zero border-radius (sharp, angular corners), monospace fonts in headings and navigation, border-heavy layout, and a GitHub-style green heatmap. Both light and dark modes are supported with a one-click toggle — no flash of unstyled content when switching pages.

Chart.js replaces Gnuplot

All charts are now rendered interactively in the browser using Chart.js. Gnuplot is no longer required. Reports are fully self-contained HTML files.

Features

Here is a list of some features of gitstats:

• General: headline numbers (commits, authors, lines, files, active days, longest streak), commits per year, top contributors, latest releases.

• Activity: commits by year, month and week; a punch card of day of week by hour of day; month of year; timezones.

• Authors: every author’s commits, lines and active span; a contributor timeline; cumulative lines added per author; the top author per year and month; commits by email domain; contributor growth.

• Files: file count over time, extensions ranked by lines, and the most-changed files.

• Lines: lines of code over time, and lines added and removed per month.

• Tags: every tag with its commits and authors.

• Code Ownership: bus-factor risk (files only one person has changed), ownership by author, and the files shared by the most people.

• Hotspots: every file plotted by its size against how often it changes, and the large, frequently changed files ranked by score.

• History: the project’s life one year at a time — its peaks, quiet years and revivals, newcomers and releases — with optional AI narration.

• Portfolio: analyze several repositories at once for an aggregate overview.

• Wrapped card: a shareable SVG card of one year in the repository, with --wrapped.

• Readable anywhere: interactive charts, light and dark themes, and layouts that work on phones; long quiet periods are shaded on every timeline.

• Customizable: config values through gitstats.conf.

• Cross-platform: works on Linux, Windows, and macOS.

AI-Powered Features 🤖

GitStats supports AI-powered insights to enhance your repository analysis with natural language summaries and actionable recommendations.

Quick Start:

# Install with AI support
pip install gitstats[ai]

# Enable AI with OpenAI
export OPENAI_API_KEY=your-api-key
gitstats --ai --ai-provider openai <gitpath> [<outputpath>]

For detailed setup instructions, configuration options, and examples, see the AI Integration Documentation.

Contributing

As an open source project, gitstats welcomes contributions of all forms.

Thanks to all contributors:

The gitstats project was originally created by Heikki Hokkainen and is currently maintained by Xianpeng Shen.