Welcome to GitStats documentation!

PyPI - Python Version

`$ gitstats`

📊 Generate insightful visual reports from Git.

📘 Documentation: gitstats.readthedocs.io 📊 GitStats Gallery: shenxianpeng.dev/gitstats/gallery/

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):

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:
  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>/.

Customizing the badge

Static hosting can’t vary a file on ?query parameters, so customization works through pre-rendered files and configuration instead.

Pick a metric by URL. Alongside badge.svg, every report contains a badges/ directory with one badge per metric — switching what the badge says is just switching the URL:

badges/commits.svg — 1,234 commits
badges/last-commit.svg — Aug 2026 (date of the latest commit)
badges/authors.svg — 12 authors
badges/files.svg — 245 files
badges/lines.svg — 44,025 lines

Style with config keys. The badge_* options control every generated badge (including which metric badge.svg itself shows):

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

badge_color accepts shields.io color names (brightgreen, green, yellow, orange, red, blue, lightgrey), hex values like #30a14e, or any SVG color. badge_style is flat (rounded, subtle gradient) or flat-square (sharp corners, matching the report’s angular terminal aesthetic).

Full shields.io customization. Each metric is also exported as badges/<metric>.json in the shields.io endpoint schema. Point shields at it and use any of their URL parameters — arbitrary colors, style=for-the-badge, logos — while the data stays yours and stays live:

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

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: total files, lines, commits, authors, age.
Activity: commits by hour of day, day of week, hour of week, month of year, year and month, and year.
Authors: list of authors (name, commits (%), first commit date, last commit date, age), author of month, author of year.
Files: file count by date, extensions.
Lines: line of code by date.
Tags: tags by date and author.
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.

About