Getting Started

Prerequisites

Before using gitstats, ensure you have the following installed:

Note

Starting from version 2.0.0, gitstats uses Chart.js (bundled with the report) for rendering charts to modernize the visualizations and improve performance.

Installation

Install gitstats using pip:

pip install gitstats

Quick Start

Generate a basic report by running:

gitstats . report

Tip

Alternatively, use uv to download and run gitstats in one command:

uvx gitstats . report

Where:

  • . is the current directory (your Git repository), you can specify any Git repository path.

  • report is the output directory where HTML files will be generated

View a live example: https://shenxianpeng.github.io/gitstats/index.html

Generate Report with JSON Output

To generate both HTML and JSON formats:

gitstats . report --format json

This creates a report.json file alongside the HTML report.

Tip

Use jq to parse the JSON file:

cat report.json | jq .

This allows you to extract specific data or integrate with other tools.

Command Line Usage

Basic Syntax

gitstats [options] <gitpath> <outputpath>

Arguments:

  • <gitpath> - Path to your Git repository (e.g., . for current directory)

  • <outputpath> - Directory where the report will be generated

Options:

  • -h, --help - Show help message and exit

  • -v, --version - Show program version number

  • -c key=value, --config key=value - Override configuration values (can be used multiple times)

  • -f {json}, --format {json} - Generate additional output format

Full Help Output

usage: gitstats [-h] [-v] [-c key=value] [-f {json}] <gitpath> <outputpath>

Generate statistics for a Git repository.

positional arguments:
  <gitpath>             Path(s) to the Git repository.
  <outputpath>          Path to the directory where the output will be stored.

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -c key=value, --config key=value
                        Override configuration value. Can be specified multiple
                        times. See configuration documentation for available options.
  -f {json}, --format {json}
                        Generate additional output format.

Examples

Generate report for current directory:

gitstats . my-report

Generate report for specific repository:

gitstats /path/to/repo output-folder

Generate report with JSON output:

gitstats . report --format json

Override configuration values:

gitstats . report -c max_authors=10 -c authors_top=3

For more configuration options, see the Configuration page.