GitStats 📊

Visualize Your Git Repositories.

Example

Run gitstats . report¹ to generate this report: https://shenxianpeng.github.io/gitstats/index.html.

Run gitstats . report --format json to generate above report along with a JSON file².

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.

📈 More examples: Jenkins project example: A report showcasing data from the Jenkins project.

Requirements

• Python 3.9+
• Gnuplot (http://www.gnuplot.info): You can install Gnuplot on
  • Ubuntu with sudo apt install gnuplot
  • macOS with brew install gnuplot
  • Windows with choco install gnuplot
• Git (http://git-scm.com/)

Installation

Install from PyPI

pip install gitstats

Install from Docker

You can also get gitstats docker image.

docker run ghcr.io/shenxianpeng/gitstats:latest --help

Usage

gitstats --help
usage: gitstats [-h] [-v] [-c key=value] [-f {json}] <gitpath> [<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. Default configuration: {'max_domains':
                        10, 'max_ext_length': 10, 'style': 'gitstats.css', 'max_authors': 20, 'authors_top': 5, 'commit_begin':
                        '', 'commit_end': 'HEAD', 'linear_linestats': 1, 'project_name': '', 'processes': 8, 'start_date': ''}.
  -f {json}, --format {json}
                        The extra format of the output file.

Tip

If you want to use gitstats with CI like GitHub Actions or Jenkins to generate reports and deploy them, please the following examples.

Use gitstats in GitHub Actions

Example GitHub Actions

Use gitstats in GitHub Actions to generate reports and deploy them to GitHub Pages.

name: GitStats Preview

on:
  cron:
    - cron: '0 0 * * 0'  # Run at every sunday at 00:00
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 0 # get all history.

    - name: Install Dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y gnuplot

    - name: Generate GitStats Report
      run: |
        pipx install gitstats
        gitstats . gitstats-report

    - name: Deploy to GitHub Pages for view
      uses: peaceiris/actions-gh-pages@v4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: gitstats-report

Use gitstats in Jenkins

Example Jenkinsfile

Use gitstats in Jenkins to generate reports and publish them to Jenkins server.

pipeline {
    agent any
    options {
        cron('0 0 * * 0')  // Run at every sunday at 00:00
    }
    stages {
        stage('Generate GitStats Report') {
            steps {
                checkout scm
                sh '''
                python3 -m venv venv
                source venv/bin/activate
                pip install gitstats
                gitstats . gitstats-report
                '''
            }
        }
        stage('Publish GitStats Report') {
            steps {
                publishHTML([allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'gitstats-report', reportFiles: 'index.html', reportName: 'GitStats Report'])
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

FAQ

1. How do I generate statistics of a non-master branch?

   Use the -c commit_end=devel parameter.

2. I have files in my git repository that I would like to exclude from the statistics. How do I do that?

   At the moment, the only way is to use git-filter-branch(1) to create a temporary repository and generate the statistics from that.

3. How do I merge author information when the same author has made commits using different names or emails?

   Use Git's .mailmap feature, as described in the gitmailmap documentation.

Contributors

License

Both the code and the web site are licensed under GPLv2/GPLv3.

---

The gitstats project was originally created by H​eikki H​okkanen but is no longer maintained since 2015. It is now maintained by Xianpeng Shen.

Footnotes

1. Before running gitstats, ensure all required dependencies are installed on your system. See requirements ↩

2. You can use jq to parse the JSON file: cat report.json | jq . and extract any data you need. ↩