Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

punchcard generator for git commit frequencies

Project description


Simple git punchcard utility, inspired by git-punchcard-plot but rewritten for python3 with matplotlib.



Install or upgrade from PyPI as follows:

pip install --user --upgrade git-punchcard

Also, make sure that $HOME/.local/bin is in $PATH.

To avoid conflicts with other packages, I recommend installing into an isolated environment, e.g. using pipx:

pipx install git-punchcard


Basic usage:

git punchcard

Additional arguments can be specified as follows:

git punchcard [<input path>...] [<options>]
              [--] [<log options>] [<revision range>] [-- <path>...]

For more help on available options, type:

git punchcard -h            # [options]
git help log                # [log options]
git help gitrevisions       # [revision]


The most common builtin options are:

# use a fixed timezone for all commits:
git punchcard --timezone CET
git punchcard --timezone Europe/Berlin
git punchcard --timezone UTC+02:30

# show punchcard with specified y/x axes:
git punchcard -p year/month
git punchcard -p wday/month

# histogram with specified x axis:
git punchcard -p /wday

# set the directory of the git repository (multiple allowed):
git punchcard /path/to/repo

# analyze all repositories in ~/dev:
git punchcard ~/dev/*/.git

# read commit dates from stdin:
git punchcard -

# show a github-like punchcard plot with grid:
git punchcard --grid

By default, each commit’s local timezone is used for the plot. If setting a fixed timezone, it should be specified in terms of the timezone name (e.g. CET or Europe/Berlin), but can also given by ISO 3166 country code or country name (if the timezone is ambiguous we will pick the first entry).

git log options

Additionally, you can pass any options understood by git log to e.g. restrict the range of commits and limit to commits performed by a certain author:

# include only commits by specific author:
git punchcard --author=myself

# consider only only the 20 commits:
git punchcard master~20..master

# commits within a certain time frame:
git punchcard --since="1 year ago" --until=now

# show at which times a certain file/folder is usually edited:
git punchcard --follow -- README.rst docs

# show at which times, people like to merge:
git punchcard --merges

Advanced example

Track evolution of commit activity over the years:

for year in {2016..2019}; do
    git punchcard -o $year.png --title $year \
        --since 1.1.$year --until 31.12.$year



Date: 31.10.2019

  • include license file in source distribution


Date: 31.10.2019

  • automatic deployments
  • changes in setup and testing


Date: 26.03.2019

  • fix: default to current directory if no input pathes were passed by the user


Date: 26.03.2019

  • turn -C into positional argument, remove -C option
  • allow multiple input files
  • allow passing - and files with git log output as input files
  • remove obsolete dependency on docopt
  • allow passing country codes and names instead of timezone (using first available timezone in case of ambiguity)
  • match timezones case-insensitively
  • show git command and number of commits
  • show error message without traceback for common errors


Date: 26.03.2019

  • learn --period Y/X parameter to specify Y/X axes
  • can plot histograms by leaving one of the axes empty
  • understand -v as alias for --version


Date: 21.03.2019

  • log options are now passed directly without -- same as the other options
  • drop dependency on docopt


Date: 21.03.2019

  • fix exception if called without runtime dependencies
  • import pytz only if needed
  • learn a -C DIR parameter to pass the path to the git repository
  • learn a --version parameter to show the script version
  • fix error when passing options and git options at the same time
  • turn into a module and use setuptools entry_points to generate script


Date: 11.03.2019

  • add --title parameter

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for git-punchcard, version 2.0.3
Filename, size File type Python version Upload date Hashes
Filename, size git_punchcard-2.0.3-py3-none-any.whl (7.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size git-punchcard-2.0.3.tar.gz (8.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page