Metadata-Version: 2.4
Name: gitstats
Version: 2.10.0
Summary: GitStats - Visualize Your Git Repositories
Author-email: Xianpeng Shen <xianpeng.shen@gmail.com>, Heikki Hokkanen <hoxu@users.sf.net>
Project-URL: source, https://github.com/shenxianpeng/gitstats
Project-URL: tracker, https://github.com/shenxianpeng/gitstats/issues
Project-URL: homepage, https://shenxianpeng.dev/gitstats/index.html
Project-URL: documentation, https://gitstats.readthedocs.io/
Keywords: git,gitstats,statistics,git history
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: nox; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Provides-Extra: ai
Requires-Dist: openai>=1.0; extra == "ai"
Requires-Dist: anthropic>=0.8; extra == "ai"
Requires-Dist: google-generativeai>=0.3; extra == "ai"
Requires-Dist: requests>=2.31; extra == "ai"
Dynamic: license-file

.. image:: https://raw.githubusercontent.com/shenxianpeng/gitstats/main/docs/source/banner-dark.png#gh-dark-mode-only
   :alt: gitstats — git history statistics
   :width: 100%

.. image:: https://raw.githubusercontent.com/shenxianpeng/gitstats/main/docs/source/banner-light.png#gh-light-mode-only
   :alt: gitstats — git history statistics
   :width: 100%

.. start-of-about

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

.. |marketplace| image:: https://img.shields.io/badge/GitHub_Marketplace-gitstats--action-blue.svg
   :target: https://github.com/marketplace/actions/gitstats-action
   :alt: GitHub Marketplace

.. |gitstats-report| image:: https://shenxianpeng.dev/gitstats/badge.svg
   :target: https://shenxianpeng.dev/gitstats/
   :alt: GitStats report

.. |gitstats-last-commit| image:: https://shenxianpeng.dev/gitstats/badges/last-commit.svg
   :target: https://shenxianpeng.dev/gitstats/
   :alt: GitStats last commit

.. |gitstats-summary| image:: https://shenxianpeng.dev/gitstats/badges/summary.svg
   :target: https://shenxianpeng.dev/gitstats/
   :alt: GitStats summary

.. |gitstats-activity| image:: https://shenxianpeng.dev/gitstats/badges/activity.svg
   :target: https://shenxianpeng.dev/gitstats/
   :alt: GitStats activity

.. |gitstats-health| image:: https://shenxianpeng.dev/gitstats/badges/health.svg
   :target: https://shenxianpeng.dev/gitstats/
   :alt: GitStats health

|pypi-version| |python-versions| |test-badge| |docs-badge| |marketplace| |gitstats-report|

``$ gitstats``
===============

📊 Generate insightful visual reports from Git.

📘 Documentation: `gitstats.readthedocs.io <https://gitstats.readthedocs.io/>`_
📊 GitStats Gallery: `shenxianpeng.dev/gitstats/gallery/ <https://shenxianpeng.dev/gitstats/gallery/>`_

.. contents:: Table of Contents
   :depth: 2
   :local:
   :backlinks: none

Example
-------

``gitstats .`` generates this `gitstats report <https://shenxianpeng.dev/gitstats/index.html>`_:

.. image:: https://raw.githubusercontent.com/shenxianpeng/gitstats/main/docs/source/report-dark.png#gh-dark-mode-only
   :alt: The overview page of a gitstats report
   :width: 100%
   :target: https://shenxianpeng.dev/gitstats/index.html

.. image:: https://raw.githubusercontent.com/shenxianpeng/gitstats/main/docs/source/report-light.png#gh-light-mode-only
   :alt: The overview page of a gitstats report
   :width: 100%
   :target: https://shenxianpeng.dev/gitstats/index.html

Check out the `GitStats Gallery <https://shenxianpeng.dev/gitstats/gallery/>`_ for live reports on the world's largest open-source projects — auto-generated weekly.

.. 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 .              # run instantly, no install required


gitstats is compatible with Python 3.10 and newer.


Usage
-----

.. code-block:: bash

   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:

.. code-block:: bash

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

.. code-block:: bash

   gitstats --serve .

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

.. code-block:: bash

   gitstats --verbose .
   gitstats --quiet .


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


GitHub Action
-------------

Automate your gitstats report generation with the official `GitStats Action <https://github.com/marketplace/actions/gitstats-action>`_.

.. code-block:: yaml

   - 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 <https://github.com/shenxianpeng/gitstats-action>`_ 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 <https://shenxianpeng.dev/gitstats/>`_ (click one):

|gitstats-report| |gitstats-last-commit| |gitstats-summary| |gitstats-activity| |gitstats-health|

**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``:

.. code-block:: bash

   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:

.. code-block:: markdown

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

Or in reStructuredText:

.. code-block:: rst

   .. 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 <https://github.com/marketplace/actions/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:

.. code-block:: yaml

   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
<https://gitstats.readthedocs.io/en/latest/integration.html>`_ cover GitLab
group badges, private GitLab projects and Bitbucket Pipelines.

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``
- ``badges/release.svg`` — ``v2.7.0 · 46 tags`` (newest tag and tag count)
- ``badges/active-days.svg`` — ``229 active days`` (days with commits)

A few badges pack more into one image:

- ``badges/summary.svg`` — ``563 commits | 40 authors | 18.5k lines``
- ``badges/activity.svg`` — a sparkline of commits per month over the last
  year of history, then the latest month: ``29 in Sep``
- ``badges/health.svg`` — ``active``, ``quiet`` or ``dormant`` with the age
  of the last commit (``last commit 3 days ago``), colored green, amber or
  gray; active means a commit within 30 days, quiet within a year. It keeps
  its own label and colors, and its age counts from when the report was
  generated, so regenerate the report on a schedule to keep it honest

**Pick a style by URL too.** Every badge is also written in every style, as
``badges/<style>/<name>.svg`` (``badges/terminal/summary.svg``). A README
that links one of these keeps its look when ``badge_style`` changes; the
Badges page uses them.

**Style with config keys.** The ``badge_*`` options control every generated
badge (including which badge ``badge.svg`` itself is, any name above):

.. code-block:: bash

   gitstats -c badge_metric=last-commit \
            -c badge_label="my project" \
            -c badge_color=green \
            -c badge_style=terminal . 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 one of:

- ``flat`` — rounded, subtle gradient (default)
- ``flat-square`` — sharp corners, solid fill
- ``terminal`` — the report's own look: monospace, square, a ``//`` before
  the label and a light, outlined value
- ``for-the-badge`` — taller, bold and uppercase, for a row of hero badges
- ``light`` — white label and pale blue value with a thin border, for
  READMEs on white pages

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

.. code-block:: markdown

   [![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.

.. code-block:: bash

   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.

The report shows the card on its Badges page, with a snippet to put it in a
README, and links to it from its year on the History page.

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 <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**: 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; and the commits that name an AI coding assistant, by month and by assistant.
* **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**: the bus factor, 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, with how many people have changed each.
* **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, and cut down to a short break when they would take up a quarter of it or more.
* **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 <gitpath> [<outputpath>]

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.

Thanks to all contributors:

.. image:: https://contrib.rocks/image?repo=shenxianpeng/gitstats
   :target: https://github.com/shenxianpeng/gitstats/graphs/contributors
   :alt: Contributors

----

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