gitstats is a tool that generates statistics for git repositories, providing HTML output with tables and graphs to help developers view project development history.

Explore what a gitstats report looks like with the following examples:

• 📈 Self preview of gitstats: A report generated for the GitStats project itself.
• 📈 Jenkins project example: A report showcasing data from the Jenkins project.

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.

• Python 3.9+
• Gnuplot (http://www.gnuplot.info/)
• Git (http://git-scm.com/)

# create python virtual environment
python3 -m venv venv
source venv/bin/activate

pip install gitstats

gitstats --help

You can also get gitstats docker image.

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

You can 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

Usage: gitstats [options] <gitpath..> <outputpath>

Options:
-c key=value     Override configuration value

Default config values:
{'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': ''}

Please see the manual page for more details.

gitstats your-awesome-project ~/public_html

The output will be generated in the given directory.

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

   Use the -c commit_end=web 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 MAPPING AUTHORS section of the git-shortlog(1) documentation.

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