.. start-of-about

.. figure:: https://raw.githubusercontent.com/shenxianpeng/gitstats/main/docs/source/logo.png :alt: Project Logo :align: center :width: 200px

.. |pypi-version| image:: https://img.shields.io/pypi/v/gitstats?color=blue :target: https://pypi.org/project/gitstats/ :alt: PyPI - Version

.. |python-versions| image:: https://img.shields.io/pypi/pyversions/gitstats :alt: PyPI - Python Version

.. |python-download| image:: https://static.pepy.tech/badge/gitstats/week :target: https://pepy.tech/projects/gitstats :alt: PyPI Downloads

.. |test-badge| image:: https://github.com/shenxianpeng/gitstats/actions/workflows/test.yml/badge.svg :target: https://github.com/shenxianpeng/gitstats/actions/workflows/test.yml :alt: Test

.. |sonarcloud| image:: https://sonarcloud.io/api/project_badges/measure?project=shenxianpeng_gitstats&metric=alert_status :target: https://sonarcloud.io/summary/new_code?id=shenxianpeng_gitstats :alt: Quality Gate Status

.. |docs-badge| image:: https://readthedocs.org/projects/gitstats/badge/?version=latest :target: https://gitstats.readthedocs.io/ :alt: Documentation

.. |contributors| image:: https://img.shields.io/github/contributors/shenxianpeng/gitstats :target: https://github.com/shenxianpeng/gitstats/graphs/contributors :alt: GitHub contributors

|pypi-version| |python-versions| |python-download| |test-badge| |docs-badge| |contributors|

$ gitstats

📊 Generate insightful visual reports from Git.

📘 Documentation: gitstats.readthedocs.io <https://gitstats.readthedocs.io/>_

Example

gitstats . report generates this gitstats report <https://shenxianpeng.github.io/gitstats/index.html>_.

.. image:: https://raw.githubusercontent.com/shenxianpeng/gitstats/main/docs/source/demo.gif :alt: gitstats terminal demo :align: center

Installation

.. code-block:: bash

pip install gitstats

Or, using uv <https://docs.astral.sh/uv/>_ (recommended):

.. code-block:: bash

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

gitstats is compatible with Python 3.10 and newer.

Usage

.. code-block:: bash

gitstats

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

.. code-block:: bash

gitstats --verbose . report gitstats --quiet . report

Run gitstats --help for more options, or check the documentation <https://gitstats.readthedocs.io/en/latest/getting-started.html>_.

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 <https://www.chartjs.org/>_. 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:

.. code-block:: bash

Install with AI support

pip install gitstats[ai]

Enable AI with OpenAI

export OPENAI_API_KEY=your-api-key gitstats --ai --ai-provider openai

For detailed setup instructions, configuration options, and examples, see the AI Integration Documentation <https://gitstats.readthedocs.io/en/stable/ai-integration.html>_.

.. end-of-about

Contributing

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

---

The gitstats project was originally created by Heikki Hokkainen <https://github.com/hoxu>_ and is currently maintained by Xianpeng Shen <https://github.com/shenxianpeng>_.